No OneTemporary
Actions

Size

5 MB

Referenced Files

None

Subscribers

None

View Options

This file is larger than 256 KB, so syntax highlighting was skipped.

This document is not UTF8. It was detected as ISO-8859-1 (Latin 1) and converted to UTF8 for display.

	Index: projects/entities/en_US.ISO8859-1/articles/bsdl-gpl/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/bsdl-gpl/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/bsdl-gpl/article.xml (revision 41355)
	@@ -1,575 +1,574 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	]>

	<article lang='en'>
	<title>Why you should use a BSD style license for your Open Source Project</title>
	<articleinfo>

	<authorgroup>
	<author>
	<firstname>Bruce</firstname>
	<!-- middle initial: R. -->
	<surname>Montague</surname>
	<affiliation>
	<address><email>brucem@alumni.cse.ucsc.edu</email>
	</address>
	</affiliation>
	</author>
	</authorgroup>

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	- &tm-attrib.cvsup;
	&tm-attrib.intel;
	&tm-attrib.general;
	</legalnotice>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>
	</articleinfo>

	<sect1 id="intro">
	<title>Introduction</title>

	<para>This document makes a case for using a BSD style license for
	software and data; specifically it recommends using a BSD style
	license in place of the GPL. It can also be read as a BSD versus
	GPL Open Source License introduction and summary.</para>
	</sect1>

	<sect1 id="history">
	<title>Very Brief Open Source History</title>

	<para>Long before the term <quote>Open Source</quote> was used, software was
	developed by loose associations of programmers and freely
	exchanged. Starting in the early 1950's, organizations such as
	<ulink url="http://www.share.org">SHARE</ulink> and <ulink url="http://www.decus.org">DECUS</ulink> developed much of the
	software that computer hardware companies bundled with their
	hardware offerings. At that time computer companies were in the
	hardware business; anything that reduced software cost and made
	more programs available made the hardware companies more
	competitive.</para>

	<para>This model changed in the 1960's. In 1965 ADR developed the
	first licensed software product independent of a hardware
	company. ADR was competing against a free IBM package originally
	developed by IBM customers. ADR patented their software in
	1968. To stop sharing of their program, they provided it under an
	equipment lease in which payment was spread over the lifetime of
	the product. ADR thus retained ownership and could control resale
	and reuse.</para>

	<para>In 1969 the US Department of Justice charged IBM with
	destroying businesses by bundling free software with IBM
	hardware. As a result of this suit, IBM unbundled its software;
	that is, software became independent products separate from
	hardware.</para>

	<para>In 1968 Informatics introduced the first commercial killer-app
	and rapidly established the concept of the software product, the
	software company, and very high rates of return. Informatics
	developed the perpetual license which is now standard throughout
	the computer industry, wherein ownership is never transferred to
	the customer.</para>
	</sect1>

	<sect1 id="unix-license">
	<title>Unix from a BSD Licensing Perspective</title>

	<para>AT&T, who owned the original Unix implementation, was a
	publicly regulated monopoly tied up in anti-trust court; it was
	legally unable to sell a product into the software market. It was,
	however, able to provide it to academic institutions for the price
	of media.</para>

	<para>Universities rapidly adopted Unix after an OS conference
	publicized its availability. It was extremely helpful that Unix
	ran on the PDP-11, a very affordable 16-bit computer, and was
	coded in a high-level language that was demonstrably good for
	systems programming. The DEC PDP-11 had, in effect, an open
	hardware interface designed to make it easy for customers to write
	their own OS, which was common. As DEC founder Ken Olsen famously
	proclaimed, <quote>software comes from heaven when you have good
	hardware</quote>.</para>

	<para>Unix author Ken Thompson returned to his alma mater,
	University of California Berkeley (UCB), in 1975 and taught the
	kernel line-by-line. This ultimately resulted in an evolving
	system known as BSD (Berkeley Standard Distribution). UCB
	converted Unix to 32-bits, added virtual memory, and implemented
	the version of the TCP/IP stack upon which the Internet was
	essentially built. UCB made BSD available for the cost of media,
	under what became known as <quote>the BSD license</quote>. A customer purchased
	Unix from AT&T and then ordered a BSD tape from UCB.</para>

	<para>In the mid-1980s a government anti-trust case against ATT
	ended with the break-up of ATT. ATT still owned Unix and was now
	able to sell it. ATT embarked on an aggressive licensing effort
	and most commercial Unixes of the day became ATT-derived.</para>

	<para>In the early 1990's ATT sued UCB over license violations
	related to BSD. UCB discovered that ATT had incorporated, without
	acknowledgment or payment, many improvements due to BSD into ATT's
	products, and a lengthy court case, primarily between ATT and UCB,
	ensued. During this period some UCB programmers embarked on a
	project to rewrite any ATT code associated with BSD. This project
	resulted in a system called BSD 4.4-lite (lite because it was not
	a complete system; it lacked 6 key ATT files).</para>

	<para>A lengthy series of articles published slightly later in
	Dr. Dobbs magazine described a BSD-derived 386 PC version of Unix,
	with BSD-licensed replacement files for the 6 missing 4.4 lite
	files. This system, named 386BSD, was due to ex-UCB programmer
	William Jolitz. It became the original basis of all the PC BSDs in
	use today.</para>

	<para>In the mid 1990s, Novell purchased ATT's Unix rights and a
	(then secret) agreement was reached to terminate the lawsuit. UCB
	soon terminated its support for BSD.</para>
	</sect1>

	<sect1 id="current-bsdl">
	<title>The Current State of FreeBSD and BSD Licenses</title>

	<para>The so-called <ulink url="http://www.opensource.org/licenses/bsd-license.php"> new BSD
	license</ulink> applied to FreeBSD within the last few years is
	effectively a statement that you can do anything with the program
	or its source, but you do not have any warranty and none of the
	authors has any liability (basically, you cannot sue anybody). This
	new BSD license is intended to encourage product
	commercialization. Any BSD code can be sold or included in
	proprietary products without any restrictions on the availability
	of your code or your future behavior.</para>

	<para>Do not confuse the new BSD license with <quote>public
	domain</quote>. While an item in the public domain is also free
	for all to use, it has no owner.</para>

	</sect1>

	<sect1 id="origins-gpl">
	<title>The origins of the GPL</title>

	<para>While the future of Unix had been so muddled in the late 1980s
	and early 1990s, the GPL, another development with important
	licensing considerations, reached fruition.</para>

	<para>Richard Stallman, the developer of Emacs, was a member of the
	staff at MIT when his lab switched from home-grown to proprietary
	systems. Stallman became upset when he found that he could not
	legally add minor improvements to the system. (Many of Stallman's
	co-workers had left to form two companies based on software
	developed at MIT and licensed by MIT; there appears to have been
	disagreement over access to the source code for this software).
	Stallman devised an alternative to the commercial software license
	and called it the GPL, or "GNU Public License". He also started a
	non-profit foundation, the <ulink url="http://www.fsf.org">Free
	Software Foundation</ulink> (FSF), which intended to develop an entire
	operating system, including all associated software, that would
	not be subject to proprietary licensing. This system was called
	GNU, for "GNU is Not Unix".</para>

	<para>The GPL was designed to be the antithesis of the standard
	proprietary license. To this end, any modifications that were
	made to a GPL program were required to be given back to the GPL
	community (by requiring that the source of the program be
	available to the user) and any program that used or linked to GPL
	code was required to be under the GPL. The GPL was intended to
	keep software from becoming proprietary. As the last paragraph of
	the GPL states:</para>

	<para><quote>This General Public License does not permit
	incorporating your program into proprietary
	programs.</quote>[1]</para>

	<para>The <ulink url="http://www.opensource.org/licenses/gpl-license.php">GPL</ulink>
	is a complex license so here are some rules of thumb when using
	the GPL:</para>

	<itemizedlist>

	<listitem><para>you can charge as much as you want for
	distributing, supporting, or documenting the software, but you
	cannot sell the software itself.</para></listitem>

	<listitem><para>the rule-of-thumb states that if GPL source
	is required for a program to compile, the program must be under
	the GPL. Linking statically to a GPL library requires a program
	to be under the GPL.</para></listitem>

	<listitem><para>the GPL requires that any patents associated with
	GPLed software must be licensed for everyone's free
	use.</para></listitem>

	<listitem><para>simply aggregating software together, as when
	multiple programs are put on one disk, does not count as
	including GPLed programs in non-GPLed
	programs.</para></listitem>

	<listitem><para>output of a program does not count as a derivative
	work. This enables the gcc compiler to be used in commercial
	environments without legal problems.</para></listitem>

	<listitem><para>since the Linux kernel is under the GPL, any code
	statically linked with the Linux kernel must be GPLed. This
	requirement can be circumvented by dynamically linking loadable
	kernel modules. This permits companies to distribute binary
	drivers, but often has the disadvantage that they will only work
	for particular versions of the Linux kernel.</para></listitem>
	</itemizedlist>

	<para>Due in part to its complexity, in many parts of the world
	today the legalities of the GPL are being ignored in regard to
	Linux and related software. The long-term ramifications of this
	are unclear.</para>

	</sect1>

	<sect1 id="origins-lgpl">
	<title>The origins of Linux and the LGPL</title>

	<para>While the commercial Unix wars raged, the Linux kernel was
	developed as a PC Unix clone. Linus Torvalds credits the existence
	of the GNU C compiler and the associated GNU tools for the
	existence of Linux. He put the Linux kernel under the GPL.</para>

	<para>Remember that the GPL requires anything that statically links
	to any code under the GPL also be placed under the GPL. The source
	for this code must thus be made available to the user of the
	program. Dynamic linking, however, is not considered a violation
	of the GPL. Pressure to put proprietary applications on Linux
	became overwhelming. Such applications often must link with system
	libraries. This resulted in a modified version of the GPL called
	the <ulink url="http://www.opensource.org/licenses/lgpl-license.php">LGPL</ulink>
	("Library", since renamed to "Lesser", GPL). The LGPL allows
	proprietary code to be linked to the GNU C library, glibc. You do
	not have to release the source to code which has been dynamically
	linked to an LGPLed library.</para>

	<para>If you statically link an application with glibc, such as is
	often required in embedded systems, you cannot keep your
	application proprietary, that is, the source must be
	released. Both the GPL and LGPL require any modifications to the
	code directly under the license to be released.</para>

	</sect1>

	<sect1 id="orphaning">
	<title>Open Source licenses and the Orphaning Problem</title>

	<para>One of the serious problems associated with proprietary
	software is known as <quote>orphaning</quote>. This occurs when a
	single business failure or change in a product strategy causes a
	huge pyramid of dependent systems and companies to fail for
	reasons beyond their control. Decades of experience have shown
	that the momentary size or success of a software supplier is no
	guarantee that their software will remain available, as current
	market conditions and strategies can change rapidly.</para>

	<para>The GPL attempts to prevent orphaning by severing the link to
	proprietary intellectual property.</para>

	<para>A BSD license gives a small company the equivalent of
	software-in-escrow without any legal complications or costs. If a
	BSD-licensed program becomes orphaned, a company can simply take
	over, in a proprietary manner, the program on which they are
	dependent. An even better situation occurs when a BSD code-base is
	maintained by a small informal consortium, since the development
	process is not dependent on the survival of a single company or
	product line. The survivability of the development team when they
	are mentally in the zone is much more important than simple
	physical availability of the source code.</para>

	</sect1>

	<sect1 id="license-cannot">
	<title>What a license cannot do</title>

	<para>No license can guarantee future software
	availability. Although a copyright holder can traditionally change
	the terms of a copyright at anytime, the presumption in the BSD
	community is that such an attempt simply causes the source to
	fork.</para>

	<para>The GPL explicitly disallows revoking the license. It has
	occurred, however, that a company (Mattel) purchased a GPL
	copyright (cphack), revoked the entire copyright, went to court,
	and prevailed [2]. That is, they legally revoked the entire
	distribution and all derivative works based on the
	copyright. Whether this could happen with a larger and more
	dispersed distribution is an open question; there is also some
	confusion regarding whether the software was really under the
	GPL.</para>

	<para>In another example, Red Hat purchased Cygnus, an engineering
	company that had taken over development of the FSF compiler
	tools. Cygnus was able to do so because they had developed a
	business model in which they sold support for GNU software. This
	enabled them to employ some 50 engineers and drive the direction
	of the programs by contributing the preponderance of
	modifications. As Donald Rosenberg states "projects using licenses
	like the GPL...live under constant threat of having someone take
	over the project by producing a better version of the code and
	doing it faster than the original owners." [3]</para>

	</sect1>

	<sect1 id="gpl-advantages">
	<title>GPL Advantages and Disadvantages</title>

	<para>A common reason to use the GPL is when modifying or extending
	the gcc compiler. This is particularly apt when working with
	one-off specialty CPUs in environments where all software costs
	are likely to be considered overhead, with minimal expectations
	that others will use the resulting compiler.</para>

	<para>The GPL is also attractive to small companies selling CDs in
	an environment where "buy-low, sell-high" may still give the
	end-user a very inexpensive product. It is also attractive to
	companies that expect to survive by providing various forms of
	technical support, including documentation, for the GPLed
	intellectual property world.</para>

	<para>A less publicized and unintended use of the GPL is that it is
	very favorable to large companies that want to undercut software
	companies. In other words, the GPL is well suited for use as a
	marketing weapon, potentially reducing overall economic benefit
	and contributing to monopolistic behavior.</para>

	<para>The GPL can present a real problem for those wishing to
	commercialize and profit from software. For example, the GPL adds
	to the difficulty a graduate student will have in directly forming
	a company to commercialize his research results, or the difficulty
	a student will have in joining a company on the assumption that a
	promising research project will be commercialized.</para>

	<para>For those who must work with statically-linked implementations
	of multiple software standards, the GPL is often a poor license,
	because it precludes using proprietary implementations of the
	standards. The GPL thus minimizes the number of programs that can
	be built using a GPLed standard. The GPL was intended to not
	provide a mechanism to develop a standard on which one engineers
	proprietary products. (This does not apply to Linux applications
	because they do not statically link, rather they use a trap-based
	API.)</para>

	<para>The GPL attempts to make programmers contribute to an evolving
	suite of programs, then to compete in the distribution and support
	of this suite. This situation is unrealistic for many required
	core system standards, which may be applied in widely varying
	environments which require commercial customization or integration
	with legacy standards under existing (non-GPL) licenses.
	Real-time systems are often statically linked, so the GPL and LGPL
	are definitely considered potential problems by many embedded
	systems companies.</para>

	<para>The GPL is an attempt to keep efforts, regardless of demand,
	at the research and development stages. This maximizes the
	benefits to researchers and developers, at an unknown cost to
	those who would benefit from wider distribution.</para>

	<para>The GPL was designed to keep research results from
	transitioning to proprietary products. This step is often assumed
	to be the last step in the traditional technology transfer
	pipeline and it is usually difficult enough under the best of
	circumstances; the GPL was intended to make it impossible.</para>

	</sect1>

	<sect1 id="bsd-advantages">
	<title>BSD Advantages</title>

	<para>A BSD style license is a good choice for long duration
	research or other projects that need a development environment
	that:</para>

	<itemizedlist>

	<listitem><para>has near zero cost</para></listitem>
	<listitem><para>will evolve over a long period of
	time</para></listitem>
	<listitem><para>permits anyone to retain the option of
	commercializing final results with minimal legal
	issues.</para></listitem>
	</itemizedlist>

	<para>This final consideration may often be the dominant one, as it
	was when the Apache project decided upon its license:</para>

	<para><quote>This type of license is ideal for promoting the use of
	a reference body of code that implements a protocol for common
	service. This is another reason why we choose it for the Apache
	group - many of us wanted to see HTTP survive and become a true
	multiparty standard, and would not have minded in the slightest if
	Microsoft or Netscape choose to incorporate our HTTP engine or any
	other component of our code into their products, if it helped
	further the goal of keeping HTTP common... All this means that,
	strategically speaking, the project needs to maintain sufficient
	momentum, and that participants realize greater value by
	contributing their code to the project, even code that would have
	had value if kept proprietary.</quote></para>

	<para>Developers tend to find the BSD license attractive as it keeps
	legal issues out of the way and lets them do whatever they want
	with the code. In contrast, those who expect primarily to use a
	system rather than program it, or expect others to evolve the
	code, or who do not expect to make a living from their work
	associated with the system (such as government employees), find
	the GPL attractive, because it forces code developed by others to
	be given to them and keeps their employer from retaining copyright
	and thus potentially "burying" or orphaning the software. If you
	want to force your competitors to help you, the GPL is
	attractive.</para>

	<para>A BSD license is not simply a gift. The question <quote>why
	should we help our competitors or let them steal our work?</quote>
	comes up often in relation to a BSD license. Under a BSD license,
	if one company came to dominate a product niche that others
	considered strategic, the other companies can, with minimal
	effort, form a mini-consortium aimed at reestablishing parity by
	contributing to a competitive BSD variant that increases market
	competition and fairness. This permits each company to believe
	that it will be able to profit from some advantage it can provide,
	while also contributing to economic flexibility and
	efficiency. The more rapidly and easily the cooperating members
	can do this, the more successful they will be. A BSD license is
	essentially a minimally complicated license that enables such
	behavior.</para>

	<para>A key effect of the GPL, making a complete and competitive
	Open Source system widely available at cost of media, is a
	reasonable goal. A BSD style license, in conjunction with
	ad-hoc-consortiums of individuals, can achieve this goal without
	destroying the economic assumptions built around the
	deployment-end of the technology transfer pipeline.</para>

	</sect1>

	<sect1 id="recommendations">
	<title>Specific Recommendations for using a BSD license</title>

	<itemizedlist>

	<listitem><para>The BSD license is preferable for transferring
	research results in a way that will widely be deployed and most
	benefit an economy. As such, research funding agencies, such as
	the NSF, ONR and DARPA, should encourage in the earliest phases
	of funded research projects, the adoption of BSD style licenses
	for software, data, results, and open hardware. They should
	also encourage formation of standards based around implemented
	Open Source systems and ongoing Open Source
	projects.</para></listitem>

	<listitem><para>Government policy should minimize the costs and
	difficulties in moving from research to deployment. When
	possible, grants should require results to be available under a
	commercialization friendly BSD style license.</para></listitem>

	<listitem><para>In many cases, the long-term results of a BSD
	style license more accurately reflect the goals proclaimed in
	the research charter of universities then what occurs when
	results are copyrighted or patented and subject to proprietary
	university licensing. Anecdotal evidence exists that
	universities are financially better rewarded in the long run by
	releasing research results and then appealing to donations from
	commercially successful alumni.</para></listitem>

	<listitem><para>Companies have long recognized that the creation
	of de facto standards is a key marketing technique. The BSD
	license serves this role well, if a company really has a unique
	advantage in evolving the system. The license is legally
	attractive to the widest audience while the company's expertise
	ensures their control. There are times when the GPL may be the
	appropriate vehicle for an attempt to create such a standard,
	especially when attempting to undermine or co-opt others. The
	GPL, however, penalizes the evolution of that standard, because
	it promotes a suite rather than a commercially applicable
	standard. Use of such a suite constantly raises
	commercialization and legal issues. It may not be possible to
	mix standards when some are under the GPL and others are not. A
	true technical standard should not mandate exclusion of other
	standards for non-technical reasons.</para></listitem>

	<listitem><para>Companies interested in promoting an evolving
	standard, which can become the core of other companies' commercial
	products, should be wary of the GPL. Regardless of the license
	used, the resulting software will usually devolve to whoever
	actually makes the majority of the engineering changes and most
	understands the state of the system. The GPL simply adds
	additional legal friction to the result.</para></listitem>

	<listitem><para>Large companies, in which Open Source code is
	developed, should be aware that programmers appreciate Open Source
	because it leaves the software available to the employee when
	they change employers. Some companies encourage this behavior as
	an employment perk, especially when the software involved is not
	directly strategic. It is, in effect, a front-loaded retirement
	benefit with potential lost opportunity costs but no direct
	costs. Encouraging employees to work for peer acclaim outside
	the company is a cheap portable benefit a company can sometimes
	provide with near zero downside.</para></listitem>

	<listitem><para>Small companies with software projects vulnerable
	to orphaning should attempt to use the BSD license when
	possible. Companies of all sizes should consider forming such
	Open Source projects when it is to their mutual advantage to
	maintain the minimal legal and organization overheads associated
	with a true BSD-style Open Source project.</para></listitem>

	<listitem><para>Non-profits should participate in Open Source
	projects when possible. To minimize software engineering
	problems, such as mixing code under different licenses,
	BSD-style licenses should be encouraged. Being leery of the GPL
	should particularly be the case with non-profits that interact
	with the developing world. In some locales where application of
	law becomes a costly exercise, the simplicity of the new BSD
	license, as compared to the GPL, may be of considerable
	advantage.</para></listitem>

	</itemizedlist>

	</sect1>

	<sect1 id="conclusion">
	<title>Conclusion</title>

	<para>In contrast to the GPL, which is designed to prevent the
	proprietary commercialization of Open Source code, the BSD license
	places minimal restrictions on future behavior. This allows BSD
	code to remain Open Source or become integrated into commercial
	solutions, as a project's or company's needs change. In other
	words, the BSD license does not become a legal time-bomb at any
	point in the development process.</para>

	<para>In addition, since the BSD license does not come with the legal
	complexity of the GPL or LGPL licenses, it allows developers and
	companies to spend their time creating and promoting good code
	rather than worrying if that code violates licensing.</para>

	</sect1>

	<sect1 id="addenda">
	<title>Addenda</title>

	<programlisting>
	[1] http://www.gnu.org/licenses/gpl.html

	[2] http://archives.cnn.com/2000/TECH/computing/03/28/cyberpatrol.mirrors/

	[3] Open Source: the Unauthorized White Papers, Donald K. Rosenberg, IDG Books,
	2000. Quotes are from page 114, ``Effects of the GNU GPL''.

	[4] In the "What License to Use?" section of
	http://www.oreilly.com/catalog/opensources/book/brian.html

	This whitepaper is a condensation of an original work available at
	http://alumni.cse.ucsc.edu/~brucem/open_source_license.htm

	</programlisting>

	</sect1></article>
	Index: projects/entities/en_US.ISO8859-1/articles/casestudy-argentina.com/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/casestudy-argentina.com/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/casestudy-argentina.com/article.xml (revision 41355)
	@@ -1,328 +1,327 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	]>

	<article lang='en'>
	<title>Argentina.com : A Case Study</title>
	<articleinfo>

	<authorgroup>
	<author>
	<firstname>Carlos</firstname>
	<surname>Horowicz</surname>
	<affiliation>
	<address><email>ch@argentina.com</email>
	</address>
	</affiliation>
	</author>
	</authorgroup>

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	- &tm-attrib.cvsup;
	&tm-attrib.intel;
	&tm-attrib.xfree86;
	&tm-attrib.general;
	</legalnotice>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>
	</articleinfo>

	<sect1 id="overview">
	<title>Overview</title>

	<para>Argentina.Com is an Argentine ISP with a small infrastructure
	of fewer than 15 employees and whose primary source of income
	originates in the free dialup business. It began operation in the
	year 2000 with barely one server for mail and chat.</para>

	<para>It has since grown to a market presence in the Argentine free
	dialup market of 4.5 billion minutes annually. Its most popular
	product provides nearly half a million users with free e-mail with
	webmail, POP3 and SMTP access, and 300M disk space. Towards the
	end of 2002 there were around 50,000 mail users. After two and a
	half years of re-engineering and consistent technical improvements
	this ISP has grown by a factor of 3 in terms of billing, and by a
	factor of 10 with regard to the mail user base.</para>

	<para>Our competitors in the Argentine market of free dialup include
	Fullzero which is owned by the Clarin Media Group, Alternativa
	Gratis, and Tutopia which is funded by IFX and promoted by
	Hotmail. Some of these large corporate competitors started their
	free dialup business with multi-million dollar investments and
	aggressive television and Internet ad campaigns. Argentina.Com
	does not rely on advertising like these other larger corporations.
	It has climbed to the fourth position and to an 8% market share
	during the last two years thanks to superior quality of service.</para>

	<para>In Argentina and Latin America in general people who do not
	have computers at home go to so called <quote>Locutorios</quote>
	(Internet Centers), where for a few pesos they can use a computer
	connected to the Internet and usually read and write emails
	through popular webmails like Hotmail, Yahoo or
	Argentina.Com.</para>

	<para>Due to limited financial resources, Argentina.Com made the
	decision to invest in a new email system instead of publicity in
	the media. This strategic decision opens the door to a future
	business in the corporate and paid email arena.</para>
	</sect1>

	<sect1 id="challenge">
	<title>The Challenge</title>

	<para>The main challenge for Argentina.Com is to achieve a dialup
	uptime of at least 99.95%, or less than 5 hours yearly
	downtime. Due to the high rotation and volatility in this
	business, things have to work correctly so the user does not switch
	-voluntarily or not- the dialup provider or the number he calls to
	connect. The dialup business involves a support structure to deal
	with the Telcos about telephony problems and quality of service,
	plus a technical structure where latency and packet-loss should be
	minimized due to the UDP nature of Radius and DNS, and where
	recursive DNS should always be available.</para>

	<para>This also implies having a high uptime in the POP3 and SMTP
	services, and in the webmail. For POP3 and SMTP we estimated the
	need for an uptime equal to the one for dialup, whereas for the
	webmail we could live with 99.5% which means around two days of
	yearly downtime.</para>

	<para>We decided to migrate the email to a proprietary, opensource
	architecture which should be horizontally scalable, and whose
	antivirus and antispam infrastructure should support more than
	just one type of mailstore or back-end.</para>

	<para>The rough competition in the free email market, mostly due to
	the recent improvements introduced by Hotmail, Yahoo and Gmail,
	made it necessary to design the new system with at least 300M user
	disk space, but at a cost lower than 3 US dollars per GB with some
	degree of redundancy. Bear in mind that rackmountable hardware is
	hard to find in Argentina, and is between 30 and 40% more
	expensive than in the US. Our total budget for equipment
	acquisition in two years was 75,000 USD, which is only a fraction
	of our direct competitors' investments.</para>

	<para>With regard to the antispam service, it became necessary to
	develop a product that could compete with the systems offered by
	the big ones. Given the hostile conditions imposed by the
	existence of spam (dictionary attacks, spams with high degree of
	obfuscation and refinement, phishing, trojans, mail-bombs, etc.)
	it becomes very difficult to achieve an excellent uptime while
	repelling attacks. One must also be careful that the user does not
	lose mails because of false positives in the classification
	strategy, that he does not become flooded with spam or spam
	notifications, and dangerous mails do not make it through to his
	mailbox. In addition, the technical infrastructure for spam
	classification should not introduce noticeable delays in the
	delivery of mails. Finally, the mail system has to be protected
	from spammers who might misuse it to send spam.</para>

	<para>The opensource paradigm tends to require hiring large teams of
	system administrators, operators and programmers who apply
	patches, correct bugs and integrate platforms. The opposed
	paradigm is also costly because of expensive software licences,
	the need for increasingly expensive hardware and a large support
	staff. So the challenge was to find the right mixture for scarce
	human and monetary resources, high stability and predictability,
	and quick and reliable deployment. In Buenos Aires, well-trained
	Computer Science professionals are hard to find, most of them live
	and work abroad, while the remaining have stable jobs either at
	the government or big companies.</para>

	</sect1>

	<sect1 id="freebsd">
	<title>The FreeBSD solution</title>

	<sect2 id="freebsd-intro">
	<title>Introduction</title>

	<para>At the beginning of 2003 we had a CriticalPath mail system
	running on Solaris x86 plus a Redhat box for SMTP, Radius and
	DNS. The DNS and Radius services were constantly down and we
	were struggling with huge mail queues. There was an attempt to
	install CriticalPath for Linux into Redhat on an Intel box with
	a Megaraid card, but the disk latency was enormous and the mail
	application never really worked.</para>

	<para>The first step depicted towards the "FreeBSD solution"
	consisted in migrating this hardware and commercial software to
	FreeBSD 4.8 with Linux emulation.</para>
	</sect2>

	<sect2 id="freebsd-choice">
	<title>The choice of FreeBSD</title>

	<para>The FreeBSD operating system is well-known for its great
	stability, plus its pragmatism and common sense to put
	applications on-line thanks to its excellent <ulink
	url="http://www.FreeBSD.org/ports">Ports System</ulink>. We
	consider its <ulink url="http://www.FreeBSD.org/releng">release
	engineering process</ulink> to be easily understandable, while
	the users' community at the official mailing lists keeps a
	polite and civilized style when it comes to asking for support
	or reading other people's problems and solutions.</para>

	<para>Another important feature is quick deployment. Fortunately,
	we could state our OS install policy around FreeBSD's great
	out-of-the-box capability. In a small company you sometimes need
	to run to a Datacenter and quickly setup a server for some
	service. In the last two years, Argentina.Com acquired around
	forty servers, most of them Pentium IV but also several
	double-Xeons and a few double-Opterons to be co-located in the
	Datacenters where we have dialup and hosting operation
	contracts. All of them run FreeBSD, ranging from 4.8 (there are
	a couple with two years uptime and zero trouble) til currently
	6.0-BETA2.</para>

	<para>The general policy for the operating system is to try to
	bring all servers periodically to the stable code branch by
	using <literal>RELENG_4</literal>, <literal>RELENG_5</literal>
	and now <literal>RELENG_6</literal>. This regularity lets us be
	more prepared regarding possible exploits at the operating
	system or base software level, especially in web servers.</para>

	</sect2>

	<sect2 id="freebsd-engineer">
	<title>Basic re-engineering</title>

	<para>The first re-engineering step was to put in place two
	FreeBSD 4.8 boxes whose unique task was to be authoritative DNS
	for all our domains. The chosen software was Bind9. Those boxes
	were co-located in different datacenters, taking care that there
	was good latency between them to avoid zone transfer problems,
	and making it possible to deal with TTLs between 60 and 600
	seconds to have quicker response in case of trouble.</para>

	<para>Second step was to deploy two more boxes of the same class,
	again in different Datacenters, to only deal with Radius and
	recursive DNS. The Network Access Servers at the Telcos were
	configured to send Radius Authorization and Accounting to those
	servers, and to assign these recursive DNSs to dialup users.</para>

	<para>The third <quote>golden rule</quote> never to put SMTP
	incoming and outgoing in the same servers. We deployed separate
	FreeBSD boxes with postfix for incoming and outgoing mail.</para>

	</sect2>

	<sect2 id="freebsd-email">
	<title>Email migration</title>

	<para>The email migration required careful planning due to the
	fact that we were going to migrate both mail front and
	back-ends. We first built a perimetral antispam and antivirus
	system in FreeBSD 4.x and 5.x based on postfix, amavisd-new,
	clamav and SpamAssassin. These systems were to deliver mails to
	both the old and the new system until the new back-end was in
	place. In the meantime, we added small FreeBSD NFS boxes to
	increase CriticalPath's mailspool, without any problem.</para>

	<para>At the frontline of incoming mail, we put in place several
	MXs of the Argentina.com domain to filter dictionary attacks
	(attempts to forward mail to nonexistent users) as well as a
	black-list derived from SURBL that resulted in almost no false
	positives. The mails are then multiplexed to a cluster of
	double-Xeons and double-Opterons where we run amavisd-new with
	MySQL based white and black-listing. We discarded the use of
	Bayes and Autowhitelisting at the global level because of great
	quantities of false positives and false negatives. We instead
	defined a few spam levels going from the least to the most
	tolerant, each one with cutoff or discard levels. Every email
	with a score below the one associated with the selected spam
	tolerance goes to the user's Inbox. Emails between this level
	and the cutoff level go to a user's folder named Spam, and those
	above the cutoff level get discarded because it is a very obvious
	spam. For the sake of simplicity, we transparently associated
	the use of the Address Book with the antispam system, so that
	every personal contact gets automatically whitelisted.</para>

	<para>With the introduction of Spamassassin 3.x, the DNS traffic
	to query global blacklists grew considerably, so we signed
	agreements with SpamCop, Spamhaus and SURBL to install public
	mirrors of their databases in our FreeBSD equipment. Thanks to
	these mirrors that cost us between 1 and 2Mbps in traffic, we
	were able to dramatically cut down Spamassassin latency.</para>

	<para>At the 3rd level there is the delivery to the maildrops. As
	soon as we started building a new Cyrus-Imap back-end with MySQL
	authentication, we needed to multiplex incoming mail to users in
	both old and new maildrop formats. Finally, we managed to
	migrate hundreds of thousands of mailspools to the new Cyrus
	architecture using a great tool named imapsync, which is
	directly installable from ports. We also put perdition, a POP3
	and IMAP proxy, in the middle to assure a transparent migration
	and distribution of mailboxes across several servers. Briefly,
	all information of where a user's maildrop is located resides in
	MySQL, and is being used by all software pieces in the
	chain.</para>

	<para>With regard to the hardware for disk space, we currently use
	seven Cyrus-Imap loaded FreeBSD boxes with diverse hardware. The
	biggest are Pentium IV with 4G of RAM and 3ware cards in chassis
	with 12 hotswappable bays, organized in 3 RAID-5 units of 1
	Terabyte each. The 3ware software sends you en email whenever
	the RAID is degraded -mostly because of a failing disk- and lets
	you rebuild the RAID with everything up and running. We use
	smartmontools in the cases where we have less redundancy, to
	have immediate alerts of disks with temperature problems or
	failing selftests.</para>

	<para>As webmail software, we chose a commercial product named
	Atmail, which is available with perl sources and utilizes
	mod_perl. Under FreeBSD it is extremely easy to deal with perl
	modules, you do not even need to use the CPAN shell, you just
	have to choose the right port and run "make install". After
	several months of integration work, we integrated the
	Client-only version of Atmail that talks IMAP with our
	back-ends. We had to modify some parts of the code to adapt the
	product to our massive free environment, and to our antispam and
	antivirus perimeter, in addition to our specific customizations
	and translations.</para>

	</sect2>

	<sect2 id="freebsd-web">
	<title>Web migration</title>

	<para>With the adoption of FreeBSD, there was almost no additional
	effort necessary to setup a working Apache, PHP and MySQL
	environment in minutes. Even the upgrades from PHP4 to PHP5 were
	painless. The ports system was again extremely useful in these
	cases, and permitted us to do things like compress text and html
	contents in Apache with just a few lines of documentation. In
	addition, we have experienced excellent performance and
	rock-solid stability and uptime.</para>
	</sect2>

	</sect1>

	<sect1 id="results">
	<title>Results</title>

	<para>We managed to deploy a FreeBSD based email architecture that
	is horizontally scalable, using 3 Terabyte Intel based storage
	servers at a current cost of 3 dollars per Gigabyte with
	redundancy.</para>

	<para>The great stability achieved enabled Argentina.Com to explore
	other fields like hosting for resellers and housing with presence
	in three Argentine Datacenters.</para>

	<para>We offer now also corporate dialup for roaming users in
	Argentina and Peru thanks to our presence and contracts with most
	Telcos. Among our indirect customers, there are major American
	companies like Ford, Exxon and Reuters. We now run the free dialup
	business in Brazil, Chile, Colombia and Panama as well.</para>
	</sect1>

	</article>


	Index: projects/entities/en_US.ISO8859-1/articles/committers-guide/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/committers-guide/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/committers-guide/article.xml (revision 41355)
	@@ -1,4477 +1,4480 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	]>

	<article lang='en'>
	<articleinfo>
	<title>Committer's Guide</title>

	<corpauthor>The &os; Documentation Project</corpauthor>

	<copyright>
	<year>1999</year>
	<year>2000</year>
	<year>2001</year>
	<year>2002</year>
	<year>2003</year>
	<year>2004</year>
	<year>2005</year>
	<year>2006</year>
	<year>2007</year>
	<year>2008</year>
	<year>2009</year>
	<year>2010</year>
	<year>2011</year>
	<year>2012</year>
	<year>2013</year>
	<holder>The FreeBSD Documentation Project</holder>
	</copyright>

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	&tm-attrib.coverity;
	- &tm-attrib.cvsup;
	&tm-attrib.ibm;
	&tm-attrib.intel;
	&tm-attrib.sparc;
	&tm-attrib.general;
	</legalnotice>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>

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

	<para>Almost all FreeBSD developers have commit rights to one or
	more repositories. However, a few developers do not, and some
	of the information here applies to them as well. (For
	instance, some people only have rights to work with the
	Problem Report database). Please see <xref
	linkend="non-committers"/> for more information.</para>

	<para>This document may also be of interest to members of the
	FreeBSD community who want to learn more about how the project
	works.</para>
	</abstract>
	</articleinfo>

	<sect1 id="admin">
	<title>Administrative Details</title>

	<informaltable frame="none" orient="port" pgwide="1">
	<tgroup cols="2">
	<colspec colwidth="20*"/>
	<colspec colwidth="80*"/>
	<tbody>
	<row>
	<entry><emphasis>Login Methods</emphasis></entry>
	<entry>&man.ssh.1;, protocol 2 only</entry>
	</row>

	<row>
	<entry><emphasis>Main Shell Host</emphasis></entry>
	<entry><hostid
	role="fqdn">freefall.FreeBSD.org</hostid></entry>
	</row>

	<row>
	<entry><emphasis><literal>src/</literal> Subversion
	Root</emphasis></entry>
	<entry>
	<literal>svn+ssh://</literal><hostid
	role="fqdn">svn.FreeBSD.org</hostid><filename>/base</filename>
	(see also <xref linkend="subversion-primer"/>).</entry>
	</row>
	<row>
	<entry><emphasis><literal>doc/</literal> Subversion
	Root</emphasis></entry>
	<entry>
	<literal>svn+ssh://</literal><hostid
	role="fqdn">svn.FreeBSD.org</hostid><filename>/doc</filename>
	(see also <xref linkend="subversion-primer"/>).</entry>
	</row>

	<row>
	<entry><emphasis><literal>ports/</literal> Subversion
	Root</emphasis></entry>
	<entry>
	<literal>svn+ssh://</literal><hostid
	role="fqdn">svn.FreeBSD.org</hostid><filename>/ports</filename>
	(see also <xref linkend="subversion-primer"/>).</entry>
	</row>

	<row>
	<entry><emphasis>Internal Mailing Lists</emphasis></entry>

	<entry>developers (technically called all-developers),
	doc-developers, doc-committers, ports-developers,
	ports-committers, src-developers, 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-reports</filename>
	on the <hostid role="domainname">FreeBSD.org</hostid>
	cluster.
	</entry>
	</row>

	<row>
	<entry><emphasis>Ports Management Team monthly
	reports</emphasis></entry>
	<entry><filename>/home/portmgr/public/monthly-reports</filename>
	on the <hostid role="domainname">FreeBSD.org</hostid>
	cluster.</entry>
	</row>

	<row>
	<entry><emphasis>Noteworthy <literal>src/</literal> SVN
	Branches</emphasis></entry>

	<entry>
	<literal>stable/7</literal> (7.X-STABLE),
	<literal>stable/8</literal> (8.X-STABLE),
	<literal>stable/9</literal> (9.X-STABLE),
	<literal>head</literal> (-CURRENT)
	</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>It is required that you use &man.ssh.1;
	to connect to the project hosts.
	If you do
	not know anything about &man.ssh.1;, please see
	<xref linkend="ssh.guide"/>.</para>

	<para>Useful links:</para>

	<itemizedlist>
	<listitem><para><ulink url="&url.base;/internal/">FreeBSD
	Project Internal Pages</ulink></para></listitem>

	<listitem><para><ulink
	url="&url.base;/internal/machines.html">FreeBSD Project
	Hosts</ulink></para></listitem>

	<listitem><para><ulink
	url="&url.base;/administration.html">FreeBSD Project
	Administrative Groups</ulink></para></listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="committer.types">
	<title>Commit Bit Types</title>

	<para>The FreeBSD 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" pgwide="1">
	<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/, 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="subversion-primer">
	<title>Subversion Primer</title>

	<para>It is assumed that you are already familiar with the basic
	operation of the version control systems in use. Traditionally
	this was CVS. Subversion is used for the <literal>src</literal>
	tree as of May 2008, the <literal>doc/www</literal> tree as of
	May 2012 and the <literal>ports</literal> tree as of July 2012.
	</para>

	<para><ulink url="http://wiki.freebsd.org/SubversionMissing">There
	is a list of things missing in Subversion when compared to CVS
	</ulink>. The notes at <ulink
	url="http://people.freebsd.org/~peter/svn_notes.txt"></ulink>
	might also be useful.</para>

	<sect2 id="svn-intro">
	<title>Introduction</title>

	<para>The &os; source repository switched from
	<acronym>CVS</acronym> to Subversion on May 31st, 2008. The
	first real <acronym>SVN</acronym> commit is
	<emphasis>r179447</emphasis>.</para>

	<para>The &os; <literal>doc/www</literal> repository switched
	from <acronym>CVS</acronym> to Subversion on May 19th, 2012.
	The first real <acronym>SVN</acronym> commit is
	<emphasis>r38821</emphasis>.</para>

	<note>
	<para>Part of the <literal>doc/www</literal>
	<acronym>CVS</acronym> to <acronym>SVN</acronym> conversion
	included an infrastructural change to the build process.
	The most notable change is the location of the
	&os; website <literal>www</literal> tree, which has
	been moved from
	<literal>www/<replaceable>lang</replaceable>/</literal> to
	<literal>head/<replaceable>lang</replaceable>/htdocs/</literal>.</para>
	</note>

	<para>The &os; <literal>ports</literal> repository switched
	from <acronym>CVS</acronym> to Subversion on July 14th, 2012.
	The first real <acronym>SVN</acronym> commit is
	<emphasis>r300894</emphasis>.</para>

	<para>There are mechanisms in place to automatically merge
	- changes back from the Subversion repository to the
	- <acronym>CVS</acronym> one, so regular users should not notice
	- a difference, however developers most certainly will.</para>
	+ changes back from the Subversion <literal>src</literal>
	+ repository to the <acronym>CVS</acronym> repository for
	+ some &os; branches (<literal>releng/6</literal> through
	+ <literal>releng/9</literal>), however this is purely to
	+ support pre-existing end-user installs and should not be
	+ relied upon, recommended or advertised. Future branches
	+ will not be exported to CVS at all. The
	+ <literal>ports</literal> repository was exported to CVS
	+ for a period of time to aid end user migration, but as of
	+ 28th February 2013 is no longer exported.</para>

	<para>Subversion is not that different from
	<acronym>CVS</acronym> when it comes to daily use, but there
	are differences. Subversion has a number of features that
	should make developers' lives easier. The most important
	advantage to Subversion (and the reason why &os; switched) is
	that it handles branches and merging much better than CVS
	does. Some of the principal differences are:</para>

	<itemizedlist>
	<listitem>
	<para>Commits are atomic.</para>
	</listitem>
	<listitem>
	<para>Revision numbers apply across the repository—all
	files that were modified in the same commit have the same
	revision number.</para>
	</listitem>
	<listitem>
	<para>Branching and tagging are namespace operations.</para>
	</listitem>
	<listitem>
	<para>Directories are versioned.</para>
	</listitem>
	<listitem>
	<para>Files and directories can have arbitrary, versioned
	metadata attached to them.</para>
	</listitem>
	<listitem>
	<para>Files and directories can be copied, with full history
	tracking.</para>
	</listitem>
	<listitem>
	<para>No more contortions due to <acronym>CVS</acronym>
	weakness such as applying &man.patch.1; files at compile
	time in order to avoid touching vendor branch code.</para>
	</listitem>
	<listitem>
	<para>No more repo-copies.</para>
	</listitem>
	</itemizedlist>

	<para>Subversion can be installed from the &os; Ports
	Collection, by issuing the following commands:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/devel/subversion</userinput>
	&prompt.root; <userinput>make clean install</userinput></screen>
	</sect2>

	<sect2 id="svn-getting-started">
	<title>Getting Started</title>

	<para>There are a few ways to obtain a working copy of the tree
	from Subversion. This section will explain them.</para>

	<sect3>
	<title>Direct Checkout</title>

	<para>The first is to check out directly from the main
	repository. For the <literal>src</literal> tree,
	use:</para>

	<screen>&prompt.user; <userinput>svn checkout svn+ssh://svn.freebsd.org/base/head /usr/src</userinput></screen>

	<para>For the <literal>doc</literal> tree, use:</para>

	<screen>&prompt.user; <userinput>svn checkout svn+ssh://svn.freebsd.org/doc/head /usr/doc</userinput></screen>

	<para>For the <literal>ports</literal> tree, use:</para>

	<screen>&prompt.user; <userinput>svn checkout svn+ssh://svn.freebsd.org/ports/head /usr/ports</userinput></screen>

	<note>
	<para>Though the remaining examples in this document are
	written with the workflow of working with the
	<literal>src</literal> tree in mind, the underlying
	concepts are the same for working with the
	<literal>doc</literal> and the <literal>ports</literal>
	tree.
	Ports related Subversion operations are listed in
	<xref linkend="ports"/>.</para>
	</note>

	<para>The above command will check out a
	<literal>CURRENT</literal> source tree as <filename
	class="directory"><replaceable>/usr/src/</replaceable></filename>,
	which can be any target directory on the local filesystem.
	Omitting the final argument of that command causes the
	working copy, in this case, to be named <quote>head</quote>,
	but that can be renamed safely.</para>

	<para><literal>svn+ssh</literal> means the
	<acronym>SVN</acronym> protocol tunnelled over
	<acronym>SSH</acronym>. The name of the server is
	<literal>svn.freebsd.org</literal>, <literal>base</literal>
	is the path to the repository, and <literal>head</literal>
	is the subdirectory within the repository.</para>

	<para>If your &os; login name is different from your login
	name on your local machine, you must either include it in
	the <acronym>URL</acronym> (for example
	<literal>svn+ssh://jarjar@svn.freebsd.org/base/head</literal>),
	or add an entry to your <filename>~/.ssh/config</filename>
	in the form:</para>

	<programlisting>Host svn.freebsd.org
	User jarjar</programlisting>

	<para>This is the simplest method, but it's hard to tell just
	yet how much load it will place on the repository.
	Subversion is much faster than <acronym>CVS</acronym>,
	however.</para>

	<note>
	<para>The <command>svn diff</command> does not require
	access to the server as <acronym>SVN</acronym> stores a
	reference copy of every file in the working copy. This,
	however, means that Subversion working copies are very
	large in size.</para>
	</note>
	</sect3>

	<sect3>
	<title>Checkout from a Mirror</title>

	- <para>You can check out a working copy from a mirror by simply
	+ <para>Check out a working copy from a mirror by
	substituting the mirror's <acronym>URL</acronym> for
	<literal>svn+ssh://svn.freebsd.org/base</literal>. This can
	- be an official mirror or a mirror you maintain yourself
	- using <command>svnsync</command> or similar.</para>
	+ be an official mirror or a mirror maintained by
	+ using <command>svnsync</command>.</para>

	<para>There is a serious disadvantage to this method: every
	time something is to be committed, a <command>svn switch
	--relocate</command> to the master repository has to be
	done, remembering to <command>svn switch</command> back to
	the mirror after the commit. Also, since <command>svn
	switch</command> only works between repositories that have
	the same UUID, some hacking of the local repository's UUID
	has to occur before it is possible to start using it.</para>

	- <para>Unlike with <acronym>CVS</acronym> and
	- <acronym>csup</acronym>, the hassle of a local
	+ <para>Unlike with <acronym>CVS</acronym>,
	+ the hassle of a local
	<command>svnsync</command> mirror probably is not worth it
	unless the network connectivity situation or other factors
	demand it. If it is needed, see the end of this chapter for
	information on how to set one up.</para>
	</sect3>

	<sect3 id="subversion-primer-base-layout">
	<title><literal>RELENG_*</literal> Branches and General
	Layout</title>

	<para>In <literal>svn+ssh://svn.freebsd.org/base</literal>,
	<emphasis>base</emphasis> refers to the source tree.
	Similarly, <emphasis>ports</emphasis> refers to the ports
	tree, and so on. These are separate repositories with their
	own change number sequences, access controls and commit
	mail.</para>

	<para>For the base repository, HEAD refers to the -CURRENT
	tree. For example, <filename>head/bin/ls</filename> is what
	would go into <filename>/usr/src/bin/ls</filename> in a
	- release. Some other key locations are:</para>
	+ release. Some key locations are:</para>

	<itemizedlist>
	<listitem>
	+ <para><emphasis>/head/</emphasis>
	+ which corresponds to <literal>HEAD</literal>, also known as
	+ <literal>-CURRENT</literal>.
	+ </para>
	+ </listitem>
	+ <listitem>
	<para><emphasis>/stable/<replaceable>n</replaceable></emphasis>
	which corresponds to
	<literal>RELENG_<replaceable>n</replaceable></literal>.</para>
	</listitem>
	<listitem>
	<para><emphasis>/releng/<replaceable>n.n</replaceable></emphasis>
	which corresponds to
	<literal>RELENG_<replaceable>n_n</replaceable></literal>.</para>
	</listitem>
	<listitem>
	<para><emphasis>/release/<replaceable>n.n.n</replaceable></emphasis>
	which corresponds to
	<literal>RELENG_<replaceable>n_n_n</replaceable>_RELEASE</literal>.</para>
	</listitem>
	<listitem>
	<para><emphasis>/vendor*</emphasis> is the vendor branch
	import work area. This directory itself does not
	contain branches, however its subdirectories do. This
	contrasts with the <emphasis>stable</emphasis>,
	<emphasis>releng</emphasis> and
	<emphasis>release</emphasis> directories.</para>
	</listitem>
	<listitem>
	<para><emphasis>/projects</emphasis> and
	<emphasis>/user</emphasis> feature a branch work area,
	like in Perforce. As above, the
	<emphasis>/user</emphasis> directory does not contain
	branches itself.</para>
	</listitem>
	</itemizedlist>
	</sect3>

	<sect3>
	<title>&os; Documentation Project Branches and
	Layout</title>

	<para>In <literal>svn+ssh://svn.freebsd.org/doc</literal>,
	<emphasis>doc</emphasis> refers repository root of the
	source tree.</para>

	<para>In general, most &os; Documentation Project work will be
	done within the <filename>head/</filename> branch of the
	source tree.</para>

	<para>&os; documentation is written and/or translated to
	various languages, each of which within a separate
	directory within the <filename>head/</filename>
	branch.</para>

	<para>Each translation set contains several subdirectories for
	the various parts of the &os; Documentation Project. A few
	noteworthy directories are:</para>

	<itemizedlist>
	<listitem>
	<para><emphasis>/articles/</emphasis> contains the source
	code for articles written by various &os;
	contributors.</para>
	</listitem>
	<listitem>
	<para><emphasis>/books/</emphasis> contains the source
	code for the different books, such as the
	&os; Handbook.</para>
	</listitem>
	<listitem>
	<para><emphasis>/htdocs/</emphasis> contains the source
	code for the &os; website.</para>
	</listitem>
	</itemizedlist>
	</sect3>

	<sect3>
	<title>&os; Ports Tree Branches and Layout</title>

	<para>In <literal>svn+ssh://svn.freebsd.org/ports</literal>,
	<emphasis>ports</emphasis> refers repository root of the
	ports tree.</para>

	<para>In general, most &os; port work will be done within
	the <filename>head/</filename> branch of the ports tree
	which is the actual ports tree used to install software.
	Some other key locations are:</para>

	<itemizedlist>
	<listitem>
	<para><emphasis>/branches/RELENG_<replaceable>n_n_n
	</replaceable></emphasis> which corresponds to
	<literal>RELENG_<replaceable>n_n_n</replaceable></literal>
	is used to merge back security updates in preparation
	for a release.</para>
	</listitem>
	<listitem>
	<para><emphasis>/tags/RELEASE_<replaceable>n_n_n</replaceable></emphasis>
	which corresponds to <literal>RELEASE_<replaceable>n_n_n</replaceable></literal>
	represents a release tag of the ports tree.</para>
	</listitem>
	<listitem>
	<para><emphasis>/tags/RELEASE_<replaceable>n</replaceable>_EOL</emphasis>
	represents the end of life tag of a specific &os;
	branch.</para>
	</listitem>
	</itemizedlist>
	</sect3>
	</sect2>

	<sect2 id="svn-daily-use">
	<title>Daily Use</title>

	<para>This section will explain how to perform common day-to-day
	operations with Subversion. There should be no difference
	between <acronym>SVN</acronym> and <acronym>SVK</acronym> in
	daily use, except for the revision renumbering mentioned
	earlier.</para>

	<sect3>
	<title>Help</title>

	<para>Both <acronym>SVN</acronym> and <acronym>SVK</acronym>
	have built in help documentation. It can be accessed by
	typing the following command:</para>

	<screen>&prompt.user; <userinput>svn help</userinput></screen>
	</sect3>

	<sect3>
	<title>Checkout</title>

	<para>As seen earlier, to check out the &os; head
	branch:</para>

	<screen>&prompt.user; <userinput>svn checkout svn+ssh://svn.freebsd.org/base/head /usr/src</userinput></screen>

	<para>At some point, more than just <literal>HEAD</literal>
	will probably be useful, for instance when merging changes
	to stable/7. Therefore, it may be useful to have a partial
	checkout of the complete tree (a full checkout would be very
	painful).</para>

	<para>To do this, first check out the root of the
	repository:</para>

	<screen>&prompt.user; <userinput>svn checkout --depth=immediates svn+ssh://svn.freebsd.org/base</userinput></screen>

	<para>This will give <literal>base</literal> with all the
	files it contains (at the time of writing, just
	<filename>ROADMAP.txt</filename>) and empty subdirectories
	for <literal>head</literal>, <literal>stable</literal>,
	<literal>vendor</literal> and so on.</para>

	<para>Expanding the working copy is possible. Just change the
	depth of the various subdirectories:</para>

	<screen>&prompt.user; <userinput>svn up --set-depth=infinity base/head</userinput>
	&prompt.user; <userinput>svn up --set-depth=immediates base/release base/releng base/stable</userinput></screen>

	<para>The above command will pull down a full copy of
	<literal>head</literal>, plus empty copies of every
	<literal>release</literal> tag, every
	<literal>releng</literal> branch, and every
	<literal>stable</literal> branch.</para>

	<para>If at a later date merging to
	<literal>7-STABLE</literal> is required, expand the working
	copy:</para>

	<screen>&prompt.user; <userinput>svn up --set-depth=infinity base/stable/7</userinput></screen>

	<para>Subtrees do not have to be expanded completely. For
	instance, expanding only <literal>stable/7/sys</literal> and
	then later expand the rest of
	<literal>stable/7</literal>:</para>

	<screen>&prompt.user; <userinput>svn up --set-depth=infinity base/stable/7/sys</userinput>
	&prompt.user; <userinput>svn up --set-depth=infinity base/stable/7</userinput></screen>

	<para>Updating the tree with <command>svn update</command>
	will only update what was previously asked for (in this
	case, <literal>head</literal> and
	<literal>stable/7</literal>; it will not pull down the whole
	tree.</para>

	<note>
	<para>Decreasing the depth of a working copy is not
	possible.</para>
	</note>
	</sect3>

	<sect3>
	<title>Anonymous Checkout</title>

	<para>It is possible to anonymously check out the &os;
	repository with Subversion. This will give access to a
	read-only tree that can be updated, but not committed
	- to. To do this, use one of the following commands:</para>
	+ to. To do this, use the following command:</para>

	- <screen>&prompt.user; <userinput>svn co svn://svn.freebsd.org/base/head /usr/src</userinput>
	-&prompt.user; <userinput>svn co http://svn.freebsd.org/base/head /usr/src</userinput></screen>
	+ <screen>&prompt.user; <userinput>svn co <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/base/head /usr/src</userinput></screen>
	+
	+ <para>Select the closest mirror and verify the mirror server
	+ certificate from the list of <ulink
	+ url="&url.books.handbook;/svn-mirrors.html">Subversion
	+ mirror sites</ulink>.</para>
	</sect3>

	<sect3>
	<title>Updating the Tree</title>

	<para>To update a working copy to either the latest revision,
	or a specific revision:</para>

	<screen>&prompt.user; <userinput>svn update</userinput>
	&prompt.user; <userinput>svn update -<replaceable>r12345</replaceable></userinput></screen>
	</sect3>

	<sect3>
	<title>Status</title>

	<para>To view the local changes that have been made to the
	working copy:</para>

	<screen>&prompt.user; <userinput>svn status</userinput></screen>

	<para>To show local changes and files that are out-of-date do:</para>

	<screen>&prompt.user; <userinput>svn status --show-updates</userinput></screen>
	</sect3>

	<sect3>
	<title>Editing and Committing</title>

	<para>Unlike Perforce,
	<acronym>SVN</acronym> and <acronym>SVK</acronym> do not
	need to be told in advance about file editing.</para>

	<para><command>svn commit</command> works like the equivalent
	<acronym>CVS</acronym> command. To commit all changes in
	the current directory and all subdirectories:</para>

	<screen>&prompt.user; <userinput>svn commit</userinput></screen>

	<para>To commit all changes in, for example, <filename
	class="directory"><replaceable>lib/libfetch/</replaceable></filename>
	and <filename
	class="directory"><replaceable>usr/bin/fetch/</replaceable></filename>
	in a single operation:</para>

	<screen>&prompt.user; <userinput>svn commit <replaceable>lib/libfetch</replaceable> <replaceable>usr/bin/fetch</replaceable></userinput></screen>

	<para>There is also a commit wrapper for the ports tree
	to handle the properties and sanity checking your
	changes:</para>

	<screen>&prompt.user; <userinput>/usr/ports/Tools/scripts/psvn commit
	</userinput></screen>
	</sect3>

	<sect3 id="subversion-primer-add-remove">
	<title>Adding and Removing Files</title>

	<note>
	<para>Before adding files, get a copy of <ulink
	url="http://people.freebsd.org/~peter/auto-props.txt">auto-props.txt</ulink>
	(there is also a <ulink
	url="http://people.freebsd.org/~beat/cvs2svn/auto-props.txt">
	ports tree specific version</ulink>)
	and add it to <filename>~/.subversion/config</filename>
	according to the instructions in the file. If you added
	something before you've read this, you may use
	<command>svn rm --keep-local</command> for just added
	files, fix your config file and re-add them again. The
	initial config file is created when you first run a svn
	command, even something as simple as <command>svn
	help</command>.
	</para>
	</note>

	<para>Files are added to a
	<acronym>SVN</acronym> repository with <command>svn
	add</command>. To add a file named
	<emphasis>foo</emphasis>, edit it, then:</para>

	<screen>&prompt.user; <userinput>svn add <replaceable>foo</replaceable></userinput></screen>

	<para>Files can be removed with <command>svn
	remove</command>:</para>

	<screen>&prompt.user; <userinput>svn remove <replaceable>foo</replaceable></userinput></screen>

	<para>Subversion does not require <command>rm</command>ing the
	file before <command>svn rm</command>ing it, and indeed
	complains if that happens.</para>

	<para>It is possible to add directories with <command>svn
	add</command>:</para>

	<screen>&prompt.user; <userinput>mkdir <replaceable>bar</replaceable></userinput>
	&prompt.user; <userinput>svn add <replaceable>bar</replaceable></userinput></screen>

	<para>Although <command>svn mkdir</command> makes this
	easier by combining the creation of the directory and the
	adding of it:</para>

	<screen>&prompt.user; <userinput>svn mkdir <replaceable>bar</replaceable></userinput></screen>

	<para>The directory is not immediately
	created in the repository when you use <command>svn
	mkdir</command>. Subversion
	allows directories to be removed using <command>svn
	rm</command>, however there is no <command>svn
	rmdir</command>:</para>

	<screen>&prompt.user; <userinput>svn rm <replaceable>bar</replaceable></userinput></screen>
	</sect3>

	<sect3>
	<title>Copying and Moving Files</title>

	<para>The following (obviously) creates a copy of
	<filename>foo.c</filename>, named
	<filename>bar.c</filename>:</para>

	<screen>&prompt.user; <userinput>svn copy <replaceable>foo.c</replaceable> <replaceable>bar.c</replaceable></userinput></screen>

	<para>To move and rename a file:</para>

	<screen>&prompt.user; <userinput>svn move <replaceable>foo.c</replaceable> <replaceable>bar.c</replaceable></userinput></screen>

	<para>The above command is the exact equivalent of:</para>

	<screen>&prompt.user; <userinput>svn copy <replaceable>foo.c</replaceable> <replaceable>bar.c</replaceable></userinput>
	&prompt.user; <userinput>svn remove <replaceable>foo.c</replaceable></userinput></screen>
	</sect3>

	<sect3>
	<title>Log and Annotate</title>

	<para><command>svn log</command> will show all the
	revisions that affect a directory and files within that
	directory in reverse chronological order, if run on a
	directory. This contrasts with <command>cvs log</command>
	in that <acronym>CVS</acronym> shows the complete log for
	each file in the directory, including duplicate entries for
	revisions that affect multiple files.</para>

	<para><command>svn annotate</command>, or equally <command>svn
	praise</command> or <command>svn blame</command>, is
	equivalent to <command>cvs annotate</command> in everything
	but output format.</para>
	</sect3>

	<sect3>
	<title>Diffs</title>

	<para><command>svn diff</command> displays changes to the
	working copy of the repository. Diffs generated by
	<acronym>SVN</acronym> are unified
	and include new files by default
	in the diff output.</para>

	<para><command>svn
	diff</command> can show the changes between two revisions
	of the same file:</para>

	<screen>&prompt.user; <userinput>svn diff -r179453:179454 ROADMAP.txt</userinput></screen>

	<para>It can also show all changes for a specific changeset.
	The following will show what changes were made to the
	current directory and all subdirectories in changeset
	179454:</para>

	<screen>&prompt.user; <userinput>svn diff -c179454 .</userinput></screen>
	</sect3>

	<sect3>
	<title>Reverting</title>

	<para>Local changes (including additions and deletions) can be
	reverted using <command>svn revert</command>.
	It does not update out-of-date
	files—it just replaces them with pristine copies of
	the original version.</para>
	</sect3>

	<sect3>
	<title>Conflicts</title>

	<para>If a <command>svn update</command> resulted in a merge
	conflict, Subversion will remember which files have
	conflicts and refuse to commit any changes to those files
	until explicitly told that the conflicts have been resolved.
	The simple, not yet deprecated procedure is the
	following:</para>

	<screen>&prompt.user; <userinput>svn resolved <replaceable>foo</replaceable></userinput></screen>

	<para>However, the preferred procedure is:</para>

	<screen>&prompt.user; <userinput>svn resolve --accept=working <replaceable>foo</replaceable></userinput></screen>

	<para>The two examples are equivalent. Possible values for
	<literal>--accept</literal> are:</para>

	<itemizedlist>
	<listitem>
	<para><literal>working</literal>: use the version in your
	working directory (which one presumes has been edited to
	resolve the conflicts).</para>
	</listitem>
	<listitem>
	<para><literal>base</literal>: use a pristine copy of the
	version you had before <command>svn update</command>,
	discarding your own changes, the conflicting changes,
	and possibly other intervening changes as well.</para>
	</listitem>
	<listitem>
	<para><literal>mine-full</literal>: use what you had
	before <command>svn update</command>, including your own
	changes, but discarding the conflicting changes, and
	possibly other intervening changes as well.</para>
	</listitem>
	<listitem>
	<para><literal>theirs-full</literal>: use the version that
	was retrieved when you did <command>svn
	update</command>, discarding your own changes.</para>
	</listitem>
	</itemizedlist>
	</sect3>
	</sect2>

	<sect2>
	<title>Advanced Use</title>

	<sect3>
	<title>Sparse Checkouts</title>

	<para>The equivalent to <command>cvs checkout -l</command>,
	which checks out a directory without its subdirectories, is
	<command>svn checkout -N</command>. Unlike
	<acronym>CVS</acronym>, <acronym>SVN</acronym> remembers the
	<literal>-N</literal> so that a <command>svn
	update</command> does not end up pulling down the
	subdirectories. In Subversion 1.5 and newer,
	<literal>-N</literal> has been deprecated in favour of the
	<literal>--depth</literal> option which allows for precise
	control. Therefore:</para>

	<screen>&prompt.user; <userinput>svn checkout -N svn+ssh://svn.freebsd.org/base ~/freebsd</userinput></screen>

	<para>is equivalent to:</para>

	<screen>&prompt.user; <userinput>svn checkout --depth=empty svn+ssh://svn.freebsd.org/base ~/freebsd</userinput></screen>

	<para>Valid arguments to <literal>--depth</literal>
	are:</para>

	<itemizedlist>
	<listitem>
	<para><literal>empty</literal>: the directory itself
	without any of its contents.</para>
	</listitem>
	<listitem>
	<para><literal>files</literal>: the directory and any
	files it contains.</para>
	</listitem>
	<listitem>
	<para><literal>immediates</literal>: the directory and any
	files and directories it contains, but none of the
	subdirectories' contents.</para>
	</listitem>
	<listitem>
	<para><literal>infinity</literal>: anything.</para>
	</listitem>
	</itemizedlist>

	<para>The <literal>--depth</literal> option applies to many
	other commands, including <command>svn commit</command>,
	<command>svn revert</command>, and <command>svn
	diff</command>.</para>

	<para>Since <literal>--depth</literal> is sticky, there is a
	<literal>--set-depth</literal> option for <command>svn
	update</command> that will change the selected depth.
	Thus, given the working copy produced by the previous
	example:</para>

	<screen>&prompt.user; <userinput>cd <replaceable>~/freebsd</replaceable></userinput>
	&prompt.user; <userinput>svn update --set-depth=immediates .</userinput></screen>

	<para>The above command will populate the working copy in
	<replaceable>~/freebsd</replaceable> with
	<filename>ROADMAP.txt</filename> and empty subdirectories,
	and nothing will happen when <command>svn update</command>
	is executed on the subdirectories. However, the following
	command will set the depth for head (in this case) to
	infinity, and fully populate it:</para>

	<screen>&prompt.user; <userinput>svn update --set-depth=infinity <replaceable>head</replaceable></userinput></screen>
	</sect3>

	<sect3>
	<title>Direct Operation</title>

	<para>Certain operations can be performed directly on the
	repository, without touching the working copy.
	Specifically, this applies to any operation that does not
	require editing a file, including:</para>

	<itemizedlist>
	<listitem>
	<para><literal>log</literal>,
	<literal>diff</literal>.</para>
	</listitem>
	<listitem>
	<para><literal>mkdir</literal>.</para>
	</listitem>
	<listitem>
	<para><literal>remove</literal>, <literal>copy</literal>,
	<literal>rename</literal>.</para>
	</listitem>
	<listitem>
	<para><literal>propset</literal>,
	<literal>propedit</literal>,
	<literal>propdel</literal>.</para>
	</listitem>
	<listitem>
	<para><literal>merge</literal>.</para>
	</listitem>
	</itemizedlist>

	<para>Branching is very fast. The following command would be
	used to branch <literal>RELENG_8</literal>:</para>

	<screen>&prompt.user; <userinput>svn copy svn+ssh://svn.freebsd.org/base/head svn+ssh://svn.freebsd.org/base/stable/8</userinput></screen>

	<para>This is equivalent to the following set of
	commands which take minutes and hours as opposed to seconds,
	depending on your network connection:</para>

	<screen>&prompt.user; <userinput>svn checkout --depth=immediates svn+ssh://svn.freebsd.org/base</userinput>
	&prompt.user; <userinput>cd base</userinput>
	&prompt.user; <userinput>svn update --depth=infinity head</userinput>
	&prompt.user; <userinput>svn copy head stable/8</userinput>
	&prompt.user; <userinput>svn commit stable/8</userinput></screen>
	</sect3>

	<sect3 id="subversion-primer-merge">
	<title>Merging with <acronym>SVN</acronym></title>

	<para>This section deals with merging code from one branch to
	another (typically, from head to a stable branch).</para>

	<note>
	<para>In all examples below, <literal>&dollar;FSVN</literal>
	refers to the location of the &os; Subversion repository,
	<literal>svn+ssh://svn.freebsd.org/base/</literal>.</para>
	</note>

	<sect4>
	<title>About Merge Tracking</title>

	<para>From the user's perspective, merge tracking
	information (or mergeinfo) is stored in a property called
	<literal>svn:mergeinfo</literal>, which is a
	comma-separated list of revisions and ranges of revisions
	that have been merged. When set on a file, it applies
	only to that file. When set on a directory, it applies to
	that directory and its descendants (files and directories)
	except for those that have their own
	<literal>svn:mergeinfo</literal>.</para>

	<para>It is <emphasis>not</emphasis> inherited. For
	instance, <filename
	class="directory">stable/6/contrib/openpam/</filename>
	does not implicitly inherit mergeinfo from <filename
	class="directory">stable/6/</filename>, or <filename
	class="directory">stable/6/contrib/</filename>. Doing
	so would make partial checkouts very hard to manage.
	Instead, mergeinfo is explicitly propagated down the tree.
	For merging something into <filename
	class="directory">branch/foo/bar/</filename>, the
	following rules apply:</para>

	<orderedlist>
	<listitem>
	<para>If <filename
	class="directory">branch/foo/bar/</filename> doesn't
	already have a mergeinfo record, but a direct ancestor
	(for instance, <filename
	class="directory">branch/foo/</filename>) does,
	then that record will be propagated down to
	<filename class="directory">branch/foo/bar/</filename>
	before information
	about the current merge is recorded.</para>
	</listitem>
	<listitem>
	<para>Information about the current merge will
	<emphasis>not</emphasis> be propagated back up that
	ancestor.</para>
	</listitem>
	<listitem>
	<para>If a direct descendant of <filename
	class="directory">branch/foo/bar/</filename> (for
	instance, <filename
	class="directory">branch/foo/bar/baz/</filename>)
	already has a mergeinfo record, information about the
	current merge will be propagated down to it.</para>
	</listitem>
	</orderedlist>

	<para>If you consider the case where a revision changes
	several separate parts of the tree (for example, <filename
	class="directory">branch/foo/bar/</filename> and
	<filename class="directory">branch/foo/quux/</filename>),
	but you only want to merge some of it (for example,
	<filename class="directory">branch/foo/bar/</filename>),
	you will see that these rules make sense. If mergeinfo
	was propagated up, it would seem like that revision had
	also been merged to <filename
	class="directory">branch/foo/quux/</filename>, when in
	fact it had not been.</para>
	</sect4>

	<sect4>
	<title>Selecting the Source and Target</title>

	<para>Because of mergeinfo propagation, it is important to
	choose the source and target for the merge carefully to
	minimise property changes on unrelated directories.</para>

	<para>The rules for selecting the merge target (the
	directory that you will merge the changes to) can be
	summarized as follows:</para>

	<orderedlist>
	<listitem>
	<para>Never merge directly to a file.</para>
	</listitem>
	<listitem>
	<para>Never, ever merge directly to a file.</para>
	</listitem>
	<listitem>
	<para><emphasis>Never, ever, ever</emphasis> merge
	directly to a file.</para>
	</listitem>
	<listitem>
	<para>Changes to kernel code should be merged to
	<filename class="directory">sys/</filename>. For
	instance, a change to the &man.ichwd.4; driver should
	be merged to <filename
	class="directory">sys/</filename>, not <filename
	class="directory">sys/dev/ichwd/</filename>.
	Likewise, a change to the TCP/IP stack should be
	merged to <filename class="directory">sys/</filename>,
	not <filename
	class="directory">sys/netinet/</filename>.</para>
	</listitem>
	<listitem>
	<para>Changes to code under <filename
	class="directory">etc/</filename> should be merged
	at <filename class="directory">etc/</filename>, not
	below it.</para>
	</listitem>
	<listitem>
	<para>Changes to vendor code (code in <filename
	class="directory">contrib/</filename>, <filename
	class="directory">crypto/</filename> and so on)
	should be merged to the directory where vendor imports
	happen. For instance, a change to <filename
	class="directory">crypto/openssl/util/</filename>
	should be merged to <filename
	class="directory">crypto/openssl/</filename>. This
	is rarely an issue, however, since changes to vendor
	code are usually merged wholesale.</para>
	</listitem>
	<listitem>
	<para>Changes to userland programs should as a general
	rule be merged to the directory that contains the
	Makefile for that program. For instance, a change to
	<filename
	class="directory">usr.bin/xlint/arch/i386/</filename>
	should be merged to <filename
	class="directory">usr.bin/xlint/</filename>.</para>
	</listitem>
	<listitem>
	<para>Changes to userland libraries should as a general
	rule be merged to the directory that contains the
	Makefile for that library. For instance, a change to
	<filename class="directory">lib/libc/gen/</filename>
	should be merged to <filename
	class="directory">lib/libc/</filename>.</para>
	</listitem>
	<listitem>
	<para>There may be cases where it makes sense to deviate
	from the rules for userland programs and libraries.
	For instance, everything under <filename
	class="directory">lib/libpam/</filename> is merged
	to <filename class="directory">lib/libpam/</filename>,
	even though the library itself and all of the modules
	each have their own Makefile.</para>
	</listitem>
	<listitem>
	<para>Changes to manual pages should be merged to <filename
	class="directory">share/man/man<replaceable>N</replaceable>/</filename>,
	for the appropriate value of
	<literal>N</literal>.</para>
	</listitem>
	<listitem>
	<para>Other changes to <filename
	class="directory">share/</filename> should be merged
	to the appropriate subdirectory and not to
	<filename class="directory">share/</filename>
	directly.</para>
	</listitem>
	<listitem>
	<para>Changes to a top-level file in the source tree
	such as <filename>UPDATING</filename> or
	<filename>Makefile.inc1</filename> should be merged
	directly to that file rather than to the root of the
	whole tree. Yes, this is an exception to the first
	three rules.</para>
	</listitem>
	<listitem>
	<para>When in doubt, ask.</para>
	</listitem>
	</orderedlist>

	<para>If you need to merge changes to several places at once
	(for instance, changing a kernel interface and every
	userland program that uses it), merge each target
	separately, then commit them together. For instance, if
	you merge a revision that changed a kernel
	<acronym>API</acronym> and updated all the userland bits
	that used that <acronym>API</acronym>, you would merge the
	kernel change to sys, and the userland bits to the
	appropriate userland directories, then commit all of these
	in one go.</para>

	<para>The source will almost invariably be the same as the
	target. For instance, you will always merge <filename
	class="directory">stable/7/lib/libc/</filename> from
	<filename class="directory">head/lib/libc/</filename>.
	The only exception would be when merging changes to code
	that has moved in the source branch but not in the parent
	branch. For instance, a change to &man.pkill.1; would be
	merged from <filename
	class="directory">bin/pkill/</filename> in head to
	<filename class="directory">usr.bin/pkill/</filename> in
	stable/7.</para>
	</sect4>

	<sect4>
	<title>Preparing the Merge Target</title>

	<para>Because of the mergeinfo propagation issues described
	earlier, it is very important that you never merge changes
	into a sparse working copy. You must always have a full
	checkout of the branch you will merge into. For instance,
	when merging from HEAD to 7, you must have a full checkout
	of stable/7:</para>

	<screen>&prompt.user; <userinput>cd stable/7</userinput>
	&prompt.user; <userinput>svn up --set-depth=infinity</userinput></screen>

	<para>The target directory must also be up-to-date and must
	not contain any uncommitted changes or stray files.</para>
	</sect4>

	<sect4>
	<title>Identifying Revisions</title>

	<para>Identifying revisions to be merged is a must. If the
	target already has complete mergeinfo, ask
	<acronym>SVN</acronym> for a list:</para>

	<screen>&prompt.user; <userinput>cd stable/6/contrib/openpam</userinput>
	&prompt.user; <userinput>svn mergeinfo --show-revs=eligible $FSVN/head/contrib/openpam</userinput></screen>

	<para>If the target does not have complete mergeinfo, check
	the log for the merge source.</para>
	</sect4>

	<sect4>
	<title>Merging</title>

	<para>Now, let's start merging!</para>

	<sect5>
	<title>The Principles</title>

	<para>Say you would like to merge:</para>

	<itemizedlist>
	<listitem>
	<para>revision <literal>&dollar;R</literal>.</para>
	</listitem>
	<listitem>
	<para>in directory &dollar;target in stable branch
	&dollar;B.</para>
	</listitem>
	<listitem>
	<para>from directory &dollar;source in head.</para>
	</listitem>
	<listitem>
	<para>&dollar;FSVN is
	<literal>svn+ssh://svn.freebsd.org/base</literal>.</para>
	</listitem>
	</itemizedlist>

	<para>Assuming that revisions &dollar;P and &dollar;Q have
	already been merged, and that the current directory is
	an up-to-date working copy of stable/&dollar;B, the
	existing mergeinfo looks like this:</para>

	<screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R $target</userinput>
	$target - /head/$source:$P,$Q</screen>

	<para>Merging is done like so:</para>

	<screen>&prompt.user; <userinput>svn merge -c$R $FSVN/head/$source $target</userinput></screen>

	<para>Checking the results of this is possible with
	<command>svn diff</command>.</para>

	<para>The svn:mergeinfo now looks like:</para>

	<screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R $target</userinput>
	$target - head/$source:$P,$Q,$R</screen>

	<para>If the results are not exactly as shown, assistance
	may be required before committing as mistakes may have
	been made, or there may be something wrong with the
	existing mergeinfo, or there may be a bug in
	Subversion.</para>
	</sect5>

	<sect5>
	<title>Practical Example</title>
	<para>As a practical example, consider the following scenario:
	The changes to <filename>netmap.4</filename> in r238987 is
	to be merged from CURRENT to 9-STABLE. The file resides in
	<filename class="directory">head/share/man/man4</filename> and
	according to <xref linkend="subversion-primer-merge"/> this
	is also where to do the merge. Note that in this example
	all paths are relative to the top of the svn repository.
	for more information on the directory layout, see
	<xref linkend="subversion-primer-base-layout"/>.</para>
	<para>The first step is to inspect the existing mergeinfo.</para>

	<screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R stable/9/share/man/man4</userinput></screen>

	<para>Take a quick note of how it looks before moving on to the next
	step; doing the actual merge:</para>

	<screen>&prompt.user; <userinput>svn merge -c r238987 svn+ssh://svn.freebsd.org/base/head/share/man/man4 stable/9/share/man/man4</userinput>
	--- Merging r238987 into 'stable/9/share/man/man4':
	U stable/9/share/man/man4/netmap.4
	--- Recording mergeinfo for merge of r238987 into
	'stable/9/share/man/man4':
	U stable/9/share/man/man4</screen>

	<para>Check that the revision number of the merged revision
	has been added. Once this is verified, the only thing left
	is the actual commit.</para>

	<screen>&prompt.user; <userinput>svn commit stable/9/share/man/man4</userinput></screen>
	</sect5>

	<sect5>
	<title>Merging into the Kernel
	(<filename class="directory">sys/</filename>)</title>

	<para>As stated above, merging into the kernel is
	different from merging in the rest of the tree. In many
	ways merging to the kernel is simpler because there is
	always the same merge target
	(<filename class="directory">sys/</filename>).</para>

	<para>Once <command>svn merge</command> has been executed,
	<command>svn diff</command> has to be run on the
	directory to check the changes. This may show some
	unrelated property changes, but these can be ignored.
	Next, build and test the kernel, and, once the tests are
	complete, commit the code as normal, making sure that
	the commit message starts with <quote>Merge
	<replaceable>r226222</replaceable> from head</quote>,
	or similar.</para>
	</sect5>
	</sect4>

	<sect4>
	<title>Precautions Before Committing</title>

	<para>As always, build world (or appropriate parts of
	it).</para>

	<para>Check the changes with <command>svn diff</command> and
	<command>svn stat</command>. Make sure all the files that
	should have been added or deleted were in fact added or
	deleted.</para>

	<para>Take a closer look at any property change (marked by a
	<literal>M</literal> in the second column of <command>svn
	stat</command>). Normally, no svn:mergeinfo properties
	should be anywhere except the target directory (or
	directories).</para>

	<para>If something looks fishy, ask for help.</para>
	</sect4>

	<sect4>
	<title>Committing</title>

	<para>Make sure to commit a top level directory to have the
	mergeinfo included as well. Do not specify individual
	files on the command line. For more information about
	committing files in general, see the relevant section of
	this primer.</para>
	</sect4>
	</sect3>

	<sect3>
	<title>Vendor imports with <acronym>SVN</acronym></title>

	<important>
	<para>Please read this entire section before starting a vendor
	import.</para>
	</important>

	<note>
	<para>Patches to vendor code fall into two categories:</para>

	<itemizedlist>
	<listitem>
	<para>Vendor patches: these are patches that have been
	issued by the vendor, or that have been extracted from
	the vendor's version control system, which address
	issues which in your opinion can't wait until the next
	vendor release.</para>
	</listitem>
	<listitem>
	<para>&os; patches: these are patches that modify the
	vendor code to address &os;-specific issues.</para>
	</listitem>
	</itemizedlist>

	<para>The nature of a patch dictates where it should be
	committed:</para>

	<itemizedlist>
	<listitem>
	<para>Vendor patches should be committed to the vendor
	branch, and merged from there to head. If the patch
	addresses an issue in a new release that is currently
	being imported, it <emphasis>must not</emphasis> be
	committed along with the new release: the release must
	be imported and tagged first, then the patch can be
	applied and committed. There is no need to re-tag the
	vendor sources after committing the patch.</para>
	</listitem>
	<listitem>
	<para>&os; patches should be committed directly to
	head.</para>
	</listitem>
	</itemizedlist>
	</note>

	<sect4>
	<title>Preparing the tree</title>

	<para>If importing for the first time after the switch to
	Subversion, flattening and cleaning up the vendor tree is
	necessary, as well as bootstrapping the merge history in
	the main tree.</para>

	<sect5>
	<title>Flattening</title>

	<para>During the conversion from <acronym>CVS</acronym> to
	Subversion, vendor branches were imported with the same
	layout as the main tree. This means that the
	<literal>pf</literal> vendor sources ended up in
	<filename>vendor/pf/dist/contrib/pf</filename>. The
	vendor source is best directly in
	<filename>vendor/pf/dist</filename>.</para>

	<para>To flatten the <literal>pf</literal> tree:</para>

	<screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/dist/contrib/pf</replaceable></userinput>
	&prompt.user; <userinput>svn mv $(svn list) ../..</userinput>
	&prompt.user; <userinput>cd ../..</userinput>
	&prompt.user; <userinput>svn rm contrib</userinput>
	&prompt.user; <userinput>svn propdel -R svn:mergeinfo .</userinput>
	&prompt.user; <userinput>svn commit</userinput></screen>

	<para>The <literal>propdel</literal> bit is necessary
	because starting with 1.5, Subversion will automatically
	add <literal>svn:mergeinfo</literal> to any directory
	that is copied or moved. In this case, as nothing is
	being merged from the deleted tree, they just get in the
	way.</para>

	<para>Tags may be flattened as well (3, 4, 3.5 etc.); the
	procedure is exactly the same, only changing
	<literal>dist</literal> to <literal>3.5</literal> or
	similar, and putting the <command>svn commit</command>
	off until the end of the process.</para>
	</sect5>
	<sect5>
	<title>Cleaning up</title>

	<para>The <literal>dist</literal> tree can be cleaned up
	as necessary. Disabling keyword expansion is
	recommended, as it makes no sense on unmodified vendor
	code and in some cases it can even be harmful.
	<application>OpenSSH</application>, for example, includes
	two files that originated with &os; and still contain the
	original version tags. To do this:</para>

	<screen>&prompt.user; <userinput>svn propdel svn:keywords -R .</userinput>
	&prompt.root; <userinput>svn commit</userinput></screen>
	</sect5>
	<sect5>
	<title>Bootstrapping merge history</title>

	<para>If importing for the first time after the switch to
	Subversion, bootstrap
	<literal>svn:mergeinfo</literal> on the target directory
	in the main tree to the revision that corresponds
	to the last related change to the vendor tree, prior to
	importing new sources:</para>

	<screen>&prompt.user; <userinput>cd <replaceable>head/contrib/pf</replaceable></userinput>
	&prompt.user; <userinput>svn merge --record-only svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist@180876</replaceable> .</userinput>
	&prompt.user; <userinput>svn commit</userinput></screen>
	</sect5>
	</sect4>

	<sect4>
	<title>Importing new sources</title>

	<para>With two commits—one for the import itself and
	one for the tag—this step can optionally be repeated
	for every upstream release between the last import and the
	current import.</para>

	<sect5>
	<title>Preparing the vendor sources</title>

	<para>Unlike in <acronym>CVS</acronym> where only the needed
	parts were imported into the vendor tree to avoid bloating
	the main tree, Subversion is able to store a full
	distribution in the vendor tree. So, import everything,
	but merge only what is required.</para>

	<para>A <command>svn add</command> is required to add any
	files that were added since the last vendor import, and
	<command>svn rm</command> is required to remove any that
	were removed since. Preparing sorted lists of the
	contents of the vendor tree and of the sources that are
	about to be imported is recommended, to facilitate the
	process.</para>

	<screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/dist</replaceable></userinput>
	&prompt.user; <userinput>svn list -R \| grep -v '/$' \| sort >../old</userinput>
	&prompt.user; <userinput>cd <replaceable>../pf-4.3</replaceable></userinput>
	&prompt.user; <userinput>find . -type f \| cut -c 3- \| sort >../new</userinput></screen>

	<para>With these two files,
	<command>comm -23 ../old ../new</command>
	will list removed files (files only in
	<filename>old</filename>), while
	<command>comm -13 ../old ../new</command>
	will list added files only in <filename>new</filename>.</para>
	</sect5>
	<sect5>
	<title>Importing into the vendor tree</title>

	<para>Now, the sources must be copied into
	<filename><replaceable>dist</replaceable></filename> and
	the <command>svn add</command> and
	<command>svn rm</command> commands should be used as
	needed:</para>

	<screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/pf-4.3</replaceable></userinput>
	&prompt.user; <userinput>tar cf - . \| tar xf - -C ../dist</userinput>
	&prompt.user; <userinput>cd <replaceable>../dist</replaceable></userinput>
	&prompt.user; <userinput>comm -23 ../old ../new \| xargs svn rm</userinput>
	&prompt.user; <userinput>comm -13 ../old ../new \| xargs svn --parents add</userinput></screen>

	<para>If any directories were removed, they will have to be
	<command>svn rm</command>ed manually. Nothing will break
	if they are not, but they will remain in the tree.</para>

	<para>Check properties on any new files. All text files
	should have <literal>svn:eol-style</literal> set to
	<literal>native</literal>. All binary files should have
	<literal>svn:mime-type</literal> set to
	<literal>application/octet-stream</literal> unless there
	is a more appropriate media type. Executable files should
	have <literal>svn:executable</literal> set to
	<literal>*</literal>. No other properties should exist
	on any file in the tree.</para>

	<para>Committing is now possible, however it is good
	practice to make sure that everything is OK by using the
	<command>svn stat</command> and
	<command>svn diff</command> commands.</para>
	</sect5>
	<sect5>
	<title>Tagging</title>

	<para>Once committed, vendor releases should be tagged for
	future reference. The best and quickest way to do this
	is directly in the repository:</para>

	<screen>&prompt.user; <userinput>svn cp svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/4.3</replaceable></userinput></screen>

	<para>Once that is complete, <command>svn up</command> the
	working copy of
	<filename><replaceable>vendor/pf</replaceable></filename>
	to get the new tag, although this is rarely
	needed.</para>

	<para>If creating the tag in the working copy of the tree,
	<command>svn:mergeinfo</command> results must be removed:</para>

	<screen>&prompt.user; <userinput>cd <replaceable>vendor/pf</replaceable></userinput>
	&prompt.user; <userinput>svn cp dist 4.3</userinput>
	&prompt.user; <userinput>svn propdel svn:mergeinfo -R 4.3</userinput></screen>
	</sect5>
	</sect4>
	<sect4>
	<title>Merging to head</title>

	<screen>&prompt.user; <userinput>cd <replaceable>head/contrib/pf</replaceable></userinput>
	&prompt.user; <userinput>svn up</userinput>
	&prompt.user; <userinput>svn merge --accept=postpone svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> .</userinput></screen>

	<para>The <literal>--accept=postpone</literal> tells
	Subversion that it shouldn't complain because merge conflicts
	will be taken care of manually.</para>

	<para>It is necessary to resolve any merge conflicts.
	This process is the same in <acronym>SVN</acronym> as in
	<acronym>CVS</acronym>.</para>

	<para>Make sure that any files that were added or removed in
	the vendor tree have been properly added or removed in the
	main tree. To check diffs against the vendor branch:</para>

	<screen>&prompt.user; <userinput>svn diff --no-diff-deleted --old=svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> --new=.</userinput></screen>

	<para>The <literal>--no-diff-deleted</literal> tells
	Subversion not to complain about files that are in the
	vendor tree but not in the main tree, i.e., things that
	would have previously been removed before the vendor
	import, like for example the like the vendor's makefiles
	and configure scripts.</para>

	<para>Using <acronym>CVS</acronym>, once a file was off the
	vendor branch, it was not able to be put back. With
	Subversion, there is no concept of on or off the vendor
	branch. If a file that previously had local
	modifications, to make it not show up in diffs in the
	vendor tree, all that has to be done is remove any left-over
	cruft like &os; version tags, which is much easier.</para>

	<para>If any changes are required for the world to build
	with the new sources, make them now, and keep testing
	until everything builds and runs perfectly.</para>
	</sect4>
	<sect4>
	<title>Committing the vendor import</title>

	<para>Committing is now possible! Everything must be
	committed in one go. If done properly, the tree will move
	from a consistent state with old code, to a consistent
	state with new code.</para>
	</sect4>

	<sect4>
	<title>From scratch</title>

	<sect5>
	<title>Importing into the vendor tree</title>

	<para>This section is an example of importing and tagging
	<application>byacc</application> into
	<filename class="directory">head</filename>.</para>

	<para>First, prepare the directory in
	<filename class="directory">vendor</filename>:</para>

	<screen>&prompt.user; <userinput>svn co --depth immediates <replaceable>$FSVN/vendor</replaceable></userinput>
	&prompt.user; <userinput>cd <replaceable>vendor</replaceable></userinput>
	&prompt.user; <userinput>svn mkdir <replaceable>byacc</replaceable></userinput>
	&prompt.user; <userinput>svn mkdir <replaceable>byacc/dist</replaceable></userinput></screen>

	<para>Now, import the sources into the
	<filename class="directory">dist</filename> directory. Once
	the files are in place, <command>svn add</command> the new
	ones, then <command>svn commit</command> and tag the
	imported version. To save time and bandwidth, direct remote
	committing and tagging is possible:</para>

	<screen>&prompt.user; <userinput>svn cp -m <replaceable>"Tag byacc 20120115"</replaceable> <replaceable>$FSVN/vendor/byacc/dist</replaceable> <replaceable>$FSVN/vendor/byacc/20120115</replaceable></userinput></screen>
	</sect5>

	<sect5>
	<title>Merging to head</title>

	<para>Due to this being a new file, copy it for the
	merge:</para>

	<screen>&prompt.user; <userinput>svn cp -m <replaceable>"Import byacc to contrib"</replaceable> <replaceable>$FSVN/vendor/byacc/dist</replaceable> <replaceable>$FSVN/head/contrib/byacc</replaceable></userinput></screen>

	<para>Working normally on newly imported sources is still
	possible.</para>
	</sect5>
	</sect4>
	</sect3>

	<sect3>
	<title>Reverting a Commit</title>

	<para>Reverting a commit to a previous version is fairly
	easy:</para>

	<screen>&prompt.user; <userinput>svn merge -r179454:179453 ROADMAP.txt</userinput>
	&prompt.user; <userinput>svn commit</userinput></screen>

	<para>Change number syntax, with negative meaning a reverse
	change, can also be used:</para>

	<screen>&prompt.user; <userinput>svn merge -c -179454 ROADMAP.txt</userinput>
	&prompt.user; <userinput>svn commit</userinput></screen>

	<para>This can also be done directly in the repository:</para>

	<screen>&prompt.user; <userinput>svn merge -r179454:179453 svn+ssh://svn.freebsd.org/base/ROADMAP.txt</userinput></screen>

	<note>
	<para>It is important to ensure that the mergeinfo
	is correct when reverting a file in order to permit
	<command>svn mergeinfo --eligible</command> to work as
	expected.</para>
	</note>

	<para>Reverting the deletion of a file is slightly different.
	Copying the version of the file that predates the deletion
	is required. For example, to restore a file that was
	deleted in revision N, restore version N-1:</para>

	<screen>&prompt.user; <userinput>svn copy svn+ssh://svn.freebsd.org/base/ROADMAP.txt@179454</userinput>
	&prompt.user; <userinput>svn commit</userinput></screen>

	<para>or, equally:</para>

	<screen>&prompt.user; <userinput>svn copy svn+ssh://svn.freebsd.org/base/ROADMAP.txt@179454 svn+ssh://svn.freebsd.org/base</userinput></screen>

	<para>Do <emphasis>not</emphasis> simply recreate the file
	manually and <command>svn add</command> it—this will
	cause history to be lost.</para>
	</sect3>

	<sect3>
	<title>Fixing Mistakes</title>

	<para>While we can do surgery in an emergency, do not plan on
	having mistakes fixed behind the scenes. Plan on mistakes
	remaining in the logs forever. Be sure to check the output
	of <command>svn status</command> and <command>svn
	diff</command> before committing.</para>

	<para>Mistakes will happen but,
	they can generally be fixed without
	disruption.</para>

	<para>Take a case of adding a file in the wrong location. The
	right thing to do is to <command>svn move</command> the file
	to the correct location and commit. This causes just a
	couple of lines of metadata in the repository journal, and
	the logs are all linked up correctly.</para>

	<para>The wrong thing to do is to delete the file and then
	<command>svn add</command> an independent copy in the
	correct location. Instead of a couple of lines of text, the
	repository journal grows an entire new copy of the file.
	This is a waste.</para>
	</sect3>

	<sect3>
	<title>Setting up a <application>svnsync</application>
	Mirror</title>

	<para>You probably do not want to do this unless there is a
	good reason for it. Such reasons might be to support many
	multiple local read-only client machines, or if your network
	bandwidth is limited. Starting a fresh mirror from empty
	would take a very long time. Expect a minimum of 10 hours
	for high speed connectivity. If you have international
	links, expect this to take 4 to 10 times longer.</para>

	<para>A far better option is to grab a seed file. It is large
	(~1GB) but will consume less network traffic and take less
	time to fetch than a svnsync will. This is possible in one
	of the following three ways:</para>

	<screen>&prompt.user; <userinput>rsync -va --partial --progress freefall:/home/peter/svnmirror-base-r179637.tbz2 .</userinput></screen>

	<screen>&prompt.user; <userinput>rsync -va --partial --progress rsync://repoman.freebsd.org:50873/svnseed/svnmirror-base-r215629.tar.xz .</userinput></screen>

	<screen>&prompt.user; <userinput>fetch ftp://ftp.freebsd.org/pub/FreeBSD/development/subversion/svnmirror-base-r221445.tar.xz</userinput></screen>

	<para>Once you have the file, extract it to somewhere like
	<filename class="directory">home/svnmirror/base/</filename>.
	Then, update it, so that it fetches changes since the last
	revision in the archive:</para>

	<screen>&prompt.user; <userinput>svnsync sync file:///home/svnmirror/base</userinput></screen>

	<para>You can then set that up to run from &man.cron.8;, do
	checkouts locally, set up a svnserve server for your local
	machines to talk to, etc.</para>

	<para>The seed mirror is set to fetch from
	<literal>svn://svn.freebsd.org/base</literal>. The
	configuration for the mirror is stored in <literal>revprop
	0</literal> on the local mirror. To see the
	configuration, try:</para>

	<screen>&prompt.user; <userinput>svn proplist -v --revprop -r 0 file:///home/svnmirror/base</userinput></screen>

	<para>Use <literal>propset</literal> to change things.</para>
	</sect3>

	<sect3>
	<title>Committing High-<acronym>ASCII</acronym> Data</title>

	<para>Files that have high-<acronym>ASCII</acronym> bits are
	considered binary files in <acronym>SVN</acronym>, so the
	pre-commit checks fail and indicate that the
	<literal>mime-type</literal> property should be set to
	<literal>application/octet-stream</literal>. However, the
	use of this is discouraged, so please do not set it. The
	best way is always avoiding high-<acronym>ASCII</acronym>
	data, so that it can be read everywhere with any text editor
	but if it is not avoidable, instead of changing the
	mime-type, set the <literal>fbsd:notbinary</literal>
	property with <literal>propset</literal>:</para>

	<screen>&prompt.user; <userinput>svn propset fbsd:notbinary yes foo.data</userinput></screen>
	</sect3>

	<sect3>
	<title>Maintaining a Project Branch</title>

	<para>A project branch is one that's synced to head (or
	another branch) is used to develop a project then commit it
	back to head. In <acronym>SVN</acronym>,
	<quote>dolphin</quote> branching is used for this. A
	<quote>dolphin</quote> branch is one that diverges for a
	while and is finally committed back to the original branch.
	During development code migration in one direction (from
	head to the branch only). No code is committed back to head
	until the end. Once you commit back at the end, the branch
	is dead (although you can have a new branch with the same
	name after you delete the branch if you want).</para>

	<para>As per <ulink
	url="http://people.freebsd.org/~peter/svn_notes.txt">http://people.freebsd.org/~peter/svn_notes.txt</ulink>,
	work that is intended to be merged back into HEAD should be
	in <filename class="directory">base/projects/</filename>.
	If you are doing work that is beneficial to the &os;
	community in some way but not intended to be merged directly
	back into HEAD then the proper location is <filename
	class="directory">base/user/<replaceable>your-name</replaceable>/</filename>.
	<ulink
	url="http://svnweb.freebsd.org/base/projects/GUIDELINES.txt">This
	page</ulink> contains further details.</para>

	<para>To create a project branch:</para>

	<screen>&prompt.user; <userinput>svn copy svn+ssh://svn.freebsd.org/base/head svn+ssh://svn.freebsd.org/base/projects/spif</userinput></screen>

	<para>To merge changes from HEAD back into the project
	branch:</para>

	<screen>&prompt.user; <userinput>cd copy_of_spif</userinput>
	&prompt.user; <userinput>svn merge svn+ssh://svn.freebsd.org/base/head</userinput>
	&prompt.user; <userinput>svn commit</userinput></screen>

	<para>It is important to resolve any merge conflicts before
	committing.</para>
	<!--
	<para>To collapse everything back at the end:</para>

	<screen>&prompt.user; <userinput>svn write me</userinput></screen>
	-->
	</sect3>
	</sect2>

	<sect2>
	<title>Some Tips</title>

	<para>In commit logs etc., <quote>rev 179872</quote> should be
	spelled <quote>r179872</quote> as per convention.</para>

	<para>Don't remove and re-add the same file in a single commit
	as this will break the CVS exporter.</para>

	<para>Speeding up svn is
	possible by adding the following to <filename>~/.ssh/config</filename>:</para>

	<screen>Host *
	ControlPath ~/.ssh/sockets/master-%l-%r@%h:%p
	ControlMaster auto
	ControlPersist yes</screen>

	<para>and then typing</para>
	<screen><userinput>mkdir ~/.ssh/sockets</userinput></screen>

	<para>Checking out a working copy with a stock Subversion client
	without &os;-specific patches
	(<makevar>OPTIONS_SET=FREEBSD_TEMPLATE</makevar>) will mean that
	<literal>&dollar;FreeBSD&dollar;</literal> tags will not be
	expanded. Once the correct version has been installed, trick
	Subversion into expanding them like so:</para>

	<screen>&prompt.user; <userinput>svn propdel -R svn:keywords .</userinput>
	&prompt.user; <userinput>svn revert -R .</userinput></screen>

	<para>This will wipe out uncommitted patches.</para>
	</sect2>
	</sect1>

	<sect1 id="conventions">
	<title>Conventions and Traditions</title>

	<para>As a new developer there are a number of things you should do
	first. The first set is specific to committers only. (If you are
	not a committer, e.g., have GNATS-only access, then your mentor needs
	to do these things for you.)</para>

	<sect2 id="conventions-committers">
	<title>Guidelines For Committers</title>

	<note>
	<para>The <literal>.ent</literal>, <literal>.xml</literal>,
	and <literal>.xml</literal> files listed below exist in the
	&os; Documentation Project SVN repository at
	<hostid role="fqdn">svn.FreeBSD.org/doc/</hostid>.</para>
	</note>

	<para>If you have been given commit rights to one or more of the
	repositories:</para>

	<itemizedlist>
	<listitem>
	<para>Add your author entity to
	<filename>head/share/xml/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 version control skills.</para>

	<important>
	<para>New files that do not have the
	<literal>FreeBSD=%H</literal> <command>svn:keywords</command>
	property will be rejected when attempting to commit them to the
	repository. Be sure to read <xref
	linkend="subversion-primer-add-remove"/>
	regarding adding and removing files, in addition
	to verifying that <filename>~/.subversion/config</filename>
	contains the necessary "auto-props"
	entries from <filename>auto-props.txt</filename> mentioned
	there.</para>
	</important>

	<note>
	<para>Don't forget to get mentor approval for these patches!</para>
	</note>

	</listitem>

	<listitem>
	<para>Add yourself to the <quote>Developers</quote> section of
	the <ulink url="&url.articles.contributors;/index.html">Contributors List</ulink>
	(<filename>head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename>) and remove yourself from the <quote>Additional
	Contributors</quote> section (<filename>head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename>).
	Please note that entries are sorted by last name.</para>
	</listitem>

	<listitem>
	<para>Add an entry for yourself to
	<filename>head/share/xml/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>head/share/pgpkeys</filename> (and if you do not
	have a key, you should create one). Do not forget to commit
	the updated <filename>head/share/pgpkeys/pgpkeys.ent</filename>
	and <filename>head/share/pgpkeys/pgpkeys-developers.xml</filename>.
	Please note that entries are sorted by last name.</para>

	<para>&a.des.email; has
	written a shell script (<filename>head/share/pgpkeys/addkey.sh</filename>) to make this extremely simple. See the
	<ulink
	url="http://svnweb.FreeBSD.org/doc/head/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>Add an entry for yourself to
	<filename>src/share/misc/committers-<replaceable>repository</replaceable>.dot</filename>,
	where repository is either doc, ports or src, depending on the commit privileges
	you obtained.</para>
	</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>If you already have an account at the <ulink url="http://wiki.freebsd.org">&os; wiki</ulink>,
	make sure your mentor moves you from the
	<ulink url="http://wiki.freebsd.org/ContributorsGroup">Contributors group</ulink>
	to the
	<ulink url="http://wiki.freebsd.org/DevelopersGroup">Developers group</ulink>.
	Otherwise, consider signing up for an account so you can publish
	projects and ideas you are working on.</para>
	</listitem>

	<listitem>
	<para>Once you get access to the wiki, you may
	add yourself to the <ulink
	url="http://wiki.freebsd.org/HowWeGotHere">How We Got
	Here</ulink> and <ulink
	url="http://wiki.freebsd.org/IrcNicks">Irc Nicks</ulink>
	pages.</para>
	</listitem>

	<listitem>
	<para>If you subscribe to &a.svn-src-all.name;,
	&a.svn-ports-all.name; or &a.svn-doc-all.name;,
	you will probably want to unsubscribe to avoid receiving duplicate
	copies of commit messages and their followups.</para>
	</listitem>
	</itemizedlist>

	<note>
	<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>
	</note>
	</sect2>

	<sect2 id="conventions-everyone">
	<title>Guidelines For Everyone</title>

	<para>Whether or not you have commit rights:</para>

	<itemizedlist>
	<listitem>
	<para>Introduce yourself to the other developers, 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
	developer in FreeBSD. (You should also mention who your mentor
	will be). 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>
	</itemizedlist>

	<note>
	<para>If you are a developer but not a committer, you will
	not be subscribed to the committers or developers mailing lists;
	the subscriptions are derived from the access rights.</para>
	</note>
	</sect2>

	<sect2 id="mentors">
	<title>Mentors</title>

	<para>All new developers 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 developer community. Your mentor is also
	personally responsible for your actions during this initial
	period.</para>

	<para>For committers: 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>
	</sect2>
	</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 (c) [year] [your name]
	* 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 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.
	*
	* [id for your version control system, if any]
	*/</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 the &a.core; 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>

	<para>Project policy dictates that code under some non-BSD licenses
	must be placed only in specific sections of the repository, and
	in some cases, compilation must be conditional or even disabled
	by default. For example, the GENERIC kernel must be compiled
	under only licenses identical to or substantially similar to the
	BSD license. GPL, APSL, CDDL, etc, licensed software must not be
	compiled into GENERIC.</para>

	<para>Developers are reminded that in open source, getting "open"
	right is just as important as getting "source" right, as improper
	handling of intellectual property has serious consequences. Any
	questions or concerns should immediately be brought to the
	attention of the core team.</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><replaceable>repository</replaceable>-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 revision history
	to see who has committed changes in the past. &a.fenner.email; 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
	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 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 a version control system 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="&url.articles.pr-guidelines;/index.html">FreeBSD Problem Report Handling Guidelines</ulink></para>
	</listitem>

	<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.
	- This lets you query the PR database without needing to be connected to
	- the Internet.</para>
	+ GNATS tree by creating an <application>rsync</application> mirror.
	+ Then you can run GNATS commands locally, allowing you to query the PR
	+ database without an Internet connection.</para>

	<sect2>
	<title>Mirroring the GNATS Tree</title>

	- <para>It is possible to mirror the GNATS database by adding this line
	- to your <filename>supfile</filename>. 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>
	+ <para>It is possible to mirror the GNATS database by installing
	+ <filename role="package">net/rsync</filename>, and
	+ executing:</para>

	- <programlisting>gnats release=current prefix=/usr</programlisting>
	+ <screen>&prompt.user; <userinput>rsync -va rsync://bit0.us-west.freebsd.org/FreeBSD-bit/gnats .</userinput></screen>

	- <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>
	</sect2>

	<sect2 id="gnatstools">
	<title>Useful Tools</title>

	<para>Other than <command>edit-pr</command> there are a
	collection of tools in <filename>~gnats/tools/</filename>
	on <hostid>freefall</hostid> which can make
	working with PRs much easier.</para>

	<para><command>open-pr</command>, <command>close-pr</command>,
	<command>take-pr</command>, and <command>feedback-pr</command>
	take PR numbers as arguments and then ask you to select from a
	preexisting list of change reasons or let you type in your
	own.</para>

	<para><command>change-pr</command> is a multi purpose tool
	that lets you make multiple changes at the same time with one
	command.</para>

	<para>For example, to assign PR 123456 to yourself type
	<command>take-pr <replaceable>123456</replaceable></command>.
	If you want to set the PR to patched awaiting an MFC at
	the same time use:
	<command>change-pr -t -p -m "awaiting MFC"
	<replaceable>123456</replaceable></command></para>
	</sect2>
	</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>

	<variablelist>

	<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.email;</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.email;</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.re.members.email;</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.simon.email;</term>

	<listitem>
	<para>Simon is the
	<ulink url="&url.base;/security/">FreeBSD Security
	Officer</ulink>
	and oversees the &a.security-officer;.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.wollman.email;</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>&a.svn-src-all.name;, &a.svn-ports-all.name; and
	&a.svn-doc-all.name; are the mailing lists that the
	version control system uses to send commit messages to.
	You should <emphasis>never</emphasis> send email directly
	to these lists. 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.</para>

	<para>The &a.developers; is for the exclusive use of
	FreeBSD committers. In order to develop FreeBSD, committers must
	have the ability to openly discuss matters that will be resolved
	before they are publicly announced. Frank discussions of work in
	progress are not suitable for open publication and may harm FreeBSD.</para>

	<para>All FreeBSD committers are reminded to obey the copyright of the
	original author(s) of &a.developers; mail. Do not publish or
	forward messages from the &a.developers; outside the list
	membership without permission of all of the authors.</para>

	<para>Copyright violators will be removed from the &a.developers;,
	resulting in a suspension of commit privileges. Repeated or
	flagrant violations may result in permanent revocation of
	commit privileges.</para>

	<para>This list is
	<emphasis>not</emphasis> intended as a place for code reviews or a
	replacement for the &a.arch;. 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.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect1>

	<sect1 id="ssh.guide">
	<title>SSH Quick-Start Guide</title>

	<procedure>
	<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 the <filename><replaceable>yourlogin</replaceable></filename> file in
	<filename class="directory">/etc/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="coverity">
	<title>&coverity.prevent; Availability for &os; Committers</title>

	<para>In January 2006, the &os; Foundation obtained a license for
	&coverity.prevent; from &coverity; Ltd. With this donation, all
	&os; developers can obtain access to <application>Coverity
	Prevent</application> analysis results of all &os; Project
	software.</para>

	<para>&os; developers who are interested in obtaining access to the
	analysis results of the automated <application>Coverity
	Prevent</application> runs, can find out more by logging
	into <hostid>freefall</hostid> and reading the relevant bits of the
	files:</para>

	<variablelist>
	<varlistentry>
	<term><filename>/usr/local/coverity/coverity_license.txt</filename></term>
	<listitem>
	<para>The license terms to which the &os; developers will have
	to agree in order to use &coverity.prevent; analysis
	results.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><filename>/usr/local/coverity/coverity_announcement.txt</filename></term>
	<listitem>
	<para>The announcement posted to the developers' mailing list of the
	&os; Project. It contains useful information about the &os;
	Foundation and &coverity; Ltd., as well as signup information
	for registering with the &coverity.prevent; installation of the
	&os; Cluster.</para>

	<para>After reading and understanding the license terms
	of <filename>coverity_license.txt</filename>, all &os; developers
	who are interested in using the analysis results of
	&coverity.prevent; should read this file.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><filename>/usr/local/coverity/coverity_readme.txt</filename></term>
	<listitem>
	<para>A short guide about fixes which are committed to the &os;
	source tree after being detected by &coverity.prevent; and
	analyzed by a &os; developer.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>The &os; Wiki includes a mini-guide for developers who are
	interested in working with the &coverity.prevent; analysis reports:
	<ulink url="http://wiki.freebsd.org/CoverityPrevent"></ulink>. Please
	note that this mini-guide is only readable by &os; developers, so if you
	cannot access this page, you will have to ask someone to add you to the
	appropriate Wiki access list.</para>

	<para>Finally, all &os; developers who are going to use &coverity.prevent;
	are always encouraged to ask for more details and usage information, by
	posting any questions to the mailing list of the &os; developers.</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>, or
	<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 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>surprized</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">
	http://www.FreeBSD.org/doc/en_US.ISO8859-1/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 repository 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.base;/administration.html">
	http://www.FreeBSD.org/administration.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 a version control system 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
	<emphasis>very</emphasis> 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_7_0</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>
	</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 architecture ports during recent
	release cycles 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 &arch.i386;, and our 64-bit
	reference platform is &arch.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 &arch.i386; and &arch.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>The &arch.ia64; platform has many of the same complications that
	&arch.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 asking for differences between revisions, 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 be
	easily available for all developers. Embedded platforms may
	substitute an emulator available in the FreeBSD cluster for
	actual hardware.</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>Tier 1 architectures are expected to be completely
	integrated into the source tree and have all features
	necessary to produce an entire system relevant for that target
	architecture. Tier 1 architectures generally have at least 6 active
	developers.</para>

	<para>Tier 1 architectures are expected to be fully supported by
	the ports system. All the ports should build on a Tier 1
	platform, or have the appropriate filters to prevent the
	inappropriate ones from building there. The packaging system
	must support all Tier 1 architectures. To ensure an
	architecture's Tier 1 status, proponents of that architecture
	must show that all relevant packages can be built on that
	platform.</para>

	<para>Tier 1 embedded architectures must be able to cross-build
	packages on at least one other Tier 1 architecture. The
	packages must be the most relevant for the platform, but may
	be a non-empty subset of those that build natively.</para>

	<para>Tier 1 architectures must be fully documented. All basic
	operations need to be covered by the handbook or other
	documents. All relevant integration documentation must also
	be integrated into the tree, or readily available.</para>

	<para>Current Tier 1 platforms are &arch.i386; and &arch.amd64;.</para>
	</sect2>

	<sect2>
	<title>Tier 2: Developmental Architectures</title>

	<para>Tier 2 platforms are not supported by the security officer
	and release engineering teams. Platform maintainers are
	responsible for toolchain support in the tree. The toolchain
	maintainer is expected to work with the platform maintainers
	to refine these changes. Major new toolchain components are
	allowed to break support for Tier 2 architectures if the
	FreeBSD-local changes have not been incorporated upstream. The
	toolchain maintainers are expected to provide prompt review of
	any proposed changes and cannot block, through their inaction,
	changes going into the tree. 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. New features that may be difficult
	to implement on Tier 2 architectures should provide a means of
	disabling them on those architectures. 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 multi-user on
	actual hardware. Generally, there must be at least three active
	developers working on the platform.</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. Well supported
	niche architectures may also be Tier 2.</para>

	<para>Tier 2 architectures may have some support for them
	integrated into the ports infrastructure. They may have cross
	compilation support added, at the discretion of portmgr. Some
	ports must built natively into packages if the package system
	supports that architecture. If not integrated into the base
	system, some external patches for the architecture for ports
	must be available.</para>

	<para>Tier 2 architectures can be integrated into the FreeBSD
	handbook. The basics for how to get a system running must be
	documented, although not necessarily for every single board or
	system a Tier 2 architecture supports. The supported hardware
	list must exist and should be no more than a couple of months
	old. It should be integrated into the FreeBSD
	documentation.</para>

	<para>Current Tier 2 platforms are &arch.arm;, &arch.ia64;, &arch.pc98;, &arch.powerpc;, and &arch.sparc64;.</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 in the early stages of
	development, for non-mainstream hardware platforms, or which
	are considered legacy systems unlikely to see broad future
	use. New Tier 3 systems will not be committed to the base
	source tree. 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.
	Platforms that transition to Tier 3 status may be removed from
	the tree if they are no longer actively supported by the
	FreeBSD developer community at the discretion of the release
	engineer.</para>

	<para>Tier 3 platforms may have ports support, either integrated
	or external, but do not require it.</para>

	<para>Tier 3 platforms must have the basics documented for how
	to build a kernel and how to boot it on at least one target
	hardware or emulation environment. This documentation need
	not be integrated into the FreeBSD tree.</para>

	<para>Current Tier 3 platforms are &arch.mips; and &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 from your machine (located
	in the <filename>ports/Tools/scripts</filename> directory).
	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 port's
	category <filename>Makefile</filename>. It was
	written by &a.mharo.email;, &a.will.email;, and &a.garga.email;. When sending
	questions about this script to the &a.ports;, please also CC
	&a.crees.email;, the current maintainer.</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>Removing an Existing Port</title>

	<qandaentry>
	<question>
	<para>How do I remove an existing port?</para>
	</question>

	<answer>
	<para>First, please read the section about repository
	copies. Before you remove the port, you have to verify
	there are no other ports depending on it.</para>
	<itemizedlist>
	<listitem>
	<para>Make sure there is no dependency on the port
	in the ports collection:</para>
	<itemizedlist>
	<listitem>
	<para>The port's PKGNAME should appear in exactly one
	line in a recent INDEX file.</para>
	</listitem>
	<listitem>
	<para>No other ports should contain any reference to
	the port's directory or PKGNAME in their
	Makefiles</para>
	</listitem>
	</itemizedlist>
	</listitem>
	<listitem>
	<para>Then, remove the port:</para>

	<procedure>
	<step>
	<para>Remove the port's files via <command>svn remove</command>.</para>
	</step>

	<step>
	<para>Remove the <makevar>SUBDIR</makevar> listing of the port
	in the parent directory <filename>Makefile</filename>.</para>
	</step>

	<step>
	<para>Add an entry to
	<filename>ports/MOVED</filename>.</para>
	</step>

	<step>
	<para>Remove the port from
	<filename>ports/LEGAL</filename> if it is there.</para>
	</step>
	</procedure>
	</listitem>
	</itemizedlist>

	<para>Alternatively, you can use the <command>rmport</command>
	script, from <filename class="directory">ports/Tools/scripts</filename>.
	This script was written by &a.vd.email;. When sending
	questions about this script to the &a.ports;, please also CC
	&a.crees.email;, the current maintainer.</para>
	</answer>
	</qandaentry>
	</qandadiv>

	<qandadiv>
	<title>Re-adding a Deleted Port</title>

	<qandaentry>
	<question>
	<para>How do I re-add a deleted port?</para>
	</question>

	<answer>
	<para>This is essentially the reverse of deleting a port.</para>
	<procedure>
	<step>
	<para>Figure out when the port was removed. Use this
	<ulink url="http://people.freebsd.org/~crees/removed_ports/index.xml">list</ulink>
	and then copy the last living revision of the port:

	<screen>&prompt.user; <userinput>cd /usr/ports/<replaceable>category
	</replaceable></userinput>
	&prompt.user; <userinput>svn cp 'svn+ssh://svn.freebsd.org/ports/<replaceable>category</replaceable>/<replaceable>portname</replaceable>/@{<replaceable>YYYY-MM-DD</replaceable>}' <replaceable>portname</replaceable>
	</userinput></screen>

	Pick a date that is before the removal but after the last true
	commit.</para>
	</step>

	<step>
	<para>Perform whatever changes are necessary to make the port
	work again. If it was deleted because the distfiles are
	no longer available you will need to volunteer to host them
	yourself, or find someone else to do so.</para>
	</step>

	<step>
	<para><command>svn add</command> or <command>svn remove</command>
	any appropriate files.</para>
	</step>

	<step>
	<para>Restore the <makevar>SUBDIR</makevar> listing of the port
	in the parent directory <filename>Makefile</filename>, and
	delete the entry from <filename>ports/MOVED</filename>.</para>
	</step>

	<step>
	<para>If the port had an entry in
	<filename>ports/LEGAL</filename>, restore it.</para>
	</step>

	<step>
	<para><command>svn commit</command> these changes, preferably in
	one step.</para>
	</step>
	</procedure>

	<tip>
	<para><command>addport</command> now detects when the port to
	add has previously existed, and should handle all except
	the <filename>ports/LEGAL</filename> step automatically.</para>
	</tip>
	</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>What do I need to do?</para>
	</question>

	<answer>
	<para>With Subversion, a repo copy can be done by any
	committer:</para>

	<itemizedlist>
	<listitem>
	<para>Doing a repo copy:</para>

	<procedure>
	<step>
	<para>First make sure that you were using an up to
	date ports tree and the target directory does not
	exist.</para>
	</step>

	<step>
	<para>Use <command>svn move</command> or <command>svn
	copy</command> to do the repo copy.</para>
	</step>

	<step>
	<para>Upgrade the copied port to the new version.
	Remember to change the <makevar>LATEST_LINK</makevar>
	so there are no duplicate ports with the same name.
	In some rare cases it may be necessary to change the
	<makevar>PORTNAME</makevar> instead of
	<makevar>LATEST_LINK</makevar>, but this should only
	be done when it is really needed — e.g., using
	an existing port as the base for a very similar
	program with a different name, or upgrading a port to
	a new upstream version which actually changes the
	distribution name, like the transition from
	<filename>textproc/libxml</filename> to
	<filename>textproc/libxml2</filename>. In most cases,
	changing <makevar>LATEST_LINK</makevar> should
	suffice.</para>
	</step>

	<step>
	<para>Add the new subdirectory to the
	<makevar>SUBDIR</makevar> listing in the parent
	directory <filename>Makefile</filename>. 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 an entry to
	<filename>ports/MOVED</filename>, if you remove the
	original port.</para>
	</step>

	<step>
	<para>Commit all changes on one commit. A forced commit
	is no longer needed with Subversion.</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 and the
	old <makevar>SUBDIR</makevar> 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>

	<para>For more information on the background and
	policies surrounding a ports freeze, see the
	<ulink url="&url.base;/portmgr/qa.html">Portmgr
	Quality Assurance page</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>What is a <quote>ports slush</quote> or
	<quote>feature freeze</quote>?</para>
	</question>

	<answer>
	<para>During a release cycle the ports tree may be in a
	<quote>slush</quote> state instead of in a hard freeze.
	The goal during a slush is to reach a stable ports tree
	to avoid rebuilding large sets of packages for the
	release and to tag the tree. During this time
	<quote>sweeping changes</quote> are prohibited unless
	specifically permitted by portmgr. Complete details
	about what qualifies as a sweeping change can be found
	on the <ulink
	- url="&url.base/portmgr;/implementation.html">Portmgr
	+ url="&url.base;/portmgr/implementation.html">Portmgr
	Implementation page</ulink>.</para>

	<para>The benefit of a slush as opposed to a complete
	freeze is that it allows maintainers to continue adding
	new ports, making routine version updates, and bug fixes
	to most existing ports, as long as the number of
	affected ports is minimal. For example, updating the
	shared library version on a port that many other ports
	depend on.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>How long is a ports freeze or slush?</para>
	</question>

	<answer>
	<para>A freeze only lasts long enough to tag the tree.
	A slush usually lasts a week or two, but may last
	longer.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>What does it mean to me?</para>
	</question>

	<answer>
	<para>During a ports freeze, you are not allowed to
	commit anything to the tree without explicit approval
	from the Ports Management Team. <quote>Explicit
	approval</quote> here means that you send a patch to
	the Ports Management Team for review and get a reply
	saying, <quote>Go ahead and commit it.</quote>
	</para>

	<para>Not everything is allowed to be committed during
	a freeze. Please see the <ulink
	url="&url.base;/portmgr/qa.html">Portmgr Quality
	Assurance page</ulink> for more information.
	</para>

	<para>Note that you do not have implicit permission to fix
	a port during the freeze just because it is
	broken.</para>

	<para>During a ports slush, you are still allowed to
	commit but you must exercise more caution in what you
	commit. Furthermore a special note (typically
	<quote>Feature Safe: yes</quote>) must be added to the
	commit message.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>How do I know when the ports slush starts?</para>
	</question>

	<answer>
	<para>The Ports Management Team 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 slush 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 slush starts, there will be another
	announcement to the &a.ports; and &a.committers;, of course.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>How do I know when the freeze or slush ends?</para>
	</question>

	<answer>
	<para>A few hours after the release, the Ports Management
	Team will send out a mail to the &a.ports; and &a.committers;
	announcing the end of the ports freeze or slush. Note
	that the release being cut does not automatically indicate
	the end of the freeze. We have to make sure there will
	be no 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>Please see
	<ulink url="&url.books.porters-handbook;/makefile-categories.html#PROPOSING-CATEGORIES">
	Proposing a New Category</ulink> in the Porter's Handbook.
	Once that procedure has been followed and the PR has been
	assigned to &a.portmgr;, it is their decision whether or
	not to approve it. If they do, it is their responsibility
	to do the following:</para>

	<procedure>
	<step>
	<para>Perform any needed moves. (This only applies
	to physical categories.)</para>
	</step>

	<step>
	<para>Update the <makevar>VALID_CATEGORIES</makevar>
	definition in <filename>ports/Mk/bsd.port.mk</filename>.
	</para>
	</step>

	<step>
	<para>Assign the PR back to you.</para>
	</step>
	</procedure>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>What do I need to do to implement a new physical
	category?</para>
	</question>

	<answer>
	<procedure>
	<step>
	<para>Upgrade each moved 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 <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 move
	operation.
	Hint: do not forget to look at the
	<makevar>PKGORIGIN</makevar>s of any slave ports of the
	ports you just moved!</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>Add appropriate entries to
	<filename>ports/MOVED</filename>.</para>
	</step>

	<step>
	<para>Update the documentation by modifying the
	following:</para>

	<itemizedlist>
	<listitem>
	<para>the
	<ulink url="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">
	list of categories</ulink> in the Porter's Handbook</para>
	</listitem>

	<listitem>
	<para>
	<filename>www/en/ports/categories</filename>.
	Note that these are now displayed by sub-groups,
	as specified in
	<filename>www/en/ports/categories.descriptions</filename>.
	</para>
	</listitem>
	</itemizedlist>
	<para>(Note: these are
	in the docs, not the ports, repository). If you
	are not a docs committer, you will need to submit
	a PR for this.</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>

	<para>It is not necessary to manually update the <ulink
	url="&url.base;/ports/index.html">ports web pages</ulink>
	to reflect the new category. This is now done automatically
	via your change to <filename>www/en/ports/categories</filename>
	and the daily automated rebuild of <filename>INDEX</filename>.
	</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>What do I need to do to implement a new virtual
	category?</para>
	</question>

	<answer>
	<para>This is much simpler than a physical category. You
	only need to modify the following:</para>

	<itemizedlist>
	<listitem>
	<para>the
	<ulink url="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">
	list of categories</ulink> in the Porter's Handbook</para>
	</listitem>

	<listitem>
	<para><filename>www/en/ports/categories</filename></para>
	</listitem>
	</itemizedlist>
	</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/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, <filename>INDEX</filename> is no longer stored
	in the SVN repository. The file can either be generated
	by running <command>make index</command>, or a pre-generated
	version can be downloaded with <command>make
	fetchindex</command>.</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 Management Team 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="non-committers">
	<title>Issues Specific To Developers Who Are Not Committers</title>

	<para>A few people who have access to the FreeBSD machines do not
	have commit bits. For instance, the project is willing to give
	access to the GNATS database to contributors who have shown interest
	and dedication in working on Problem Reports.</para>

	<para>Almost all of this document will apply to these developers as
	well (except things specific to commits and the mailing list
	memberships that go with them). In particular, we recommend that
	you read:</para>

	<itemizedlist>
	<listitem>
	<para>
	<link linkend="admin">Administrative Details</link>
	</para>
	</listitem>

	<listitem>
	<para>
	<link linkend="conventions-everyone">Conventions</link>
	</para>

	<note>
	<para>You should get your mentor to add you to the
	<quote>Additional Contributors</quote>
	(<filename>doc/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename>),
	if you are not already listed there.</para>
	</note>
	</listitem>

	<listitem>
	<para>
	<link linkend="developer.relations">Developer Relations</link>
	</para>
	</listitem>

	<listitem>
	<para>
	<link linkend="ssh.guide">SSH Quick-Start Guide</link>
	</para>
	</listitem>

	<listitem>
	<para>
	<link linkend="rules">The FreeBSD Committers' Big List of Rules</link>
	</para>
	</listitem>
	</itemizedlist>

	</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.email; 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>Free 4-CD and DVD Sets</term>

	<listitem>
	<para>&os; committers can get a free 4-CD or DVD set at
	conferences from <ulink url="http://www.freebsdmall.com">
	&os; Mall, Inc.</ulink>. The sets are no longer available
	as a subscription due to the high shipment costs to
	countries outside the USA.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Freenode IRC Cloaks</term>

	<listitem>
	<para>&os; developers may request a cloaked hostmask for their
	account on the Freenode IRC network in the form of
	<literal>freebsd/developer/</literal><replaceable>freefall name</replaceable>
	or <literal>freebsd/developer/</literal><replaceable>NickServ name</replaceable>.
	To request a cloak, send an email to &a.eadler.email; with your
	requested hostmask and NickServ account name.</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.email; for horror stories.</para>
	</listitem>
	</itemizedlist>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>How do I add a new file to a 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
	the add operation as you normally would. This works
	fine for the <literal>doc</literal> and
	<literal>ports</literal> trees. The <literal>src</literal>
	tree uses SVN and requires more care because of the
	<literal>mergeinfo</literal> properties. See section 1.4.6
	of the <ulink url="http://wiki.freebsd.org/SubversionPrimer">
	Subversion Primer</ulink> for details. Refer to <ulink
	url="http://wiki.freebsd.org/SubversionPrimer/Merging">
	SubversionPrimer/Merging</ulink> for details on how to
	perform an MFC.</para>
	</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" pgwide="1">
	<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>

	<row>
	<entry><literal>Security:</literal></entry>

	<entry>If the change is related to a security
	vulnerability or security exposure, include one or
	more references or a description of the
	issue.</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>

	<qandaentry>
	<question>
	<para>I would like to mentor a new committer. What process
	do I need to follow?</para>
	</question>

	<answer>
	<para>See the <ulink
	url="http://www.freebsd.org/internal/new-account.html">New
	Account Creation Procedure</ulink> document on the internal
	pages.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</sect1>
	</article>
	Index: projects/entities/en_US.ISO8859-1/articles/compiz-fusion/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/compiz-fusion/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/compiz-fusion/article.xml (revision 41355)
	@@ -1,398 +1,396 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	]>

	<article lang="en">
	<articleinfo>
	<title>Installing and using Compiz Fusion</title>

	<author>
	<firstname>Manolis</firstname>
	<surname>Kiagias</surname>
	<affiliation>
	<address><email>manolis@FreeBSD.org</email></address>
	</affiliation>
	</author>

	<copyright>
	<year>2008</year>
	<holder role="mailto:manolis@FreeBSD.org">Manolis Kiagias</holder>
	</copyright>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	&tm-attrib.general;
	</legalnotice>

	<abstract>
	<para>The Linux world has been overwhelmed lately by what seems to be
	the latest fashion: 3D Desktop effects. While their usefulness is
	rather heavily debated, the wow factor behind the composited desktop
	holds quite well. Several different programs have emerged, like
	<ulink url="http://compiz.org/"><application>Compiz</application></ulink>,
	<ulink url="http://www.beryl-project.org/"><application>Beryl</application></ulink>,
	and the latest <ulink
	url="http://www.compiz-fusion.org/"><application>Compiz Fusion</application></ulink>.
	You do not need to miss these effects when using &os;. These
	instructions will help you install and configure your system for the
	latest 3D desktop experience using
	<application>Compiz Fusion</application> and nVidia drivers
	(if applicable).</para>
	</abstract>
	</articleinfo>

	<sect1 id="introduction">
	<title>Introduction</title>

	<para>While installing <application>Compiz Fusion</application> from
	the Ports Collection is a rather trivial task, configuring it
	requires a few more steps that are not described in the port's
	documentation. This article will help you configure your
	<application>&xorg;</application> server for composite operation,
	setup your nVidia card, and finally guide you to the final steps for
	executing the <command>compiz</command> program itself.</para>

	<para>After reading this article, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>How to setup the latest nVidia driver (if required) for your
	system.</para>
	</listitem>

	<listitem>
	<para>How to setup your <filename>xorg.conf</filename> file for
	desktop composition.</para>
	</listitem>

	<listitem>
	<para>How to install and configure
	<application>Compiz Fusion</application> using the
	Ports Collection.</para>
	</listitem>

	<listitem>
	<para>How to troubleshoot common problems associated with
	desktop effects.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="nvidia-setup">
	<title>Setting up the &os; nVidia driver</title>

	<para>Desktop effects can cause quite a load on your graphics card.
	If you are using an nVidia-based graphics card, you will need to
	install and configure the proprietary &os; driver that is suitable for
	your system. If you are using another card, that you know can handle
	desktop effects, you may skip this section and continue with the
	<filename>xorg.conf</filename> configuration.</para>

	<sect2 id="determine-driver">
	<title>Determining the correct driver to use</title>

	<para>There are various versions of the nVidia drivers in the
	Ports Collection. The correct one to use depends on the actual
	model (and age) of your graphics card:</para>

	<itemizedlist>
	<listitem>
	<para>The latest versions of nVidia cards are supported by the
	<filename role="package">x11/nvidia-driver</filename> port.</para>
	</listitem>

	<listitem>
	<para>nVidia cards like the GeForce 2MX/3/4 series are supported by
	the 96<replaceable>XX</replaceable> series of drivers, available
	in the <filename role="package">x11/nvidia-driver-96xx</filename>
	port.</para>
	</listitem>

	<listitem>
	<para>Even older cards, like GeForce and RIVA TNT are supported
	by the 71<replaceable>XX</replaceable> series of drivers,
	available in the
	<filename role="package">x11/nvidia-driver-71xx</filename>
	port.</para>
	</listitem>
	</itemizedlist>

	<para>In fact, nVidia provides detailed information on which card is
	supported by which driver. This information is available directly
	on their web site: <ulink
	url="http://www.nvidia.com/object/IO_32667.html"></ulink>.</para>
	</sect2>

	<sect2 id="install-driver">
	<title>Installing the nVidia driver</title>

	<para>Having determined the correct driver to use for your card,
	installation is as simple as installing any other port.</para>

	<note>
	<para>Make sure to update your ports tree using your favorite method
	- (like <application>csup</application>,
	- <application>CVSup</application> or
	- <application>portsnap</application>) before you install any
	+ (e.g., <application>portsnap</application>) before you install any
	application from the ports system. Graphics drivers and the
	desktop effects programs are under heavy development, and are
	updated regularly.</para>
	</note>

	<para>For example, to install the latest driver:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/x11/nvidia-driver</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>The driver will create a kernel module, which should be loaded
	at system startup. You will need to add the following line to the
	<filename>/boot/loader.conf</filename> file:</para>

	<programlisting>nvidia_load="YES"</programlisting>

	<note>
	<para>You may attempt to immediately load the kernel module into the
	running kernel by issuing a command like
	<command>kldload nvidia</command>, however it has been noted that
	the latest versions of <application>&xorg;</application> will not
	function properly if the driver is not loaded at boot time. After
	editing <filename>/boot/loader.conf</filename>, a reboot is
	recommended.</para>
	</note>

	<para>With the kernel module loaded, you normally only need to change
	a single line in your <filename>xorg.conf</filename> file to enable
	the proprietary driver:</para>

	<para>Find the following line in
	<filename>/etc/X11/xorg.conf</filename>:</para>

	<programlisting>Driver "nv"</programlisting>

	<para>and change it to:</para>

	<programlisting>Driver "nvidia"</programlisting>

	<para>Start your GUI as usual, and you should be greeted by the nVidia
	splash. Everything should work as usual. Note, that at this point
	you have only set up <application>&xorg;</application> to use the
	nVidia driver, but further configuration is needed before you can
	actually use 3D desktop effects. This is described in the following
	sections.</para>

	<note>
	<para>Although not strictly necessary, you may also wish to install
	<filename role="package">x11/nvidia-xconfig</filename> and
	<filename role="package">x11/nvidia-settings</filename> ports. The
	former can assist you in writing settings to
	<filename>/etc/X11/xorg.conf</filename> from the command line, and
	the latter will allow you to modify screen settings from a GUI while
	running the <application>&xorg;</application> system.</para>
	</note>
	</sect2>
	</sect1>

	<sect1 id="xorg-configuration">
	<title>Configuring xorg.conf for desktop effects</title>

	<para>Before you install and run
	<application>Compiz Fusion</application>, you need to add a few
	settings to <filename>/etc/X11/xorg.conf</filename>:</para>

	<para>Add the following section to enable composite effects:</para>

	<programlisting>Section "Extensions"
	Option "Composite" "Enable"
	EndSection</programlisting>

	<para>Locate the <quote>Screen</quote> section which should look similar
	to the one below:</para>

	<programlisting>Section "Screen"
	Identifier "Screen0"
	Device "Card0"
	Monitor "Monitor0"
	...</programlisting>

	<para>and add the following two lines (after <quote>Monitor</quote> will
	do):</para>

	<programlisting>DefaultDepth 24
	Option "AddARGBGLXVisuals" "True"</programlisting>

	<para>Locate the <quote>Subsection</quote> that refers to the
	screen resolution that you wish to use. For example, if you wish to
	use 1280x1024, locate the section that follows. If the desired
	resolution does not appear in any subsection, you may add the relevant
	entry by hand:</para>

	<programlisting>SubSection "Display"
	Viewport 0 0
	Modes "1280x1024"
	EndSubSection</programlisting>

	<para>A color depth of 24 bits is needed for desktop composition,
	change the above subsection to:</para>

	<programlisting>SubSection "Display"
	Viewport 0 0
	Depth 24
	Modes "1280x1024"
	EndSubSection</programlisting>

	<para>Finally, confirm that the <quote>glx</quote> and
	<quote>extmod</quote> modules are loaded in the <quote>Module</quote>
	section:</para>

	<programlisting>Section "Module"
	Load "extmod"
	Load "glx"
	...</programlisting>

	<note>
	<para>If you installed the
	<filename role="package">x11/nvidia-xconfig</filename> port,
	you should be able to perform most of the above settings by
	entering the following commands (as root):</para>

	<screen>&prompt.root; <userinput>nvidia-xconfig --add-argb-glx-visuals</userinput>
	&prompt.root; <userinput>nvidia-xconfig --composite</userinput>
	&prompt.root; <userinput>nvidia-xconfig --depth=24</userinput></screen>

	<para>You may wish to run <command>nvidia-xconfig -A \| more</command>
	to see a list of all the options offered by the above program.</para>
	</note>
	</sect1>

	<sect1 id="compiz-fusion">
	<title>Installing and configuring Compiz Fusion</title>

	<para>Installing <application>Compiz Fusion</application>
	is as simple as any other port:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/compiz-fusion</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>Make sure to select the <quote>EXTRA</quote> plugins and the
	<quote>EMERALD</quote> window decorator from the options dialog that
	appears. If you are using <application>GNOME</application>, or
	already have support for <command>gconf</command> in your system, you
	may also wish to select <quote>gconf support</quote>. In this way,
	your effect settings will be integrated with the other desktop settings,
	and will be viewable via <command>gconf-editor</command>.
	<application>Compiz Fusion</application>
	<emphasis>can</emphasis> however save its settings to flat files, if
	such an integration is not wanted. In this case, a
	<filename>.compizconfig</filename> directory will be created inside
	your home directory.</para>

	<para>When the installation is finished, start your graphic desktop and
	at a terminal, enter the following commands (as a normal user):</para>

	<screen>&prompt.user; <userinput>compiz --replace --sm-disable --ignore-desktop-hints ccp &</userinput>
	&prompt.user; <userinput>emerald --replace &</userinput></screen>

	<para>Your screen will flicker for a few seconds, as your window manager
	(e.g. <application>Metacity</application> if you are using
	<application>GNOME</application>) is replaced by
	<application>Compiz Fusion</application>.
	<application>Emerald</application> takes care of the window
	decorations (i.e. close, minimize, maximize buttons, title bars
	and so on).</para>

	<para>You may convert this to a trivial script and have it run at
	startup automatically (e.g. by adding to <quote>Sessions</quote> in
	a <application>GNOME</application> desktop):</para>

	<programlisting>#! /bin/sh
	compiz --replace --sm-disable --ignore-desktop-hints ccp &
	emerald --replace &</programlisting>

	<para>Save this in your home directory as, for example,
	<filename>start-compiz</filename> and make it executable:</para>

	<screen>&prompt.user; <userinput>chmod +x ~/start-compiz</userinput></screen>

	<para>Then use the GUI to add it to
	<guimenuitem>Startup Programs</guimenuitem>
	(located in <guimenuitem>System</guimenuitem>,
	<guimenuitem>Preferences</guimenuitem>,
	<guimenuitem>Sessions</guimenuitem> on a
	<application>GNOME</application> desktop).</para>

	<para>To actually select all the desired effects and their settings,
	execute (again as a normal user) the
	<application>Compiz Config Settings Manager</application>:</para>

	<screen>&prompt.user; <userinput>ccsm</userinput></screen>

	<note>
	<para>In <application>GNOME</application>, this can also be found in
	the <guimenuitem>System</guimenuitem>,
	<guimenuitem>Preferences</guimenuitem> menu.</para>
	</note>

	<para>If you have selected <quote>gconf support</quote> during the build,
	you will also be able to view these settings using
	<command>gconf-editor</command> under <literal>apps/compiz</literal>.
	</para>
	</sect1>

	<sect1 id="compiz-troubleshooting">
	<title>Troubleshooting Compiz Fusion</title>

	<para>The following section covers frequently asked questions regarding
	problems when running
	<application>Compiz Fusion</application>.</para>

	<qandaset>
	<qandaentry>
	<question id="no-decorations">
	<para>I have installed
	<application>Compiz Fusion</application>,
	and after running the commands you mention, my windows are left
	without title bars and buttons. What is wrong?</para>
	</question>

	<answer>
	<para>You are probably missing a setting in
	<filename>/etc/X11/xorg.conf</filename>. Review this file
	carefully and check especially the <literal>DefaultDepth</literal>
	and <literal>AddARGBGLXVisuals</literal> directives.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="xorg-crash">
	<para>When I run the command to start
	<application>Compiz Fusion</application>, the X server
	crashes and I am back at the console. What is wrong?</para>
	</question>

	<answer>
	<para>If you check your <filename>/var/log/Xorg.0.log</filename>
	file, you will probably find error messages during the X
	startup. The most common would be:</para>

	<screen>(EE) NVIDIA(0): Failed to initialize the GLX module; please check in your X
	(EE) NVIDIA(0): log file that the GLX module has been loaded in your X
	(EE) NVIDIA(0): server, and that the module is the NVIDIA GLX module. If
	(EE) NVIDIA(0): you continue to encounter problems, Please try
	(EE) NVIDIA(0): reinstalling the NVIDIA driver.</screen>

	<para>This is usually the case when you upgrade
	<application>&xorg;</application>. You will need to reinstall the
	<filename role="package">x11/nvidia-driver</filename> port so
	glx is built again.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</sect1>
	</article>
	Index: projects/entities/en_US.ISO8859-1/articles/contributors/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/contributors/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/contributors/article.xml (revision 41355)
	@@ -1,428 +1,427 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;

	<!ENTITY % contrib.ent SYSTEM "contrib.ent">
	%contrib.ent;
	<!ENTITY % not.published "IGNORE">
	]>

	<article lang='en'>
	<articleinfo>
	<title>Contributors to FreeBSD</title>

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	- &tm-attrib.cvsup;
	&tm-attrib.sun;
	&tm-attrib.general;
	</legalnotice>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>

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

	<note>
	<para>As of 2010, the following section is several years out-of-date.
	Donations from the past several years appear
	<ulink url="&url.base;/donations/donors.html">here</ulink>.
	</para>
	</note>

	<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.email; 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.email;</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.email;</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.email;</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.email;,
	provided Wangtek and Archive QIC-02 tape drives in order to
	improve the <devicename>wt</devicename> driver.</para>
	</listitem>

	<listitem>
	<para>Ernst Winter (<ulink url="http://berklix.org/ewinter/">Deceased</ulink>)
	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>&a.kuku.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.email; 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>

	<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="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 reverse 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 reverse chronological order:</emphasis></para>

	&contrib.develalumni;
	</sect1>

	<sect1 id="contrib-portmgralumni">
	<title>Ports Management Team Alumni</title>

	<indexterm><primary>portmgr team</primary></indexterm>
	<para>The following people were members of the FreeBSD portmgr team during
	the periods indicated. We thank them for their past efforts in the
	service of the FreeBSD project.</para>

	<para><emphasis>In rough reverse chronological order:</emphasis></para>

	&contrib.portmgralumni;
	</sect1>

	<sect1 id="contrib-develinmemoriam">
	<title>Development Team: In Memoriam</title>

	<indexterm><primary>development team</primary></indexterm>
	<para>During the many years that the FreeBSD Project has been in
	existence, sadly, some of our developers have passed away.
	Here are some remembrances.</para>

	<para><emphasis>In rough reverse chronological order of their
	passing:</emphasis></para>

	&contrib.develinmemoriam;
	</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>
	Index: projects/entities/en_US.ISO8859-1/articles/contributors/contrib.additional.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/contributors/contrib.additional.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/contributors/contrib.additional.xml (revision 41355)
	@@ -1,11124 +1,11169 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!-- $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>AIDA Shinra
	<email>aida-s@jcom.home.ne.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 Myles Landwehr
	<email>aaron@snaphat.com</email></para>
	</listitem>

	<listitem>
	<para>Aaron Smith
	<email>aaron@mutex.org</email></para>
	</listitem>

	<listitem>
	<para>Aaron Straup Cope
	<email>ascope@cpan.org</email></para>
	</listitem>

	<listitem>
	<para>Aaron Voisine
	<email>voisine@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Aaron Zauner
	<email>az_mail@gmx.at</email></para>
	</listitem>

	<listitem>
	<para>Aasmund Eikli
	<email>inter@o12a.com</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 C. Migus
	<email>adam@migus.org</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 Jette
	<email>jettea46@yahoo.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 McLaurin
	<email>adam.freebsd@fastmail.fm</email></para>
	</listitem>

	<listitem>
	<para>Adam Strohl
	<email>troll@digitalspark.net</email></para>
	</listitem>

	<listitem>
	<para>Adam Wight
	<email>adamw@tulum.brsys.com</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 Filipi-Martin
	<email>adrian@ubergeeks.com</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 Pircalabu
	<email>apircalabu@bitdefender.com</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>Aftab Jahan Subedar
	<email>jahan@bol-online.com</email></para>
	</listitem>

	<listitem>
	<para>Ajit Thyagarajan</para>
	</listitem>

	<listitem>
	<para>Akinori YAMADA
	<email>yamada-a@nextcom.co.jp</email></para>
	</listitem>

	<listitem>
	<para>Akira Ikeuchi
	<email>a_ikeuchi@mic.mitsumi.co.jp</email></para>
	</listitem>

	<listitem>
	<para>Akira SAWADA</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>Al Hoang
	<email>hoanga@mac.com</email></para>
	</listitem>

	<listitem>
	<para>Alain Kalker
	<email>A.C.P.M.Kalker@student.utwente.nl</email></para>
	</listitem>

	<listitem>
	<para>Alan Amesbury
	<email>amesbury@indefi.net</email></para>
	</listitem>

	<listitem>
	<para>Alan Bawden
	<email>alan@curry.epilogue.com</email></para>
	</listitem>

	<listitem>
	<para>Alan Snelson
	<email>Alan@Wave2.co.uk</email></para>
	</listitem>

	<listitem>
	<para>Albert Graef
	<email>Dr.Graef@t-online.de</email></para>
	</listitem>

	<listitem>
	<para>Aldert Nooitgedagt
	<email>aldert@nooitgedagt.net</email></para>
	</listitem>

	<listitem>
	<para>Aldis Berjoza
	<email>killasmurf86@gmail.com</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>Aleksandr S. Goncharov
	<email>mraleks@bk.ru</email></para>
	</listitem>

	<listitem>
	<para>Alex D. Chen
	<email>dhchen@elearning.nsysu.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>Alex Deiter
	<email>tiamat@komi.mts.ru</email></para>
	</listitem>

	<listitem>
	<para>Alex G. Bulushev
	<email>bag@demos.su</email></para>
	</listitem>

	<listitem>
	<para>Alex Kapranoff
	<email>alex@kapranoff.ru</email></para>
	</listitem>

	<listitem>
	<para>Alex Keda
	<email>admin@lissyara.su</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 M
	<email>alex@myzona.net</email></para>
	</listitem>

	<listitem>
	<para>Alex Miller
	<email>asm@asm.kiev.ua</email></para>
	</listitem>

	<listitem>
	<para>Alex Perel
	<email>veers@disturbed.net</email></para>
	</listitem>

	<listitem>
	<para>Alex Pesternikov
	<email>ap@page2rss.com</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 Samorukov
	<email>samm@os2.kiev.ua</email></para>
	</listitem>

	<listitem>
	<para>Alex Semenyaka
	<email>alex@rinet.ru</email></para>
	</listitem>

	<listitem>
	<para>Alex Steiner
	<email>ast@treibsand.com</email></para>
	</listitem>

	<listitem>
	<para>Alex Trull
	<email>alexander@trull.com</email></para>
	</listitem>

	<listitem>
	<para>Alex Varju
	<email>freebsd-ports@varju.ca</email></para>
	</listitem>

	<listitem>
	<para>Alex Vasylenko
	<email>lxv@omut.org</email></para>
	</listitem>

	<listitem>
	<para>Alex Wilkinson
	<email>alex.wilkinson@dsto.defence.gov.au</email></para>
	</listitem>

	<listitem>
	<para>Alex Zepeda
	<email>garbanzo@hooked.net</email></para>
	</listitem>

	<listitem>
	<para>Alexander Bechikov
	<email>goo@t72.ru</email></para>
	</listitem>

	<listitem>
	<para>&a.arundel.email;</para>
	</listitem>

	<listitem>
	<para>Alexander Churanov
	<email>alexanderchuranov@gmail.com</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 Pereira Girald
	<email>girald@etcom.ufrgs.br</email></para>
	</listitem>

	<listitem>
	<para>Alexander Grigoryev
	<email>alexander.4mail@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Alexander Gromnizki
	<email>gromnizki@unixdev.net</email></para>
	</listitem>

	<listitem>
	<para>Alexander Haderer
	<email>alexander.haderer@charite.de</email></para>
	</listitem>

	<listitem>
	<para>Alexander Koch
	<email>fbsd@meersau.de</email></para>
	</listitem>

	<listitem>
	<para>Alexander Kojevnikov
	<email>alexander@kojevnikov.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 Peresunko
	<email>alex@freeman.org.ua</email></para>
	</listitem>

	<listitem>
	<para>Alexander Pohoyda
	<email>alexander.pohoyda@gmx.net</email></para>
	</listitem>

	<listitem>
	<para>Alexander Pyhalov
	<email>alp@sfedu.ru</email></para>
	</listitem>

	<listitem>
	<para>alexander smishlajev
	<email>alex@ank-sia.com</email></para>
	</listitem>

	<listitem>
	<para>Alexander V. Ribchansky
	<email>triosoft@triosoft.com.ua</email></para>
	</listitem>

	<listitem>
	<para>Alexander Yerenkow
	<email>yerenkow@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Alexander Zagrebin
	<email>alexz@visp.ru</email></para>
	</listitem>

	<listitem>
	<para>Alexander Zhuravlev
	<email>zaa@zaa.pp.ru</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>Alexandros Kosiaris
	<email>akosiaris+ports@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Alexey Illarionov
	<email>littlesavage@rambler.ru</email></para>
	</listitem>

	<listitem>
	<para>Alexey V. Antipovsky
	<email>kemm@in-line.ru</email></para>
	</listitem>

	<listitem>
	<para>Alexey V. Neyman
	<email>alex.neyman@auriga.ru</email></para>
	</listitem>

	<listitem>
	<para>Alexey Y. Mikhailov
	<email>karma@ez.pereslavl.ru</email></para>
	</listitem>

	<listitem>
	<para>Alexey Shuvaev
	<email>shuvaev@physik.uni-wuerzburg.de</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>Ali Mashtizadeh
	<email>mashtizadeh@gmail.com</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>Amarendra Godbole
	<email>amarendra.godbole@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Amy Baron
	<email>amee@beer.org</email></para>
	</listitem>

	<listitem>
	<para>Anthony Garcia
	<email>agarcia@experts-exchange.com</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 Borodin
	<email>anatoly.borodin@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Anatoly Vorobey
	<email>mellon@pobox.com</email></para>
	</listitem>

	<listitem>
	<para>Anatoly Zherdev
	<email>tolyar@mx.ru</email></para>
	</listitem>

	<listitem>
	<para>Anders Andersson
	<email>anders@codefactory.se</email></para>
	</listitem>

	<listitem>
	<para>Anders Nor Berle
	<email>debolaz@debolaz.com</email></para>
	</listitem>

	<listitem>
	<para>Anders Thulin
	<email>Anders.X.Thulin@telia.se</email></para>
	</listitem>

	<listitem>
	<para>Anders Troback
	<email>freebsd@troback.com</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>Andre Yelistratov
	<email>andre@andre.net.ru</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 Fuchs
	<email>asf@boinkor.net</email></para>
	</listitem>

	<listitem>
	<para>Andreas Gustafsson
	<email>gson@araneus.fi</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 K Foerster
	<email>akf3@akfoerster.de</email></para>
	</listitem>

	<listitem>
	<para>Andreas Kasparz
	<email>andy@interface-business.de</email></para>
	</listitem>

	<listitem>
	<para>Andreas Kohn
	<email>andreas@syndrom23.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 Möller
	<email>segfault@gmx.net</email></para>
	</listitem>

	<listitem>
	<para>Andreas Riedel
	<email>rian@hrz.tu-chemnitz.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>Andres Vega Garcia</para>
	</listitem>

	<listitem>
	<para>Andrew Arensburger
	<email>arensb@ooblick.com</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 Greenwood
	<email>greenwood.andy@gmail.com</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@iu.edu</email></para>
	</listitem>

	<listitem>
	<para>Andrew Khlebutin
	<email>andrey@hm.perm.ru</email></para>
	</listitem>

	<listitem>
	<para>Andrew Kochetkov
	<email>kochetkov.andrew@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Andrew Kolchoogin
	<email>andrew@rinet.ru</email></para>
	</listitem>

	<listitem>
	<para>Andrew L. Kilpatrick
	<email>tiger@whitetigersd.com</email></para>
	</listitem>

	<listitem>
	<para>Andrew L. Neporada
	<email>andrew@chg.ru</email></para>
	</listitem>

	<listitem>
	<para>Andrew Marks
	<email>andrew@amrx.net</email></para>
	</listitem>

	<listitem>
	<para>Andrew McKay
	<email>andy@openirc.co.uk</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 Morton
	<email>drewish@katherinehouse.com</email></para>
	</listitem>

	<listitem>
	<para>Andrew P. Lentvorski
	<email>bsder@allcaps.org</email></para>
	</listitem>

	<listitem>
	<para>Andrew Predoehl
	<email>predoehl@mail.kg</email></para>
	</listitem>

	<listitem>
	<para>Andrew Reilly
	<email>a.reilly@lake.com</email></para>
	</listitem>

	<listitem>
	+ <para>Andrew Romanenko
	+ <email>melanhit@gmail.com</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 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 V. Stikheev
	<email>sand@links.ru</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 Surkov
	<email>nsand@sura.ru</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 Fawcett
	<email>andy@athame.co.uk</email></para>
	</listitem>

	<listitem>
	<para>Andy Gilligan
	<email>andy@evo6.org</email></para>
	</listitem>

	<listitem>
	<para>Andy Kosela
	<email>andy.kosela@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Andy Miller
	<email>andy@trit.org</email></para>
	</listitem>

	<listitem>
	<para>Andy Newman
	<email>atrn@zeta.org.au</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>Anes Muhametov
	<email>anes@anes.su</email></para>
	</listitem>

	<listitem>
	<para>Angel Todorov
	<email>todorov_bg@gmx.net</email></para>
	</listitem>

	<listitem>
	<para>Angelo Turetta
	<email>aturetta@commit.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 Ginepro
	<email>anthony.ginepro@laposte.net</email></para>
	</listitem>

	<listitem>
	<para>Anthony Mawer
	<email>gnats@mawer.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>Antoine Pelisse
	<email>apelisse@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Anton Hryciuk
	<email>gnixua@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Anton N. Bruesov
	<email>antonz@library.ntu-kpi.kiev.ua</email></para>
	</listitem>

	<listitem>
	<para>Anton Shterenlikht
	<email>mexas@bris.ac.uk</email></para>
	</listitem>

	<listitem>
	<para>Anton Voronin
	<email>anton@urc.ac.ru</email></para>
	</listitem>

	<listitem>
	<para>Antonio Bonifati
	<email>ant@monitor.deis.unical.it</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>Aragon Gouveia
	<email>aragon@phat.za.net</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 Berthomier
	<email>oz@cyprio.net</email></para>
	</listitem>

	<listitem>
	<para>Arnaud Launay
	<email>asl@launay.org</email></para>
	</listitem>

	<listitem>
	<para>Arne Henrik Juul
	<email>arnej@Lise.Unit.NO</email></para>
	</listitem>

	<listitem>
	<para>Aron Schlesinger
	<email>as@bsdgroup.de</email></para>
	</listitem>

	<listitem>
	<para>Aron Stansvik
	<email>elvstone@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Artem Kazakov
	<email>kazakov@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Artem Naluzhnyy
	<email>tut@nhamon.com.ua</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>Attila Nagy
	<email>bra@fsn.hu</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>Axel Gonzalez
	<email>loox@e-shell.net</email></para>
	</listitem>

	<listitem>
	<para>Balázs Nagy
	<email>js@iksz.hu</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>Bartek Rutkowski
	<email>r@robakdesign.com</email></para>
	</listitem>

	<listitem>
	<para>Bartosz Fabianowski
	<email>freebsd@chillt.de</email></para>
	</listitem>

	<listitem>
	<para>Bayanzul Lodoysamba
	<email>baynaa@yahoo.com</email></para>
	</listitem>

	<listitem>
	<para>Ben Hutchinson
	<email>benhutch@xfiles.org.uk</email></para>
	</listitem>

	<listitem>
	<para>Ben Jackson</para>
	</listitem>

	<listitem>
	<para>Ben Walter
	<email>bwalter@itachi.swcp.com</email></para>
	</listitem>

	<listitem>
	<para>Ben Woolley
	<email>ports@tautology.org</email></para>
	</listitem>

	<listitem>
	<para>Benedikt Köhler
	<email>benedikt@furukama.de</email></para>
	</listitem>

	<listitem>
	<para>Beni Keller
	<email>navigium@grindcore.ch</email></para>
	</listitem>

	<listitem>
	<para>Benjamin Lewis
	<email>bhlewis@gte.net</email></para>
	</listitem>

	<listitem>
	<para>Benjamin Lutz
	<email>benlutz@datacomm.ch</email></para>
	</listitem>

	<listitem>
	<para>Benny Kjrgaard
	<email>benny@catpipe.net</email></para>
	</listitem>

	<listitem>
	<para>Benoit Calvez
	<email>benoit@litchis.org</email></para>
	</listitem>

	<listitem>
	<para>Berend de Boer
	<email>berend@pobox.com</email></para>
	</listitem>

	<listitem>
	<para>Bernd Luevelsmeyer
	<email>bdluevel@heitec.net</email></para>
	</listitem>

	<listitem>
	<para>Bernd Rosauer
	<email>br@schiele-ct.de</email></para>
	</listitem>

	<listitem>
	<para>Bill Cadwallader
	<email>hurbold@yahoo.com</email></para>
	</listitem>

	<listitem>
	<para>Bill Kish
	<email>kish@osf.org</email></para>
	</listitem>

	<listitem>
	<para>Bill Lloyd
	<email>wlloyd@mpd.ca</email></para>
	</listitem>

	<listitem>
	<para>Bill Moran
	<email>wmoran@collaborativefusion.com</email></para>
	</listitem>

	<listitem>
	<para>Bill Trost
	<email>trost@cloud.rain.com</email></para>
	</listitem>

	<listitem>
	<para>Björn König
	<email>bkoenig@cs.tu-berlin.de</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>BluePex Security Solutions
	<email>freebsd-ports@bluepex.com</email></para>
	</listitem>

	<listitem>
	<para>Bob Eager
	<email>bob@eager.cx</email></para>
	</listitem>

	<listitem>
	<para>Bob Frazier
	<email>bobf@mrp3.com</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 Kovalenko
	<email>boris@tagnet.ru</email></para>
	</listitem>

	<listitem>
	<para>Boris Lytochkin
	<email>lytboris@gmail.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 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>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 B. Powers
	<email>bbp2006@columbia.edu</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 Cully
	<email>shmit@kublai.com</email></para>
	</listitem>

	<listitem>
	<para>Brian Gardner
	<email>brian@getsnappy.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 M. Clapper
	<email>bmc@clapper.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. Gaeke
	<email>brg@dgate.org</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 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>Bruno Schwander
	<email>bruno@tinkerbox.org</email></para>
	</listitem>

	<listitem>
	<para>Byung-Hee HWANG
	<email> bh@izb.knu.ac.kr</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>Carlos A. M. dos Santos
	<email>unixmania@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Carlos Eduardo G. Carvalho
	<email>cartola@openit.com.br</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>Cédric Lamalle
	<email>cedric@cedric.trix.net</email></para>
	</listitem>

	<listitem>
	<para>Cezary Morga
	<email>cm@therek.net</email></para>
	</listitem>

	<listitem>
	<para>Chad Castleberry
	<email>crcastle@ius.edu</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>Charles Swiger
	<email>chuck@pkix.net</email></para>
	</listitem>

	<listitem>
	<para>Cheng-Tao Lin
	<email>b89605222@ntu.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>ChenGuang LI
	<email>horus.li@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Chess Griffin
	<email>chess@chessgriffin.com</email></para>
	</listitem>

	<listitem>
	<para>Chet Ramey
	<email>chet@odin.INS.CWRU.Edu</email></para>
	</listitem>

	<listitem>
	<para>Chi-Feng QU
	<email>chifeng@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Chia-Hsing Yu
	<email>davidyu@ucsd.edu</email></para>
	</listitem>

	<listitem>
	<para>Chia-liang Kao
	<email>clkao@CirX.ORG</email></para>
	</listitem>

	<listitem>
	<para>Chiang Cheng-Hsiung
	<email>elvis@sslab.cs.ccu.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>Chiharu Shibata
	<email>chi@bd.mbn.or.jp</email></para>
	</listitem>

	<listitem>
	<para>Chip Norkus</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 Jones
	<email>chris.jones@ualberta.ca</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 Laverdure
	<email>dashevil@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Chris Pepper
	<email>pepper@mail.rockefeller.edu</email></para>
	</listitem>

	<listitem>
	<para>Chris Petrik
	<email>c.petrik.sosa@gmail.com</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 Heckendorf
	<email>heckend@bu.edu</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>&a.kuku.email;</para>
	</listitem>

	<listitem>
	<para>Christoph Robitschko
	<email>chmr@edvz.tu-graz.ac.at</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 Boumenot
	<email>boumenot@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Christopher G. Demetriou
	<email>cgd@postgres.berkeley.edu</email></para>
	</listitem>

	<listitem>
	<para>Christopher Illies
	<email>christopher.illies@ki.se</email></para>
	</listitem>

	<listitem>
	<para>Christopher J. Ruwe
	<email>cjr@cruwe.de</email></para>
	</listitem>

	<listitem>
	<para>Christopher K. Davis
	<email>ckd-freebsd@ckdhr.com</email></para>
	</listitem>

	<listitem>
	<para>Christopher Key
	<email>cjk32@cam.ac.uk</email></para>
	</listitem>

	<listitem>
	<para>Christopher Knaust
	<email>jigboe@gmx.de</email></para>
	</listitem>

	<listitem>
	<para>Christopher N. Harrell
	<email>cnh@ivmg.net</email></para>
	</listitem>

	<listitem>
	<para>Christopher Nehren
	<email>apeiron@comcast.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>Clayton Rollins
	<email>crollins666@hotmail.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>Clive Crous
	<email>clive@darkarts.co.za</email></para>
	</listitem>

	<listitem>
	<para>Colman Reilly
	<email>careilly@tcd.ie</email></para>
	</listitem>

	<listitem>
	<para>Conor McDermottroe
	<email>ports@mcdermottroe.com</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>Corey Smith
	<email>corsmith@gmail.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 Boston
	<email>craig@yekse.gank.org</email></para>
	</listitem>

	<listitem>
	<para>Craig Butler
	<email>craig001@lerwick.hopto.org</email></para>
	</listitem>

	<listitem>
	<para>Craig Leres
	<email>leres@ee.lbl.gov</email></para>
	</listitem>

	<listitem>
	<para>Craig Loomis</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>Cristiano Rolim Pereira
	<email>cristianorolim@hotmail.com</email></para>
	</listitem>

	<listitem>
	<para>Curt Mayer
	<email>curt@toad.com</email></para>
	</listitem>

	<listitem>
	<para>Cyril Guibourg
	<email>aragorn+ports@teaser.fr</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>Daan Vreeken
	<email>Danovitsch@Vitsch.net</email></para>
	</listitem>

	<listitem>
	<para>Dai Ishijima
	<email>ishijima@tri.pref.osaka.jp</email></para>
	</listitem>

	<listitem>
	<para>Daisuke Aoyama
	<email>aoyama@peach.ne.jp</email></para>
	</listitem>

	<listitem>
	<para>Daisuke Watanabe
	<email>NU7D-WTNB@asahi-net.or.jp</email></para>
	</listitem>

	<listitem>
	<para>Damian Gerow
	<email>dgerow@afflictions.org</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 Angelescu
	<email>mrhsaacdoh@yahoo.com</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@allantgroup.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 Rench
	<email>citric@cubicone.tmetic.com</email></para>
	</listitem>

	<listitem>
	<para>Dan Smith
	<email>dan@algenta.com</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 Bretoi
	<email>daniel@netwalk.org</email></para>
	</listitem>

	<listitem>
	<para>Daniel Bryan
	<email>sisko@bsdmail.com</email></para>
	</listitem>

	<listitem>
	<para>Daniel Hagan
	<email>dhagan@acm.vt.edu</email></para>
	</listitem>

	<listitem>
	<para>Daniel J. O'Connor
	<email>darius@dons.net.au</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>Daniel W. Steinbrook
	<email>dsteinbr@fas.harvard.edu</email></para>
	</listitem>

	<listitem>
	<para>Daniel Wijnands
	<email>daniel@itxl.nl</email></para>
	</listitem>

	<listitem>
	<para>Danilo Egêa Gondolfo
	<email>danilogondolfo@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Danny Braniss
	<email>danny@cs.huji.ac.il</email></para>
	</listitem>

	<listitem>
	<para>Danny Egen</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>Dario Freni
	<email>saturnero@gufi.org</email></para>
	</listitem>

	<listitem>
	<para>Darren Pilgrim
	<email>ports.maintainer@evilphi.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>&a.tweten.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 Chaplin-Loebell
	<email>direct@klatha.com</email></para>
	</listitem>

	<listitem>
	<para>David Dawes
	<email>dawes@XFree86.org</email></para>
	</listitem>

	<listitem>
	<para>David Demelier
	<email>markand@malikania.fr</email></para>
	</listitem>

	<listitem>
	<para>David Filo</para>
	</listitem>

	<listitem>
	<para>David G. Holm
	<email>harbour@netfang.net</email></para>
	</listitem>

	<listitem>
	<para>David Gardner
	<email>david@pinko.net</email></para>
	</listitem>

	<listitem>
	<para>David Gilbert
	<email>dave@daveg.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 Johnson
	<email>david@usermode.org</email></para>
	</listitem>

	<listitem>
	<para>David Jones
	<email>dej@qpoint.torfree.net</email></para>
	</listitem>

	<listitem>
	<para>David Julien
	<email>david.julien@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>David K. Gerry
	<email>David.K.Gerry@GMail.com</email></para>
	</listitem>

	<listitem>
	<para>David Kelly
	<email>dkelly@tomcat1.tbe.com</email></para>
	</listitem>

	<listitem>
	<para>David Kirchner
	<email>dpk@dpk.net</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 Landgren
	<email>david@landgren.net</email></para>
	</listitem>

	<listitem>
	<para>David Lay
	<email>dsl@webize.com.au</email></para>
	</listitem>

	<listitem>
	<para>David Le Brun
	<email>david@trucs.org</email></para>
	</listitem>

	<listitem>
	<para>David Leonard
	<email>d@scry.dstc.edu.au</email></para>
	</listitem>

	<listitem>
	<para>David Magda
	<email>dmagda@magda.ca</email></para>
	</listitem>

	<listitem>
	<para>David Muir Sharnoff
	<email>muir@idiom.com</email></para>
	</listitem>

	<listitem>
	<para>David Otto
	<email>ottodavid@gmx.net</email></para>
	</listitem>

	<listitem>
	<para>David Quattlebaum
	<email>drq@drqware.com</email></para>
	</listitem>

	<listitem>
	<para>David Romano
	<email>unobe@cpan.org</email></para>
	</listitem>

	<listitem>
	<para>David S. Miller
	<email>davem@jenolan.rutgers.edu</email></para>
	</listitem>

	<listitem>
	<para>David Siebörger
	<email>drs@rucus.ru.ac.za</email></para>
	</listitem>

	<listitem>
	<para>David Sugar
	<email>dyfet@gnu.org</email></para>
	</listitem>

	<listitem>
	<para>David Syphers
	<email>dsyphers@u.washington.edu</email></para>
	</listitem>

	<listitem>
	<para>David Sze
	<email>dsze@alumni.uwaterloo.ca</email></para>
	</listitem>

	<listitem>
	<para>David Terry
	<email>dterry@digifonica.com</email></para>
	</listitem>

	<listitem>
	<para>David Vachulka
	<email>arch_dvx@users.sourceforge.net</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>Dax Labrador
	<email>semprix@bsdmail.org</email></para>
	</listitem>

	<listitem>
	<para>Dean Gaudet
	<email>dgaudet@arctic.org</email></para>
	</listitem>

	<listitem>
	<para>Dean Hollister
	<email>dean@odyssey.apana.org.au</email></para>
	</listitem>

	<listitem>
	<para>Dean Huxley
	<email>dean@fsa.ca</email></para>
	</listitem>

	<listitem>
	<para>Denis Barov
	<email>dindin@dindin.ru</email></para>
	</listitem>

	<listitem>
	<para>Denis Fortin</para>
	</listitem>

	<listitem>
	<para>Denis Generalov
	<email>gd@rambler-co.ru></email></para>
	</listitem>

	<listitem>
	<para>Denis Philippov
	<email>for_spam@mezon.ru</email></para>
	</listitem>

	<listitem>
	<para>Denis E. Podolskiy
	<email>bytestore@yandex.ru</email></para>
	</listitem>

	<listitem>
	<para>Denis Pokataev
	<email>catone@cpan.org</email></para>
	</listitem>

	<listitem>
	<para>Denis Shaposhnikov
	<email>dsh@vlink.ru</email></para>
	</listitem>

	<listitem>
	<para>Dennis Cabooter
	<email>dennis@rootxs.org</email></para>
	</listitem>

	<listitem>
	<para>Dennis Glatting
	<email>dennis.glatting@software-munitions.com</email></para>
	</listitem>

	<listitem>
	<para>Dennis S. Davidoff
	<email>null@cvs.1system.ru</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>Derik van Zuetphen
	<email>dz@426.ch</email></para>
	</listitem>

	<listitem>
	<para>Dermot Tynan
	<email>dtynan@kalopa.com</email></para>
	</listitem>

	<listitem>
	<para>Diego Depaoli
	<email>trebestie@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Dikshie
	<email>dikshie@lapi.itb.ac.id</email></para>
	</listitem>

	<listitem>
	<para>Dikshie
	<email>dikshie@sfc.wide.ad.jp</email></para>
	</listitem>

	<listitem>
	<para>Dierk Sacher
	<email>dierk@blaxxtarz.de</email></para>
	</listitem>

	<listitem>
	<para>Dirk Gouders
	<email>gouders@et.bocholt.fh-gelsenkirchen.de</email></para>
	</listitem>

	<listitem>
	<para>Dirk Jagdmann
	<email>doj@cubic.org</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@webweaving.org</email></para>
	</listitem>

	<listitem>
	<para>Dishanker Rajakulendren
	<email>draj@oceanfree.net</email></para>
	</listitem>

	<listitem>
	<para>Ditesh Shashikant Gathani
	<email>ditesh@gathani.org</email></para>
	</listitem>

	<listitem>
	<para>Dmitri Nikulin
	<email>setagllib@optusnet.com.au</email></para>
	</listitem>

	<listitem>
	<para>Dmitriy Limonov
	<email>earl1k@mail.ru</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 Kazarov
	<email>d.y.kazarov@mail.ru</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 Pryadko
	<email>d.pryadko@rambler-co.ru</email></para>
	</listitem>

	<listitem>
	<para>Dmitry Semkin
	<email>ds@tic-tac.ru</email></para>
	</listitem>

	<listitem>
	<para>Dmitry V. Sukhodoyev
	<email>raven428@gmail.com</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 Fandrey
	<email>lon_kamikaze@gmx.de</email></para>
	</listitem>

	<listitem>
	<para>Dominic Marks
	<email>dominic_marks@btinternet.com</email></para>
	</listitem>

	<listitem>
	<para>Dominic Mitchell
	<email>dom@happygiraffe.net</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>Dominique Goncalves
	<email>dominique.goncalves@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Don Croyle
	<email>croyle@gelemna.org</email></para>
	</listitem>

	<listitem>
	<para>Don Morrison
	<email>dmorrisn@u.washington.edu</email></para>
	</listitem>

	<listitem>
	<para>Don Owens
	<email>don@regexguy.com</email></para>
	</listitem>

	<listitem>
	<para>&a.whiteside.email;</para>
	</listitem>

	<listitem>
	<para>Don Yuniskis
	<email>dgy@rtd.com</email></para>
	</listitem>

	<listitem>
	<para>Donald Maddox
	<email>dmaddox099@yahoo.com</email></para>
	</listitem>

	<listitem>
	<para>Donn Miller
	<email>dmmiller@cvzoom.net</email></para>
	</listitem>

	<listitem>
	<para>Doug Harple
	<email>dharple@nycap.rr.com</email></para>
	</listitem>

	<listitem>
	<para>Doug Penner
	<email>darwinsurvivor@gmail.com</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>Douglas W. Thrift
	<email>douglas@douglasthrift.net</email></para>
	</listitem>

	<listitem>
	<para>Drew Derbyshire
	<email>ahd@kew.com</email></para>
	</listitem>

	<listitem>
	<para>Dustin Sallings
	<email>dustin@spy.net</email></para>
	</listitem>

	<listitem>
	<para>Dylan Carlson
	<email>absinthe@retrovertigo.com</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>Ederson de Moura
	<email>ederbs@ederbs.org</email></para>
	</listitem>

	<listitem>
	<para>Edgardo Garcia Hoeffler
	<email>edybsd@yahoo.com.ar</email></para>
	</listitem>

	<listitem>
	<para>Edmondas Girkantas
	<email>eg@fbsd.lt</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>Eijiro Shibusawa
	<email>ej-sib@ice.uec.ac.jp</email></para>
	</listitem>

	<listitem>
	<para>Eike Bernhardt
	<email>eike.bernhardt@gmx.de</email></para>
	</listitem>

	<listitem>
	<para>Eintisy Chuang
	<email>eintisy@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Elias Mandouvalos
	<email>ocean@mail.gr</email></para>
	</listitem>

	<listitem>
	<para>Elisey Savateev
	<email>b3k@mail.ru</email></para>
	</listitem>

	<listitem>
	<para>Elmar Bartel
	<email>bartel@informatik.tu-muenchen.de</email></para>
	</listitem>

	<listitem>
	<para>Emily Boyd
	<email>emily@emilyboyd.com</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 Cronin
	<email>ecronin@eecs.umich.edu</email></para>
	</listitem>

	<listitem>
	<para>Eric D. Futch
	<email>efutch@nyct.net</email></para>
	</listitem>

	<listitem>
	<para>Eric F. Crist
	<email>ecrist@secure-computing.net</email></para>
	</listitem>

	<listitem>
	<para>Eric Freeman
	<email>freebsdports@chillibear.com</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 Kjeldergaard
	<email>kjelderg@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Eric L. Hernes
	<email>erich@lodgenet.com</email></para>
	</listitem>

	<listitem>
	<para>Eric Masson
	<email>e-masson@kisoft-services.com</email></para>
	</listitem>

	<listitem>
	<para>Eric Ogren
	<email>eogren@stanford.edu</email></para>
	</listitem>

	<listitem>
	<para>Eric P. Scott
	<email>eps@sirius.com</email></para>
	</listitem>

	<listitem>
	<para>Eric S. Van Gyzen
	<email>esv@vangyzen.net</email></para>
	</listitem>

	<listitem>
	<para>Eric Schnoebelen
	<email>eric@cirr.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>Eric W. Bates
	<email>ericx@vineyard.net</email></para>
	</listitem>

	<listitem>
	<para>Eric Yu
	<email>ericyu@mail2000.com.tw</email></para>
	</listitem>

	<listitem>
	<para>Eric van Gyzen
	<email>vangyzen@stat.duke.edu</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 Greenwald
	<email>erik@smluc.org</email></para>
	</listitem>

	<listitem>
	<para>Erik H. Bakke
	<email>erikhb@bgnett.no</email></para>
	</listitem>

	<listitem>
	<para>Erik H. Moe
	<email>ehm@cris.com</email></para>
	</listitem>

	<listitem>
	<para>Erik L. Chen
	<email>d9364104@mail.nchu.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>Ernie Smallis
	<email>esmallis@stbernard.com</email></para>
	</listitem>

	<listitem>
	<para>Ernst Winter (<ulink
	url="http://berklix.org/ewinter/">Deceased</ulink>)</para>
	</listitem>

	<listitem>
	<para>Espen Skoglund
	<email>esk@ira.uka.de</email></para>
	</listitem>

	<listitem>
	<para>Espen Tagestad
	<email>espen@tagestad.no</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>Evan Sarmiento
	<email>esarmiento@wayfair.com</email></para>
	</listitem>

	<listitem>
	<para>Evgueni V. Gavrilov
	<email>aquatique@rusunix.org</email></para>
	</listitem>

	<listitem>
	<para>Ewgenij Gawrilow
	<email>gawrilow@math.tu-berlin.de</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>Fabian Keil
	<email>fk@fabiankeil.de</email></para>
	</listitem>

	<listitem>
	<para>Fabian M. Borschel
	<email>fmb@onibox.net</email></para>
	</listitem>

	<listitem>
	<para>Fabien Devaux
	<email>fab@gcu.info</email></para>
	</listitem>

	<listitem>
	<para>Fabio Tosques
	<email>fabio.tosques@rz.hu-berlin.de</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>Fernando Apesteguia
	<email>fernando.apesteguia@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Ferruccio Vitale
	<email>vitale@cs.tin.it</email></para>
	</listitem>

	<listitem>
	<para>Filipe Rocha
	<email>filiperocha@gmail.com</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>Florian Unglaub
	<email>usenet04@rootofallevil.net</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 Cabrita
	<email>include@npf.pt.freebsd.org</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 Behrens
	<email>frank@pinky.sax.de</email></para>
	</listitem>

	<listitem>
	<para>Frank Börner
	<email>frank-freebsd@online.de</email></para>
	</listitem>

	<listitem>
	<para>Frank Chen Hsiung Chan
	<email>frankch@waru.life.nthu.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>Frank Denis
	<email>j@pureftpd.org</email></para>
	</listitem>

	<listitem>
	<para>Frank Gründer
	<email>elwood@mc5sys.in-berlin.de</email></para>
	</listitem>

	<listitem>
	<para>Frank MacLachlan
	<email>fpm@n2.net</email></para>
	</listitem>

	<listitem>
	<para>Frank Mayhar
	<email>frank@exit.com</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 Steinborn
	<email>steinex@nognu.de</email></para>
	</listitem>

	<listitem>
	<para>Frank Volf
	<email>volf@oasis.IAEhv.nl</email></para>
	</listitem>

	<listitem>
	<para>Frank Wall
	<email>fw@moov.de</email></para>
	</listitem>

	<listitem>
	<para>Frank W. Josellis
	<email>frank@dynamical-systems.org</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>Fraser Tweedale
	<email>frase@frase.id.au</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>Frédéric Praca
	<email>frederic.praca@freebsd-fr.org</email></para>
	</listitem>

	<listitem>
	<para>Frederick Earl Gray
	<email>fgray@rice.edu</email></para>
	</listitem>

	<listitem>
	<para>Fredrik Lindberg
	<email>fli@shapeshifter.se</email></para>
	</listitem>

	<listitem>
	<para>Frerich Raabe
	<email>frerich.raabe@gmx.de</email></para>
	</listitem>

	<listitem>
	<para>Fumihiko Kimura
	<email>jfkimura@yahoo.co.jp</email></para>
	</listitem>

	<listitem>
	<para>Fuyuhiko Maruyama
	<email>fuyuhik8@is.titech.ac.jp</email></para>
	</listitem>

	<listitem>
	<para>&a.stanislav.email;</para>
	</listitem>

	<listitem>
	<para>Gábor Kincses
	<email>gabor@acm.org</email></para>
	</listitem>

	<listitem>
	<para>Gábor Zahemszky
	<email>zgabor@CoDe.hu</email></para>
	</listitem>

	<listitem>
	<para>Gasol Wu
	<email>gasol.wu@gmail.com</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 Hayers
	<email>gary@hayers.org</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>Gaspar Chilingarov
	<email>nightmar@lemming.acc.am</email></para>
	</listitem>

	<listitem>
	<para>Gautam Mani
	<email>execve@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Gavin Mu
	<email>gavin@FreeBSDChina.org</email></para>
	</listitem>

	<listitem>
	<para>Gea-Suan Lin
	<email>gslin@gslin.org</email></para>
	</listitem>

	<listitem>
	<para>Geoff Glasson
	<email>g_glasson@jimali.dyndns.org</email></para>
	</listitem>

	<listitem>
	<para>Geoff Rehmet
	<email>csgr@alpha.ru.ac.za</email></para>
	</listitem>

	<listitem>
	<para>Geoffrey Mainland
	<email>mainland@apeiron.net</email></para>
	</listitem>

	<listitem>
	<para>Geoffroy Rivat
	<email>grivat@sicfa.net</email></para>
	</listitem>

	<listitem>
	<para>Georg Graf
	<email>georg@graf.priv.at</email></para>
	</listitem>

	<listitem>
	<para>Georg Wagner
	<email>georg.wagner@ubs.com</email></para>
	</listitem>

	<listitem>
	<para>George Hartzell
	<email>hartzell@kestrel.alerce.com</email></para>
	</listitem>

	<listitem>
	<para>George Liaskos
	<email>geo.liaskos@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Gerasimos Dimitriadis
	<email>gedimitr@auth.gr</email></para>
	</listitem>

	<listitem>
	<para>Geraud Continsouzas
	<email>geraud@gcu.info</email></para>
	</listitem>

	<listitem>
	<para>Gerhard Gonter
	<email>g.gonter@ieee.org</email></para>
	</listitem>

	<listitem>
	<para>Gerrit Beine
	<email>tux@pinguru.net</email></para>
	</listitem>

	<listitem>
	<para>Giacomo Mariani
	<email>giacomomariani@yahoo.it</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>Gleb Sushko
	<email>neuroworker@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Glen Foster
	<email>gfoster@gfoster.com</email></para>
	</listitem>

	<listitem>
	<para>Giel van Schijndel
	<email>me@mortis.eu</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 Albrecht
	<email>gregoryba@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Greg Ansley
	<email>gja@ansley.com</email></para>
	</listitem>

	<listitem>
	<para>Greg Becker
	<email>greg@codeconcepts.com</email></para>
	</listitem>

	<listitem>
	<para>Greg J.
	<email>xcas@cox.net</email></para>
	</listitem>

	<listitem>
	+ <para>Greg Kennedy
	+ <email>kennedy.greg@gmail.com</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>Grün Christian-Rolf
	<email>kiki@bsdro.org</email></para>
	</listitem>

	<listitem>
	<para>Guillaume Paquet
	<email>amyfoub@videotron.ca</email></para>
	</listitem>

	<listitem>
	<para>Gurkan Sengun
	<email>grknsngn@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Gustavo Fukao
	<email>gustavofukao@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Guy Brand
	<email>gb@isis.u-strasbg.fr</email></para>
	</listitem>

	<listitem>
	<para>Guy Coleman
	<email>gtchask@mm.st</email></para>
	</listitem>

	<listitem>
	<para>Guy Harris
	<email>guy@netapp.com</email></para>
	</listitem>

	<listitem>
	<para>Guy Poizat
	<email>guy@device.dyndns.org</email></para>
	</listitem>

	<listitem>
	<para>H. Wade Minter
	<email>minter@lunenburg.org</email></para>
	</listitem>

	<listitem>
	<para>HAMADA Naoki
	<email>hamada@astec.co.jp</email></para>
	</listitem>

	<listitem>
	<para>HATANOU Tomomi
	<email>hatanou@infolab.ne.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>Hakisho Nukama
	<email>nukama@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Hammurabi Mendes
	<email>hmendes_br@yahoo.com</email></para>
	</listitem>

	<listitem>
	<para>Hannes Frederic Sowa
	<email>hannes@stressinduktion.org</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 Petter Selasky
	<email>hselasky@c2i.net</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 Schmalzbauer
	<email>h.schmalzbauer@omnisec.de</email></para>
	</listitem>

	<listitem>
	<para>Harald Wille
	<email>harald.wille@students.jku.at</email></para>
	</listitem>

	<listitem>
	<para>Hardy Schumacher
	<email>hardy.schumacher@gmx.de</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 Coin
	<email>harrycoin@qconline.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</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>Helko Glathe
	<email>glathe.helko@googlemail.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>Henri Michelon
	<email>michelon@e-cml.org</email></para>
	</listitem>

	<listitem>
	<para>Henrik Brautaset Aronsen
	<email>freebsd-ports@henrik.synth.no</email></para>
	</listitem>

	<listitem>
	<para>Henrik Friedrichsen
	<email>hrkfrd@googlemail.com</email></para>
	</listitem>

	<listitem>
	<para>Henrik Motakef
	<email>henrik.motakef@web.de</email></para>
	</listitem>

	<listitem>
	<para>Henrik Nymann Jensen
	<email>henriknj@0xmilk.org</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>Herbert J. Skuhra
	<email>herbert.skuhra@gmx.at</email></para>
	</listitem>

	<listitem>
	<para>Hernan Di Pietro
	<email>hernan.di.pietro@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Hideaki Machida
	<email>hido@coreblack.com</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 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>Hirohisa Yamaguchi
	<email>umq@ueo.co.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>Hiroto Kagotani
	<email>hiroto.kagotani@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Hiroya Tsubakimoto</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@frbsd.org</email></para>
	</listitem>

	<listitem>
	<para>Hugh Mahon
	<email>h_mahon@fc.hp.com</email></para>
	</listitem>

	<listitem>
	<para>Hugo Leisink
	<email>hugo@leisink.net</email></para>
	</listitem>

	<listitem>
	<para>Hung-Chi Chu
	<email>hcchu@r350.ee.ntu.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>Hung-Yi Chen
	<email>gaod.chen@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Hyogeol Lee
	<email>hyogeollee@gmail.com</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>IWATSUKI Hiroyuki
	<email>don@na.rim.or.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 Artemiev
	<email>ai@kliksys.ru</email></para>
	</listitem>

	<listitem>
	<para>Igor Khasilev
	<email>igor@jabber.paco.odessa.ua</email></para>
	</listitem>

	<listitem>
	<para>Igor Leonenko
	<email>bananaz@bk.ru</email></para>
	</listitem>

	<listitem>
	<para>Igor Pokrovsky
	<email>ip@doom.homeunix.org</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>Ildar Hizbulin
	<email>hizel@vyborg.ru</email></para>
	</listitem>

	<listitem>
	<para>Ilia Chipitsine
	<email>ilia@rediska.ru</email></para>
	</listitem>

	<listitem>
	<para>Ilya Bakulin
	<email>webmaster@kibab.com</email></para>
	</listitem>

	<listitem>
	<para>Ilya Khamushkin
	<email>ilya@space.rootshell.ru</email></para>
	</listitem>

	<listitem>
	<para>Ilya V. Komarov
	<email>mur@lynx.ru</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>Ivan Klymenko
	<email>fidaj@ukr.net</email></para>
	</listitem>

	<listitem>
	<para>Ivan Sharov
	<email>ivan.sharov@iname.com</email></para>
	</listitem>

	<listitem>
	<para>Ivan Sviridov
	<email>sin@vimcom.net</email></para>
	</listitem>

	<listitem>
	<para>J Shoemaker
	<email>shoemaker@softhome.net</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. Randolph
	<email>snortsms@servangle.net</email></para>
	</listitem>

	<listitem>
	<para>J.R. Oldroyd
	<email>fbsd@opal.com</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>Jackson Low
	<email>xxjack12xx@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Jacob Atzen
	<email>jatzen@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Jacob Bohn Lorensen
	<email>jacob@jblhome.ping.mk</email></para>
	</listitem>

	<listitem>
	<para>Jacques Marneweck
	<email>jacques@php.net</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>Jake Smith
	<email>jake@xz.cx</email></para>
	</listitem>

	<listitem>
	<para>Jakub Klausa
	<email>jacke@bofh.pl</email></para>
	</listitem>

	<listitem>
	<para>James Bailie
	<email>jimmy@mammothcheese.ca</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 McNaughton
	<email>bitbucket63-it@yahoo.com</email></para>
	</listitem>

	<listitem>
	<para>James O'Gorman
	<email>james@netinertia.co.uk</email></para>
	</listitem>

	<listitem>
	<para>James P. Howard, II
	<email>jh@jameshoward.us</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>Jamie Jones
	<email>jamie@bishopston.net</email></para>
	</listitem>

	<listitem>
	<para>Jan Conard
	<email>charly@fachschaften.tu-muenchen.de</email></para>
	</listitem>

	<listitem>
	<para>Jan Henrik Sylvester
	<email>me@janh.de</email></para>
	</listitem>

	<listitem>
	<para>Jan Jungnickel
	<email>Jan@Jungnickel.com</email></para>
	</listitem>

	<listitem>
	<para>&a.jkb.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 Siml
	<email>jsi@jules.de</email></para>
	</listitem>

	<listitem>
	<para>Jan Srzednicki
	<email>w@wrzask.pl</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>Janaka Wickramasinghe
	<email>janaka@opensource.lk</email></para>
	</listitem>

	<listitem>
	<para>Janick Taillandier
	<email>Janick.Taillandier@ratp.fr</email></para>
	</listitem>

	<listitem>
	<para>Janky Jay
	<email>ek@purplehat.org</email></para>
	</listitem>

	<listitem>
	<para>János Mohácsi
	<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 Bacon
	<email>jwbacon@tds.net</email></para>
	</listitem>

	<listitem>
	<para>Jason Burgess
	<email>dev@fenux.net</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>Javad Kouhi
	+ <email>javad.kouhi@gmail.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>Jaap Akkerhuis
	<email>jaap@NLnetLabs.nl</email></para>
	</listitem>

	<listitem>
	<para>Jean-Baptiste Quenot
	<email>jb.quenot@caraldi.com</email></para>
	</listitem>

	<listitem>
	<para>Jean Benoit
	<email>jean@unistra.fr</email></para>
	</listitem>

	<listitem>
	<para>Jean-Sebastien Roy
	<email>js@jeannot.org</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 Burchell
	<email>toxic@doobie.com</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 H. Johnson
	<email>CPE1704TKS@bellsouth.net</email></para>
	</listitem>

	<listitem>
	<para>Jeffrey Leung
	<email>zenoss@experts-exchange.com</email></para>
	</listitem>

	<listitem>
	<para>Jeff Molofee
	<email>nehe@cruzinternet.com</email></para>
	</listitem>

	<listitem>
	<para>Jeffrey Wheat
	<email>jeff@cetlink.net</email></para>
	</listitem>

	<listitem>
	<para>Jens Holmqvist
	<email>zparta@hispan.se</email></para>
	</listitem>

	<listitem>
	<para>Jens K. Loewe
	<email>bsd@tuxproject.de</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 C. Reed
	<email>reed@pugetsoundtechnology.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</para>
	</listitem>

	<listitem>
	<para>Jeremy Shaffner
	<email>jeremy@external.org</email></para>
	</listitem>

	<listitem>
	<para>Jeroen Schot
	<email>schot@a-askwadraat.nl</email></para>
	</listitem>

	<listitem>
	<para>Jerry Eriksson
	<email>jerry@freebsd.se</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 Kempf
	<email>jessekempf@gmail.com</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>Jesse van den Kieboom
	<email>troplosti@orcaweb.cjb.net</email></para>
	</listitem>

	<listitem>
	<para>Jia-Wei Ye
	<email>leafy7382@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Jian-Da Li
	<email>jdli@csie.nctu.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>Jie Gao
	<email>gaoj@cpsc.ucalgary.ca</email></para>
	</listitem>

	<listitem>
	<para>&a.babb.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>jim@corebsd.or.id</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 Riggs
	<email>ports@christianserving.org</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 Stapleton
	<email>sjss@var-dev.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>Jin-Shan Tseng
	<email>tjs@cdpa.nsysu.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>Jo Rhett
	<email>jrhett@netconsonance.com</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 Barbish
	<email>barbish@a1poweruser.com</email></para>
	</listitem>

	<listitem>
	<para>Joe Halpin
	<email>joe.halpin@attbi.com</email></para>
	</listitem>

	<listitem>
	<para>Joe Holden
	<email>joe@joeholden.co.uk</email></para>
	</listitem>

	<listitem>
	<para>Joe Horn
	<email>joehorn@gmail.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 Smith
	<email>inwap@best.com</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>Joerg Pulz
	<email>Joerg.Pulz@frm2.tum.de</email></para>
	</listitem>

	<listitem>
	<para>Joerg Schilling
	<email>schilling@fokus.gmd.de</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>Johan Strom
	<email>johan@stromnet.org</email></para>
	</listitem>

	<listitem>
	<para>Johann Tonsing
	<email>jtonsing@mikom.csir.co.za</email></para>
	</listitem>

	<listitem>
	<para>Johannes 5 Joemann
	<email>joemann@beefree.free.de</email></para>
	</listitem>

	<listitem>
	<para>Johannes Grødem
	<email>johs@copyleft.no</email></para>
	</listitem>

	<listitem>
	<para>Johannes Helander</para>
	</listitem>

	<listitem>
	<para>Johannes Stille</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</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 Ferrel
	<email>jdferrell3@yahoo.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</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 Marino
	<email>draco@marino.st</email></para>
	</listitem>

	<listitem>
	<para>John McAree
	<email>john@mcaree.org</email></para>
	</listitem>

	<listitem>
	<para>John MacFarlane
	<email>jgm@berkeley.edu</email></para>
	</listitem>

	<listitem>
	+ <para>John Mehr
	+ <email>jcm@visi.com</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 Oxley
	<email>john@yoafrica.com</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 Prather
	<email>john.c.prather@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>John Preisler
	<email>john@vapornet.com</email></para>
	</listitem>

	<listitem>
	<para>John Reynolds
	<email>johnjen@reynoldsnet.org</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 Von Essen
	<email>john@essenz.com</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 Amundsen
	<email>online@jamundsen.dyndns.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 Passki
	<email>cykyc@yahoo.com</email></para>
	</listitem>

	<listitem>
	<para>Jon Wilson
	<email>jon@phuq.co.uk</email></para>
	</listitem>

	<listitem>
	<para>Jona Joachim
	<email>walkingshadow@grummel.net</email></para>
	</listitem>

	<listitem>
	<para>Jonathan Belson
	<email>jon@witchspace.com</email></para>
	</listitem>

	<listitem>
	<para>Jonathan Bokovza
	<email>Jonathan@afarsec.com</email></para>
	</listitem>

	<listitem>
	<para>Jonathan Chen
	<email>jonc@chen.org.nz</email></para>
	</listitem>

	<listitem>
	<para>Jonathan Chu
	<email>milki@rescomp.berkeley.edu</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>jhanna@shaw.ca</email></para>
	</listitem>

	<listitem>
	<para>Jonathan Lennox
	<email>lennox@cs.columbia.edu</email></para>
	</listitem>

	<listitem>
	<para>Jonathan Liu
	<email>Net147@hotmail.com</email></para>
	</listitem>

	<listitem>
	<para>Jonathan McDowell
	<email>noodles@earth.li</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>Jordi Haarman
	<email>jhaarman-keyword-tinyerpPort.fd583c@projects.synantics.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>Joris Vandalon
	<email>joris@vandalon.nl</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 Liang
	<email>jose@jose.idv.tw</email></para>
	</listitem>

	<listitem>
	<para>Jose Marques
	<email>jose@nobody.org</email></para>
	</listitem>

	<listitem>
	<para>Jose Rodriguez
	<email>king@v2project.com</email></para>
	</listitem>

	<listitem>
	<para>José García Juanino
	<email>jjuanino@gmail.com</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 Mingrone
	<email>jrm@ftfl.ca</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 Carroll
	<email>josh.carroll@gmail.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>Josh Tolbert
	<email>hemi@puresimplicity.net</email></para>
	</listitem>

	<listitem>
	<para>Joshua D. Abraham
	<email>jabra@ccs.neu.edu</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>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>Jui-Nan Lin
	<email>jnlin@csie.nctu.edu.tw</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 C. Dunn
	<email>jdunn@aquezada.com</email></para>
	</listitem>

	<listitem>
	<para>Julian Coleman
	<email>j.d.coleman@ncl.ac.uk</email></para>
	</listitem>

	<listitem>
	<para>&a.jhs.email;</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>Jun Mukai
	<email>mukai@jmuk.org</email></para>
	</listitem>

	<listitem>
	<para>Junichi Satoh
	<email>junichi@jp.FreeBSD.org</email></para>
	</listitem>

	<listitem>
	<para>Junji NAKANISHI
	<email>jun-g@daemonfreaks.com</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>Jyun-Yan You
	<email>jyyou@cs.nctu.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>Gergely CZUCZY
	<email>gergely.czuczy@harmless.hu</email></para>
	</listitem>

	<listitem>
	<para>K.Higashino
	<email>a00303@cc.hc.keio.ac.jp</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>KIMURA Yasuhiro
	<email>yasu@utahime.org</email></para>
	</listitem>

	<listitem>
	<para>KUNISHIMA Takeo
	<email>kunishi@c.oka-pu.ac.jp</email></para>
	</listitem>

	<listitem>
	<para>Kai Vorma
	<email>vode@snakemail.hut.fi</email></para>
	</listitem>

	<listitem>
	+ <para>Kai Wang
	+ <email>kaiwang27@gmail.com</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 Liu
	<email>liukang@bjut.edu.cn</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>Karel Miklav
	<email>karel@lovetemple.net</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>Katalin Konkoly
	<email>katalin.konkoly@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Katsura Matsumoto
	<email>katsura@cc.osaka-kyoiku.ac.jp</email></para>
	</listitem>

	<listitem>
	<para>Kawanobe Koh
	<email>kawanobe@st.rim.or.jp</email></para>
	</listitem>

	<listitem>
	<para>Kay Abendroth
	<email>kay.abendroth@raxion.net</email></para>
	</listitem>

	<listitem>
	<para>Kay Lehmann
	<email>kay_lehmann@web.de</email></para>
	</listitem>

	<listitem>
	<para>Kazami
	<email>kazami@angels.vg</email></para>
	</listitem>

	<listitem>
	<para>Kazuhito HONDA
	<email>kazuhito@ph.noda.tus.ac.jp</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</para>
	</listitem>

	<listitem>
	<para>Keith Sklower</para>
	</listitem>

	<listitem>
	<para>Kelley Reynolds
	<email>kelley@insidesystems.net</email></para>
	</listitem>

	<listitem>
	<para>Ken Hornstein</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 Menzel
	<email>kenm@icarz.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 Takefu
	<email>takefu@airport.fm</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@yahoo.com</email></para>
	</listitem>

	<listitem>
	<para>Kenneth Vestergaard Schmidt
	<email>kvs@pil.dk</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 Brunelle
	<email>kruptos@mlinux.org</email></para>
	</listitem>

	<listitem>
	<para>Kevin Day
	<email>toasty@dragondata.com</email></para>
	</listitem>

	<listitem>
	<para>Kevin Golding
	<email>kevin@caomhin.demon.co.uk</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 Oberman
	<email>oberman@es.net</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>Kevin Zheng
	<email>kevinz5000@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Key-Teck SIN
	<email>ktsin@acm.org</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>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>Kirill A. Korinskiy
	<email>catap@catap.ru</email></para>
	</listitem>

	<listitem>
	<para>Kirk Strauser
	<email>kirk@strauser.com</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 Michael Indlekofer
	<email>M.Indlekofer@gmx.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>Konrad Lapsz
	<email>konrad.lapsz@gmail.com</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>Konstantinos Mplekos
	<email>mplekos@physics.upatras.gr</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>Krzysztof Kowalewski
	<email>pyzmen@kam.pl</email></para>
	</listitem>

	<listitem>
	<para>Krzysztof Pawlowski
	<email>msciciel@darkzone.ma.cx</email></para>
	</listitem>

	<listitem>
	<para>Kuan-Chung Chiu
	<email>buganini@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Kuang-che Wu
	<email>kcwu@csie.org</email></para>
	</listitem>

	<listitem>
	<para>Kuo-Feng Tseng
	<email>kftseng@iyard.org</email></para>
	</listitem>

	<listitem>
	<para>Kurt D. Zeilenga
	<email>Kurt@Boolean.NET</email></para>
	</listitem>

	<listitem>
	<para>Kurt Jaeger
	<email>fbsd-ports@opsec.eu</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 P. Maloney
	<email>larry@kiputers.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>Laurent Courty
	<email>lrntct@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Laurent Levier
	<email>llevier@argosnet.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>Leif Pedersen
	<email>pedersen@meridian-enviro.com</email></para>
	</listitem>

	<listitem>
	<para>Len Sassaman
	<email>rabbi@abditum.com</email></para>
	</listitem>

	<listitem>
	<para>Leo Kim
	<email>leo@florida.sarang.net</email></para>
	</listitem>

	<listitem>
	<para>Leo Vandewoestijne
	<email>freebsd@dns-lab.com</email></para>
	</listitem>

	<listitem>
	<para>Leonardo Silveira de A. Martins
	<email>lmartins@nepe.eee.ufg.br</email></para>
	</listitem>

	<listitem>
	<para>Leonhard Wimmer
	<email>leo@mediatomb.cc</email></para>
	</listitem>

	<listitem>
	<para>Leonid Zolotarev
	<email>leoz.2005@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Lev Walkin
	<email>vlm@lionet.info</email></para>
	</listitem>

	<listitem>
	<para>Levent Kayan
	<email>levent@corehack.org</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>Linh Pham
	<email>question+freebsdpr@closedsrc.org</email></para>
	</listitem>

	<listitem>
	<para>Lon Willett
	<email>lon%softt.uucp@math.utah.edu</email></para>
	</listitem>

	<listitem>
	<para>Loren J. Rittle
	<email>ljrittle@acm.org</email></para>
	</listitem>

	<listitem>
	<para>Loren M. Lang
	<email>lorenl@alzatex.com</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>Lubomir Metodiev Marinov
	<email>lubomir.marinov@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Lucas James
	<email>Lucas.James@ldjpc.apana.org.au</email></para>
	</listitem>

	<listitem>
	<para>Lucio Costa
	<email>lucio@zetasolucoes.com.br</email></para>
	</listitem>

	<listitem>
	<para>Luiz Eduardo Roncato Cordeiro
	<email>cordeiro@nic.br</email></para>
	</listitem>

	<listitem>
	<para>Luiz Otavio O Souza
	<email>loos.br@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Lukasz Stelmach
	<email>lukasz.stelmach@iem.pw.edu.pl</email></para>
	</listitem>

	<listitem>
	<para>Lupe Christoph
	<email>lupe@lupe-christoph.de</email></para>
	</listitem>

	<listitem>
	<para>Lutz Boehne
	<email>lboehne@damogran.de</email></para>
	</listitem>

	<listitem>
	<para>Lyndon Nerenberg
	<email>lyndon@orthanc.ab.ca</email></para>
	</listitem>

	<listitem>
	<para>M Rothwell
	<email>freebsd-ports@coreland.ath.cx</email></para>
	</listitem>

	<listitem>
	<para>M. L. Dodson
	<email>bdodson@scms.utmb.EDU</email></para>
	</listitem>

	<listitem>
	<para>M.C. Wong</para>
	</listitem>

	<listitem>
	<para>MOROHOSHI Akihiko
	<email>moro@remus.dti.ne.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>Mahlon E. Smith
	<email>mahlon@martini.nu</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>Mantas Kaulakys
	<email>stone@tainet.lt</email></para>
	</listitem>

	<listitem>
	<para>Manu Iyengar
	<email>iyengar@grunthos.pscwa.psca.com</email></para>
	</listitem>

	<listitem>
	<para>Manuel Creach
	<email>manuel.creach@me.com</email></para>
	</listitem>

	<listitem>
	<para>Manuel Rabade Garcia
	<email>mig@mig-29.net</email></para>
	</listitem>

	<listitem>
	<para>Marc Blanchet
	<email>marc.blanchet@viagenie.qc.ca</email></para>
	</listitem>

	<listitem>
	<para>Marc Frajola
	<email>marc@dev.com</email></para>
	</listitem>

	<listitem>
	<para>Marc Olzheim
	<email>marcolz@stack.nl</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>marc.vanwoerkom@fernuni-hagen.de</email></para>
	</listitem>

	<listitem>
	<para>Marcello Silva Coutinho
	<email>marcellocoutinho@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Marcelo/Porks Rossi
	<email>marcelorossi@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Marcin Cieslak
	<email>saper@system.pl</email></para>
	</listitem>

	<listitem>
	<para>Marcin Gondek
	<email>drixter@e-utp.net</email></para>
	</listitem>

	<listitem>
	<para>Marcin Jessa
	<email>yazzy@yazzy.org</email></para>
	</listitem>

	<listitem>
	<para>Marcin Wisnicki
	<email>mwisnicki@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Marco Molteni
	<email>molter@tin.it</email></para>
	</listitem>

	<listitem>
	<para>Marco van de Voort
	<email>marcov@stack.nl</email></para>
	</listitem>

	<listitem>
	<para>Marin Atanasov
	<email>dnaeon@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Marius Nünnerich
	<email>marius@nuenneri.ch</email></para>
	</listitem>

	<listitem>
	<para>Mark A. Wicks
	<email>mwicks@kettering.edu</email></para>
	</listitem>

	<listitem>
	<para>Mark Andrews</para>
	</listitem>

	<listitem>
	<para>Mark Blackman
	<email>freebsd-ports@blackmans.org</email></para>
	</listitem>

	<listitem>
	<para>Mark Cammidge
	<email>mark@gmtunx.ee.uct.ac.za</email></para>
	</listitem>

	<listitem>
	<para>Mark Daniel Reidel
	<email>ports@mark.reidel.info</email></para>
	</listitem>

	<listitem>
	<para>Mark Diekhans
	<email>markd@grizzly.com</email></para>
	</listitem>

	<listitem>
	<para>Mark Felder
	<email>feld@feld.me</email></para>
	</listitem>

	<listitem>
	<para>Mark Foster
	<email>mark@foster.cc</email></para>
	</listitem>

	<listitem>
	<para>Mark Hannon
	<email>markhannon@optusnet.com.au</email></para>
	</listitem>

	<listitem>
	<para>Mark Huizer
	<email>xaa+freebsd@timewasters.nl</email></para>
	</listitem>

	<listitem>
	<para>Mark J. Miller
	<email>joup@bigfoot.com</email></para>
	</listitem>

	<listitem>
	<para>Mark J. Taylor
	<email>mtaylor@cybernet.com</email></para>
	</listitem>

	<listitem>
	<para>Mark Johnston
	<email>mjohnston@skyweb.ca</email></para>
	</listitem>

	<listitem>
	<para>Mark Kane
	<email>mark@mkproductions.org</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 Starovoytov
	<email>mark_sf@kikg.ifmo.ru</email></para>
	</listitem>

	<listitem>
	<para>Mark Stosberg
	<email>mark@summersault.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</para>
	</listitem>

	<listitem>
	<para>Mark Valentine
	<email>mark@thuvia.org</email></para>
	</listitem>

	<listitem>
	<para>Markus Holmberg
	<email>saska@acc.umu.se</email></para>
	</listitem>

	<listitem>
	<para>Markus Niemistö
	<email>markus.niemisto@gmx.net</email></para>
	</listitem>

	<listitem>
	<para>Martijn Lina
	<email>martijn@pacno.net</email></para>
	</listitem>

	<listitem>
	<para>Martin Dieringer
	<email>martin.dieringer@gmx.de</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 Jackson
	<email>mhjacks@swbell.net</email></para>
	</listitem>

	<listitem>
	<para>Martin Kammerhofer
	<email>mkamm@gmx.net</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 Kropfinger
	<email>freebsd@rakor-net.de></email></para>
	</listitem>

	<listitem>
	<para>Martin Mersberger
	<email>gremlin@portal-to-web.de</email></para>
	</listitem>

	<listitem>
	<para>Martin Minkus
	<email>diskiller@cnbinc.com</email></para>
	</listitem>

	<listitem>
	<para>Martin Neubauer
	<email>m.ne@gmx.net</email></para>
	</listitem>

	<listitem>
	<para>Martin Otto
	<email>gamato@users.sf.net</email></para>
	</listitem>

	<listitem>
	<para>Martin Preuss
	<email>martin@libchipcard.de</email></para>
	</listitem>

	<listitem>
	<para>Martin Sugioarto
	<email>martin.sugioarto@udo.edu</email></para>
	</listitem>

	<listitem>
	<para>Martin Tournoij
	<email>carpetsmoker@gmail.com</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>Masafumi Otsune
	<email>info@otsune.com</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>Masahiro Teramoto
	<email>markun@onohara.to</email></para>
	</listitem>

	<listitem>
	<para>Masakazu HIGAKI
	<email>higamasa@dream.com</email></para>
	</listitem>

	<listitem>
	<para>Masaki TAGAWA
	<email>masaki@club.kyutech.ac.jp</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>Masanori OZAWA
	<email>ozawa@ongs.co.jp</email></para>
	</listitem>

	<listitem>
	<para>Masashi CHIBA
	<email>chiba.masashi@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Masatoshi TAMURA
	<email>tamrin@shinzan.kuee.kyoto-u.ac.jp</email></para>
	</listitem>

	<listitem>
	<para>Mathias Monnerville
	<email>mathias@monnerville.com</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 Emmerton
	<email>matt@gsicomp.on.ca</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@bsdfly.org</email></para>
	</listitem>

	<listitem>
	<para>Matt Loschert
	<email>loschert@servint.com</email></para>
	</listitem>

	<listitem>
	<para>Matt Mills
	<email>matt_mills@btopenworld.com</email></para>
	</listitem>

	<listitem>
	<para>Matt Peterson
	<email>matt@peterson.org</email></para>
	</listitem>

	<listitem>
	<para>Matt Smith
	<email>matt@xtaz.net</email></para>
	</listitem>

	<listitem>
	<para>Matt Stofko
	<email>matt@mjslabs.com</email></para>
	</listitem>

	<listitem>
	<para>Matt Thomas
	<email>matt@3am-software.com</email></para>
	</listitem>

	<listitem>
	<para>Matt Tosto
	<email>datahead4@gmail.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 Donovan
	<email>kitchetech@gmail.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 Gibson
	<email>mdg583@hotmail.com</email></para>
	</listitem>

	<listitem>
	<para>Matthew Grooms
	<email>mgrooms@shrew.net</email></para>
	</listitem>

	<listitem>
	<para>Matthew Holder
	<email>sixxgate@hotmail.com</email></para>
	</listitem>

	<listitem>
	<para>Matthew Luckie
	<email>mjl@luckie.org.nz</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>Matthew Will
	<email>mwill@spingen.com</email></para>
	</listitem>

	<listitem>
	<para>Matthew X. Economou
	<email>xenophon+fbsdports@irtnog.org</email></para>
	</listitem>

	<listitem>
	<para>Matthias Fechner
	<email>idefix@fechner.net</email></para>
	</listitem>

	<listitem>
	<para>Matthias Petermann
	<email>matthias@d2ux.net</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 Schmidt
	<email>schmidtm@mathematik.uni-marburg.de</email></para>
	</listitem>

	<listitem>
	<para>Matthias Sund
	<email>m.sund@arcor.de</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>Matthieu Guegan
	<email>matt.guegan@free.fr</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>Matus Uhlar
	<email>uhlar@fantomas.sk</email></para>
	</listitem>

	<listitem>
	<para>Maurice Castro
	<email>maurice@planet.serc.rmit.edu.au</email></para>
	</listitem>

	<listitem>
	<para>Mauricio Herrera Cuadra
	<email>mauricio@arareko.net</email></para>
	</listitem>

	<listitem>
	<para>Max Campos
	<email>mcampos@bpsw.biz</email></para>
	</listitem>

	<listitem>
	<para>Max E. Kuznecov
	<email>mek@mek.uz.ua</email></para>
	</listitem>

	<listitem>
	<para>Max Euston
	<email>meuston@jmrodgers.com</email></para>
	</listitem>

	<listitem>
	<para>Max N. Boyarov
	<email>m.boyarov@bsd.by</email></para>
	</listitem>

	<listitem>
	<para>Maxim Bolotin
	<email>max@rsu.ru</email></para>
	</listitem>

	<listitem>
	<para>Maxim Dounin
	<email>mdounin@mdounin.ru</email></para>
	</listitem>

	<listitem>
	<para>Maxim Ignatenko
	<email>gelraen.ua@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Maxim Loginov
	<email>zeliboba@mail.ru</email></para>
	</listitem>

	<listitem>
	<para>Maxim Samsonov
	<email>xors@sendmail.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>Mel Flynn
	<email>rflynn@acsalaska.net</email></para>
	</listitem>

	<listitem>
	<para>Meno Abels
	<email>meno.abels@adviser.com</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 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 Gmelin
	<email>freebsd@grem.de</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 Lyngbøl
	<email>michael@lyngbol.dk</email></para>
	</listitem>

	<listitem>
	<para>Michael Neumann
	<email>mneumann@ntecs.de</email></para>
	</listitem>

	<listitem>
	<para>Michael O. Boev
	<email>mike@tric.tomsk.gov.ru</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 Sanders
	<email>mike@topcat.hypermart.net</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 Seyfert
	<email>michaels@sdf.lonestar.org</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>Michel Lavondés
	<email>fox@vader.aacc.cc.md.us</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>Micho Durdevich
	<email>micho@math.unam.mx</email></para>
	</listitem>

	<listitem>
	<para>Mickael Maillot
	<email>mickael.maillot@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Miguel Angel Sagreras
	<email>msagre@cactus.fi.uba.ar</email></para>
	</listitem>

	<listitem>
	<para>Miguel Mendez
	<email>flynn@energyhq.es.eu.org</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 Andrews
	<email>mandrews@bit0.com</email></para>
	</listitem>

	<listitem>
	<para>Mike Bowie
	<email>mbowie@buzmo.com</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@boogie.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 Edenfield
	<email>kutulu@kutulu.org</email></para>
	</listitem>

	<listitem>
	<para>Mike Erickson
	<email>mee@quidquam.com</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</para>
	</listitem>

	<listitem>
	<para>Mike Krutov
	<email>neko@takino.org</email></para>
	</listitem>

	<listitem>
	<para>Mike Lockwood
	<email>mike@mikelockwood.com</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 Patterson
	<email>mike.patterson@unb.ca</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>Mike Tancsa
	<email>mike@sentex.net</email></para>
	</listitem>

	<listitem>
	<para>Mikhail A. Sokolov
	<email>mishania@demos.su</email></para>
	</listitem>

	<listitem>
	<para>Mikhail T.
	<email>michael@fun-box.ru</email></para>
	</listitem>

	<listitem>
	<para>Mikhail Zakharov
	<email>zmey20000@yahoo.com</email></para>
	</listitem>

	<listitem>
	<para>Mikolaj Rydzewski
	<email>miki@ceti.pl</email></para>
	</listitem>

	<listitem>
	<para>Mikolaj Golub
	<email>to.my.trociny@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Miks Mikelsons
	<email>miks@cubesystems.lv</email></para>
	</listitem>

	<listitem>
	<para>Milan Obuch
	<email>bsd@dino.sk</email></para>
	</listitem>

	<listitem>
	<para>Milosz Galazka
	<email>milosz.galazka@gmail.com</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>Mooneer Salem
	<email>mooneer@translator.cx</email></para>
	</listitem>

	<listitem>
	<para>Morgan Davis
	<email>root@io.cts.com</email></para>
	</listitem>

	<listitem>
	<para>Morten Slot Kristensen
	<email>ontherenth@gmail.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>Murilo Opsfelder
	<email>mopsfelder@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Mustafa Arif
	<email>ma499@doc.ic.ac.uk</email></para>
	</listitem>

	<listitem>
	<para>Mykola Dzham
	<email>i@levsha.me</email></para>
	</listitem>

	<listitem>
	<para>Mykola Khotyaintsev
	<email>ko@irfu.se</email></para>
	</listitem>

	<listitem>
	<para>Mykola Marzhan
	<email>delgod@portaone.com</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@jp.freebsd.org</email></para>
	</listitem>

	<listitem>
	<para>NAKAMURA Kazushi
	<email>kaz@kobe1995.net</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>Naram Qashat
	<email>cyberbotx@cyberbotx.com</email></para>
	</listitem>

	<listitem>
	<para>Narayan Namdev Newton
	<email>narayannewton@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Narvi
	<email>narvi@haldjas.folklore.ee</email></para>
	</listitem>

	<listitem>
	<para>Nate Eldredge
	<email>neldredge@math.ucsd.edu</email></para>
	</listitem>

	<listitem>
	<para>Nathan Dorfman
	<email>nathan@rtfm.net</email></para>
	</listitem>

	<listitem>
	<para>Nathaniel Roark
	<email>robb_force@holybuffalo.net</email></para>
	</listitem>

	<listitem>
	<para>Natsagdorj Shagdar
	<email>natsag2000@yahoo.com</email></para>
	</listitem>

	<listitem>
	<para>Neal Fachan
	<email>kneel@ishiboo.com</email></para>
	</listitem>

	<listitem>
	<para>Necati Ersen Siseci
	<email>siseci@enderunix.org</email></para>
	</listitem>

	<listitem>
	<para>Ned Wolpert
	<email>wolpert@codeheadsystems.com</email></para>
	</listitem>

	<listitem>
	<para>Nguyen Tam Chinh
	<email>chinhngt@sectorb.msk.ru</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 Dewing
	<email>nickdewing@gmail.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>Nicole Reid
	<email>root@cooltrainer.org</email></para>
	</listitem>

	<listitem>
	+ <para>Nikolai Lifanov
	+ <email>lifanov@mail.lifanov.com</email></para>
	+ </listitem>
	+
	+ <listitem>
	<para>Nikos Kokkalis
	<email>nickkokkalis@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Nick Leuta
	<email>skynick@mail.sc.ru</email></para>
	</listitem>

	<listitem>
	<para>Nick Rogness
	<email>nick@rogness.net</email></para>
	</listitem>

	<listitem>
	<para>Nick Williams
	<email>njw@cs.city.ac.uk</email></para>
	</listitem>

	<listitem>
	<para>Nick Withers
	<email>nick@nickwithers.com</email></para>
	</listitem>

	<listitem>
	<para>Nicko Dehaine
	<email>nicko@stbernard.com</email></para>
	</listitem>

	<listitem>
	<para>Nickolay N. Dudorov
	<email>nnd@itfs.nsk.su</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>Nikola Lecic
	<email>nikola.lecic@anthesphoria.net</email></para>
	</listitem>

	<listitem>
	+ <para>Nikola Kolev
	+ <email>koue@chaosophia.net</email></para>
	+ </listitem>
	+
	+ <listitem>
	<para>Nikos Ntarmos
	<email>ntarmos@ceid.upatras.gr</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>nemysis@gmx.ch</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>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>No Name
	<email>salexanov@gmail.com</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>Norberto Lopes
	<email>nlopes.ml@gmail.com</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>Noritoshi Demizu
	<email>demizu@dd.iij4u.or.jp</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>Olafur Osvaldsson
	<email>oli@isnic.is</email></para>
	</listitem>

	<listitem>
	<para>Oleg Alexeenkov
	<email>proler@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Oleg Ginzburg
	<email>olevole@olevole.ru</email></para>
	</listitem>

	<listitem>
	<para>Oleg Kiselyov
	<email>oleg@pobox.com</email></para>
	</listitem>

	<listitem>
	<para>Oleg A. Mamontov
	<email>oleg@mamontov.net</email></para>
	</listitem>

	<listitem>
	<para>Oleg M. Golovanov
	<email>olmi@rentech.ru</email></para>
	</listitem>

	<listitem>
	<para>Oleg R. Muhutdinov
	<email>mor@whiteluna.com</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 Ukraincev
	<email>oleg@ht-systems.ru</email></para>
	</listitem>

	<listitem>
	<para>Oleg V. Volkov
	<email>rover@lglobus.ru</email></para>
	</listitem>

	<listitem>
	<para>Oleksandr Lystopad
	<email>laa@laa.zp.ua</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 Dunkl
	<email>odunkl@gmx.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 Hartmann
	<email>ohartman@zedat.fu-berlin.de</email></para>
	</listitem>

	<listitem>
	<para>Oliver Heesakkers
	<email>dev2@heesakkers.info</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>Oliver Peter
	<email>hoschi@mouhaha.de</email></para>
	</listitem>

	<listitem>
	<para>Olivier Beyssac
	<email>obld@r14.freenix.org</email></para>
	</listitem>

	<listitem>
	<para>Olivier Cochard-Labbé
	<email>olivier@cochard.me</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>Oscar Bonilla
	<email>obonilla@galileo.edu</email></para>
	</listitem>

	<listitem>
	<para>Otacílio de Araújo Ramos Neto
	<email>otacilio.neto@ee.ufcg.edu.br</email></para>
	</listitem>

	<listitem>
	<para>Otávio Fernandes
	<email>otaviof@gmail.com</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>Panagiotis Astithas
	<email>past@noc.ntua.gr</email></para>
	</listitem>

	<listitem>
	<para>Panagiotis Kritikakos
	<email>panoskrt@googlemail.com</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>Pascal Vizeli
	<email>pvizeli@yahoo.de</email></para>
	</listitem>

	<listitem>
	<para>Pasi Hirvonen
	<email>psh@iki.fi</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 Dung
	<email>patrick_dkt@yahoo.com.hk</email></para>
	</listitem>

	<listitem>
	<para>Patrick Hausen</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>Patrick Tracanelli
	<email>eksffa@freebsdbrasil.com.br</email></para>
	</listitem>

	<listitem>
	<para>Paul
	<email>onemda@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Paul A. Hoadley
	<email>paulh@logicsquad.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</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.</para>
	</listitem>

	<listitem>
	<para>Paul Sandys
	<email>myj@nyct.net</email></para>
	</listitem>

	<listitem>
	<para>Paul Schmehl
	<email>pauls@utdallas.edu</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 Fragoso
	<email>paulo@nlink.com.br</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 Pankov
	<email>pankov_p@mail.ru</email></para>
	</listitem>

	<listitem>
	<para>Pavel Veretennikov
	<email>vermut@kid.lv</email></para>
	</listitem>

	<listitem>
	<para>Pavel I Volkov
	<email>pavelivolkov@googlemail.com</email></para>
	</listitem>

	<listitem>
	<para>Pawel Worach
	<email>pawel.worach@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Pedro A M Vazquez
	<email>vazquez@IQM.Unicamp.BR</email></para>
	</listitem>

	<listitem>
	<para>Pengfei JU
	<email>jupengfei@gmail.com</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 Ankerstål
	<email>peter@pean.org</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>Pete French
	<email>pete@twisted.org.uk</email></para>
	</listitem>

	<listitem>
	<para>Peter Haight
	<email>peterh@prognet.com</email></para>
	</listitem>

	<listitem>
	<para>Peter Holub
	<email>hopet@ics.muni.cz</email></para>
	</listitem>

	<listitem>
	<para>Peter Klatt
	<email>glocke@bsdstammtisch.at</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</para>
	</listitem>

	<listitem>
	<para>Peter Philipp
	<email>pjp@bsd-daemon.net</email></para>
	</listitem>

	<listitem>
	<para>Peter S. Housel
	<email>housel@acm.org</email></para>
	</listitem>

	<listitem>
	<para>Peter Schuller
	<email>peter.schuller@infidyne.com</email></para>
	</listitem>

	<listitem>
	<para>Peter Stubbs
	<email>PETERS@staidan.qld.edu.au</email></para>
	</listitem>

	<listitem>
	<para>Péter Terbe
	<email>sncdev@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Peter Thoenen
	<email>peter.thoenen@yahoo.com</email></para>
	</listitem>

	<listitem>
	<para>Peter Vereshagin
	<email>peter@vereshagin.org</email></para>
	</listitem>

	<listitem>
	<para>Peter W. Schmiedeskamp
	<email>pschmied@qwest.net</email></para>
	</listitem>

	<listitem>
	<para>Peter van Dijk
	<email>peter@dataloss.nl</email></para>
	</listitem>

	<listitem>
	<para>Peter van Heusden
	<email>pvh@wfeet.za.net</email></para>
	</listitem>

	<listitem>
	<para>Petr Macek
	<email>pm@kostax.cz</email></para>
	</listitem>

	<listitem>
	<para>Petr Rehor
	<email>prehor@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Phil Budne
	<email>phil@ultimate.com</email></para>
	</listitem>

	<listitem>
	<para>Phil Maker
	<email>pjm@gnu.org</email></para>
	</listitem>

	<listitem>
	<para>Phil Oleson
	<email>oz@nixil.net</email></para>
	</listitem>

	<listitem>
	<para>Phil Phillips
	<email>pphillips@experts-exchange.com</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>p.musumeci@ieee.org</email></para>
	</listitem>

	<listitem>
	<para>Philip Reynolds
	<email>philip.reynolds@rfc-networks.ie</email></para>
	</listitem>

	<listitem>
	<para>Philip Schulz
	<email>phs@deadc0.de</email></para>
	</listitem>

	<listitem>
	<para>Philippe Lefebvre
	<email>nemesis@balistik.net</email></para>
	</listitem>

	<listitem>
	<para>Philippe Pepiot
	<email>phil@philpep.org</email></para>
	</listitem>

	<listitem>
	<para>Philippe Rocques
	<email>phil@teaser.fr</email></para>
	</listitem>

	<listitem>
	<para>Pierre David
	<email>pdagog@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Pierre Y. Dampure
	<email>pierre.dampure@k2c.co.uk</email></para>
	</listitem>

	<listitem>
	<para>Pierre-Paul Lavoie
	<email>ppl@nbnet.nb.ca</email></para>
	</listitem>

	<listitem>
	<para>Pieter Danhieux
	<email>opr@bsdaemon.be</email></para>
	</listitem>

	<listitem>
	<para>Piotr Florczyk
	<email>p.florczyk@adminworkshop.pl</email></para>
	</listitem>

	<listitem>
	<para>Piotr Rybicki
	<email>meritus@innervision.pl</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>Pontus Stenetorp
	<email>ninjin@kth.se</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>Prudhvi Krishna
	<email>prudhvikrishna@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Qing Feng
	<email>qingfeng@me.com</email></para>
	</listitem>

	<listitem>
	<para>Quentin Stievenart
	<email>acieroid@awesom.eu</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>R Skinner
	<email>port_maintainer@herveybayaustralia.com.au</email></para>
	</listitem>

	<listitem>
	<para>Radek Kozlowski
	<email>radek@raadradd.com</email></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>Rafal Lesniak
	<email>fbsd@grid.einherjar.de</email></para>
	</listitem>

	<listitem>
	<para>Raffaele De Lorenzo
	<email>raffaele.delorenzo@libero.it</email></para>
	</listitem>

	<listitem>
	<para>Rainer Duffer
	<email>rainer@ultra-secure.de</email></para>
	</listitem>

	<listitem>
	<para>Rainer Hurling
	<email>rhurlin@gwdg.de</email></para>
	</listitem>

	<listitem>
	<para>Ralf Friedl
	<email>friedl@informatik.uni-kl.de</email></para>
	</listitem>

	<listitem>
	<para>Ralf Gebhart
	<email>gebhart@secnetix.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>rasmus@kaj.se</email></para>
	</listitem>

	<listitem>
	<para>Raul Pollicino
	<email>email-ports@def-defying.com</email></para>
	</listitem>

	<listitem>
	<para>Razi Khaja
	<email>razi@genet.sickkids.on.ca</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>Revis Zinkov
	<email>rzinkov@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Ricardas Cepas
	<email>rch@richard.eu.org</email></para>
	</listitem>

	<listitem>
	<para>Ricardo A. Reis
	<email>ricardo.areis@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Riccardo Veraldi
	<email>veraldi@cs.unibo.it</email></para>
	</listitem>

	<listitem>
	<para>Rich Morin
	<email>rdm@cfcl.com</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 Macklin</para>
	</listitem>

	<listitem>
	<para>Rick van der Zwet
	<email>rick@wzoeterwoude.net</email></para>
	</listitem>

	<listitem>
	<para>Roar Pettersen
	<email>roar.pettersen@it.uib.no</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 Crossfield
	<email>robcrossfield@gmail.com</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 Felber
	<email>robtone@ek-muc.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 Schlotterbeck
	<email>robert@rs.tarrant.tx.us</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 Simmons
	<email>rsimmons0@gmail.com</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</para>
	</listitem>

	<listitem>
	<para>Robin Carey
	<email>robin@mailgate.dtc.rankxerox.co.uk</email></para>
	</listitem>

	<listitem>
	<para>Robin Elfrink
	<email>elfrink@introweb.nl</email></para>
	</listitem>

	<listitem>
	<para>Robin Schilham
	<email>co9@xs4all.nl</email></para>
	</listitem>

	<listitem>
	<para>Robin Schoonover
	<email>robin.schoonover@gmail.google.com</email></para>
	</listitem>

	<listitem>
	<para>Rod Taylor
	<email>ports@rbt.ca</email></para>
	</listitem>

	<listitem>
	<para>Rodrigo Graeff
	<email>delphus@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Rodrigo Osorio
	<email>rodrigo@bebik.net</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>Roland Smith
	<email>rsmith@xs4all.nl</email></para>
	</listitem>

	<listitem>
	<para>Dr. Rolf Jansen
	<email>cyclaero@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Roman Neuhauser
	<email>neuhauser@chello.cz</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>Roman V. Palagin
	<email>romanp@unshadow.net</email></para>
	</listitem>

	<listitem>
	<para>Roman Y. Bogdanov
	<email>sam@brj.pp.ru</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>Ron van Daal
	<email>ronvdaal@n1x.nl</email></para>
	</listitem>

	<listitem>
	<para>Ronald F. Guilmette
	<email>rfg@monkeys.com</email></para>
	</listitem>

	<listitem>
	<para>Ronald Klop
	<email>ronald@echteman.nl</email></para>
	</listitem>

	<listitem>
	<para>Ronald Kuehn
	<email>kuehn@rz.tu-clausthal.de</email></para>
	</listitem>

	<listitem>
	<para>Roselyn Lee
	<email>rosel@verniernetworks.com</email></para>
	</listitem>

	<listitem>
	<para>Ross West
	<email>freebsd@linepoint.com</email></para>
	</listitem>

	<listitem>
	<para>Rostislav Krasny
	<email>rosti.bsd@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Roy Maples
	<email>roy@marples.name</email></para>
	</listitem>

	<listitem>
	<para>Ruben
	<email>chromium@hybridsource.org</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>Rusty Nejdl
	<email>rnejdl@ringofsaturn.com</email></para>
	</listitem>

	<listitem>
	<para>Ryan Grove
	<email>ryan@wonko.com</email></para>
	</listitem>

	<listitem>
	<para>Ryan Moe
	<email>ryan@transaeris.com</email></para>
	</listitem>

	<listitem>
	<para>Ryan T. Dean
	<email>rtdean@cytherianage.net</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>Ryo MIYAMOTO
	<email>rmiya@cc.hirosaki-u.ac.jp</email></para>
	</listitem>

	<listitem>
	<para>Ryo Okamoto
	<email>ryo@aquahill.net</email></para>
	</listitem>

	<listitem>
	<para>RyoTa SimaMoto
	<email>liangtai.s4@gmail.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>SPF
	<email>spf@xslt.cs.nccu.edu.tw</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>Samuel Lam
	<email>skl@ScalableNetwork.com</email></para>
	</listitem>

	<listitem>
	<para>Samuel Tardieu
	<email>sam@rfc1149.net</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>Sarod Yatawatta
	<email>sarod@users.sf.net</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 Klauder
	<email>sklauder@trimind.de</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>Saulius Menkevicius
	<email>bob@nulis.lt</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 Kleihege
	<email>scott-ports@tummy.com</email></para>
	</listitem>

	<listitem>
	<para>Scott Lambert
	<email>lambert@lambertfam.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>Scott Ullrich
	<email>sullrich@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>SeaD
	<email>sead@mail.ru</email></para>
	</listitem>

	<listitem>
	<para>Sean McLaughlin
	<email>sigma.zx@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Seamus Venasse
	<email>svenasse@polaris.ca</email></para>
	</listitem>

	<listitem>
	<para>Sébastian Santoro
	<email>dereckson@gmail.com</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>Seiya Yanagita
	<email>s_yanagita@ybb.ne.jp</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>Sergei Vyshenski
	<email>svysh@pn.sinp.msu.ru</email></para>
	</listitem>

	<listitem>
	<para>Sergey Akifyev
	<email>asa@gascom.ru</email></para>
	</listitem>

	<listitem>
	<para>Sergey V. Dyatko
	<email>sergey.dyatko@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Sergey Gershtein
	<email>sg@mplik.ru</email></para>
	</listitem>

	<listitem>
	<para>Sergey Glushchenko
	<email>deen@smz.com.ua</email></para>
	</listitem>

	<listitem>
	<para>Sergey Kosyakov
	<email>ks@itp.ac.ru</email></para>
	</listitem>

	<listitem>
	<para>Sergey Lyubka
	<email>valenok@gmail.com</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>Sergey Velichkevych
	<email>serg@cad.kiev.ua</email></para>
	</listitem>

	<listitem>
	<para>Sergio Lenzi
	<email>lenzi@bsi.com.br</email></para>
	</listitem>

	<listitem>
	<para>Sevan Janiyan
	<email>venture37@geeklan.co.uk</email></para>
	</listitem>

	<listitem>
	<para>Shane Ambler
	<email>freebsd@shaneware.biz</email></para>
	</listitem>

	<listitem>
	<para>Shane Kinney
	<email>mod6@freebsdhackers.net</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>Shigeru Yamamoto
	<email>shigeru@iij.ad.jp</email></para>
	</listitem>

	<listitem>
	<para>Shigio Yamaguchi
	<email>shigio@tamacom.com</email></para>
	</listitem>

	<listitem>
	<para>Shin'ya Murakami
	<email>murakami@ahs.scitec.kobe-u.ac.jp</email></para>
	</listitem>

	<listitem>
	<para>Shinichiro Komatsu
	<email>koma2@ms.u-tokyo.ac.jp</email></para>
	</listitem>

	<listitem>
	<para>Shinsuke Matsui
	<email>smatsui@karashi.org</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>Shuichi Tanaka
	<email>stanaka@bb.mbn.or.jp</email></para>
	</listitem>

	<listitem>
	<para>Siebrand Mazeland
	<email>s.mazeland@xs4all.nl</email></para>
	</listitem>

	<listitem>
	<para>Simon
	<email>simon@masi.ibp.fr</email></para>
	</listitem>

	<listitem>
	<para>Simon Burge
	<email>simonb@telstra.com.au</email></para>
	</listitem>

	<listitem>
	<para>Simon Cornelius P. Umacob
	<email>simoncpu@infoweapons.com</email></para>
	</listitem>

	<listitem>
	<para>Simon Dick
	<email>simond@irrelevant.org</email></para>
	</listitem>

	<listitem>
	<para>Simon Lang
	<email>simon@lang-clan.de</email></para>
	</listitem>

	<listitem>
	<para>Simon Marlow
	<email>simonmar@microsoft.com</email></para>
	</listitem>

	<listitem>
	<para>Simon Olofsson
	<email>simon@olofsson.de</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>Simun Mikecin
	<email>sime@logos.hr</email></para>
	</listitem>

	<listitem>
	<para>Sin'ichiro MIYATANI
	<email>siu@phaseone.co.jp</email></para>
	</listitem>

	<listitem>
	<para>Slaven Rezic
	<email>slaven@rezic.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 Debois
	<email>debois@diku.dk</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>Stan Barber
	<email>sob@academ.com</email></para>
	</listitem>

	<listitem>
	<para>Stanislav A. Svirid
	<email>count@riss-telecom.ru</email></para>
	</listitem>

	<listitem>
	<para>Stanislav Grozev
	<email>tacho@daemonz.org</email></para>
	</listitem>

	<listitem>
	<para>Stanislaw Halik
	<email>sthalik@tehran.lain.pl</email></para>
	</listitem>

	<listitem>
	<para>Stanislav Shalunov
	<email>shalunov@internet2.edu</email></para>
	</listitem>

	<listitem>
	<para>Stas Timokhin
	<email>devel@stasyan.com</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</para>
	</listitem>

	<listitem>
	<para>Stefan Rumetshofer
	<email>sterum@overrider.at</email></para>
	</listitem>

	<listitem>
	<para>Stefan Schmidt
	<email>stefan.schmidt@twest.de</email></para>
	</listitem>

	<listitem>
	<para>Stefan Schwarzer
	<email>sschwarzer@sschwarzer.net</email></para>
	</listitem>

	<listitem>
	<para>Stefan Tell
	<email>stefan.tell@crashmail.de</email></para>
	</listitem>

	<listitem>
	<para>Stefan `Sec` Zehl
	<email>sec@42.org</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>Steinar Haug
	<email>sthaug@nethelp.no</email></para>
	</listitem>

	<listitem>
	<para>Sten Poldma
	<email>exile@chamber.ee</email></para>
	</listitem>

	<listitem>
	<para>Sten Spans
	<email>sten@blinkenlights.nl</email></para>
	</listitem>

	<listitem>
	<para>Stepan Zastupov
	<email>redchrom@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Stephane Lapie
	<email>stephane.lapie@darkbsd.org</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 Fisher
	<email>stephentfisher@yahoo.com</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 Hurd
	<email>admin@nix.synchro.net</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>Stephon Chen
	<email>stephon@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Steve Ames
	<email>steve@energistic.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</para>
	</listitem>

	<listitem>
	<para>Steve Franks
	<email>bahamasfranks@gmail.com</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>Steve O'Hara-Smith
	<email>steve@sohara.org</email></para>
	</listitem>

	<listitem>
	<para>Steve Piette
	<email>steve@simon.chi.il.US</email></para>
	</listitem>

	<listitem>
	<para>Steve Roome
	<email>steve@pepcross.com</email></para>
	</listitem>

	<listitem>
	<para>Steve Schwarz
	<email>schwarz@alpharel.com</email></para>
	</listitem>

	<listitem>
	<para>Steve Wills
	<email>steve@mouf.net</email></para>
	</listitem>

	<listitem>
	<para>Steven Enderle
	<email>panic@subphase.de</email></para>
	</listitem>

	<listitem>
	<para>Steven H. Samorodin
	<email>samorodi@NUXI.com</email></para>
	</listitem>

	<listitem>
	<para>Steven Hartland
	<email>steven.hartland@multiplay.co.uk</email></para>
	</listitem>

	<listitem>
	<para>Steven Honson
	<email>steven@honson.org</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</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>Stylianos Sideridis
	<email>siderste@yahoo.gr</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>Sulev-Madis Silber
	<email>madis555@hot.ee</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>Sutra Zhou
	<email>zhoushuqun@gmail.com</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>Sven Klose
	<email>pixel@hugbox.org</email></para>
	</listitem>

	<listitem>
	<para>Sven Mohr
	<email>svmohr@rm6.net</email></para>
	</listitem>

	<listitem>
	<para>Svyatoslav Lempert
	<email>svyatoslav.lempert@gmail.com</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>TERAMOTO Masahiro
	<email>markun@onohara.to</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>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>Tanja Wittke
	<email>tawi@gruft.de</email></para>
	</listitem>

	<listitem>
	<para>Tarasov Alexey
	<email>master@preved.cn</email></para>
	</listitem>

	<listitem>
	<para>Tassilo Philipp
	<email>tphilipp@potion-studios.com</email></para>
	</listitem>

	<listitem>
	<para>Tatoku Ogaito
	<email>tacha@tera.fukui-med.ac.jp</email></para>
	</listitem>

	<listitem>
	<para>Tatsuki Makino
	<email>tatsuki_makino@hotmail.com</email></para>
	</listitem>

	<listitem>
	<para>Tatsuya Kudoh
	<email>cdr@cosmonet.org</email></para>
	</listitem>

	<listitem>
	<para>Tatsuya Ueda
	<email>ml+freebsd@tatsuya.info</email></para>
	</listitem>

	<listitem>
	<para>Taylor Dondich
	<email>tdondich@majiknetworks.com</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>Ted Stodgell
	<email>trs137@psu.edu</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>Terry Sposato
	<email>terry@sucked-in.com</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>Thaddeus Covert
	<email>tcovert+ports@sahuagin.net</email></para>
	</listitem>

	<listitem>
	<para>Theo de Raadt
	<email>deraadt@OpenBSD.org</email></para>
	</listitem>

	<listitem>
	<para>Thierry Dussuet
	<email>thierry@dussuet.lugs.ch</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 BRETON
	<email>tom@h-inventory.com</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 Dreibholz
	<email>dreibh@iem.uni-due.de</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 Hurst
	<email>tom@hur.st</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 Melzer
	<email>tmelzer@tomesoft.de</email></para>
	</listitem>

	<listitem>
	<para>Thomas Ptacek</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-Martin Seck
	- <email>tmseck@netcologne.de</email></para>
	- </listitem>
	-
	- <listitem>
	<para>Thorsten Greiner
	<email>thorsten@tgreiner.net</email></para>
	</listitem>

	<listitem>
	<para>Þórður Ívarsson
	<email>totii@est.is</email></para>
	</listitem>

	<listitem>
	<para>Tillman Hodgson
	<email>tillman@seekingfire.com</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 Niemueller
	<email>tim@niemueller.de</email></para>
	</listitem>

	<listitem>
	<para>Tim Pozar
	<email>pozar@lns.com</email></para>
	</listitem>

	<listitem>
	<para>Tim Singletary
	<email>tsingle@sunland.gsfc.nasa.gov</email></para>
	</listitem>

	<listitem>
	<para>Tim Welch
	<email>ports@thepentagon.org</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>Timofeev Vladimir
	<email>vovkasm@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Timothy Beyer
	<email>beyert@cs.ucr.edu</email></para>
	</listitem>

	<listitem>
	<para>Timothy Bourke
	<email>timbob@bigpond.com</email></para>
	</listitem>

	<listitem>
	<para>Timothy Jensen
	<email>toast@blackened.com</email></para>
	</listitem>

	<listitem>
	<para>Timothy Redaelli
	<email>drizzt@drizzt.ath.cx</email></para>
	</listitem>

	<listitem>
	<para>Tobias Begalke
	<email>tobega@spyz.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>Todd Mortensen
	<email>todd@thisisa.com</email></para>
	</listitem>

	<listitem>
	<para>Tofig Suleymanov
	<email>tofig@freebsd.az</email></para>
	</listitem>

	<listitem>
	<para>Tom
	<email>root@majestix.cmr.no</email></para>
	</listitem>

	<listitem>
	<para>Tom Carrick
	<email>knyghtmare@knyghtmare.com</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 Mortensen
	<email>tom@tavrasm.org</email></para>
	</listitem>

	<listitem>
	<para>Tom Mueller-Kortkamp
	<email>tmueko@kommunity.net</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>Tomas Verbaitis
	<email>tomasv@megalogika.lt</email></para>
	</listitem>

	<listitem>
	+ <para>Tomasz Walaszek
	+ <email>tmwalaszek@gmail.com</email></para>
	+ </listitem>
	+
	+ <listitem>
	<para>Tomaz<!-- &zcaron; not rendered?--> Muraus
	<email>kami@k5-storitve.net</email></para>
	</listitem>

	<listitem>
	<para>Tomek Cedro
	<email>tomek.cedro@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Tomohiko Kurahashi
	<email>kura@melchior.q.t.u-tokyo.ac.jp</email></para>
	</listitem>

	<listitem>
	<para>Tomoyuki Sakurai
	<email>cherry@trombik.org</email></para>
	</listitem>

	<listitem>
	<para>Toni Andjelkovic
	<email>toni@soth.at</email></para>
	</listitem>

	<listitem>
	<para>Toni Gundogdu
	<email>legatvs@gmail.com</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>Tony Shadwick
	<email>numbski@hksilver.net</email></para>
	</listitem>

	<listitem>
	<para>Tor Halvard "Squat" Furulund
	<email>squat@squat.no</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>Trevor Cornpropst
	<email>tcornpropst@cox.net</email></para>
	</listitem>

	<listitem>
	<para>Troels Kofoed Jacobsen
	<email>tkjacobsen@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Tsung-Han Yeh
	<email>snowfly@yuntech.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>Tz-Huan Huang
	<email>tzhuan@gmail.com</email></para>
	</listitem>

	<listitem>
	+ <para>Tzanetos Balitsaris
	+ <email>tzabal@it.teithe.gr</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>udo.schweigert@siemens.com</email></para>
	</listitem>

	<listitem>
	<para>Uffe Jakobsen
	<email>uffe@uffe.org</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>Ullrich Franke
	<email>trash.esiac@googlemail.com</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>Vaggelis Typaldos
	<email>frances@mylannet.gr</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 Goncharov
	<email>vadim_nuclight@mail.ru</email></para>
	</listitem>

	<listitem>
	<para>Vadim Kolontsov
	<email>vadim@tversu.ac.ru</email></para>
	</listitem>

	<listitem>
	<para>Vadim Kurland
	<email>vadim@fwbuilder.org</email></para>
	</listitem>

	<listitem>
	<para>Vadim Mikhailov
	<email>mvp@braz.ru</email></para>
	</listitem>

	<listitem>
	<para>Vaida Bogdan
	<email>vaida.bogdan@gmail.com</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>Valery Komarov
	<email>komarov@valerka.net</email></para>
	</listitem>

	<listitem>
	<para>Van Jacobson
	<email>van@ee.lbl.gov</email></para>
	</listitem>

	<listitem>
	<para>Vany Serezhkin
	<email>ivan@serezhkin.com</email></para>
	</listitem>

	<listitem>
	<para>Vaclav Haisman
	<email>v.haisman@sh.cvut.cz</email></para>
	</listitem>

	<listitem>
	<para>Vasek Balcar
	<email>vasek@ti.cz</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>Veniamin Gvozdikov
	<email>g.veniamin@googlemail.com</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>Victor Cruceru
	<email>victor.cruceru@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Victor Popov
	<email>v.a.popov@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Victor Semionov
	<email>semionov@mail.bg</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>Vitaly Magerya
	<email>vmagerya@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Vivek Khera
	<email>vivek@khera.org</email></para>
	</listitem>


	<listitem>
	<para>Vlad GALU
	<email>dudu@dudu.ro</email></para>
	</listitem>

	<listitem>
	<para>Vlad V. Teterya
	<email>vlad@vlad.uz.ua</email></para>
	</listitem>

	<listitem>
	<para>Vladimir A. Jakovenko
	<email>vovik@ntu-kpi.kiev.ua</email></para>
	</listitem>

	<listitem>
	<para>Vladimir Gorelov
	<email>virtual.lark@gmail.com</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 Osintsev
	<email>oc@nm.ru</email></para>
	</listitem>

	<listitem>
	<para>Vladimir Savichev
	<email>vlad@ariel.phys.wesleyan.edu</email></para>
	</listitem>

	<listitem>
	<para>Volker Theile
	<email>votdev@gmx.de</email></para>
	</listitem>

	<listitem>
	<para>Volker Quetschke
	<email>quetschke@scytek.de</email></para>
	</listitem>

	<listitem>
	<para>Volodymyr Kostyrko
	<email>c.kworr@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Vsevolod Lobko
	<email>seva@ip.net.ua</email></para>
	</listitem>

	<listitem>
	<para>Vyacheslav Anikin
	<email>ghos@mail.ru</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>Waitman Gobble
	+ <email>waitman@waitman.net</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>Watanabe Kazuhiro
	<email>CQG00620@nifty.ne.jp</email></para>
	</listitem>

	<listitem>
	<para>Wayne Scott
	<email>wscott@ichips.intel.com</email></para>
	</listitem>

	<listitem>
	<para>Wei-Hao Syu
	<email>whsyu@arbor.ee.ntu.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>Wei-Yu Chen
	<email>weiyu.csie@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Wei Guo
	<email>darcsis@gmail.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 Jan Withagen
	<email>wjw@withagen.nl</email></para>
	</listitem>

	<listitem>
	<para>Willem van Engen
	<email>wvengen@stack.nl</email></para>
	</listitem>

	<listitem>
	<para>William Grzybowski
	<email>william88@gmail.com</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>&a.wolf.email;</para>
	</listitem>

	<listitem>
	<para>Woodchuck Dave
	<email>djv@bedford.net</email></para>
	</listitem>

	<listitem>
	<para>Woody Carey
	<email>woodycarey@hotmail.com</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.email;</para>
	</listitem>

	<listitem>
	<para>Xavier Beaudouin
	<email>kiwi@oav.net</email></para>
	</listitem>

	<listitem>
	<para>Yamagi Burmeister
	<email>yamagi@yamagi.org</email></para>
	</listitem>

	<listitem>
	<para>Yanhui Shen
	<email>shen.elf@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Yann Berthier
	<email>yb@bachibouzouk.org</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>Yi-Feng Tzeng
	<email>yftzeng@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Yi-Hsuan Hsin
	<email>mhsin@mhsin.org</email></para>
	</listitem>

	<listitem>
	<para>Ying-Chieh Chen
	<email>yinjieh@csie.nctu.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>Yinghong Liu
	<email>relaxbsd@gmail.com</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>Yoshiaki Uchikawa
	<email>yoshiaki@kt.rim.or.jp</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>Yuan-Chung Hsiao
	<email>ychsiao@ychsiao.idv.tw</email></para>
	</listitem>

	<listitem>
	<para>Yuan Jue
	<email>yuanjue@yuanjue.net</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>Yuki SHIMAZU
	<email>y.shimazu@nifty.com</email></para>
	</listitem>

	<listitem>
	<para>Yuri Kurenkov
	<email>y.kurenkov@init.ru</email></para>
	</listitem>

	<listitem>
	<para>Yuriy N. Shkandybin
	<email>jura@netams.com</email></para>
	</listitem>

	<listitem>
	<para>Yuriy Tsibizov
	<email>Yuriy.Tsibizov@gfk.ru</email></para>
	</listitem>

	<listitem>
	<para>Yusuke Nawano
	<email>azuki@azkey.org</email></para>
	</listitem>

	<listitem>
	<para>Yu-Xi Lim
	<email>yuxi@gmx.net</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 Thompson
	<email>hideo@lastamericanempire.com</email></para>
	</listitem>

	<listitem>
	<para>Zach Zurflu
	<email>zach@pabst.bendnet.com</email></para>
	</listitem>

	<listitem>
	<para>Zachariah Thompson
	<email>lin-chi@lastamericanempire.com</email></para>
	</listitem>

	<listitem>
	<para>Zak Johnson
	<email>zakj@nox.cx</email></para>
	</listitem>

	<listitem>
	<para>Zane C. Bowers
	<email>vvelox@vvelox.net</email></para>
	</listitem>

	<listitem>
	<para>Zhen REN
	<email>bg1tpt@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Zhihao Yuan
	<email>lichray@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Zhixiang JIANG
	<email>luckrill@yahoo.com.cn</email></para>
	</listitem>

	<listitem>
	<para>Zhong Ming-Xun
	<email>zmx@mail.CDPA.nsysu.edu.tw</email></para>
	</listitem>

	<listitem>
	<para>appleboy
	<email>appleboy.tw@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>arci
	<email>vega@sophia.inria.fr</email></para>
	</listitem>

	<listitem>
	<para>ayunyan
	<email>ayunyan@gmail.com</email></para>
	</listitem>

	<listitem>
	<para>Bartoletti
	<email>coder@tuxfamily.org</email></para>
	</listitem>

	<listitem>
	<para>der Mouse
	<email>mouse@Collatz.McRCIM.McGill.EDU</email></para>
	</listitem>

	<listitem>
	<para>Piotr Szerman
	<email>pmsz@tlen.pl</email></para>
	</listitem>

	<listitem>
	<para>rossiya
	<email>rossiya@gmail.com</email></para>
	</listitem>

	</itemizedlist>
	Index: projects/entities/en_US.ISO8859-1/articles/contributors/contrib.committers.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/contributors/contrib.committers.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/contributors/contrib.committers.xml (revision 41355)
	@@ -1,1681 +1,1689 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!-- $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.ariff.email;</para>
	</listitem>

	<listitem>
	<para>&a.tabthorpe.email;</para>
	</listitem>

	<listitem>
	<para>&a.eadler.email;</para>
	</listitem>

	<listitem>
	<para>&a.akiyama.email;</para>
	</listitem>

	<listitem>
	<para>&a.monthadar.email;</para>
	</listitem>

	<listitem>
	<para>&a.ambrisko.email;</para>
	</listitem>

	<listitem>
	<para>&a.shaun.email;</para>
	</listitem>

	<listitem>
	<para>&a.brix.email;</para>
	</listitem>

	<listitem>
	<para>&a.jonathan.email;</para>
	</listitem>

	<listitem>
	<para>&a.mandree.email;</para>
	</listitem>

	<listitem>
	<para>&a.will.email;</para>
	</listitem>

	<listitem>
	<para>&a.dim.email;</para>
	</listitem>

	<listitem>
	<para>&a.mva.email;</para>
	</listitem>

	<listitem>
	<para>&a.araujo.email;</para>
	</listitem>

	<listitem>
	<para>&a.mat.email;</para>
	</listitem>

	<listitem>
	<para>&a.syuu.email;</para>
	</listitem>

	<listitem>
	<para>&a.gavin.email;</para>
	</listitem>

	<listitem>
	<para>&a.jsa.email;</para>
	</listitem>

	<listitem>
	<para>&a.jadawin.email;</para>
	</listitem>

	<listitem>
	<para>&a.timur.email;</para>
	</listitem>

	<listitem>
	<para>&a.jhb.email;</para>
	</listitem>

	<listitem>
	<para>&a.gjb.email;</para>
	</listitem>

	<listitem>
	<para>&a.art.email;</para>
	</listitem>

	<listitem>
	<para>&a.kib.email;</para>
	</listitem>

	<listitem>
	<para>&a.tobez.email;</para>
	</listitem>

	<listitem>
	<para>&a.gber.email;</para>
	</listitem>

	<listitem>
	<para>&a.pb.email;</para>
	</listitem>

	<listitem>
	<para>&a.tdb.email;</para>
	</listitem>

	<listitem>
	<para>&a.gblach.email;</para>
	</listitem>

	<listitem>
	<para>&a.mbr.email;</para>
	</listitem>

	<listitem>
	<para>&a.wblock.email;</para>
	</listitem>

	<listitem>
	<para>&a.novel.email;</para>
	</listitem>

	<listitem>
	<para>&a.garga.email;</para>
	</listitem>

	<listitem>
	<para>&a.sbz.email;</para>
	</listitem>

	<listitem>
	<para>&a.ebrandi.email;</para>
	</listitem>

	<listitem>
	<para>&a.harti.email;</para>
	</listitem>

	<listitem>
	<para>&a.makc.email;</para>
	</listitem>

	<listitem>
	<para>&a.antoine.email;</para>
	</listitem>

	<listitem>
	<para>&a.db.email;</para>
	</listitem>

	<listitem>
	<para>&a.sbruno.email;</para>
	</listitem>

	<listitem>
	<para>&a.brueffer.email;</para>
	</listitem>

	<listitem>
	<para>&a.markus.email;</para>
	</listitem>

	<listitem>
	<para>&a.oleg.email;</para>
	</listitem>

	<listitem>
	<para>&a.jchandra.email;</para>
	</listitem>

	<listitem>
	<para>&a.acm.email;</para>
	</listitem>

	<listitem>
	<para>&a.carvay.email;</para>
	</listitem>

	<listitem>
	<para>&a.gahr.email;</para>
	</listitem>

	<listitem>
	<para>&a.adrian.email;</para>
	</listitem>

	<listitem>
	<para>&a.dchagin.email;</para>
	</listitem>

	<listitem>
	<para>&a.charnier.email;</para>
	</listitem>

	<listitem>
	<para>&a.jon.email;</para>
	</listitem>

	<listitem>
	<para>&a.loader.email;</para>
	</listitem>

	<listitem>
	<para>&a.luoqi.email;</para>
	</listitem>

	<listitem>
	<para>&a.ache.email;</para>
	</listitem>

	<listitem>
	<para>&a.melifaro.email;</para>
	</listitem>

	<listitem>
	<para>&a.theraven.email;</para>
	</listitem>

	<listitem>
	<para>&a.davidch.email;</para>
	</listitem>

	<listitem>
	<para>&a.marcus.email;</para>
	</listitem>

	<listitem>
	<para>&a.tijl.email;</para>
	</listitem>

	<listitem>
	<para>&a.rakuco.email;</para>
	</listitem>

	<listitem>
	<para>&a.alc.email;</para>
	</listitem>

	<listitem>
	<para>&a.cracauer.email;</para>
	</listitem>

	<listitem>
	<para>&a.brucec.email;</para>
	</listitem>

	<listitem>
	<para>&a.culot.email;</para>
	</listitem>

	<listitem>
	<para>&a.joel.email;</para>
	</listitem>

	<listitem>
	<para>&a.bapt.email;</para>
	</listitem>

	<listitem>
	<para>&a.davidc.email;</para>
	</listitem>

	<listitem>
	<para>&a.brd.email;</para>
	</listitem>

	<listitem>
	<para>&a.brooks.email;</para>
	</listitem>

	<listitem>
	<para>&a.pjd.email;</para>
	</listitem>

	<listitem>
	<para>&a.jwd.email;</para>
	</listitem>

	<listitem>
	<para>&a.carl.email;</para>
	</listitem>

	<listitem>
	<para>&a.vd.email;</para>
	</listitem>

	<listitem>
	<para>&a.rdivacky.email;</para>
	</listitem>

	<listitem>
	<para>&a.mdodd.email;</para>
	</listitem>

	<listitem>
	<para>&a.danfe.email;</para>
	</listitem>

	<listitem>
	<para>&a.dd.email;</para>
	</listitem>

	<listitem>
	<para>&a.iedowse.email;</para>
	</listitem>

	<listitem>
	<para>&a.bdrewery.email;</para>
	</listitem>

	<listitem>
	<para>&a.gad.email;</para>
	</listitem>

	<listitem>
	<para>&a.olivierd.email;</para>
	</listitem>

	<listitem>
	<para>&a.bruno.email;</para>
	</listitem>

	<listitem>
	<para>&a.ale.email;</para>
	</listitem>

	<listitem>
	<para>&a.peadar.email;</para>
	</listitem>

	<listitem>
	<para>&a.deischen.email;</para>
	</listitem>

	<listitem>
	<para>&a.eivind.email;</para>
	</listitem>

	<listitem>
	<para>&a.julian.email;</para>
	</listitem>

	<listitem>
	<para>&a.ae.email;</para>
	</listitem>

	<listitem>
	<para>&a.lme.email;</para>
	</listitem>

	<listitem>
	<para>&a.rse.email;</para>
	</listitem>

	<listitem>
	<para>&a.ru.email;</para>
	</listitem>

	<listitem>
	<para>&a.le.email;</para>
	</listitem>

	<listitem>
	<para>&a.se.email;</para>
	</listitem>

	<listitem>
	<para>&a.bde.email;</para>
	</listitem>

	<listitem>
	<para>&a.jasone.email;</para>
	</listitem>

	<listitem>
	<para>&a.bf.email;</para>
	</listitem>

	<listitem>
	<para>&a.madpilot.email;</para>
	</listitem>

	<listitem>
	<para>&a.rafan.email;</para>
	</listitem>

	<listitem>
	<para>&a.stefanf.email;</para>
	</listitem>

	<listitem>
	<para>&a.scf.email;</para>
	</listitem>

	<listitem>
	<para>&a.green.email;</para>
	</listitem>

	<listitem>
	<para>&a.lioux.email;</para>
	</listitem>

	<listitem>
	<para>&a.fanf.email;</para>
	</listitem>

	<listitem>
	<para>&a.mdf.email;</para>
	</listitem>

	<listitem>
	<para>&a.blackend.email;</para>
	</listitem>

	<listitem>
	<para>&a.olli.email;</para>
	</listitem>

	<listitem>
	<para>&a.decke.email;</para>
	</listitem>

	<listitem>
	<para>&a.shige.email;</para>
	</listitem>

	<listitem>
	<para>&a.gallatin.email;</para>
	</listitem>

	<listitem>
	<para>&a.avg.email;</para>
	</listitem>

	<listitem>
	<para>&a.beat.email;</para>
	</listitem>

	<listitem>
	<para>&a.danger.email;</para>
	</listitem>

	<listitem>
	<para>&a.sjg.email;</para>
	</listitem>

	<listitem>
	<para>&a.gibbs.email;</para>
	</listitem>

	<listitem>
	<para>&a.pfg.email;</para>
	</listitem>

	<listitem>
	<para>&a.girgen.email;</para>
	</listitem>

	<listitem>
	<para>&a.pgollucci.email;</para>
	</listitem>

	<listitem>
	<para>&a.trociny.email;</para>
	</listitem>

	<listitem>
	<para>&a.daichi.email;</para>
	</listitem>

	<listitem>
	<para>&a.bgray.email;</para>
	</listitem>

	<listitem>
	<para>&a.dg.email;</para>
	</listitem>

	<listitem>
	<para>&a.grehan.email;</para>
	</listitem>

	<listitem>
	<para>&a.jamie.email;</para>
	</listitem>

	<listitem>
	<para>&a.edwin.email;</para>
	</listitem>

	<listitem>
	<para>&a.bar.email;</para>
	</listitem>

	<listitem>
	<para>&a.jmg.email;</para>
	</listitem>

	<listitem>
	<para>&a.mjg.email;</para>
	</listitem>

	<listitem>
	<para>&a.jhale.email;</para>
	</listitem>

	<listitem>
	<para>&a.randi.email;</para>
	</listitem>

	<listitem>
	+ <para>&a.smh.email;</para>
	+ </listitem>
	+
	+ <listitem>
	<para>&a.ehaupt.email;</para>
	</listitem>

	<listitem>
	<para>&a.jhay.email;</para>
	</listitem>

	<listitem>
	<para>&a.jh.email;</para>
	</listitem>

	<listitem>
	<para>&a.jgh.email;</para>
	</listitem>

	<listitem>
	<para>&a.ghelmer.email;</para>
	</listitem>

	<listitem>
	<para>&a.mux.email;</para>
	</listitem>

	<listitem>
	<para>&a.wen.email;</para>
	</listitem>

	<listitem>
	<para>&a.dhn.email;</para>
	</listitem>

	<listitem>
	<para>&a.jhibbits.email;</para>
	</listitem>

	<listitem>
	<para>&a.nhibma.email;</para>
	</listitem>

	<listitem>
	<para>&a.pho.email;</para>
	</listitem>

	<listitem>
	<para>&a.mich.email;</para>
	</listitem>

	<listitem>
	<para>&a.cognet.email;</para>
	</listitem>

	<listitem>
	<para>&a.sunpoet.email;</para>
	</listitem>

	<listitem>
	<para>&a.lwhsu.email;</para>
	</listitem>

	<listitem>
	<para>&a.chinsan.email;</para>
	</listitem>

	<listitem>
	<para>&a.davide.email;</para>
	</listitem>

	<listitem>
	<para>&a.iwasaki.email;</para>
	</listitem>

	<listitem>
	<para>&a.mjacob.email;</para>
	</listitem>

	<listitem>
	<para>&a.versus.email;</para>
	</listitem>

	<listitem>
	<para>&a.raj.email;</para>
	</listitem>

	<listitem>
	<para>&a.gj.email;</para>
	</listitem>

	<listitem>
	<para>&a.weongyo.email;</para>
	</listitem>

	<listitem>
	<para>&a.peterj.email;</para>
	</listitem>

	<listitem>
	<para>&a.jinmei.email;</para>
	</listitem>

	<listitem>
	<para>&a.ahze.email;</para>
	</listitem>

	<listitem>
	<para>&a.markj.email;</para>
	</listitem>

	<listitem>
	<para>&a.tj.email;</para>
	</listitem>

	<listitem>
	<para>&a.kan.email;</para>
	</listitem>

	<listitem>
	<para>&a.bjk.email;</para>
	</listitem>

	<listitem>
	<para>&a.phk.email;</para>
	</listitem>

	<listitem>
	<para>&a.pluknet.email;</para>
	</listitem>

	<listitem>
	<para>&a.cokane.email;</para>
	</listitem>

	<listitem>
	<para>&a.kargl.email;</para>
	</listitem>

	<listitem>
	<para>&a.kato.email;</para>
	</listitem>

	<listitem>
	<para>&a.kris.email;</para>
	</listitem>

	<listitem>
	<para>&a.keramida.email;</para>
	</listitem>

	<listitem>
	<para>&a.arved.email;</para>
	</listitem>

	<listitem>
	<para>&a.fjoe.email;</para>
	</listitem>

	<listitem>
	<para>&a.manolis.email;</para>
	</listitem>

	<listitem>
	<para>&a.kientzle.email;</para>
	</listitem>

	<listitem>
	<para>&a.jkim.email;</para>
	</listitem>

	<listitem>
	<para>&a.zack.email;</para>
	</listitem>

	<listitem>
	<para>&a.jceel.email;</para>
	</listitem>

	<listitem>
	<para>&a.koobs.email;</para>
	</listitem>

	<listitem>
	<para>&a.jkois.email;</para>
	</listitem>

	<listitem>
	<para>&a.motoyuki.email;</para>
	</listitem>

	<listitem>
	<para>&a.maxim.email;</para>
	</listitem>

	<listitem>
	<para>&a.taras.email;</para>
	</listitem>

	<listitem>
	<para>&a.jkoshy.email;</para>
	</listitem>

	<listitem>
	<para>&a.wkoszek.email;</para>
	</listitem>

	<listitem>
	<para>&a.ak.email;</para>
	</listitem>

	<listitem>
	<para>&a.skreuzer.email;</para>
	</listitem>

	<listitem>
	<para>&a.gabor.email;</para>
	</listitem>

	<listitem>
	<para>&a.anchie.email;</para>
	</listitem>

	<listitem>
	<para>&a.rik.email;</para>
	</listitem>

	<listitem>
	<para>&a.kuriyama.email;</para>
	</listitem>

	<listitem>
	<para>&a.gleb.email;</para>
	</listitem>

	<listitem>
	<para>&a.rene.email;</para>
	</listitem>

	<listitem>
	<para>&a.jlaffaye.email;</para>
	</listitem>

	<listitem>
	<para>&a.clement.email;</para>
	</listitem>

	<listitem>
	<para>&a.mlaier.email;</para>
	</listitem>

	<listitem>
	<para>&a.erwin.email;</para>
	</listitem>

	<listitem>
	<para>&a.martymac.email;</para>
	</listitem>

	<listitem>
	<para>&a.glarkin.email;</para>
	</listitem>

	<listitem>
	<para>&a.benl.email;</para>
	</listitem>

	<listitem>
	<para>&a.dru.email;</para>
	</listitem>

	<listitem>
	<para>&a.jlh.email;</para>
	</listitem>

	<listitem>
	<para>&a.leeym.email;</para>
	</listitem>

	<listitem>
	<para>&a.sam.email;</para>
	</listitem>

	<listitem>
	<para>&a.oliver.email;</para>
	</listitem>

	<listitem>
	<para>&a.grog.email;</para>
	</listitem>

	<listitem>
	<para>&a.netchild.email;</para>
	</listitem>

	<listitem>
	<para>&a.ian.email;</para>
	</listitem>

	<listitem>
	<para>&a.achim.email;</para>
	</listitem>

	<listitem>
	<para>&a.truckman.email;</para>
	</listitem>

	<listitem>
	<para>&a.glewis.email;</para>
	</listitem>

	<listitem>
	<para>&a.qingli.email;</para>
	</listitem>

	<listitem>
	<para>&a.delphij.email;</para>
	</listitem>

	<listitem>
	<para>&a.avatar.email;</para>
	</listitem>

	<listitem>
	<para>&a.pclin.email;</para>
	</listitem>

	<listitem>
	<para>&a.yzlin.email;</para>
	</listitem>

	<listitem>
	<para>&a.linimon.email;</para>
	</listitem>

	<listitem>
	<para>&a.dryice.email;</para>
	</listitem>

	<listitem>
	<para>&a.kevlo.email;</para>
	</listitem>

	<listitem>
	<para>&a.zml.email;</para>
	</listitem>

	<listitem>
	<para>&a.nox.email;</para>
	</listitem>

	<listitem>
	<para>&a.remko.email;</para>
	</listitem>

	<listitem>
	<para>&a.avl.email;</para>
	</listitem>

	<listitem>
	<para>&a.issyl0.email;</para>
	</listitem>

	<listitem>
	<para>&a.scottl.email;</para>
	</listitem>

	<listitem>
	<para>&a.imp.email;</para>
	</listitem>

	<listitem>
	<para>&a.ade.email;</para>
	</listitem>

	<listitem>
	<para>&a.eri.email;</para>
	</listitem>

	<listitem>
	<para>&a.pav.email;</para>
	</listitem>

	<listitem>
	<para>&a.rmacklem.email;</para>
	</listitem>

	<listitem>
	<para>&a.kmacy.email;</para>
	</listitem>

	<listitem>
	<para>&a.rm.email;</para>
	</listitem>

	<listitem>
	<para>&a.mtm.email;</para>
	</listitem>

	<listitem>
	<para>&a.jmallett.email;</para>
	</listitem>

	<listitem>
	<para>&a.dwmalone.email;</para>
	</listitem>

	<listitem>
	<para>&a.nobutaka.email;</para>
	</listitem>

	<listitem>
	<para>&a.amdmi3.email;</para>
	</listitem>

	<listitem>
	<para>&a.dmarion.email;</para>
	</listitem>

	<listitem>
	<para>&a.kwm.email;</para>
	</listitem>

	<listitem>
	<para>&a.emaste.email;</para>
	</listitem>

	<listitem>
	<para>&a.cherry.email;</para>
	</listitem>

	<listitem>
	<para>&a.matusita.email;</para>
	</listitem>

	<listitem>
	<para>&a.mm.email;</para>
	</listitem>

	<listitem>
	<para>&a.sem.email;</para>
	</listitem>

	<listitem>
	<para>&a.mckay.email;</para>
	</listitem>

	<listitem>
	<para>&a.mckusick.email;</para>
	</listitem>

	<listitem>
	<para>&a.jmelo.email;</para>
	</listitem>

	<listitem>
	<para>&a.ken.email;</para>
	</listitem>

	<listitem>
	<para>&a.mezz.email;</para>
	</listitem>

	<listitem>
	<para>&a.dinoex.email;</para>
	</listitem>

	<listitem>
	<para>&a.sanpei.email;</para>
	</listitem>

	<listitem>
	<para>&a.rmh.email;</para>
	</listitem>

	<listitem>
	<para>&a.stephen.email;</para>
	</listitem>

	<listitem>
	<para>&a.marcel.email;</para>
	</listitem>

	<listitem>
	<para>&a.kmoore.email;</para>
	</listitem>

	<listitem>
	<para>&a.marck.email;</para>
	</listitem>

	<listitem>
	<para>&a.mav.email;</para>
	</listitem>

	<listitem>
	<para>&a.lippe.email;</para>
	</listitem>

	<listitem>
	<para>&a.markm.email;</para>
	</listitem>

	<listitem>
	<para>&a.knu.email;</para>
	</listitem>

	<listitem>
	<para>&a.max.email;</para>
	</listitem>

	<listitem>
	<para>&a.maho.email;</para>
	</listitem>

	<listitem>
	<para>&a.trasz.email;</para>
	</listitem>

	<listitem>
	<para>&a.neel.email;</para>
	</listitem>

	<listitem>
	<para>&a.dbn.email;</para>
	</listitem>

	<listitem>
	<para>&a.bland.email;</para>
	</listitem>

	<listitem>
	<para>&a.gnn.email;</para>
	</listitem>

	<listitem>
	<para>&a.simon.email;</para>
	</listitem>

	<listitem>
	<para>&a.rnoland.email;</para>
	</listitem>

	<listitem>
	<para>&a.anders.email;</para>
	</listitem>

	<listitem>
	<para>&a.obrien.email;</para>
	</listitem>

	<listitem>
	<para>&a.ohauer.email;</para>
	</listitem>

	<listitem>
	<para>&a.olgeni.email;</para>
	</listitem>

	<listitem>
	<para>&a.andre.email;</para>
	</listitem>

	<listitem>
	<para>&a.osa.email;</para>
	</listitem>

	<listitem>
	<para>&a.philip.email;</para>
	</listitem>

	<listitem>
	<para>&a.jpaetzel.email;</para>
	</listitem>

	<listitem>
	<para>&a.pgj.email;</para>
	</listitem>

	<listitem>
	<para>&a.hmp.email;</para>
	</listitem>

	<listitem>
	<para>&a.fluffy.email;</para>
	</listitem>

	<listitem>
	<para>&a.np.email;</para>
	</listitem>

	<listitem>
	<para>&a.wpaul.email;</para>
	</listitem>

	<listitem>
	<para>&a.rpaulo.email;</para>
	</listitem>

	<listitem>
	<para>&a.dumbbell.email;</para>
	</listitem>

	<listitem>
	<para>&a.mp.email;</para>
	</listitem>

	<listitem>
	<para>&a.pawel.email;</para>
	</listitem>

	<listitem>
	<para>&a.roam.email;</para>
	</listitem>

	<listitem>
	<para>&a.cperciva.email;</para>
	</listitem>

	<listitem>
	<para>&a.alfred.email;</para>
	</listitem>

	<listitem>
	<para>&a.csjp.email;</para>
	</listitem>

	<listitem>
	<para>&a.wes.email;</para>
	</listitem>

	<listitem>
	<para>&a.gerald.email;</para>
	</listitem>

	<listitem>
	<para>&a.sperber.email;</para>
	</listitem>

	<listitem>
	<para>&a.sepotvin.email;</para>
	</listitem>

	<listitem>
	<para>&a.mpp.email;</para>
	</listitem>

	<listitem>
	<para>&a.thomas.email;</para>
	</listitem>

	<listitem>
	<para>&a.hq.email;</para>
	</listitem>

	<listitem>
	<para>&a.dfr.email;</para>
	</listitem>

	<listitem>
	<para>&a.attilio.email;</para>
	</listitem>

	<listitem>
	<para>&a.lbr.email;</para>
	</listitem>

	<listitem>
	<para>&a.darrenr.email;</para>
	</listitem>

	<listitem>
	<para>&a.crees.email;</para>
	</listitem>

	<listitem>
	<para>&a.mr.email;</para>
	</listitem>

	<listitem>
	<para>&a.bcr.email;</para>
	</listitem>

	<listitem>
	<para>&a.trhodes.email;</para>
	</listitem>

	<listitem>
	<para>&a.benno.email;</para>
	</listitem>

	<listitem>
	<para>&a.beech.email;</para>
	</listitem>

	<listitem>
	<para>&a.matteo.email;</para>
	</listitem>

	<listitem>
	<para>&a.luigi.email;</para>
	</listitem>

	<listitem>
	<para>&a.jeff.email;</para>
	</listitem>

	<listitem>
	<para>&a.roberto.email;</para>
	</listitem>

	<listitem>
	<para>&a.rodrigc.email;</para>
	</listitem>

	<listitem>
	<para>&a.guido.email;</para>
	</listitem>

	<listitem>
	<para>&a.rea.email;</para>
	</listitem>

	<listitem>
	<para>&a.ray.email;</para>
	</listitem>

	<listitem>
	<para>&a.ps.email;</para>
	</listitem>

	<listitem>
	<para>&a.wsalamon.email;</para>
	</listitem>

	<listitem>
	<para>&a.bsam.email;</para>
	</listitem>

	<listitem>
	<para>&a.hrs.email;</para>
	</listitem>

	<listitem>
	<para>&a.bschmidt.email;</para>
	</listitem>

	<listitem>
	<para>&a.sos.email;</para>
	</listitem>

	<listitem>
	<para>&a.wosch.email;</para>
	</listitem>

	<listitem>
	<para>&a.ed.email;</para>
	</listitem>

	<listitem>
	<para>&a.cy.email;</para>
	</listitem>

	<listitem>
	<para>&a.das.email;</para>
	</listitem>

	<listitem>
	<para>&a.scheidell.email;</para>
	</listitem>

	<listitem>
	<para>&a.schweikh.email;</para>
	</listitem>

	<listitem>
	<para>&a.matthew.email;</para>
	</listitem>

	<listitem>
	<para>&a.stas.email;</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para>&a.tmseck.email;</para>
	</listitem>

	<listitem>
	<para>&a.hselasky.email;</para>
	</listitem>

	<listitem>
	<para>&a.johans.email;</para>
	</listitem>

	<listitem>
	<para>&a.lev.email;</para>
	</listitem>

	<listitem>
	<para>&a.gshapiro.email;</para>
	</listitem>

	<listitem>
	<para>&a.wxs.email;</para>
	</listitem>

	<listitem>
	<para>&a.nork.email;</para>
	</listitem>

	<listitem>
	<para>&a.simokawa.email;</para>
	</listitem>

	<listitem>
	<para>&a.syrinx.email;</para>
	</listitem>

	<listitem>
	<para>&a.vanilla.email;</para>
	</listitem>

	<listitem>
	<para>&a.ashish.email;</para>
	</listitem>

	<listitem>
	<para>&a.silby.email;</para>
	</listitem>

	<listitem>
	<para>&a.bms.email;</para>
	</listitem>

	<listitem>
	<para>&a.jls.email;</para>
	</listitem>

	<listitem>
	<para>&a.demon.email;</para>
	</listitem>

	<listitem>
	<para>&a.skv.email;</para>
	</listitem>

	<listitem>
	<para>&a.flo.email;</para>
	</listitem>

	<listitem>
	<para>&a.glebius.email;</para>
	</listitem>

	<listitem>
	<para>&a.kensmith.email;</para>
	</listitem>

	<listitem>
	<para>&a.des.email;</para>
	</listitem>

	<listitem>
	<para>&a.sobomax.email;</para>
	</listitem>

	<listitem>
	<para>&a.brian.email;</para>
	</listitem>

	<listitem>
	<para>&a.sson.email;</para>
	</listitem>

	<listitem>
	<para>&a.ssouhlal.email;</para>
	</listitem>

	<listitem>
	<para>&a.uqs.email;</para>
	</listitem>

	<listitem>
	<para>&a.mohans.email;</para>
	</listitem>

	<listitem>
	<para>&a.vsevolod.email;</para>
	</listitem>

	<listitem>
	<para>&a.zi.email;</para>
	</listitem>

	<listitem>
	<para>&a.lstewart.email;</para>
	</listitem>

	<listitem>
	<para>&a.rrs.email;</para>
	</listitem>

	<listitem>
	<para>&a.rstone.email;</para>
	</listitem>

	<listitem>
	<para>&a.xride.email;</para>
	</listitem>

	<listitem>
	<para>&a.marius.email;</para>
	</listitem>

	<listitem>
	<para>&a.cs.email;</para>
	</listitem>

	<listitem>
	<para>&a.sumikawa.email;</para>
	</listitem>

	<listitem>
	<para>&a.clsung.email;</para>
	</listitem>

	<listitem>
	<para>&a.ryusuke.email;</para>
	</listitem>

	<listitem>
	<para>&a.suz.email;</para>
	</listitem>

	<listitem>
	<para>&a.nyan.email;</para>
	</listitem>

	<listitem>
	<para>&a.sahil.email;</para>
	</listitem>

	<listitem>
	<para>&a.tota.email;</para>
	</listitem>

	<listitem>
	<para>&a.tanimura.email;</para>
	</listitem>

	<listitem>
	<para>&a.romain.email;</para>
	</listitem>

	<listitem>
	<para>&a.sylvio.email;</para>
	</listitem>

	<listitem>
	<para>&a.dteske.email;</para>
	</listitem>

	<listitem>
	<para>&a.itetcu.email;</para>
	</listitem>

	<listitem>
	<para>&a.mi.email;</para>
	</listitem>

	<listitem>
	<para>&a.gordon.email;</para>
	</listitem>

	<listitem>
	<para>&a.lth.email;</para>
	</listitem>

	<listitem>
	<para>&a.jase.email;</para>
	</listitem>

	<listitem>
	<para>&a.lx.email;</para>
	</listitem>

	<listitem>
	<para>&a.fabient.email;</para>
	</listitem>

	<listitem>
	<para>&a.thierry.email;</para>
	</listitem>

	<listitem>
	<para>&a.thompsa.email;</para>
	</listitem>

	<listitem>
	<para>&a.flz.email;</para>
	</listitem>

	<listitem>
	<para>&a.yar.email;</para>
	</listitem>

	<listitem>
	<para>&a.jilles.email;</para>
	</listitem>

	<listitem>
	<para>&a.andreast.email;</para>
	</listitem>

	<listitem>
	<para>&a.ganbold.email;</para>
	</listitem>

	<listitem>
	<para>&a.tuexen.email;</para>
	</listitem>

	<listitem>
	<para>&a.andrew.email;</para>
	</listitem>

	<listitem>
	<para>&a.gonzo.email;</para>
	</listitem>

	<listitem>
	<para>&a.ume.email;</para>
	</listitem>

	<listitem>
	<para>&a.ups.email;</para>
	</listitem>

	<listitem>
	<para>&a.vanhu.email;</para>
	</listitem>

	<listitem>
	<para>&a.bryanv.email;</para>
	</listitem>

	<listitem>
	<para>&a.avilla.email;</para>
	</listitem>

	<listitem>
	<para>&a.nivit.email;</para>
	</listitem>

	<listitem>
	<para>&a.jfv.email;</para>
	</listitem>

	<listitem>
	<para>&a.ivoras.email;</para>
	</listitem>

	<listitem>
	<para>&a.ticso.email;</para>
	</listitem>

	<listitem>
	<para>&a.stefan.email;</para>
	</listitem>

	<listitem>
	<para>&a.kaiw.email;</para>
	</listitem>

	<listitem>
	<para>&a.takawata.email;</para>
	</listitem>

	<listitem>
	<para>&a.rwatson.email;</para>
	</listitem>

	<listitem>
	<para>&a.adamw.email;</para>
	</listitem>

	<listitem>
	<para>&a.naddy.email;</para>
	</listitem>

	<listitem>
	<para>&a.peter.email;</para>
	</listitem>

	<listitem>
	<para>&a.dwhite.email;</para>
	</listitem>

	<listitem>
	<para>&a.nwhitehorn.email;</para>
	</listitem>

	<listitem>
	<para>&a.miwi.email;</para>
	</listitem>

	<listitem>
	<para>&a.swills.email;</para>
	</listitem>

	<listitem>
	<para>&a.wollman.email;</para>
	</listitem>

	<listitem>
	<para>&a.keichii.email;</para>
	</listitem>

	<listitem>
	<para>&a.joerg.email;</para>
	</listitem>

	<listitem>
	<para>&a.davidxu.email;</para>
	</listitem>

	<listitem>
	<para>&a.emax.email;</para>
	</listitem>

	<listitem>
	<para>&a.yongari.email;</para>
	</listitem>

	<listitem>
	<para>&a.zec.email;</para>
	</listitem>

	<listitem>
	<para>&a.bz.email;</para>
	</listitem>

	<listitem>
	<para>&a.zeising.email;</para>
	</listitem>

	<listitem>
	<para>&a.phantom.email;</para>
	</listitem>

	<listitem>
	<para>&a.sephe.email;</para>
	</listitem>

	<listitem>
	<para>&a.zont.email;</para>
	</listitem>

	<listitem>
	<para>&a.az.email;</para>
	</listitem>
	</itemizedlist>
	Index: projects/entities/en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml (revision 41355)
	@@ -1,1080 +1,1125 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>

	<!-- $FreeBSD$ -->
	<itemizedlist>
	+
	<listitem>
	- <para>&a.wilko.email; (2000 - 2012)</para>
	+ <para>&a.randi.email; (2010 - 2012)</para>
	</listitem>

	<listitem>
	- <para>&a.dougb.email; (2000 - 2012)</para>
	+ <para>&a.zack.email; (2010 - 2012)</para>
	</listitem>

	<listitem>
	- <para>&a.murray.email; (2000 - 2012)</para>
	+ <para>&a.erik.email; (2008 - 2012)</para>
	</listitem>

	<listitem>
	- <para>&a.steve.email; (1996 - 2012)</para>
	+ <para>&a.carvay.email; (2008 - 2012)</para>
	</listitem>

	<listitem>
	- <para>&a.erik.email; (2008 - 2012)</para>
	+ <para>&a.lulf.email; (2007 - 2012)</para>
	</listitem>

	<listitem>
	+ <para>&a.mnag.email; (2005 - 2012)</para>
	+ </listitem>
	+
	+ <listitem>
	<para>&a.ceri.email; (2002 - 2012)</para>
	</listitem>

	<listitem>
	- <para>&a.mnag.email; (2005 - 2012)</para>
	+ <para>Doug Barton (2000 - 2012)</para>
	</listitem>

	<listitem>
	- <para>&a.lulf.email; (2007 - 2012)</para>
	+ <para>&a.wilko.email; (2000 - 2012)</para>
	</listitem>

	<listitem>
	- <para>&a.niels.email; (2004 - 2011)</para>
	+ <para>&a.murray.email; (2000 - 2012)</para>
	</listitem>

	<listitem>
	+ <para>&a.steve.email; (1996 - 2012)</para>
	+ </listitem>
	+
	+ <listitem>
	<para>&a.jacula.email; (2010 - 2011)</para>
	</listitem>

	<listitem>
	<para>&a.nemoliu.email; (2007 - 2011)</para>
	</listitem>

	<listitem>
	<para>&a.alexbl.email; (2006 - 2011)</para>
	</listitem>

	<listitem>
	<para>&a.alepulver.email; (2006 - 2011)</para>
	</listitem>

	<listitem>
	<para>&a.tmclaugh.email; (2005 - 2011)</para>
	</listitem>

	<listitem>
	<para>&a.anray.email; (2005 - 2011)</para>
	</listitem>

	<listitem>
	+ <para>&a.niels.email; (2004 - 2011)</para>
	+ </listitem>
	+
	+ <listitem>
	<para>&a.sergei.email; (2003 - 2011)</para>
	</listitem>

	<listitem>
	<para>&a.krion.email; (2003 - 2011)</para>
	</listitem>

	<listitem>
	+ <para>&a.mux.email; (2002 - 2011)</para>
	+ </listitem>
	+
	+ <listitem>
	<para>&a.hm.email; (1998 - 2011)</para>
	</listitem>

	<listitem>
	<para>&a.ijliao.email; (2001 - 2011)</para>
	</listitem>

	<listitem>
	<para>&a.scrappy.email; (1996 - 2011)</para>
	</listitem>

	<listitem>
	<para>&a.snb.email; (2009 - 2010)</para>
	</listitem>

	<listitem>
	+ <para>&a.cbzimmer.email; (2009 - 2010)</para>
	+ </listitem>
	+
	+ <listitem>
	<para>&a.bushman.email; (2007 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.benjsc.email; (2007 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.rink.email; (2006 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.piso.email; (2006 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.laszlof.email; (2006 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.bvs.email; (2005 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.barner.email; (2005 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.vs.email; (2004 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.dds.email; (2003 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.perky.email; (2002 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.yoichi.email; (2001 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.okazaki.email; (2000 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.cjh.email; (2000 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.jesusr.email; (1998 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.sat.email; (2006 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.jcamou.email; (2005 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.rushani.email; (2003 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.nik.email; (1998 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.lofi.email; (2003 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.den.email; (2003 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.obraun.email; (2002 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.anholt.email; (2002 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.mwlucas.email; (2001 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.chern.email; (2001 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.mita.email; (2000 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.horikawa.email; (2000 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.clive.email; (2000 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.bmah.email; (2000 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.gioria.email; (1999 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.tg.email; (1995 - 2009)</para>
	</listitem>

	<listitem>
	+ <para>&a.kishore.email; (2007 - 2008)</para>
	+ </listitem>
	+
	+ <listitem>
	<para>&a.twinterg.email; (2006 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.koitsu.email; (2006 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.bakul.email; (2006 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.jylefort.email; (2005 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.garys.email; (2005 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.damien.email; (2005 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.aaron.email; (2005 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.tackerman.email; (2004 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.metal.email; (2004 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.marks.email; (2004 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.lesi.email; (2004 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.josef.email; (2004 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.dhartmei.email; (2004 - 2008)</para>
	</listitem>

	<listitem>
	+ <para>&a.sah.email; (2004 - 2008)</para>
	+ </listitem>
	+
	+ <listitem>
	<para>&a.rsm.email; (2003 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.hoek.email; (2003 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.eik.email; (2003 - 2008)</para>
	</listitem>

	<listitem>
	+ <para>&a.matk.email; (2003 - 2008)</para>
	+ </listitem>
	+
	+ <listitem>
	<para>&a.seanc.email; (2002 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.njl.email; (2002 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.ikob.email; (2002 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.pdeuskar.email; (2001 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.mikeh.email; (2001 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.shiba.email; (2000 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.pat.email; (2000 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.onoe.email; (2000 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.lkoeller.email; (2000 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.jayanth.email; (2000 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.jake.email; (2000 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.dmlb.email; (2000 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.bmilekic.email; (2000 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.babkin.email; (2000 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.joe.email; (1999 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.imura.email; (1999 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.andy.email; (1999 - 2008)</para>
	</listitem>

	<listitem>
	+ <para>&a.shige.email; (1999 - 2008)</para>
	+ </listitem>
	+
	+ <listitem>
	<para>&a.hosokawa.email; (1998 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.foxfair.email; (1998 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.billf.email; (1998 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.tegge.email; (1997 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.jlemon.email; (1997 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.fenner.email; (1996 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.andreas.email; (1996 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.jkh.email; (1993 - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.jdp.email; ( - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.hsu.email; ( - 2008)</para>
	</listitem>

	<listitem>
	<para>&a.farrokhi.email; (2006 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.cel.email; (2006 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.vsevolod.email; (2005 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.lawrance.email; (2005 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.rees.email; (2004 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.tjr.email; (2002 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.johan.email; (2002 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.markp.email; (2001 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.jesper.email; (2001 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.eric.email; (2001 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.trevor.email; (2000 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.non.email; (2000 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.kbyanc.email; (2000 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.jeh.email; (2000 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.gsutter.email; (2000 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.bsd.email; (2000 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.tom.email; (1999 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.mharo.email; (1999 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.chris.email; (1999 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.bp.email; (1999 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.archie.email; (1998 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.vkashyap.email; (2004 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.niklas.email; (2004 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.smkelly.email; (2003 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.arun.email; (2003 - 2006)</para>
	</listitem>

	<listitem>
	+ <para>&a.am.email; (2003 - 2006)</para>
	+ </listitem>
	+
	+ <listitem>
	<para>&a.scop.email; (2002 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.mheinen.email; (2002 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.jennifer.email; (2002 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.adamw.email; (2002 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.znerd.email; (2001 - 2006)</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para>&a.keichii.email; (2001 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.ue.email; (2001 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.tmm.email; (2001 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.robert.email; (2001 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.petef.email; (2001 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.mike.email; (2001 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.greid.email; (2001 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.cjc.email; (2001 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.bbraun.email; (2001 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.sf.email; (2000 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.kiri.email; (2000 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.dannyboy.email; (2000 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.ben.email; (2000 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.sheldonh.email; (1999 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.roger.email; (1999 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.nsayer.email; (1999 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.nbm.email; (1999 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.jedgar.email; (1999 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.nsouch.email; (1998 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.nectar.email; (1998 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.mph.email; (1998 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.kjc.email; (1997 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.hanai.email; (1997 - 2006)</para>
	</listitem>

	<listitem>
	<para>&a.viny.email; (2004 - 2005)</para>
	</listitem>

	<listitem>
	<para>&a.stephane.email; (2002 - 2005)</para>
	</listitem>

	<listitem>
	<para>&a.arr.email; (2001 - 2005)</para>
	</listitem>

	<listitem>
	<para>&a.sada.email; (1998 - 2005)</para>
	</listitem>

	<listitem>
	<para>&a.flathill.email; (1998 - 2005)</para>
	</listitem>

	<listitem>
	<para>&a.paul.email; (1993 - 2005)</para>
	</listitem>

	<listitem>
	<para>&a.mini.email; (2002 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.emoore.email; (2002 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.wjv.email; (2001 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.rpratt.email; (2001 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.orion.email; (2001 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.logo.email; (2001 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.tomsoft.email; (2000 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.patrick.email; (2000 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.chm.email; (2000 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.taoka.email; (1999 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.jmas.email; (1999 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.dcs.email; (1999 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.dan.email; (1999 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.smace.email; (1993 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.alex.email; ( - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.dwcjr.email; (2002 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.zarzycki.email; (2001 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.tshiozak.email; (2001 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.pirzyk.email; (2001 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.wsanchez.email; (2000 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.toshi.email; (2000 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.mb.email; (2000 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.marko.email; (2000 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.furuta.email; (2000 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.bean.email; (2000 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.shin.email; (1999 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.pho.email; (1999 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.newton.email; (1999 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.mtaylor.email; (1999 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.lile.email; (1999 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.jim.email; (1999 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.ejc.email; (1999 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.dick.email; (1999 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.dbaker.email; (1999 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.cpiazza.email; (1999 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.cp.email; (1999 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.thepish.email; (1998 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.semenu.email; (1998 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.rvb.email; (1998 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.rnordier.email; (1998 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.dt.email; (1998 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.dirk.email; (1998 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.dillon.email; (1998 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.stark.email; (1997 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.pds.email; (1997 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.jseger.email; (1997 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.helbig.email; (1997 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.fsmp.email; (1997 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.cwt.email; (1997 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.brandon.email; (1997 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.smpatel.email; (1996 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.msmith.email; (1996 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.mbarkah.email; (1996 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.jfitz.email; (1996 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.davidn.email; (1996 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.uhclem.email; (1995 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.lars.email; (1995 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.jfieber.email; (1995 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.dufault.email; (1995 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.amurai.email; (1995 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.ugen.email; (1994 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.swallace.email; (1994 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.stb.email; (1994 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.rich.email; (1994 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.pst.email; (1994 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.mks.email; (1994 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.ljo.email; (1994 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.csgr.email; (1994 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.adam.email; (1994 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.nate.email; (1993 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.gpalmer.email; (1993 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.rgrimes.email; (1992 - 2003)</para>
	</listitem>

	<listitem>
	<para>&a.amorita.email; (2001 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.uch.email; (2000 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.shafeeq.email; (2000 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.reg.email; (2000 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.keith.email; (2000 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.issei.email; (2000 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.cshumway.email; (2000 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.assar.email; (2000 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.nakai.email; (1999 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.asmodai.email; (1999 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.dburr.email; (1998 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.abial.email; (1998 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.jmb.email; (1997 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.danny.email; (1997 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.graichen.email; (1996 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.torstenb.email; (1995 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.jmacd.email; (1995 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.erich.email; (1995 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.martin.email; (1994 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.unfurl.email; (2000 - 2001)</para>
	</listitem>

	<listitem>
	<para>&a.rv.email; (2000 - 2001)</para>
	</listitem>

	<listitem>
	<para>&a.dec.email; (2000 - 2001)</para>
	</listitem>

	<listitem>
	<para>&a.groudier.email; (1999 - 2001)</para>
	</listitem>

	<listitem>
	<para>&a.yokota.email; (1997 - 2001)</para>
	</listitem>

	<listitem>
	<para>&a.dima.email; (1995 - 2001)</para>
	</listitem>

	<listitem>
	<para>&a.sef.email; (1993 - 2001)</para>
	</listitem>

	<listitem>
	<para>&a.asami.email; (1993 - 2001)</para>
	</listitem>

	<listitem>
	<para>&a.gehenna.email; (1999 - 2000)</para>
	</listitem>

	<listitem>
	<para>&a.tedm.email; (1997 - 2000)</para>
	</listitem>

	<listitem>
	<para>&a.nsj.email; (1996 - 2000)</para>
	</listitem>

	<listitem>
	<para>&a.jraynard.email; (1996 - 2000)</para>
	</listitem>

	<listitem>
	<para>&a.chuckr.email; (1996 - 2000)</para>
	</listitem>

	<listitem>
	<para>&a.karl.email; (1995 - 2000)</para>
	</listitem>

	<listitem>
	<para>&a.gclarkii.email; (1993 - 2000)</para>
	</listitem>

	<listitem>
	<para>&a.jgreco.email; (1997 - 1999)</para>
	</listitem>

	<listitem>
	<para>&a.jamil.email; (1997 - 1999)</para>
	</listitem>

	<listitem>
	<para>&a.ats.email; (1992 - 1999)</para>
	</listitem>

	<listitem>
	<para>&a.meganm.email; (1997 - 1998)</para>
	</listitem>

	<listitem>
	<para>&a.ahd.email; (1997 - 1998)</para>
	</listitem>

	<listitem>
	<para>&a.ahasty.email; (1997 - 1998)</para>
	</listitem>

	<listitem>
	<para>&a.dyson.email; (1993 - 1998)</para>
	</listitem>

	<listitem>
	<para>&a.olah.email; (1995 - 1996)</para>
	</listitem>

	<listitem>
	<para>&a.jhs.email; (1995 - 1995)</para>
	</listitem>

	<listitem>
	<para>gjp (1995 - 1995)</para>
	</listitem>

	<listitem>
	<para>&a.alm.email; (1993 - 1995)</para>
	</listitem>
	</itemizedlist>
	Index: projects/entities/en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml (revision 41355)
	@@ -1,56 +1,64 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!-- $FreeBSD$ -->

	<itemizedlist>
	<listitem>
	+ <para>&a.beat.email; (2011 - 2013)</para>
	+ </listitem>
	+
	+ <listitem>
	+ <para>&a.linimon.email; (2004 - 2013)</para>
	+ </listitem>
	+
	+ <listitem>
	<para>&a.pav.email; (2006 - 2012)</para>
	</listitem>

	<listitem>
	<para>&a.flz.email; (2008 - 2012)</para>
	</listitem>

	<listitem>
	<para>&a.kris.email; (2001 - 2010)</para>
	</listitem>

	<listitem>
	<para>&a.krion.email; (2004 - 2009)</para>
	</listitem>

	<listitem>
	<para>&a.clement.email; (2005 - 2007)</para>
	</listitem>

	<listitem>
	<para>&a.eik.email; (2004 - 2005)</para>
	</listitem>

	<listitem>
	<para>&a.will.email; (2001 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.knu.email; (2001 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.lioux.email; (2001 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.sobomax.email; (2001 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.steve.email; (2001 - 2004)</para>
	</listitem>

	<listitem>
	<para>&a.ade.email; (2001 - 2002)</para>
	</listitem>

	<listitem>
	<para>&a.asami.email; ( - 2001)</para>
	</listitem>
	</itemizedlist>
	Index: projects/entities/en_US.ISO8859-1/articles/freebsd-questions/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/freebsd-questions/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/freebsd-questions/article.xml (revision 41355)
	@@ -1,622 +1,606 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	]>

	<article lang='en'>
	<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>

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	&tm-attrib.microsoft;
	- &tm-attrib.netscape;
	&tm-attrib.opengroup;
	&tm-attrib.qualcomm;
	&tm-attrib.general;
	</legalnotice>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>

	<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 the <ulink url="&a.questions.url;">information page of the FreeBSD-questions mailing list</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>&microsoft; Exchange</para>
	</listitem>

	<listitem>
	- <para>&microsoft; Internet Mail</para>
	- </listitem>
	-
	- <listitem>
	<para>&microsoft; &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
	+ <para>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>
	Index: projects/entities/en_US.ISO8859-1/articles/freebsd-update-server/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/freebsd-update-server/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/freebsd-update-server/article.xml (revision 41355)
	@@ -1,833 +1,817 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	<!ENTITY fbus.ap "<application>FreeBSD Update Server</application>">
	]>

	<article lang="en">
	<articleinfo>
	<title>Build Your Own &os; Update Server</title>

	<author>
	<firstname>Jason</firstname>
	<surname>Helfman</surname>
	<affiliation>
	<address>&a.jgh.email;</address>
	</affiliation>
	</author>

	<copyright>
	<year>2009</year>
	<year>2010</year>
	<year>2011</year>
	+ <year>2013</year>
	<holder role="mailto:jgh@FreeBSD.org">Jason Helfman</holder>
	</copyright>

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	&tm-attrib.general;
	&tm-attrib.intel;
	&tm-attrib.amd;
	</legalnotice>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>
	</articleinfo>

	<abstract>
	<para>This article describes building an internal &fbus.ap;.
	The <ulink
	- url="&url.base;/cgi/cvsweb.cgi/projects/freebsd-update-server/">freebsd-update-server</ulink> software
	- is written by &a.cperciva.email;, current Security Officer of &os;.
	+ url="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">freebsd-update-server</ulink>
	+ is written by &a.cperciva.email;, Security Officer Emeritus of &os;.
	For users that think it is convenient to update their systems
	against an official update server, building their own &fbus.ap; may
	help to extend its functionality by supporting manually-tweaked
	&os; releases or by providing a local mirror that will allow faster
	updates for a number of machines.</para>
	</abstract>

	<sect1 id="acknowledgments">
	<title>Acknowledgments</title>
	<para>This article was subsequently printed at <ulink
	url="http://bsdmag.org/magazine/1021-bsd-as-a-desktop">BSD
	Magazine</ulink>.</para>
	</sect1>

	<sect1 id="introduction">
	<title>Introduction</title>

	<para>Experienced users or administrators are often responsible for
	several machines or environments. They understand the difficult
	demands and challenges of maintaining such an infrastructure.
	Running a &fbus.ap; makes it easier to deploy security and software
	patches to selected test machines before rolling them out to
	production. It also means a number of systems can be updated from the
	local network rather than a potentially slower Internet connection.
	This article outlines the steps involved in creating an internal
	&fbus.ap;.</para>
	</sect1>

	<sect1 id="prerequisites">
	<title>Prerequisites</title>

	<para>To build an internal &fbus.ap; some requirements should be
	met.</para>

	<itemizedlist>
	<listitem>
	<para>A running &os; system.</para>

	<note>
	<para>At a minimum, updates require building on a &os;
	release greater than or equal to the target release
	version for distribution.</para>
	</note>
	</listitem>

	<listitem>
	<para>A user account with at least 4 GB of available space.
	This will allow the creation of updates for 7.1 and 7.2, but the
	exact space requirements may change from version to version.</para>
	</listitem>

	<listitem>
	<para>An &man.ssh.1; account on a remote machine to upload
	distributed updates.</para>
	</listitem>

	<listitem>
	<para>A web server, like <ulink
	url="&url.books.handbook;/network-apache.html">Apache</ulink>,
	with over half of the space required for the build. For instance,
	test builds for 7.1 and 7.2 consume a total amount of 4 GB,
	and the webserver space needed to distribute these updates is
	2.6 GB.</para>
	</listitem>

	<listitem>
	<para>Basic knowledge of shell scripting with Bourne shell,
	&man.sh.1;.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="Configuration">
	<title>Configuration: Installation & Setup</title>

	<para>Download the <ulink
	- url="&url.base;/cgi/cvsweb.cgi/projects/freebsd-update-server/">freebsd-update-server</ulink>
	- software as a <ulink
	- url="&url.base;/cgi/cvsweb.cgi/projects/freebsd-update-server/freebsd-update-server.tar.gz?tarball=1">tar archive</ulink>,
	- or use &man.csup.1; and the <literal>projects-all</literal>
	- collection.</para>
	+ url="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">
	+ freebsd-update-server</ulink> software by installing <filename
	+ role="package">devel/subversion </filename>, and execute:</para>

	+ <screen>&prompt.user; <userinput>svn co http://svn.freebsd.org/base/user/cperciva/freebsd-update-build freebsd-update-server</userinput></screen>
	+
	<para>Update <filename>scripts/build.conf</filename> appropriately.
	It is sourced during all build operations.</para>

	<para>Here is the default <filename>build.conf</filename>, which should
	be modified to suit your environment.</para>

	<informalexample>
	<programlisting>

	# Main configuration file for FreeBSD Update builds. The
	# release-specific configuration data is lower down in
	# the scripts tree.

	# Location from which to fetch releases
	export FTP=ftp://ftp2.freebsd.org/pub/FreeBSD/releases<co id="ftp-id"/>

	# Host platform
	export HOSTPLATFORM=`uname -m`

	# Host name to use inside jails
	export BUILDHOSTNAME=${HOSTPLATFORM}-builder.daemonology.net<co id="buildhost-id"/>

	# Location of SSH key
	export SSHKEY=/root/.ssh/id_dsa<co id="sshkey-id"/>

	# SSH account into which files are uploaded
	MASTERACCT=builder@wadham.daemonology.net<co id="mstacct-id"/>

	# Directory into which files are uploaded
	MASTERDIR=update-master.freebsd.org<co id="mstdir-id"/></programlisting>
	</informalexample>

	<para>Parameters for consideration would be:</para>

	<calloutlist>
	<callout arearefs="ftp-id">
	<para>This is the location where ISO images are downloaded from (by
	the <function>fetchiso()</function> subroutine
	of <filename>scripts/build.subr</filename>). The location
	configured is not limited to FTP URIs. Any URI scheme
	supported by standard &man.fetch.1; utility should work
	fine.</para>

	<para>Customizations to the <function>fetchiso()</function> code can
	be installed by copying the
	default <filename>build.subr</filename> script to the release and
	architecture-specific area
	at <filename>scripts/RELEASE/ARCHITECTURE/build.subr</filename>
	and applying local changes.</para>
	</callout>

	<callout arearefs="buildhost-id">
	<para>The name of the build host. This information will be
	displayed on updated systems when issuing:</para>

	<screen>&prompt.user; <userinput>uname -v</userinput></screen>
	</callout>

	<callout arearefs="sshkey-id">
	<para>The <application>SSH</application> key for uploading files to
	the update server. A key pair can be created by
	typing <command>ssh-keygen -t dsa</command>. This parameter is
	optional; standard password authentication will be used as a
	fallback authentication method when <literal>SSHKEY</literal> is
	not defined.</para>

	<para>The &man.ssh-keygen.1; manual page has more detailed
	information about <application>SSH</application> and the
	appropriate steps for creating and using one.</para>
	</callout>

	<callout arearefs="mstacct-id">
	<para>Account for uploading files to the update
	server.</para>
	</callout>

	<callout arearefs="mstdir-id">
	<para>Directory on the update server where files are uploaded
	to.</para>
	</callout>
	</calloutlist>

	<para>The default <filename>build.conf</filename> file shipped with
	the <application>freebsd-update-server</application> sources is
	suitable for building &arch.i386; releases of &os;. As an example of
	building an update server for other architectures, the following steps
	outline the configuration changes needed for &arch.amd64;:</para>

	<procedure>
	<step>
	<para>Create a build environment for &arch.amd64;:</para>

	<informalexample>
	<screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/scripts/7.2-RELEASE/amd64</userinput></screen>
	</informalexample>
	</step>

	<step>
	<para>Install a <filename>build.conf</filename> file in the
	newly created build directory. The build configuration
	options for &os; 7.2-RELEASE on &arch.amd64; should be similar
	to:</para>

	<informalexample>
	<programlisting># SHA256 hash of RELEASE disc1.iso image.
	export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5<co id="sha256-id"/>

	# Components of the world, source, and kernels
	export WORLDPARTS="base catpages dict doc games info manpages proflibs lib32"
	export SOURCEPARTS="base bin contrib crypto etc games gnu include krb5 \
	lib libexec release rescue sbin secure share sys tools \
	ubin usbin cddl"
	export KERNELPARTS="generic"

	# EOL date
	export EOL=1275289200<co id="eol-id"/></programlisting>
	</informalexample>

	<calloutlist>
	<callout arearefs="sha256-id">
	<para>The &man.sha256.1; hash key for the desired release, is
	published within the respective <ulink
	url="&url.base;/releases/">release announcement</ulink>.</para>
	</callout>

	<callout arearefs="eol-id">
	<para>To generate the "End of Life" number for
	<filename>build.conf</filename>, refer to the "Estimated
	EOL" posted on the <ulink
	url="&url.base;/security/security.html">&os;
	Security Website</ulink>. The value
	of <literal>EOL</literal> can be derived from the date listed on
	the web site, using the &man.date.1; utility, for example:</para>
	<screen>&prompt.user; <userinput>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' '+%s'</userinput></screen>
	</callout>
	</calloutlist>
	</step>
	</procedure>
	</sect1>

	<sect1 id="build">
	<title>Building Update Code</title>

	<para>The first step is to run <filename>scripts/make.sh</filename>.
	This will build some binaries, create directories, and generate an RSA
	signing key used for approving builds. In this step, a passphrase will
	have to be supplied for the final creation of the signing key.</para>

	<screen>&prompt.root; <userinput>sh scripts/make.sh</userinput>
	cc -O2 -fno-strict-aliasing -pipe findstamps.c -o findstamps
	findstamps.c: In function 'usage':
	findstamps.c:45: warning: incompatible implicit declaration of built-in function 'exit'
	cc -O2 -fno-strict-aliasing -pipe unstamp.c -o unstamp
	install findstamps ../bin
	install unstamp ../bin
	rm -f findstamps unstamp
	Generating RSA private key, 4096 bit long modulus
	................................................................................++
	...................++
	e is 65537 (0x10001)

	Public key fingerprint:
	27ef53e48dc869eea6c3136091cc6ab8589f967559824779e855d58a2294de9e

	Encrypting signing key for root
	enter aes-256-cbc encryption password:
	Verifying - enter aes-256-cbc encryption password:</screen>

	<note>
	<para>Keep a note of the generated key fingerprint. This value
	is required in <filename>/etc/freebsd-update.conf</filename> for
	binary updates.</para>
	</note>

	<para>At this point, we are ready to stage a build.</para>

	<informalexample>
	<screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
	&prompt.root; <userinput>sh scripts/init.sh <replaceable>amd64 7.2-RELEASE</replaceable></userinput></screen>
	</informalexample>

	<para>What follows is a sample of an <emphasis>initial</emphasis> build
	run.</para>

	<screen>&prompt.root; <userinput>sh scripts/init.sh amd64 7.2-RELEASE</userinput>
	Mon Aug 24 16:04:36 PDT 2009 Starting fetch for FreeBSD/amd64 7.2-RELEASE
	/usr/local/freebsd-update-server/work/7.2-RELE100% of 588 MB 359 kBps 00m00s
	Mon Aug 24 16:32:38 PDT 2009 Verifying disc1 hash for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 16:32:44 PDT 2009 Extracting components for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 16:34:05 PDT 2009 Constructing world+src image for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 16:35:57 PDT 2009 Extracting world+src for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 23:36:24 UTC 2009 Building world for FreeBSD/amd64 7.2-RELEASE
	Tue Aug 25 00:31:29 UTC 2009 Distributing world for FreeBSD/amd64 7.2-RELEASE
	Tue Aug 25 00:32:36 UTC 2009 Building and distributing kernels for FreeBSD/amd64 7.2-RELEASE
	Tue Aug 25 00:44:44 UTC 2009 Constructing world components for FreeBSD/amd64 7.2-RELEASE
	Tue Aug 25 00:44:56 UTC 2009 Distributing source for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 17:46:18 PDT 2009 Moving components into staging area for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 17:46:33 PDT 2009 Identifying extra documentation for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 17:47:13 PDT 2009 Extracting extra docs for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 17:47:18 PDT 2009 Indexing release for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 17:50:44 PDT 2009 Indexing world0 for FreeBSD/amd64 7.2-RELEASE

	Files built but not released:
	Files released but not built:
	Files which differ by more than contents:
	Files which differ between release and build:
	kernel\|generic\|/GENERIC/hptrr.ko
	kernel\|generic\|/GENERIC/kernel
	src\|sys\|/sys/conf/newvers.sh
	world\|base\|/boot/loader
	world\|base\|/boot/pxeboot
	world\|base\|/etc/mail/freebsd.cf
	world\|base\|/etc/mail/freebsd.submit.cf
	world\|base\|/etc/mail/sendmail.cf
	world\|base\|/etc/mail/submit.cf
	world\|base\|/lib/libcrypto.so.5
	world\|base\|/usr/bin/ntpq
	world\|base\|/usr/lib/libalias.a
	world\|base\|/usr/lib/libalias_cuseeme.a
	world\|base\|/usr/lib/libalias_dummy.a
	world\|base\|/usr/lib/libalias_ftp.a
	...</screen>

	<para>Then the build of the world is performed again, with world
	patches. A more detailed explanation may be found
	in <filename>scripts/build.subr</filename>.</para>

	<warning>
	<para>During this second build cycle, the network time protocol
	- daemon, &man.ntpd.8;, is turned off. Per &a.cperciva.email;, current
	- Security Officer of &os;, "the <ulink
	- url="&url.base;/cgi/cvsweb.cgi/projects/freebsd-update-server/">freebsd-update-server</ulink>
	+ daemon, &man.ntpd.8;, is turned off. Per &a.cperciva.email;,
	+ Security Officer Emeritus of &os;, "the <ulink
	+ url="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">freebsd-update-server</ulink>
	build code needs to identify timestamps which are stored in files so
	that they can be ignored when comparing builds to determine which
	files need to be updated. This timestamp-finding works by doing two
	builds 400 days apart and comparing the results."</para>
	</warning>

	<screen>Mon Aug 24 17:54:07 PDT 2009 Extracting world+src for FreeBSD/amd64 7.2-RELEASE
	Wed Sep 29 00:54:34 UTC 2010 Building world for FreeBSD/amd64 7.2-RELEASE
	Wed Sep 29 01:49:42 UTC 2010 Distributing world for FreeBSD/amd64 7.2-RELEASE
	Wed Sep 29 01:50:50 UTC 2010 Building and distributing kernels for FreeBSD/amd64 7.2-RELEASE
	Wed Sep 29 02:02:56 UTC 2010 Constructing world components for FreeBSD/amd64 7.2-RELEASE
	Wed Sep 29 02:03:08 UTC 2010 Distributing source for FreeBSD/amd64 7.2-RELEASE
	Tue Sep 28 19:04:31 PDT 2010 Moving components into staging area for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 19:04:46 PDT 2009 Extracting extra docs for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 19:04:51 PDT 2009 Indexing world1 for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 19:08:04 PDT 2009 Locating build stamps for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 19:10:19 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 19:10:19 PDT 2009 Preparing to copy files into staging area for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 19:10:20 PDT 2009 Copying data files into staging area for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 12:16:57 PDT 2009 Copying metadata files into staging area for FreeBSD/amd64 7.2-RELEASE
	Mon Aug 24 12:16:59 PDT 2009 Constructing metadata index and tag for FreeBSD/amd64 7.2-RELEASE

	Files found which include build stamps:
	kernel\|generic\|/GENERIC/hptrr.ko
	kernel\|generic\|/GENERIC/kernel
	world\|base\|/boot/loader
	world\|base\|/boot/pxeboot
	world\|base\|/etc/mail/freebsd.cf
	world\|base\|/etc/mail/freebsd.submit.cf
	world\|base\|/etc/mail/sendmail.cf
	world\|base\|/etc/mail/submit.cf
	world\|base\|/lib/libcrypto.so.5
	world\|base\|/usr/bin/ntpq
	world\|base\|/usr/include/osreldate.h
	world\|base\|/usr/lib/libalias.a
	world\|base\|/usr/lib/libalias_cuseeme.a
	world\|base\|/usr/lib/libalias_dummy.a
	world\|base\|/usr/lib/libalias_ftp.a
	...</screen>

	<para>Finally, the build completes.</para>

	<screen>Values of build stamps, excluding library archive headers:
	v1.2 (Aug 25 2009 00:40:36)
	v1.2 (Aug 25 2009 00:38:22)
	@(#)FreeBSD 7.2-RELEASE #0: Tue Aug 25 00:38:29 UTC 2009
	FreeBSD 7.2-RELEASE #0: Tue Aug 25 00:38:29 UTC 2009
	root@server.myhost.com:/usr/obj/usr/src/sys/GENERIC
	7.2-RELEASE
	Mon Aug 24 23:55:25 UTC 2009
	Mon Aug 24 23:55:25 UTC 2009
	##### built by root@server.myhost.com on Tue Aug 25 00:16:15 UTC 2009
	##### built by root@server.myhost.com on Tue Aug 25 00:16:15 UTC 2009
	##### built by root@server.myhost.com on Tue Aug 25 00:16:15 UTC 2009
	##### built by root@server.myhost.com on Tue Aug 25 00:16:15 UTC 2009
	Mon Aug 24 23:46:47 UTC 2009
	ntpq 4.2.4p5-a Mon Aug 24 23:55:53 UTC 2009 (1)
	* Copyright (c) 1992-2009 The FreeBSD Project.
	Mon Aug 24 23:46:47 UTC 2009
	Mon Aug 24 23:55:40 UTC 2009
	Aug 25 2009
	ntpd 4.2.4p5-a Mon Aug 24 23:55:52 UTC 2009 (1)
	ntpdate 4.2.4p5-a Mon Aug 24 23:55:53 UTC 2009 (1)
	ntpdc 4.2.4p5-a Mon Aug 24 23:55:53 UTC 2009 (1)
	Tue Aug 25 00:21:21 UTC 2009
	Tue Aug 25 00:21:21 UTC 2009
	Tue Aug 25 00:21:21 UTC 2009
	Mon Aug 24 23:46:47 UTC 2009

	FreeBSD/amd64 7.2-RELEASE initialization build complete. Please
	review the list of build stamps printed above to confirm that
	they look sensible, then run
	# sh -e approve.sh amd64 7.2-RELEASE
	to sign the release.</screen>

	<para>Approve the build if everything is correct. More information on
	determining this can be found in the distributed source
	file named <filename>USAGE</filename>. Execute
	<filename>scripts/approve.sh</filename>, as directed. This will sign
	the release, and move components into a staging area suitable for
	uploading.</para>

	<informalexample>
	<screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
	&prompt.root; <userinput>sh scripts/mountkey.sh</userinput></screen>
	</informalexample>

	<screen>&prompt.root; <userinput>sh -e scripts/approve.sh amd64 7.2-RELEASE</userinput>
	Wed Aug 26 12:50:06 PDT 2009 Signing build for FreeBSD/amd64 7.2-RELEASE
	Wed Aug 26 12:50:06 PDT 2009 Copying files to patch source directories for FreeBSD/amd64 7.2-RELEASE
	Wed Aug 26 12:50:06 PDT 2009 Copying files to upload staging area for FreeBSD/amd64 7.2-RELEASE
	Wed Aug 26 12:50:07 PDT 2009 Updating databases for FreeBSD/amd64 7.2-RELEASE
	Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE</screen>

	<para>After the approval process is complete, the upload procedure may
	be started.</para>

	<informalexample>
	<screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
	&prompt.root; <userinput>sh scripts/upload.sh <replaceable>amd64 7.2-RELEASE</replaceable></userinput></screen>
	</informalexample>

	<note>
	<para>In the event update code needs to be re-uploaded, this may be
	done by changing to the public distributions directory for the
	target release and updating attributes of the
	<emphasis>uploaded</emphasis> file.</para>

	<informalexample>
	<screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server/pub/<replaceable>7.2-RELEASE/amd64</replaceable></userinput>
	&prompt.root; <userinput>touch -t <replaceable>200801010101.01</replaceable> uploaded</userinput></screen>
	</informalexample>
	</note>

	<!-- If freebsd-update works with other http servers too, we should
	avoid making the instructions Apache-specific here. -->

	<!-- there are specific web instructions in the uploaded code that pertain to Apache. I believe it is worded fine here, now, and if others choose to use another web server, that is their choice to figure out -->
	<para>The uploaded files will need to be in the
	document root of the webserver in order for updates
	to be distributed. The exact configuration will vary depending on the
	web server used. For the <application>Apache</application> web server,
	please refer to the <ulink
	url="&url.books.handbook;/network-apache.html">Configuration of
	Apache servers</ulink> section in the Handbook.</para>

	<!-- This note seems either out of place. I find it hard to read and it
	is a bit difficult to understand why it is related to the rest of
	this section. It looks like something that would fit nicely in an
	introductory section about the way a freebsd-update server works. -->
	<!-- Agreed, it does not suite very well here. But it is now included
	above. I think it can be removed now. gabor -->
	<!-- Taken out until we decide what to do with it -->

	<!-- Agreed. However, I believe the placement of this works fine as it is.
	<note>
	<para>Updates for the current release of the &os; system you are
	updating, and what you want to upgrade <emphasis>to</emphasis> need
	to be built in order for &os; Update Server to work properly. This
	is necessary for merging of files between releases. For example, if
	you are updating a system from &os; 7.1 to &os; 7.2, you will need
	to have update code built for &os; 7.1-RELEASE and
	&os; 7.2-RELEASE.</para>
	</note> -->

	<!-- What is a 'KeyPrint'? -->
	<para>Update client's <literal>KeyPrint</literal> and
	<literal>ServerName</literal> in
	<filename>/etc/freebsd-update.conf</filename>, and perform updates as
	instructed in the <ulink
	url="&url.books.handbook;/updating-freebsdupdate.html">&os;
	Update</ulink>
	<!-- One sentence, two instances of 'in'. We can probably reword this
	part to avoid repetition. -->
	<!-- What about "place client's new keyprint and servername values to
	freebsd-update.conf, ..."? gabor -->
	section of the Handbook.</para>

	<!-- Sorry folks, but I disagree here. I believe it is worded fine. If anything, drop everything after "perform" and change "updates" to "FreeBSD Updates" and link that to the handbook -->

	<important>
	<para>In order for &fbus.ap; to work properly, updates
	for both the <emphasis>current</emphasis> release and the
	release <emphasis>one wants to upgrade to</emphasis> need to be
	built. This is necessary for determining the differences of
	files between releases. For example, when upgrading a &os;
	system from 7.1-RELEASE to 7.2-RELEASE, updates will need to be built
	and uploaded to your distribution server for both versions.</para>
	</important>

	<para>For reference, the entire run of <ulink
	url="init.txt"><filename>init.sh</filename></ulink> is
	attached.</para>
	</sect1>

	<sect1 id="patch">
	<title>Building a Patch</title>

	<para>Every time a <ulink
	url="&url.base;/security/advisories.html">security advisory</ulink>
	or <ulink url="&url.base;/security/notices.html">security notice</ulink>
	is announced, a patch update can be built.</para>

	<para>For this example, 7.1-RELEASE will be used.</para>

	<para>A couple of assumptions are made for a different release
	build:</para>

	<itemizedlist>
	<listitem>
	<para>Setup the correct directory structure for the initial
	build.</para>
	</listitem>

	<listitem>
	<para>Perform an initial build for 7.1-RELEASE.</para>
	</listitem>
	</itemizedlist>

	<para>Create the patch directory of the respective release
	under <filename
	class="directory">/usr/local/freebsd-update-server/patches/</filename>.</para>

	<informalexample>
	<screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/patches/7.1-RELEASE/</userinput>
	&prompt.user; <userinput>cd /usr/local/freebsd-update-server/patches/7.1-RELEASE</userinput></screen>
	</informalexample>

	<para>As an example, take the patch for &man.named.8;. Read the advisory,
	and grab the necessary file from <ulink
	url="&url.base;/security/advisories.html">&os; Security
	Advisories</ulink>. More information on interpreting the advisory,
	can be found in the <ulink
	url="&url.books.handbook;/security-advisories.html">&os; Handbook</ulink>.</para>

	<para>In the <ulink
	url="http://security.freebsd.org/advisories/FreeBSD-SA-09:12.bind.asc">security brief</ulink>,
	this advisory is called <literal>SA-09:12.bind</literal>. After
	downloading the file, it is required to rename the file to an
	appropriate patch level. It is suggested to keep this consistent with
	official &os; patch levels, but its name may be freely chosen.
	For this build, let us follow the currently established practice of
	&os; and call this <literal>p7</literal>. Rename the file:</para>

	<informalexample>
	<screen>&prompt.user; <userinput>cd /usr/local/freebsd-update-server/patches/7.1-RELEASE/; mv bind.patch 7-SA-09:12.bind </userinput></screen>
	</informalexample>

	<note>
	<para>When running a patch level build, it is assumed that previous
	patches are in place. When a patch build is run, it will run all
	patches contained in the patch directory.</para>

	<para>There can be custom patches added to any build. Use the number
	zero, or any other number.</para>
	</note>

	<warning>
	<para>It is up to the administrator of the &fbus.ap; to take
	appropriate measures to verify the authenticity of every
	patch.</para>
	</warning>

	<para>At this point, a <emphasis>diff</emphasis> is ready to be built.
	The software checks first to see if a
	<filename>scripts/init.sh</filename> has been run on the respective
	release prior to running the diff build.</para>

	<informalexample>
	<screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
	&prompt.root; <userinput>sh scripts/diff.sh <replaceable>amd64 7.1-RELEASE 7</replaceable></userinput></screen>
	</informalexample>

	<para>What follows is a sample of a <emphasis>differential</emphasis>
	build run.</para>

	<screen>&prompt.root; <userinput>sh -e scripts/diff.sh amd64 7.1-RELEASE 7</userinput>
	Wed Aug 26 10:09:59 PDT 2009 Extracting world+src for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 17:10:25 UTC 2009 Building world for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 18:05:11 UTC 2009 Distributing world for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 18:06:16 UTC 2009 Building and distributing kernels for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 18:17:50 UTC 2009 Constructing world components for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 18:18:02 UTC 2009 Distributing source for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 11:19:23 PDT 2009 Moving components into staging area for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 11:19:37 PDT 2009 Extracting extra docs for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 11:19:42 PDT 2009 Indexing world0 for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 11:23:02 PDT 2009 Extracting world+src for FreeBSD/amd64 7.1-RELEASE-p7
	Thu Sep 30 18:23:29 UTC 2010 Building world for FreeBSD/amd64 7.1-RELEASE-p7
	Thu Sep 30 19:18:15 UTC 2010 Distributing world for FreeBSD/amd64 7.1-RELEASE-p7
	Thu Sep 30 19:19:18 UTC 2010 Building and distributing kernels for FreeBSD/amd64 7.1-RELEASE-p7
	Thu Sep 30 19:30:52 UTC 2010 Constructing world components for FreeBSD/amd64 7.1-RELEASE-p7
	Thu Sep 30 19:31:03 UTC 2010 Distributing source for FreeBSD/amd64 7.1-RELEASE-p7
	Thu Sep 30 12:32:25 PDT 2010 Moving components into staging area for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 12:32:39 PDT 2009 Extracting extra docs for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 12:32:43 PDT 2009 Indexing world1 for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 12:35:54 PDT 2009 Locating build stamps for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 12:36:58 PDT 2009 Reverting changes due to build stamps for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 12:37:14 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 12:37:14 PDT 2009 Preparing to copy files into staging area for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 12:37:15 PDT 2009 Copying data files into staging area for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 12:43:23 PDT 2009 Copying metadata files into staging area for FreeBSD/amd64 7.1-RELEASE-p7
	Wed Aug 26 12:43:25 PDT 2009 Constructing metadata index and tag for FreeBSD/amd64 7.1-RELEASE-p7
	...
	Files found which include build stamps:
	kernel\|generic\|/GENERIC/hptrr.ko
	kernel\|generic\|/GENERIC/kernel
	world\|base\|/boot/loader
	world\|base\|/boot/pxeboot
	world\|base\|/etc/mail/freebsd.cf
	world\|base\|/etc/mail/freebsd.submit.cf
	world\|base\|/etc/mail/sendmail.cf
	world\|base\|/etc/mail/submit.cf
	world\|base\|/lib/libcrypto.so.5
	world\|base\|/usr/bin/ntpq
	world\|base\|/usr/include/osreldate.h
	world\|base\|/usr/lib/libalias.a
	world\|base\|/usr/lib/libalias_cuseeme.a
	world\|base\|/usr/lib/libalias_dummy.a
	world\|base\|/usr/lib/libalias_ftp.a
	...
	Values of build stamps, excluding library archive headers:
	v1.2 (Aug 26 2009 18:13:46)
	v1.2 (Aug 26 2009 18:11:44)
	@(#)FreeBSD 7.1-RELEASE-p7 #0: Wed Aug 26 18:11:50 UTC 2009
	FreeBSD 7.1-RELEASE-p7 #0: Wed Aug 26 18:11:50 UTC 2009
	root@server.myhost.com:/usr/obj/usr/src/sys/GENERIC
	7.1-RELEASE-p7
	Wed Aug 26 17:29:15 UTC 2009
	Wed Aug 26 17:29:15 UTC 2009
	##### built by root@server.myhost.com on Wed Aug 26 17:49:58 UTC 2009
	##### built by root@server.myhost.com on Wed Aug 26 17:49:58 UTC 2009
	##### built by root@server.myhost.com on Wed Aug 26 17:49:58 UTC 2009
	##### built by root@server.myhost.com on Wed Aug 26 17:49:58 UTC 2009
	Wed Aug 26 17:20:39 UTC 2009
	ntpq 4.2.4p5-a Wed Aug 26 17:29:42 UTC 2009 (1)
	* Copyright (c) 1992-2009 The FreeBSD Project.
	Wed Aug 26 17:20:39 UTC 2009
	Wed Aug 26 17:29:30 UTC 2009
	Aug 26 2009
	ntpd 4.2.4p5-a Wed Aug 26 17:29:41 UTC 2009 (1)
	ntpdate 4.2.4p5-a Wed Aug 26 17:29:42 UTC 2009 (1)
	ntpdc 4.2.4p5-a Wed Aug 26 17:29:42 UTC 2009 (1)
	Wed Aug 26 17:55:02 UTC 2009
	Wed Aug 26 17:55:02 UTC 2009
	Wed Aug 26 17:55:02 UTC 2009
	Wed Aug 26 17:20:39 UTC 2009
	...</screen>

	<para>Updates are printed, and approval is requested.</para>

	<screen>New updates:
	kernel\|generic\|/GENERIC/kernel.symbols\|f\|0\|0\|0555\|0\|7c8dc176763f96ced0a57fc04e7c1b8d793f27e006dd13e0b499e1474ac47e10\|
	kernel\|generic\|/GENERIC/kernel\|f\|0\|0\|0555\|0\|33197e8cf15bbbac263d17f39c153c9d489348c2c534f7ca1120a1183dec67b1\|
	kernel\|generic\|/\|d\|0\|0\|0755\|0\|\|
	src\|base\|/\|d\|0\|0\|0755\|0\|\|
	src\|bin\|/\|d\|0\|0\|0755\|0\|\|
	src\|cddl\|/\|d\|0\|0\|0755\|0\|\|
	src\|contrib\|/contrib/bind9/bin/named/update.c\|f\|0\|10000\|0644\|0\|4d434abf0983df9bc47435670d307fa882ef4b348ed8ca90928d250f42ea0757\|
	src\|contrib\|/contrib/bind9/lib/dns/openssldsa_link.c\|f\|0\|10000\|0644\|0\|c6805c39f3da2a06dd3f163f26c314a4692d4cd9a2d929c0acc88d736324f550\|
	src\|contrib\|/contrib/bind9/lib/dns/opensslrsa_link.c\|f\|0\|10000\|0644\|0\|fa0f7417ee9da42cc8d0fd96ad24e7a34125e05b5ae075bd6e3238f1c022a712\|
	...
	FreeBSD/amd64 7.1-RELEASE update build complete. Please review
	the list of build stamps printed above and the list of updated
	files to confirm that they look sensible, then run
	# sh -e approve.sh amd64 7.1-RELEASE
	to sign the build.</screen>

	<para>Follow the same process as noted before for approving a
	build:</para>

	<screen>&prompt.root; <userinput>sh -e scripts/approve.sh amd64 7.1-RELEASE</userinput>
	Wed Aug 26 12:50:06 PDT 2009 Signing build for FreeBSD/amd64 7.1-RELEASE
	Wed Aug 26 12:50:06 PDT 2009 Copying files to patch source directories for FreeBSD/amd64 7.1-RELEASE
	Wed Aug 26 12:50:06 PDT 2009 Copying files to upload staging area for FreeBSD/amd64 7.1-RELEASE
	Wed Aug 26 12:50:07 PDT 2009 Updating databases for FreeBSD/amd64 7.1-RELEASE
	Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.1-RELEASE

	The FreeBSD/amd64 7.1-RELEASE update build has been signed and is
	ready to be uploaded. Remember to run
	# sh -e umountkey.sh
	to unmount the decrypted key once you have finished signing all
	the new builds.</screen>

	<para>After approving the build, upload the software:</para>

	<informalexample>
	<screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
	&prompt.root; <userinput>sh scripts/upload.sh <replaceable>amd64 7.1-RELEASE</replaceable></userinput></screen>
	</informalexample>

	<para>For reference, the entire run of
	<ulink url="diff.txt"><filename>diff.sh</filename></ulink> is
	attached.</para>
	</sect1>

	<sect1 id="tips">
	<title>Tips</title>

	<!-- These are nice tips, but there are only a few of them and they need a
	bit of rewording to make sense. I'd like to see something that
	explains at least the following for every tip:

	* Why is this tip necessary? What is the original problem it tries
	to solve?
	* How to install the changes of the tip, preferably in a <procedure>
	element, with clearly separated steps.
	* How to check that the changes of the tip had a measurable and
	noticeable effect.

	We can do this in a followup commit. It doesn't have to be completed
	before we commit this to CVS. -->

	<!-- thank you, i just learned these in the process, and thought I would share. They are "tips" and not necessary, so I do see your point, and I would suggest maybe even renaming the section to something more appropriate. Nothing really comes to mind now, though. -->

	<!-- this tip will allow you to maintain a custom release and custom kernel, and update it like any other binary update -->
	<itemizedlist>
	<listitem>
	<para>If a custom release is built using the native
	<command>make release</command> <ulink
	url="&url.articles.releng;/release-build.html">procedure</ulink>,
	<application>freebsd-update-server</application> code will work
	from your release. As an example, a release without ports or
	documentation can be built by clearing functionality pertaining
	to documentation subroutines <function> findextradocs ()</function>,
	<function>addextradocs ()</function> and altering the download
	location in <function>fetchiso ()</function>, respectively, in
	<filename>scripts/build.subr</filename>. As a last step, change
	the &man.sha256.1; hash in <filename>build.conf</filename> under
	your respective release and architecture and you are ready to build
	off your custom release.</para>

	<screen># Compare ${WORKDIR}/release and ${WORKDIR}/$1, identify which parts
	# of the world\|doc subcomponent are missing from the latter, and
	# build a tarball out of them.
	findextradocs () {
	}

	# Add extra docs to ${WORKDIR}/$1
	addextradocs () {
	}
	</screen>
	</listitem>
	- <!-- this tip will speed up your build process, however it is not necessary -->
	<listitem>
	<para>Adding <option>-j <replaceable>NUMBER</replaceable></option>
	flags to <maketarget>buildworld</maketarget> and
	<maketarget>obj</maketarget> targets in the
	<filename>scripts/build.subr</filename> script may speed up
	processing depending on the hardware used, however it is not
	necessary. Using these flags in other targets is not
	recommended, as it may cause the build to become unreliable.</para>

	<screen> # Build the world
	log "Building world"
	cd /usr/src &&
	make -j 2 ${COMPATFLAGS} buildworld 2>&1

	# Distribute the world
	log "Distributing world"
	cd /usr/src/release &&
	make -j 2 obj &&
	make ${COMPATFLAGS} release.1 release.2 2>&1</screen>
	</listitem>

	<listitem>
	-<!-- Parse error. I don't understand what this paragraph suggests or
	- recommends. Also, why do we need to block RSTs? I don't really
	- like gratuitous blocking of RST, ICMP or other packets. Our
	- kernel can rate-limit most of the "strange" packets alredy. -->
	-
	-<!-- there is a bug in earlier versions of the software that get the updates, and not blocking them will result in failure to update systems -->
	-
	- <para>Create a <ulink
	- url="&url.books.handbook;/firewalls.html">firewall</ulink>
	- rule to block outgoing RST packets. Due to a bug noted <ulink
	- url="http://lists.freebsd.org/pipermail/freebsd-stable/2009-April/049578.html">in a posting</ulink>
	- on the &a.stable; in April 2009, there may be
	- time-outs and failures when updating a system.</para>
	- </listitem>
	-
	- <!-- this tip is not necessary, however if you wish to retain mirrors and redundancy, this tip will help you. -->
	- <listitem>
	<para>Create an appropriate <ulink
	url="&url.books.handbook;/network-dns.html">DNS</ulink>
	SRV record for the update server, and put others behind it with
	variable weights. Using this facility will provide update
	- mirrors.</para>
	+ mirrors, however this tip is not necessary unless you wish to
	+ provide a redundant service.</para>

	<screen> _http._tcp.update.myserver.com. IN SRV 0 2 80 host1.myserver.com.
	SRV 0 1 80 host2.myserver.com.
	SRV 0 0 80 host3.myserver.com.</screen>
	</listitem>
	</itemizedlist>
	</sect1>
	</article>
	Index: projects/entities/en_US.ISO8859-1/articles/geom-class/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/geom-class/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/geom-class/article.xml (revision 41355)
	@@ -1,720 +1,719 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	]>

	<article lang='en'>
	<title>Writing a GEOM Class</title>
	<articleinfo>

	<authorgroup>
	<author>
	<firstname>Ivan</firstname>
	<surname>Voras</surname>
	<affiliation>
	<address><email>ivoras@FreeBSD.org</email>
	</address>
	</affiliation>
	</author>
	</authorgroup>

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	- &tm-attrib.cvsup;
	&tm-attrib.intel;
	&tm-attrib.general;
	</legalnotice>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>

	<abstract>

	<para>This text documents some starting points in developing
	GEOM classes, and kernel modules in general. It is assumed
	that the reader is familiar with C userland programming.</para>

	</abstract>

	</articleinfo>

	<!-- Introduction -->
	<sect1 id="intro">
	<title>Introduction</title>

	<sect2 id="intro-docs">
	<title>Documentation</title>

	<para>Documentation on kernel programming is scarce — it is one of
	few areas where there is nearly nothing in the way of friendly
	tutorials, and the phrase <quote>use the source!</quote> really
	holds true. However, there are some bits and pieces (some of
	them seriously outdated) floating around that should be studied
	before beginning to code:</para>

	<itemizedlist>

	<listitem><para>The <ulink
	url="&url.books.developers-handbook;/index.html">FreeBSD
	Developer's Handbook</ulink> — part of the documentation
	project, it does not contain anything specific to kernel
	programming, but rather some general useful information.</para></listitem>

	<listitem><para>The <ulink
	url="&url.books.arch-handbook;/index.html">FreeBSD
	Architecture Handbook</ulink> — also from the documentation
	project, contains descriptions of several low-level facilities
	and procedures. The most important chapter is 13, <ulink
	url="&url.books.arch-handbook;/driverbasics.html">Writing
	FreeBSD device drivers</ulink>.</para></listitem>

	<listitem><para>The Blueprints section of <ulink
	url="http://www.freebsddiary.org">FreeBSD Diary</ulink> web
	site — contains several interesting articles on kernel
	facilities.</para></listitem>

	<listitem><para>The man pages in section 9 — for important
	documentation on kernel functions.</para></listitem>

	<listitem><para>The &man.geom.4; man page and <ulink
	url="http://phk.freebsd.dk/pubs/">PHK's GEOM slides</ulink>
	— for general introduction of the GEOM
	subsystem.</para></listitem>

	<listitem><para>Man pages &man.g.bio.9;, &man.g.event.9;, &man.g.data.9;,
	&man.g.geom.9;, &man.g.provider.9; &man.g.consumer.9;, &man.g.access.9;
	& others linked from those, for documentation on specific
	functionalities.
	</para></listitem>

	<listitem><para>The &man.style.9; man page — for documentation on
	the coding-style conventions which must be followed for any code
	which is to be committed to the FreeBSD Subversion tree.</para></listitem>

	</itemizedlist>

	</sect2>
	</sect1>

	<sect1 id="prelim">
	<title>Preliminaries</title>

	<para>The best way to do kernel development is to have (at least)
	two separate computers. One of these would contain the
	development environment and sources, and the other would be used
	to test the newly written code by network-booting and
	network-mounting filesystems from the first one. This way if
	the new code contains bugs and crashes the machine, it will not
	mess up the sources (and other <quote>live</quote> data). The
	second system does not even require a proper display. Instead, it
	could be connected with a serial cable or KVM to the first
	one.</para>

	<para>But, since not everybody has two or more computers handy, there are
	a few things that can be done to prepare an otherwise <quote>live</quote>
	system for developing kernel code. This setup is also applicable
	for developing in a <ulink url="http://www.vmware.com/">VMWare</ulink>
	or <ulink url="http://www.qemu.org/">QEmu</ulink> virtual machine (the
	next best thing after a dedicated development machine).</para>

	<sect2 id="prelim-system">
	<title>Modifying a system for development</title>

	<para>For any kernel programming a kernel with
	<option>INVARIANTS</option> enabled is a must-have. So enter
	these in your kernel configuration file:</para>

	<programlisting>options INVARIANT_SUPPORT
	options INVARIANTS</programlisting>

	<para>For more debugging you should also include WITNESS support,
	which will alert you of mistakes in locking:</para>

	<programlisting>options WITNESS_SUPPORT
	options WITNESS</programlisting>

	<para>For debugging crash dumps, a kernel with debug symbols is
	needed:</para>

	<programlisting> makeoptions DEBUG=-g</programlisting>

	<para>With the usual way of installing the kernel (<command>make
	installkernel</command>) the debug kernel will not be
	automatically installed. It is called
	<filename>kernel.debug</filename> and located in
	<filename>/usr/obj/usr/src/sys/KERNELNAME/</filename>. For
	convenience it should be copied to
	<filename>/boot/kernel/</filename>.</para>

	<para>Another convenience is enabling the kernel debugger so you
	can examine a kernel panic when it happens. For this, enter
	the following lines in your kernel configuration file:</para>

	<programlisting>options KDB
	options DDB
	options KDB_TRACE</programlisting>

	<para>For this to work you might need to set a sysctl (if it is
	not on by default):</para>

	<programlisting> debug.debugger_on_panic=1</programlisting>

	<para>Kernel panics will happen, so care should be taken with
	the filesystem cache. In particular, having softupdates might
	mean the latest file version could be lost if a panic occurs
	before it is committed to storage. Disabling softupdates
	yields a great performance hit, and still does not guarantee
	data consistency. Mounting filesystem with the <quote>sync</quote> option
	is needed for that. For a compromise, the softupdates cache delays can
	be shortened. There are three sysctl's that are useful for
	this (best to be set in
	<filename>/etc/sysctl.conf</filename>):</para>

	<programlisting>kern.filedelay=5
	kern.dirdelay=4
	kern.metadelay=3</programlisting>

	<para>The numbers represent seconds.</para>

	<para>For debugging kernel panics, kernel core dumps are
	required. Since a kernel panic might make filesystems
	unusable, this crash dump is first written to a raw
	partition. Usually, this is the swap partition. This partition must be at
	least as large as the physical RAM in the machine. On the
	next boot, the dump is copied to a regular file.
	This happens after filesystems are checked and mounted, and
	before swap is enabled. This is controlled with two
	<filename>/etc/rc.conf</filename> variables:</para>

	<programlisting>dumpdev="/dev/ad0s4b"
	dumpdir="/usr/core </programlisting>

	<para>The <varname>dumpdev</varname> variable specifies the swap
	partition and <varname>dumpdir</varname> tells the system
	where in the filesystem to relocate the core dump on reboot.</para>

	<para>Writing kernel core dumps is slow and takes a long time so
	if you have lots of memory (>256M) and lots of panics it could
	be frustrating to sit and wait while it is done (twice — first
	to write it to swap, then to relocate it to filesystem). It is
	convenient then to limit the amount of RAM the system will use
	via a <filename>/boot/loader.conf</filename> tunable:</para>

	<programlisting> hw.physmem="256M"</programlisting>

	<para>If the panics are frequent and filesystems large (or you
	simply do not trust softupdates+background fsck) it is advisable
	to turn background fsck off via
	<filename>/etc/rc.conf</filename> variable:</para>

	<programlisting> background_fsck="NO"</programlisting>

	<para>This way, the filesystems will always get checked when
	needed. Note that with background fsck, a new panic could happen while
	it is checking the disks. Again, the safest way is not to have
	many local filesystems by using another computer as an NFS
	server.</para>
	</sect2>

	<sect2 id="prelim-starting">
	<title>Starting the project</title>

	<para>For the purpose of creating a new GEOM class, an empty
	subdirectory has to be created under an arbitrary user-accessible
	directory. You do not have to create the module directory under
	<filename>/usr/src</filename>.</para>
	</sect2>

	<sect2 id="prelim-makefile">
	<title>The Makefile</title>

	<para>It is good practice to create
	<filename>Makefile</filename>s for every nontrivial coding
	project, which of course includes kernel modules.</para>

	<para>Creating the <filename>Makefile</filename> is simple
	thanks to an extensive set of helper routines provided by the
	system. In short, here is how a minimal <filename>Makefile</filename>
	looks for a kernel module:</para>

	<programlisting>SRCS=g_journal.c
	KMOD=geom_journal

	.include <bsd.kmod.mk></programlisting>

	<para>This <filename>Makefile</filename> (with changed filenames)
	will do for any kernel module, and a GEOM class can reside in just
	one kernel module. If more than one file is required, list it in the
	<envar>SRCS</envar> variable, separated with whitespace from
	other filenames.</para>
	</sect2>
	</sect1>

	<sect1 id="kernelprog">
	<title>On FreeBSD kernel programming</title>

	<sect2 id="kernelprog-memalloc">
	<title>Memory allocation</title>

	<para>See &man.malloc.9;. Basic memory allocation is only
	slightly different than its userland equivalent. Most
	notably, <function>malloc</function>() and
	<function>free</function>() accept additional parameters as is
	described in the man page.</para>

	<para>A <quote>malloc type</quote> must be declared in the
	declaration section of a source file, like this:</para>

	<programlisting> static MALLOC_DEFINE(M_GJOURNAL, "gjournal data", "GEOM_JOURNAL Data");</programlisting>

	<para>To use this macro, <filename>sys/param.h</filename>,
	<filename>sys/kernel.h</filename> and
	<filename>sys/malloc.h</filename> headers must be
	included.</para>

	<para>There is another mechanism for allocating memory, the UMA
	(Universal Memory Allocator). See &man.uma.9; for details, but
	it is a special type of allocator mainly used for speedy
	allocation of lists comprised of same-sized items (for
	example, dynamic arrays of structs).</para>
	</sect2>

	<sect2 id="kernelprog-lists">
	<title>Lists and queues</title>

	<para>See &man.queue.3;. There are a LOT of cases when a list of
	things needs to be maintained. Fortunately, this data
	structure is implemented (in several ways) by C macros
	included in the system. The most used list type is TAILQ
	because it is the most flexible. It is also the one with largest
	memory requirements (its elements are doubly-linked) and
	also the slowest (although the speed variation is on
	the order of several CPU instructions more, so it should not be
	taken seriously).</para>

	<para>If data retrieval speed is very important, see
	&man.tree.3; and &man.hashinit.9;.</para>
	</sect2>

	<sect2 id="kernelprog-bios">
	<title>BIOs</title>

	<para>Structure <structname>bio</structname> is used for any and
	all Input/Output operations concerning GEOM. It basically
	contains information about what device ('provider') should
	satisfy the request, request type, offset, length, pointer to
	a buffer, and a bunch of <quote>user-specific</quote> flags
	and fields that can help implement various hacks.</para>

	<para>The important thing here is that <structname>bio</structname>s
	are handled asynchronously. That means that, in most parts of the code,
	there is no analogue to userland's &man.read.2; and
	&man.write.2; calls that do not return until a request is
	done. Rather, a developer-supplied function is called as a
	notification when the request gets completed (or results in
	error).</para>

	<para>The asynchronous programming model (also
	called <quote>event-driven</quote>) is somewhat harder
	than the much more used imperative one used in userland
	(at least it takes a
	while to get used to it). In some cases the helper routines
	<function>g_write_data</function>() and
	<function>g_read_data</function>() can be used, but <emphasis>not
	always</emphasis>. In particular, they cannot be used when
	a mutex is held; for example, the GEOM topology mutex or
	the internal mutex held during the <function>.start</function>() and
	<function>.stop</function>() functions.</para>

	</sect2>
	</sect1>

	<sect1 id="geom">
	<title>On GEOM programming</title>

	<sect2 id="geom-ggate">
	<title>Ggate</title>

	<para>If maximum performance is not needed, a much simpler way
	of making a data transformation is to implement it in userland
	via the ggate (GEOM gate) facility. Unfortunately, there is no
	easy way to convert between, or even share code between the
	two approaches.</para>
	</sect2>

	<sect2 id="geom-class">
	<title>GEOM class</title>

	<para>GEOM classes are transformations on the data. These transformations
	can be combined in a tree-like fashion. Instances of GEOM classes are
	called <emphasis>geoms</emphasis>.</para>

	<para>Each GEOM class has several <quote>class methods</quote> that get called
	when there is no geom instance available (or they are simply not
	bound to a single instance):</para>

	<itemizedlist>

	<listitem><para><function>.init</function> is called when GEOM
	becomes aware of a GEOM class (e.g. when the kernel module
	gets loaded.)</para></listitem>

	<listitem><para><function>.fini</function> gets called when GEOM
	abandons the class (e.g. when the module gets
	unloaded)</para></listitem>

	<listitem><para><function>.taste</function> is called next, once for
	each provider the system has available. If applicable, this
	function will usually create and start a geom
	instance.</para></listitem>

	<listitem><para><function>.destroy_geom</function> is called when
	the geom should be disbanded</para></listitem>

	<listitem><para><function>.ctlconf</function> is called when user
	requests reconfiguration of existing geom</para></listitem>

	</itemizedlist>

	<para>Also defined are the GEOM event functions, which will get
	copied to the geom instance.</para>

	<para>Field <function>.geom</function> in the
	<structname>g_class</structname> structure is a LIST of geoms
	instantiated from the class.</para>

	<para>These functions are called from the g_event kernel thread.</para>

	</sect2>

	<sect2 id="geom-softc">
	<title>Softc</title>

	<para>The name <quote>softc</quote> is a legacy term for
	<quote>driver private data</quote>. The name most probably
	comes from the archaic term <quote>software control block</quote>.
	In GEOM, it is a structure (more precise: pointer to a
	structure) that can be attached to a geom instance to hold
	whatever data is private to the geom instance. Most GEOM classes
	have the following members:</para>

	<itemizedlist>
	<listitem><para><varname>struct g_provider *provider</varname> : The
	<quote>provider</quote> this geom instantiates</para></listitem>

	<listitem><para><varname>uint16_t n_disks</varname> : Number of
	consumer this geom consumes</para></listitem>

	<listitem><para><varname>struct g_consumer **disks</varname> : Array
	of <varname>struct g_consumer*</varname>. (It is not possible
	to use just single indirection because struct g_consumer*
	are created on our behalf by GEOM).</para></listitem>
	</itemizedlist>

	<para>The <structname>softc</structname> structure contains all
	the state of geom instance. Every geom instance has its own
	softc.</para>
	</sect2>

	<sect2 id="geom-metadata">
	<title>Metadata</title>

	<para>Format of metadata is more-or-less class-dependent, but
	MUST start with:</para>

	<itemizedlist>

	<listitem><para>16 byte buffer for null-terminated signature
	(usually the class name)</para></listitem>

	<listitem><para>uint32 version ID</para></listitem>

	</itemizedlist>

	<para>It is assumed that geom classes know how to handle metadata
	with version ID's lower than theirs.</para>

	<para>Metadata is located in the last sector of the provider
	(and thus must fit in it).</para>

	<para>(All this is implementation-dependent but all existing
	code works like that, and it is supported by libraries.)</para>
	</sect2>

	<sect2 id="geom-creating">
	<title>Labeling/creating a geom</title>

	<para>The sequence of events is:</para>

	<itemizedlist>

	<listitem><para>user calls &man.geom.8; utility (or one of its
	hardlinked friends)</para></listitem>

	<listitem><para>the utility figures out which geom class it is
	supposed to handle and searches for
	<filename>geom_<replaceable>CLASSNAME</replaceable>.so</filename>
	library (usually in
	<filename>/lib/geom</filename>).</para></listitem>

	<listitem><para>it &man.dlopen.3;-s the library, extracts the
	definitions of command-line parameters and helper
	functions.</para></listitem>

	</itemizedlist>

	<para>In the case of creating/labeling a new geom, this is what
	happens:</para>

	<itemizedlist>

	<listitem><para>&man.geom.8; looks in the command-line argument
	for the command (usually <option>label</option>), and calls a helper
	function.</para></listitem>

	<listitem><para>The helper function checks parameters and gathers
	metadata, which it proceeds to write to all concerned
	providers.</para></listitem>

	<listitem><para>This <quote>spoils</quote> existing geoms (if any) and
	initializes a new round of <quote>tasting</quote> of the providers. The
	intended geom class recognizes the metadata and brings the
	geom up.</para></listitem>

	</itemizedlist>

	<para>(The above sequence of events is implementation-dependent
	but all existing code works like that, and it is supported by
	libraries.)</para>

	</sect2>

	<sect2 id="geom-command">
	<title>Geom command structure</title>

	<para>The helper <filename>geom_CLASSNAME.so</filename> library
	exports <structname>class_commands</structname> structure,
	which is an array of <structname>struct g_command</structname>
	elements. Commands are of uniform format and look like:</para>

	<programlisting> verb [-options] geomname [other]</programlisting>

	<para>Common verbs are:</para>

	<itemizedlist>

	<listitem><para>label — to write metadata to devices so they can be
	recognized at tasting and brought up in geoms</para></listitem>

	<listitem><para>destroy — to destroy metadata, so the geoms get
	destroyed</para></listitem>

	</itemizedlist>

	<para>Common options are:</para>

	<itemizedlist>
	<listitem><para><literal>-v</literal> : be verbose</para></listitem>
	<listitem><para><literal>-f</literal> : force</para></listitem>
	</itemizedlist>

	<para>Many actions, such as labeling and destroying metadata can
	be performed in userland. For this, <structname>struct
	g_command</structname> provides field
	<varname>gc_func</varname> that can be set to a function (in
	the same <filename>.so</filename>) that will be called to
	process a verb. If <varname>gc_func</varname> is NULL, the
	command will be passed to kernel module, to
	<function>.ctlreq</function> function of the geom
	class.</para>
	</sect2>

	<sect2 id="geom-geoms">
	<title>Geoms</title>

	<para>Geoms are instances of GEOM classes. They have internal
	data (a softc structure) and some functions with which they
	respond to external events.</para>

	<para>The event functions are:</para>

	<itemizedlist>
	<listitem><para><function>.access</function> : calculates
	permissions (read/write/exclusive)</para></listitem>

	<listitem><para><function>.dumpconf</function> : returns
	XML-formatted information about the geom</para></listitem>

	<listitem><para><function>.orphan</function> : called when some
	underlying provider gets disconnected</para></listitem>

	<listitem><para><function>.spoiled</function> : called when some
	underlying provider gets written to</para></listitem>

	<listitem><para><function>.start</function> : handles I/O</para></listitem>
	</itemizedlist>

	<para>These functions are called from the <function>g_down</function>
	kernel thread and there can be no sleeping in this context,
	(see definition of sleeping elsewhere) which limits what can be done
	quite a bit, but forces the handling to be fast.</para>

	<para>Of these, the most important function for doing actual
	useful work is the <function>.start</function>() function,
	which is called when a BIO request arrives for a provider
	managed by a instance of geom class.</para>
	</sect2>

	<sect2 id="geom-threads">
	<title>Geom threads</title>

	<para>There are three kernel threads created and run by the GEOM
	framework:</para>

	<itemizedlist>
	<listitem><para><literal>g_down</literal> : Handles requests coming
	from high-level entities (such as a userland request) on the
	way to physical devices</para></listitem>

	<listitem><para><literal>g_up</literal> : Handles responses from
	device drivers to requests made by higher-level
	entities</para></listitem>

	<listitem><para><literal>g_event</literal> : Handles all other
	cases: creation of geom instances, access counting, <quote>spoil</quote>
	events, etc.</para></listitem>
	</itemizedlist>

	<para>When a user process issues <quote>read data X at offset Y
	of a file</quote> request, this is what happens:</para>

	<itemizedlist>

	<listitem><para>The filesystem converts the request into a struct bio
	instance and passes it to the GEOM subsystem. It knows what geom
	instance should handle it because filesystems are hosted
	directly on a geom instance.</para></listitem>

	<listitem><para>The request ends up as a call to the
	<function>.start</function>() function made on the g_down
	thread and reaches the top-level geom instance.</para></listitem>

	<listitem><para>This top-level geom instance (for example the
	partition slicer) determines that the request should be
	routed to a lower-level instance (for example the disk
	driver). It makes a copy of the bio request (bio requests
	<emphasis>ALWAYS</emphasis> need to be copied between
	instances, with <function>g_clone_bio</function>()!),
	modifies the data offset and target provider fields and
	executes the copy with
	<function>g_io_request</function>()</para></listitem>

	<listitem><para>The disk driver gets the bio request also as a call
	to <function>.start</function>() on the
	<literal>g_down</literal> thread. It talks to hardware,
	gets the data back, and calls
	<function>g_io_deliver</function>() on the bio.</para></listitem>

	<listitem><para>Now, the notification of bio completion
	<quote>bubbles up</quote> in the <literal>g_up</literal>
	thread. First the partition slicer gets
	<function>.done</function>() called in the
	<literal>g_up</literal> thread, it uses information stored
	in the bio to free the cloned <structname>bio</structname>
	structure (with <function>g_destroy_bio</function>()) and
	calls <function>g_io_deliver</function>() on the original
	request.</para></listitem>

	<listitem><para>The filesystem gets the data and transfers it to
	userland.</para></listitem>
	</itemizedlist>

	<para>See &man.g.bio.9; man page for information how the data is
	passed back and forth in the <structname>bio</structname>
	structure (note in particular the <varname>bio_parent</varname>
	and <varname>bio_children</varname> fields and how they are
	handled).</para>

	<para>One important feature is: <emphasis>THERE CAN BE NO SLEEPING IN G_UP
	AND G_DOWN THREADS</emphasis>. This means that none of the following
	things can be done in those threads (the list is of course not
	complete, but only informative):</para>

	<itemizedlist>
	<listitem><para>Calls to <function>msleep</function>() and
	<function>tsleep</function>(), obviously.</para></listitem>

	<listitem><para>Calls to <function>g_write_data</function>() and
	<function>g_read_data</function>(), because these sleep
	between passing the data to consumers and
	returning.</para></listitem>

	<listitem><para>Waiting for I/O.</para></listitem>

	<listitem><para>Calls to &man.malloc.9; and
	<function>uma_zalloc</function>() with
	<varname>M_WAITOK</varname> flag set</para></listitem>

	<listitem><para>sx and other sleepable locks</para></listitem>
	</itemizedlist>

	<para>This restriction is here to stop GEOM code clogging the I/O
	request path, since sleeping is usually not
	time-bound and there can be no guarantees on how long will it
	take (there are some other, more technical reasons also). It
	also means that there is not much that can be done in those
	threads; for example, almost any complex thing requires memory
	allocation. Fortunately, there is a way out: creating
	additional kernel threads.</para>
	</sect2>

	<sect2 id="geom-kernelthreads">
	<title>Kernel threads for use in geom code</title>

	<para>Kernel threads are created with &man.kthread.create.9;
	function, and they are sort of similar to userland threads in
	behaviour, only they cannot return to caller to signify
	termination, but must call &man.kthread.exit.9;.</para>

	<para>In GEOM code, the usual use of threads is to offload
	processing of requests from <literal>g_down</literal> thread
	(the <function>.start</function>() function). These threads
	look like <quote>event handlers</quote>: they have a linked
	list of event associated with them (on which events can be posted
	by various functions in various threads so it must be
	protected by a mutex), take the events from the list one by
	one and process them in a big <literal>switch</literal>()
	statement.</para>

	<para>The main benefit of using a thread to handle I/O requests
	is that it can sleep when needed. Now, this sounds good, but
	should be carefully thought out. Sleeping is well and very
	convenient but can very effectively destroy performance of the
	geom transformation. Extremely performance-sensitive classes
	probably should do all the work in
	<function>.start</function>() function call, taking great care
	to handle out-of-memory and similar errors.</para>

	<para>The other benefit of having a event-handler thread like
	that is to serialize all the requests and responses coming
	from different geom threads into one thread. This is also very
	convenient but can be slow. In most cases, handling of
	<function>.done</function>() requests can be left to the
	<literal>g_up</literal> thread.</para>

	<para>Mutexes in FreeBSD kernel (see &man.mutex.9;) have
	one distinction from their more common userland cousins — the
	code cannot sleep while holding
	a mutex). If the code needs to sleep a lot, &man.sx.9; locks
	may be more appropriate. On the other hand, if you do almost
	everything in a single thread, you may get away with no
	mutexes at all.</para>

	</sect2>

	</sect1>

	</article>
	Index: projects/entities/en_US.ISO8859-1/articles/hubs/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/hubs/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/hubs/article.xml (revision 41355)
	@@ -1,1076 +1,1069 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	]>

	<article lang='en'>
	<articleinfo>
	<title>Mirroring FreeBSD</title>
	<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>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>

	<abstract>
	<para>An in-progress article on how to mirror FreeBSD, aimed at
	hub administrators.</para>
	</abstract>
	</articleinfo>

	<note>
	<para>We are not accepting new mirrors at this time.</para>
	</note>

	<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: 1.0 TB</para></listitem>
	<listitem><para>CVS repository: 5.4 GB</para></listitem>
	<listitem><para>CTM deltas: 3.2 GB</para></listitem>
	<listitem><para>Web pages: 463 MB</para></listitem>
	</itemizedlist>
	<para>
	The current disk usage of FTP Distribution can be found at
	<ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes">ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes</ulink>.
	</para>
	</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
	rsync. This can have a huge
	impact on CPU and memory requirements as it is
	considered a memory hog.
	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).</para>
	<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>
	<para>FreeBSD's <application>ftpd</application>, <application>proftpd</application>,
	<application>wu-ftpd</application> and maybe <application>ncftpd</application>
	are among the most commonly used FTPds.
	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:</para>
	<itemizedlist>
	<listitem><para><filename role="package">net/rsync</filename></para></listitem>
	</itemizedlist>
	</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 will need
	to install a web server.
	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:</para>

	<itemizedlist>
	<listitem>
	<para><filename role="package">www/apache22</filename>:
	<application>Apache</application> is the most widely
	deployed web server on the Internet. It is used
	extensively by the FreeBSD Project.</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 <application>Apache</application>. It is
	optimized for excellent performance on FreeBSD.</para>
	</listitem>

	<listitem>
	<para><filename role="package">www/boa</filename>:
	<application>Boa</application> is another alternative to
	<application>thttpd</application> and
	<application>Apache</application>. It should provide
	considerably better performance than
	<application>Apache</application> for purely static
	content. It does not, at the time of this writing,
	contain the same set of optimizations for FreeBSD that
	are found in <application>thttpd</application>.</para>
	</listitem>
	</itemizedlist>
	</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.email;.
	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. &a.jdp; 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:</para>

	<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-without-gui</filename>, and configures it mirror-ready. Some
	site administrators may want a different setup though.
	</para>
	</listitem>
	</itemizedlist>

	<para>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 do not 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 do not 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:</para>
	<programlisting>
	cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --allow-root=/home/ncvs pserver
	</programlisting>
	<para>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:</para>
	<programlisting>
	/dev/da0s1b /anoncvstmp mfs rw,-s=786432,-b=4096,-f=512,-i=560,-c=3,-m=0,nosuid 0 0
	</programlisting>
	<para>This is (of course) tuned a lot, and was suggested by &a.jdp.email;.
	</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. Some of the most commonly used are:</para>
	<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><filename role="package">ftp/wget</filename></para></listitem>
	</itemizedlist>

	<para><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.</para>
	<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>
	<para>A command line to mirror FreeBSD might look like:</para>
	<screen>&prompt.user; <userinput>rsync -vaz --delete ftp4.de.FreeBSD.org::FreeBSD/ /pub/FreeBSD/</userinput>
	</screen>
	<para>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:</para>
	<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>

	<para>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.</para>
	<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. This reduces I/O operations by assuming the
	recorded information about each file is correct.</para>
	</note>
	</sect3>
	</sect2>
	<sect2 id="mirror-cvs">
	<title>Mirroring the CVS repository</title>
	<para>There are various ways to mirror the CVS repository.
	<application>CVSup</application> is the most common method.</para>

	<sect3 id="mirror-cvs-cvsup">
	<title>Using CVSup</title>
	<para>
	<application>CVSup</application> is described in some
	detail in <xref linkend="mirror-serv-cvsup"/> and <xref linkend="mirror-ftp-cvsup"/>.
	</para>
	<para>It is very easy to setup a
	<application>CVSup</application> mirror. Installing
	<filename role="package">net/cvsup-mirror</filename> will
	make sure all of the needed programs are installed and then
	gather all the needed information to configure the mirror.</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.</para>
	<itemizedlist>
	<listitem><para><application>FTP</application></para></listitem>
	<listitem><para><application>Rsync</application></para></listitem>
	<listitem><para><application>HTTP</application></para></listitem>
	</itemizedlist>

	<important>
	<para>AnonCVS cannot be used to mirror the CVS repository
	since CVS does not allow you to access the repository
	itself, only checked out versions of the modules.</para>
	</important>
	</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 as easy as:</para>
	<screen>&prompt.user; <userinput>cvs -d /home/ncvs co www</userinput></screen>
	<para>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>

	<para>
	If you do not 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:</para>
	<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>
	Using <filename role="package">ftp/wget</filename> or other web-mirror tools is
	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:</para>
	<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>
	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>/usr/share/examples/etc/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 your 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.</para>
	<important>
	<para>
	The building of the documentation, as well as lots
	of side issues, is documented itself in the
	<ulink url="&url.books.fdp-primer;">&os; Documentation
	Project Primer</ulink>.
	Please read this piece of documentation, especially if you
	have problems building the documentation.
	</para>
	</important>
	</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:</para>
	<itemizedlist>
	<listitem><para>FTP fileset: daily</para></listitem>
	<listitem><para>CVS repository: hourly</para></listitem>
	<listitem><para>WWW pages: daily</para></listitem>
	</itemizedlist>
	</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 am 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, in addition to FTP.
	Refer to <xref linkend="mirror-ftp-rsync"/> and
	<xref linkend="mirror-ftp-cvsup"/> how to access
	via these protocols.
	</para>
	<para>
	Mirrors are also encouraged to 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 the &a.cvsup-master;.
	Make sure you read the
	<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</para>
	<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>

	<para>So far to distinguish official mirrors.
	Official mirrors are not necessarily <emphasis>Tier-1</emphasis>-mirrors.
	However you probably will not 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>.</para>
	<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>
	Tier-1 mirrors are required to:</para>
	<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>

	<para>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 does not 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>
	-->
	<para>
	We are not accepting any new mirrors at this time.
	</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>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>ftp2.ru.FreeBSD.org - <email>mirror@macomnet.ru</email> -
	<ulink url="http://mirror.macomnet.net/mrtg/mirror.macomnet.net_195.128.64.25.html">(Bandwidth)</ulink>
	<ulink url="http://mirror.macomnet.net/mrtg/mirror.macomnet.net_proc.html">(HTTP and FTP 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/index.en.html">(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>cvsup4.ru.FreeBSD.org - <email>maxim@FreeBSD.org</email> -
	<ulink url="http://ftp.mtu.ru/mrtg/ftp.mtu.ru_proc2.html">(CVSup processes)</ulink></para>
	</listitem>
	</itemizedlist>
	</sect2>
	</sect1>
	</article>
	Index: projects/entities/en_US.ISO8859-1/articles/p4-primer/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/p4-primer/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/p4-primer/article.xml (revision 41355)
	@@ -1,893 +1,894 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	]>

	<article lang='en'>
	<title>Perforce in &os; Development</title>

	<articleinfo>

	<authorgroup>
	<author>
	<firstname>Scott</firstname>
	<surname>Long</surname>
	<affiliation>
	<address><email>scottl@FreeBSD.org</email>
	</address>
	</affiliation>
	</author>
	</authorgroup>

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	&tm-attrib.cvsup;
	&tm-attrib.general;
	</legalnotice>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>
	</articleinfo>

	<sect1 id="intro">
	<title>Introduction</title>

	<para>The &os; project uses the <application>Perforce</application>
	version control system to manage experimental projects that are
	- not ready for the main CVS repository.</para>
	+ not ready for the main Subversion repository.</para>

	<sect2 id="resources">
	<title>Availability, Documentation, and Resources</title>

	<para>While <application>Perforce</application> is a commercial
	product, the client software for interacting with the server is
	freely available from Perforce. It can be easily installed on
	&os; via the <filename role="package">devel/p4</filename>
	port or can be downloaded from the <application>Perforce</application>
	web site at <ulink
	url="http://www.perforce.com/perforce/loadprog.html"></ulink>,
	which also offers client applications for other OS's.</para>

	<para>While there is a GUI client available, most people use the
	command line application called <command>p4</command>. This
	document is written from the point of view of using this
	command.</para>

	<para>Detailed documentation is available online at <ulink
	url="http://www.perforce.com/perforce/technical.html"></ulink>.</para>

	<para>Reading the <quote>Perforce User's Guide</quote> and
	<quote>Perforce Command Reference</quote> is highly recommended.
	The <application>p4</application> application also contains an
	extensive amount of online help accessible via the <command>p4
	help</command> command.</para>

	<para>The &os; <application>Perforce</application> server is
	hosted on <hostid role="fqdn">perforce.freebsd.org</hostid>,
	port <literal>1666</literal>. The repository is browsable
	- online at <ulink url="http://perforce.freebsd.org"></ulink>.
	+ online at <ulink url="http://p4web.freebsd.org"></ulink>.
	Some portions of the repository are also automatically exported
	- to a number of <application>CVSup</application> servers.</para>
	+ to a number of legacy <application>CVSup</application> servers.</para>
	</sect2>
	</sect1>

	<sect1 id="start">
	<title>Getting Started</title>

	<para>The first step to using <application>Perforce</application> is
	to obtain an account on the server. If you already have a <hostid
	role="domainname">FreeBSD.org</hostid> account, log into <hostid
	role="hostname">freefall</hostid>, run the following command, and
	enter a password that is not the same as your &os; login or any
	other SSH passphrase:</para>

	<screen>&prompt.user; <userinput>/usr/local/bin/p4newuser</userinput></screen>

	<para>Of course if you do not have a <hostid
	role="domainname">FreeBSD.org</hostid> account, you will need to
	coordinate with your sponsor.</para>

	<warning>
	<para>An email will be sent to your &os; address that contains
	the password you specified above in cleartext. Be sure to change
	the password once your <application>Perforce</application> account
	has been created!</para>
	</warning>

	<para>The next step is to set the environment variables that
	<command>p4</command> needs, and verify that it can connect to the
	server. The <envar>P4PORT</envar> variable is required to be set
	for all operations, and specifies the appropriate
	<application>Perforce</application> server to talk to. For the
	&os; project, set it like so:</para>

	<screen>&prompt.user; <userinput>export P4PORT=perforce.freebsd.org:1666</userinput></screen>

	<note>
	<para>Users with shell access on the <hostid
	role="domainname">FreeBSD.org</hostid> cluster may wish to tunnel
	the <application>Perforce</application> client-server protocol via
	an SSH tunnel, in which case the above string should be set to
	<literal>localhost</literal>.</para>
	</note>

	<para>The &os; server also requires that the <envar>P4USER</envar>
	and <envar>P4PASSWD</envar> variables be set. Use the username
	and password from above, like so:</para>

	<screen>&prompt.user; <userinput>export P4USER=<replaceable>username</replaceable></userinput>
	&prompt.user; <userinput>export P4PASSWD=<replaceable>password</replaceable></userinput></screen>

	<para>Test that this works by running the following command:</para>

	<screen>&prompt.user; <userinput>p4 info</userinput></screen>

	<para>This should return a list of information about the server. If
	it does not, check that you have the <envar>P4PORT</envar>
	variable set correctly.</para>
	</sect1>

	<sect1 id="clients">
	<title>Clients</title>

	<para><application>Perforce</application> provides access to the
	repository and tracks state on a per-client basis. In
	<application>Perforce</application> terms, a client is a
	specification that maps files and directories from the repository
	to the local machine. Each user can have multiple clients, and
	each client can access different or overlapping parts of the
	repository. The client also specifies the root directory of the
	file tree that it maps, and it specifies the machine that the tree
	lives on. Thus, working on multiple machines requires that
	multiple clients be used.</para>

	<para>Clients may be accessed via the <command>p4 client</command>
	command. Running this command with no arguments will bring up a
	client template in an editor, allowing you to create a new client
	for your work. The important fields in this template are
	explained below:</para>

	<variablelist>
	<varlistentry>
	<term><literal>Client:</literal></term>

	<listitem>
	<para>This is the name of the client spec. It can be anything
	you want, but it must be unique within the
	<application>Perforce</application> server. A naming
	convention that is commonly used is
	<literal><replaceable>username</replaceable>_<replaceable>machinename</replaceable></literal>,
	which makes it easy to identify clients when browsing them.
	A default name will be filled in that is just the machine
	name.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>Description:</literal></term>

	<listitem>
	<para>This can contain a simple text description to help
	identify the client.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>Root:</literal></term>

	<listitem>
	<para>This is the local directory that will serve as the root
	directory of all the files in the client mapping. This should
	be a unique location in your filesystem that does not overlap
	with other files or <application>Perforce</application>
	clients.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>Options:</literal></term>

	<listitem>
	<para>Most of the default options are fine, though it is
	usually a good idea to make sure that the
	<option>compress</option> and <option>rmdir</option> options
	are present and do not have a <literal>no</literal> prefix on
	them. Details about each option are in the
	<application>Perforce</application> docs.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>LineEnd:</literal></term>

	<listitem>
	<para>This handles CR-LF conversions and should be left to the
	default unless you have special needs for it.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>View:</literal></term>

	<listitem>
	<para>This is where the server-to-local file mappings go. The
	default is</para>

	<programlisting>//depot/... //<replaceable>client</replaceable>/...</programlisting>

	<para>This will map the entire
	<application>Perforce</application> repository to the
	<filename class="directory">Root</filename> directory of your
	client. <emphasis>DO NOT USE THIS DEFAULT!</emphasis> The
	&os; repo is huge, and trying to map and sync it all will
	take an enormous amount of resources. Instead, only map the
	section of the repo that you intend to work on. For
	example, there is the smpng project tree at <filename
	class="directory">//depot/projects/smpng</filename>. A
	mapping for this might look like:</para>

	<programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/...</programlisting>

	<para>The <literal>...</literal> should be taken literally. It
	is a <application>Perforce</application> idiom for saying
	<quote>this directory and all files and directories below
	it.</quote></para>

	<para>A Perforce <quote>view</quote> can contain multiple mappings. Let's say you
	want to map in both the SMPng tree and the NFS tree. Your
	View might look like:</para>

	<programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/smpng/...
	//depot/projects/nfs/... //<replaceable>client</replaceable>/nfs/...</programlisting>

	<para>Remember that the <replaceable>client</replaceable> is
	the name of the client that was specified in the
	<literal>Client</literal> section, but in the
	<literal>View</literal> it also resolves to the directory
	that was specified in the <literal>Root</literal>
	section.</para>

	<para>Also note that the same file or directory cannot be
	mapped multiple times in a single view. The following is
	illegal and will produce undefined results:</para>

	<programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/smpng-foo/...
	//depot/projects/smpng/... //<replaceable>client</replaceable>/smpng-bar/...</programlisting>

	<para>Views are a tricky part of the learning experience with
	<application>Perforce</application>, so do not be afraid to
	ask questions.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>Existing clients can be listed via the <command>p4
	clients</command> command. They can be viewed without being
	modified via the <command>p4 client -o
	<replaceable>clientname</replaceable></command> command.</para>

	<para>Whenever you are interacting with files in
	<application>Perforce</application>, the <envar>P4CLIENT</envar>
	environment variable must be set to the name of the client that
	you are using, like so:</para>

	<screen>&prompt.user; <userinput>export P4CLIENT=<replaceable>myclientname</replaceable></userinput></screen>

	<para>Note that client mappings in the repository are not exclusive;
	multiple clients can map in the same part of the repository. This
	allows multiple people to access and modify the same parts of the
	repository, allowing a team of people to work together on the same
	code.</para>
	</sect1>

	<sect1 id="syncing">
	<title>Syncing</title>

	<para>Once you have a client specification defined and the
	<envar>P4CLIENT</envar> variable set, the next step is to pull the
	files for that client down to your local machine. This is done
	with the <command>p4 sync</command> command, which instructs
	<application>Perforce</application> to synchronize the local files
	in your client with the repository. The first time it runs, it
	will download all of the files. Subsequent runs will only
	download files that have changed since the previous run. This
	allows you to stay in sync with others whom you might be working
	with.</para>

	<para>Sync operations only work on files that the
	<application>Perforce</application> server knows has changed. If
	you change or delete a file locally without informing the server,
	doing a sync will not bring it back. However, doing a <command>p4
	sync -f</command> will unconditionally sync all files, regardless
	of their state. This is useful for resolving problems where you
	think that your tree might be corrupt.</para>

	<para>You can sync a subset of your tree or client by specifying a
	relative path to the sync command. For example, to only sync the
	<filename class="directory">ufs</filename> directory of the
	<literal>smpng</literal> project, you might do the
	following:</para>

	<screen>&prompt.user; <userinput>cd <replaceable>projectroot</replaceable>/smpng</userinput>
	&prompt.user; <userinput>p4 sync src/sys/ufs/...</userinput></screen>

	<para>Specifying a local relative path works for many other
	<command>p4</command> commands.</para>
	</sect1>

	<sect1 id="branches">
	<title>Branches</title>

	<para>One of the strongest features of
	<application>Perforce</application> is branching. Branches are
	very cheap to create, and moving changes between related branches
	is very easy (as will be explained later). Branches also allow
	you to do very experimental work in a sandbox-like environment,
	without having to worry about colliding with others or
	destabilizing the main tree. They also provide insulation against
	mistakes while learning the <application>Perforce</application>
	system. With all of these benefits, it makes sense for each
	project to have its own branch, and we strongly encourage that
	with &os;. Frequent submits of changes to the server are also
	encouraged.</para>

	- <para>The <application>Perforce</application> repository (the
	+ <para>sSimilar to <application>Subversion</application>, the
	+ <application>Perforce</application> repository (the
	<quote>depot</quote>) is a single flat tree. Every file, whether
	a unique creation or a derivative from a branch, is accessible via
	a simple path under the server <filename
	class="directory">//depot</filename> directory. When you create a
	branch, all you are doing is creating a new path under the
	<filename class="directory">//depot</filename>. This is in sharp
	contrast to systems like CVS, where each branch lives in the same
	path as its parent. With <application>Perforce</application>, the
	server tracks the relationship between the files in the parent and
	child, but the files themselves live under their own paths.</para>

	<para>The first step to creating a branch is to create a branch
	specification. This is similar to a client specification, but is
	created via the command <command>p4 branch
	<replaceable>branchname</replaceable></command>.</para>

	<para>The following important fields are explained:</para>

	<variablelist>
	<varlistentry>
	<term><literal>Branch</literal></term>

	<listitem>
	<para>The name of the branch. It can be any name, but must be
	unique within the repository. The common convention in &os;
	is to use
	<replaceable>username</replaceable>_<replaceable>projectname</replaceable>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>Description</literal></term>

	<listitem>
	<para>This can hold a simple text description to describe the
	branch.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>View</literal></term>

	<listitem>
	<para>This is the branch mapping. Instead of mapping from the
	depot to the local machine like a client map, it maps between
	the branch parent and branch child in the depot. For example,
	you might want to create a branch of the smpng project. The
	mapping might look like:</para>

	<programlisting>//depot/projects/smpng/... //depot/projects/my-super-smpng/...</programlisting>

	<para>Or, you might want to create a brand new branch off of
	the stock &os; sources:</para>

	<programlisting>//depot/vendor/freebsd/... //depot/projects/my-new-project/...</programlisting>

	<para>This will map the &os; HEAD tree to your new
	branch.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>Creating the branch spec only saves the spec itself in the
	server, it does not modify the depot or change any files. The
	directory that you specified in the branch is empty on the server
	until you populate it.</para>

	<para>To populate your branch, first edit your client with the
	<command>p4 client</command> command and make sure that the branch
	directory is mapped in your client. You might need to add a
	<literal>View</literal> line like:</para>

	<programlisting>//depot/projects/my-new-project/... //<replaceable>myclient</replaceable>/my-new-project/...</programlisting>

	<para>The next step is to run the <command>p4 integrate</command>
	command, as described in the next section.</para>
	</sect1>

	<sect1 id="Integrations">
	<title>Integrations</title>

	<para><quote>Integration</quote> is the term used by
	<application>Perforce</application> to describe the action of
	moving changes from one part of the depot to another. It is most
	commonly done in conjunction with creating and maintaining
	branches. An integration is done when you want to initially
	populate a branch, and it is done when you want to move subsequent
	changes in the branch from the parent to the child, or from the
	child to the parent. A common example of this is periodically
	integrating changes from the vendor &os; tree to your child branch
	tree, allowing you to keep up to date with changes in the &os;
	tree. The <application>Perforce</application> server tracks the
	changes in each tree and knows when there are changes that can be
	integrated from one tree to another.</para>

	<para>The common way to do an integration is with the following
	command:</para>

	<screen>&prompt.user; <userinput>p4 integrate -b <replaceable>branchname</replaceable></userinput></screen>

	<para><replaceable>branchname</replaceable> is the name given to a
	branch spec, as discussed in the previous section. This command
	will instruct <application>Perforce</application> to look for
	changes in the branch parent that are not yet in the child. From
	those changes it will prepare a list of diffs to move. If the
	integration is being done for the first time on a branch (i.e.
	doing an initial population operation), then the parent files will
	simply be copied to the child location on the local
	machine.</para>

	<para>Once the integration operation is done, you must run
	<command>p4 resolve</command> to accept the changes and resolve
	possible conflicts. Conflicts can arise from overlapping changes
	that happened in both the parent and child copy of a file.
	Usually, however, there are no conflicts, and
	<application>Perforce</application> can quickly figure out how to
	merge the changes together. Use the following commands to do a
	resolve operation:</para>

	<screen>&prompt.user; <userinput>p4 resolve -as</userinput>
	&prompt.user; <userinput>p4 resolve</userinput></screen>

	<para>The first invocation will instruct
	<application>Perforce</application> to automatically merge the
	changes together and accept files that have no conflicts. The
	second invocation will allow you to inspect each file that has a
	possible conflict and resolve it by hand if needed.</para>

	<para>Once all of the integrated files have been resolved, they need
	to be committed back to the repository. This is done via the
	<command>p4 submit</command> command, explained in the next
	section.</para>
	</sect1>

	<sect1 id="submit">
	<title>Submit</title>

	<para>Changes that are made locally should be committed back to the
	<application>Perforce</application> server for safe keeping and so
	that others can access them. This is done via the <command>p4
	submit</command> command. When you run this command, it will open
	up a submit template in an editor. &os; has a custom template,
	and the important fields are described below:</para>

	<programlisting>Description:
	<enter description here>
	PR:
	Submitted by:
	Reviewed by:
	Approved by:
	Obtained from:
	MFP4 after:</programlisting>

	<para>It is good practice to provide at least 2-3 sentences that
	describe what the changes are that you are submitting. You should
	say what the change does, why it was done that way or what
	problem is solves, and what APIs it might change or other side
	effects it might have. This text should replace the
	<literal><enter description here></literal> line in the template.
	You should wrap your lines and start each line with a TAB. The
	tags below it are &os;-specific and can be removed if not
	needed.</para>

	<programlisting>Files:</programlisting>

	<para>This is automatically populated with all of the files in your
	client that were marked in the add, delete, integrate, or edit
	states on the server. It is always a very good idea to review
	this list and remove files that might not be ready yet.</para>

	<para>Once you save the editor session, the submit will happen to
	the server. This also means that the local copies of the
	submitted files will be copied back to the server. If anything
	goes wrong during this process, the submit will be aborted, and
	you will be notified that the submit has been turned into a
	changelist that must be corrected and re-submitted. Submits are
	atomic, so if one file fails, the entire submit is aborted.</para>

	<para>Submits cannot be reverted, but they can be aborted while in
	the editor by exiting the editor without changing the
	<literal>Description</literal> text.
	<application>Perforce</application> will complain about this the
	first time you do it and will put you back in the editor. Exiting
	the editor the second time will abort the operation. Reverting a
	submitted change is very difficult and is best handled on a
	case-by-case basis.</para>
	</sect1>

	<sect1 id="editing">
	<title>Editing</title>

	<para>The state of each file in the client is tracked and saved on
	the server. In order to avoid collisions from multiple people
	working on the same file at once,
	<application>Perforce</application> tracks which files are opened
	for edit, and uses this to help with submit, sync, and integration
	operations later on.</para>

	<para>To open a file for editing, use the <command>p4 edit</command>
	command like so:</para>

	<screen>&prompt.user; <userinput>p4 edit <replaceable>filename</replaceable></userinput></screen>

	<para>This marks the file on the server as being in the <emphasis>edit</emphasis> state,
	which then allows it to be submitted after changes are made, or
	marks it for special handling when doing an integration or sync
	operation. Note that editing is not exclusive in
	<application>Perforce</application>. Multiple people can have the
	same file in the edit state (you will be informed of others when
	you run the <command>edit</command> command), and you can submit
	your changes even when others are still editing the file.</para>

	<para>When someone else submits a change to a file that you are
	editing, you will need to resolve his changes with yours before
	your submit will succeed. The easiest way to do this is to either
	run a <command>p4 sync</command> or <command>p4 submit</command>
	and let it fail with the conflict, then run <command>p4
	resolve</command> to manually resolve and accept his changes into
	your copy, then run <command>p4 submit</command> to commit your
	changes to the repository.</para>

	<para>If you have a file open for edit and you want to throw away
	your changes and revert it to its original state, run the
	<command>p4 revert</command> command like so:</para>

	<screen>&prompt.user; <userinput>p4 revert <replaceable>filename</replaceable></userinput></screen>

	<para>This resyncs the file to the contents of the server, and
	removes the edit attribute from the server. Any local changes
	that you had will be lost. This is quite useful when you have a
	made changes to a file but later decide that you do not want to
	keep them.</para>

	<para>When a file is synced, it is marked read-only in the
	filesystem. When you tell the server to open it for editing, it
	is changed to read-write on the filesystem. While these
	permissions can easily be overridden by hand, they are meant to
	gently remind you that you should being using the <command>p4
	edit</command> command. Files that have local changes but are not
	in the edit state may get overwritten when doing a <command>p4
	sync</command>.</para>
	</sect1>

	<sect1 id="changes">
	<title>Changes, Descriptions, and History</title>

	<para>Changes to the <application>Perforce</application> depot can
	be listed via the <command>p4 changes</command> command. This
	will provide a brief description of each change, who made the
	change, and what its change number was. A change can be examined
	in detail via the <command>p4 describe
	<replaceable>changenumber</replaceable></command> command. This
	will provide the submit log and the diffs of the actual change.</para>

	<para>Commonly, the <command>p4 describe</command> command is used in one
	of three ways:</para>

	<variablelist>
	<varlistentry>
	<term><command>p4 describe -s <replaceable>CHANGE</replaceable></command></term>

	<listitem>
	<para>List a short description of
	changeset <emphasis>CHANGE</emphasis>, including the commit log of
	the particular changeset and a list of the files it affected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>p4 describe -du <replaceable>CHANGE</replaceable></command></term>

	<listitem>
	<para>List a description of changeset <emphasis>CHANGE</emphasis>,
	including the commit log of the particular changeset, a list of the
	files it affected and a patch for each modified file, in a format
	similar to <quote>unified diff</quote> patches (but not exactly the
	same).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>p4 describe -dc <replaceable>CHANGE</replaceable></command></term>

	<listitem>
	<para>List a description of changeset <emphasis>CHANGE</emphasis>,
	including the commit log of the particular changeset, a list of the
	files it affected and a patch for each modified file, in a format
	similar to <quote>context diff</quote> patches (but not exactly the
	same).</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>The <command>p4 filelog
	<replaceable>filename</replaceable></command> command will show
	the history of a file, including all submits, integrations, and
	branches of it.</para>
	</sect1>

	<sect1 id="diffs">
	<title>Diffs</title>

	<para>There are two methods of producing file diffs in
	<application>Perforce</application>, either against local changes
	that have not been submitted yet, or between two trees (or within
	a branch) in the depot. These are done with different commands,
	<option>diff</option> and <option>diff2</option>:</para>

	<variablelist>
	<varlistentry>
	<term><command>p4 diff</command></term>

	<listitem>
	<para>This generates a diff of the local changes to files in
	the edit state. The <option>-du</option> and
	<option>-dc</option> flags can be used to create unified or
	context diffs, respectively, or the <envar>P4DIFF</envar>
	environment variable can be set to a local diff command to be
	used instead. It is a very good idea to use this command to
	review your changes before submitting them.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>p4 diff2</command></term>

	<listitem>
	<para>This creates a diff between arbitrary files in the
	depot, or between files specified in a branch spec. The diff
	operation takes place on the server, so <envar>P4DIFF</envar>
	variable has no effect, though the <option>-du</option> and
	<option>-dc</option> flags do work. The two forms of this
	command are:</para>

	<screen>&prompt.user; <userinput>p4 diff2 -b <replaceable>branchname</replaceable></userinput></screen>

	<para>and</para>

	<screen>&prompt.user; <userinput>p4 diff2 //depot/<replaceable>path1</replaceable> //depot/<replaceable>path2</replaceable></userinput></screen>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>In all cases the diff will be written to the standard output.
	Unfortunately, <application>Perforce</application> produces a diff
	format that is slightly incompatible with the traditional Unix
	diff and patch tools. Using the <envar>P4DIFF</envar> variable to
	point to the real &man.diff.1; tool can help this, but only for
	the <command>p4 diff</command> command. The output of
	<option>diff2</option> command must be post-processed to be useful
	(the <option>-u</option> flag of <option>diff2</option> will
	produce unified diffs that are somewhat compatible, but it does
	not include files that have been added or deleted). There is a
	post-processing script at: <ulink
	url="http://people.freebsd.org/~scottl/awkdiff"></ulink>.</para>
	</sect1>

	<sect1 id="add-rm-files">
	<title>Adding and Removing Files</title>

	<para>Integrating a branch will bring existing files into your tree,
	but you may still want to add new files or remove existing ones.
	Adding files is easily done be creating the file and then running
	the <command>p4 add</command> command like so:</para>

	<screen>&prompt.user; <userinput>p4 add <replaceable>filename</replaceable></userinput></screen>

	<para>If you want to add a whole tree of files, run a command
	like:</para>

	<screen>&prompt.user; <userinput>find . -type f \| xargs p4 add</userinput></screen>

	<note>
	<para><application>Perforce</application> can track UNIX symlinks too, so
	you can probably
	use <quote><command>\! -type d</command></quote> as the
	matching expression in &man.find.1; above. We don't commit symlinks
	into the source tree of &os; though, so this should not be
	necessary.</para>
	</note>

	<para>Doing a <command>p4 submit</command> will then copy the file
	to the depot on the server. It is very important to only add
	files, not directories. Explicitly adding a directory will cause
	<application>Perforce</application> to treat it like a file, which
	is not what you want.</para>

	<para>Removing a file is just as easy with the <command>p4</command>
	delete command like so:</para>

	<screen>&prompt.user; <userinput>p4 delete <replaceable>filename</replaceable></userinput></screen>

	<para>This will mark the file for deletion from the depot the next
	time that a submit is run. It will also remove the local copy of
	the file, so beware.</para>

	<para>Of course, deleting a file does not actually remove it from
	the repository.</para>

	<para>Deleted files can be resurrected by syncing them to a prior
	version. The only way to permanently remove a file is to use the
	<command>p4 obliterate</command> command. This command is
	irreversible and expensive, so it is only available to those with
	admin access.</para>
	</sect1>

	<sect1 id="working-with-diffs">
	<title>Working with diffs</title>

	<para>Sometimes you might need to apply a diff from another source
	to a tree under <application>Perforce</application> control. If
	it is a large diff that affects lots of files, it might be
	inconvenient to manually run <command>p4 edit</command> on each
	file. There is a trick for making this easier. First, make sure
	that no files are open on your client and that your tree is synced
	and up to date. Then apply the diff using the normal tools, and
	coerce the permissions on the files if needed. Then run the
	following commands:</para>

	<screen>&prompt.user; <userinput>p4 diff -se ... \| xargs p4 edit</userinput>
	&prompt.user; <userinput>p4 diff -sd ... \| xargs p4 delete</userinput>
	&prompt.user; <userinput>find . -type f \| xargs p4 add</userinput></screen>

	<para>The first command tells <application>Perforce</application> to
	look for files that have changed, even if they are not open. The
	second command tells <application>Perforce</application> to look
	for files that no longer exist on the local machine but do exist
	on the server. The third command then attempts to add all of the
	files that it can find locally. This is a very brute-force
	method, but it works because <application>Perforce</application>
	will only add the files that it does not already know about. The
	result of running these commands will be a set of files that are
	opened for edit, removal, or add, as appropriate.</para>

	<para>Verify the active changelist with:</para>

	<screen>&prompt.user; <userinput>p4 changelist</userinput>
	&prompt.user; <userinput>p4 diff -du</userinput></screen>

	<para>and just do a <command>p4 submit</command> after that.</para>
	</sect1>

	<sect1 id="renaming-files">
	<title>Renaming files</title>

	<para><application>Perforce</application> does not have a built-in
	way of renaming files or moving them to a different part of the
	tree. Simply copying a file to the new location, doing a
	<command>p4 add</command> on it, and a <command>p4
	delete</command> on the old copy, works, but does not preserve
	change history of the file. This can make future integrations
	with parents and children very bumpy, in fact. A better method of
	dealing with this is to do a one-time, in-tree integration, like
	so:</para>

	<screen>&prompt.user; <userinput>p4 integrate -i <replaceable>oldfile</replaceable> <replaceable>newfile</replaceable></userinput>
	&prompt.user; <userinput>p4 resolve</userinput>
	&prompt.user; <userinput>p4 delete <replaceable>oldfile</replaceable></userinput>
	&prompt.user; <userinput>p4 submit</userinput></screen>

	<para>The integration will force <application>Perforce</application>
	to keep a record of the relationship between the old and new
	names, which will assist it in future integrations. The
	<option>-i</option> flag tells it that it is a
	<quote>baseless</quote> integration, meaning that there is no
	branch history available for it to use in the integration. That
	is perfect for an integration like this, but should not be used
	for normal branch-based integrations.</para>
	</sect1>

	<sect1 id="freebsd-cvs-and-p4">
	- <title>Interactions between &os; CVS and Perforce</title>
	+ <title>Interactions between &os; Subversion and Perforce</title>

	- <para>The &os; <application>Perforce</application> and CVS
	- repositories are completely separate. However, changes to CVS are
	+ <para>The &os; <application>Perforce</application> and <application>Subversion</application>
	+ repositories are completely separate. However, changes to Subversion are
	tracked at near-real-time in <application>Perforce</application>.
	- Every 2 minutes, the CVS server is polled for updates in the HEAD
	+ Every 2 minutes, the Subversion server is polled for updates in the HEAD
	branch, and those updates are committed to
	<application>Perforce</application> in the <filename
	class="directory">//depot/vendor/freebsd/...</filename> tree. This
	tree is then available for branching and integrating to derivative
	projects. Any project that directly modifies that &os; source
	code should have this tree as its branch parent (or grandparent,
	depending on the needs), and periodic integrations and syncs
	should be done so that your tree stays up to date and avoids
	conflicts with mainline development.</para>

	- <para>The bridge between CVS and <application>Perforce</application>
	- is one-way; changes to CVS will be reflected in
	+ <para>The bridge between Subversion and <application>Perforce</application>
	+ is one-way; changes to Subversion will be reflected in
	<application>Perforce</application>, but changes in Perforce will
	- not be reflected in CVS. On request, some parts of the
	+ not be reflected in Subversion. On request, some parts of the
	<application>Perforce</application> repo can be exported to
	<application>CVSup</application> and made available for
	distribution that way. Contact the &os;
	<application>Perforce</application> administrators if this is
	something that you are interested in.</para>
	</sect1>

	<sect1 id="offline-ops">
	<title>Offline Operation</title>

	<para>One weakness of <application>Perforce</application> is that it
	assumes that network access to the server is always available.
	Most state, history, and metadata is saved on the server, and
	there is no provision for replicating the server like there is
	with CVS/<application>CVSup</application>. It is possible to run
	a proxy server, but it only provides very limited utility for
	offline operation.</para>

	<para>The best way to work offline is to make sure that your client
	has no open files and is fully synced before going offline. Then
	when editing a file, manually change the permissions to
	read-write. When you get back online, run the commands listed in
	the <xref linkend="working-with-diffs"/> to automatically identify
	files that have been edited, added, and removed. It is quite
	common to be surprised by <application>Perforce</application>
	overwriting a locally changed file that was not opened for edit,
	so be extra vigilant with this.</para>
	</sect1>

	<sect1 id="soc">
	<title>Notes for Google Summer of Code</title>

	<para>Most &os; projects under the Google Summer of Code program
	are located on the &os; <application>Perforce</application> server
	under one of the following locations:</para>

	<itemizedlist>
	<listitem>
	<para><filename
	class="directory">//depot/projects/soc2005/<replaceable>project-name</replaceable>/...</filename></para>
	</listitem>
	<listitem>
	<para><filename
	class="directory">//depot/projects/soc2006/<replaceable>project-name</replaceable>/...</filename></para>
	</listitem>
	<listitem>
	<para><filename
	class="directory">//depot/projects/soc2007/<replaceable>project-name</replaceable>/...</filename></para>
	</listitem>
	<listitem>
	<para><filename
	class="directory">//depot/projects/soc2008/<replaceable>project-name</replaceable>/...</filename></para>
	</listitem>
	</itemizedlist>

	<para>The project mentor is responsible for choosing a suitable
	project name and getting the student going with
	<application>Perforce</application>.</para>

	<para>Access to the &os; <application>Perforce</application> server
	does not imply membership in the &os; CVS committer community,
	though we happily encourage all students to consider joining the
	project when the time is appropriate.</para>
	</sect1>
	</article>
	Index: projects/entities/en_US.ISO8859-1/articles/portbuild/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/portbuild/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/portbuild/article.xml (revision 41355)
	@@ -1,3148 +1,3212 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	]>

	<article lang='en'>
	<articleinfo>
	<title>Package Building Procedures</title>

	<authorgroup>
	<corpauthor>The &os; Ports Management Team</corpauthor>
	</authorgroup>

	<copyright>
	<year>2003</year>
	<year>2004</year>
	<year>2005</year>
	<year>2006</year>
	<year>2007</year>
	<year>2008</year>
	<year>2009</year>
	<year>2010</year>
	<year>2011</year>
	<year>2012</year>
	<year>2013</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>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>
	</articleinfo>

	<sect1 id="intro">
	<title>Introduction</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, the main cluster in use is at
	<ulink url="http://pointyhat.FreeBSD.org"></ulink>.</para>

	<para>This article documents the internal workings of the
	cluster.</para>

	<note>
	<para>Many of the details in this article will be of interest only to
	those on the <ulink url="&url.base;/portmgr/">Ports Management</ulink>
	team.</para>
	</note>

	<sect2 id="codebase">
	<title>The codebase</title>

	<para>Most of the package building magic occurs under the
	<filename>/a/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
	(e.g., amd64, arm, &i386;, ia64, powerpc, &sparc64;), and
	<replaceable>${branch}</replaceable> will be used
	to specify the build branch (e.g., 7, 7-exp, 8, 8-exp, 9, 9-exp, 10, 10-exp).
	The set of branches that <username>portmgr</username> currently
	supports is the same as those that the &os;
	<ulink url="http://www.freebsd.org/security/index.html#supported-branches">security team</ulink>
	supports.
	</para>

	<note>
	<para>FreeBSD no longer builds packages for branches 4, 5, or 6, nor
	for the alpha architecture.</para>
	</note>

	<para>The scripts that control all of this live in either
	<filename role="directory">/a/portbuild/scripts/</filename> or.
	<filename role="directory">/a/portbuild/admin/scripts/</filename>.
	These are the checked-out copies from the Subversion repository at
	<ulink url="http://svnweb.freebsd.org/base/projects/portbuild/">
	<filename role="directory">base/projects/portbuild/</filename>
	</ulink>.</para>

	<para>Typically, incremental builds are done that use previous
	packages as dependencies; this takes less time, and puts less
	load on the mirrors. Full builds are usually only done:</para>

	<itemizedlist>
	<listitem>
	<para>right after release time, for the
	<literal>-STABLE</literal> branches</para>
	</listitem>

	<listitem>
	<para>periodically to test changes to
	<literal>-CURRENT</literal></para>
	</listitem>

	<listitem>
	<para>for experimental (<literal>"exp-"</literal>) builds</para>
	</listitem>
	</itemizedlist>

	<para>Packages from experimental builds are not uploaded.</para>
	</sect2>

	<sect2 id="codebase-notes">
	<title>Historical notes on the codebase</title>

	<para>Until mid-2010, the scripts were completely specific to
	<hostid>pointyhat.FreeBSD.org</hostid> as the head (dispatch) node. During
	the summer of 2010, a significant rewrite was done in order to allow
	for other hosts to be head nodes. Among the changes were:</para>

	<itemizedlist>
	<listitem>
	<para>removal of the hard-coding of the string
	<literal>pointyhat</literal></para>
	</listitem>

	<listitem>
	<para>factoring out all configuration constants (which
	were previously scattered throughout the code) into configuration
	files (see <link linkend="new-head-node">below</link>)</para>
	</listitem>

	<listitem>
	<para>appending the hostname to the directories
	specified by <literal>buildid</literal> (this will allow
	directories to be unambigious when copied between machines.)</para>
	</listitem>

	<listitem>
	<para>making the scripts more robust in terms of setting
	up directories and symlinks</para>
	</listitem>

	<listitem>
	<para>where necessary, changing certain script invocations
	to make all the above easier</para>
	</listitem>
	</itemizedlist>

	<note>
	<para>Also during this process, the codebase was migrated to the
	<ulink url="http://svnweb.freebsd.org/base/projects/portbuild/scripts/">
	Subversion repository</ulink>. For reference, the previous version
	may still be
	<ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Tools/portbuild/scripts/Attic/">
	found in CVS</ulink>.</para>
	</note>
	</sect2>

	<sect2 id="pointyhat-privsep">
	<title>Notes on privilege separation</title>

	<para>As of January 2013, a rewrite is in progress to further separate
	privileges. The following concepts are introduced:</para>

	<itemizedlist>
	<listitem>
	<para>Server-side user <username>portbuild</username> assumes all
	responsiblity for operations involving builds and communicating
	with the clients. This user no longer has access to
	<application>sudo</application>.</para>
	</listitem>

	<listitem>
	<para>Server-side user <username>srcbuild</username> is created
	and given responsiblity for operations involving both VCS
	operations and anything involving src builds for the clients.
	This user does not have access to
	<application>sudo</application>.</para>
	</listitem>

	<listitem>
	<para>The server-side
	<literal>ports-</literal><replaceable>arch</replaceable>
	users go away.</para>
	</listitem>

	<listitem>
	<para>None of the above server-side users have
	<application>ssh</application> keys. Individual
	<literal>portmgr</literal> will accomplish all those
	tasks using <application>ksu</application>. (This is
	still work-in-progress.)</para>
	</listitem>

	<listitem>
	<para>The only client-side user is also named
	<username>portbuild</username> and still has access to
	<application>sudo</application> for the purpose of managing
	jails.</para>
	</listitem>
	</itemizedlist>
	</sect2>
	</sect1>

	<sect1 id="management">
	<title>Build Client Management</title>

	<para>You may set up clients to either netboot from the master
	(<replaceable>connected</replaceable> nodes)
	or have them either self-hosted or netboot from some other
	<literal>pxe</literal> host
	(<replaceable>disconnected</replaceable> nodes).
	In all cases they set themselves
	up at boot-time to prepare to build packages.</para>

	<para>The cluster master <command>rsync</command>s the
	interesting data (ports and src trees, bindist tarballs,
	scripts, etc.) to disconnected nodes during the node-setup
	phase. Then, the disconnected portbuild directory is
	nullfs-mounted for jail builds.</para>

	<para>The
	<username>portbuild</username>
	user can &man.ssh.1; to the client nodes to monitor them.
	Use <command>sudo</command> and check the
	<hostid>portbuild.<replaceable>hostname</replaceable>.conf</hostid>
	for the user and access details.</para>

	<para>The <command>scripts/allgohans</command> script can
	be used to run a command on all of the
	<replaceable>${arch}</replaceable> clients.</para>
	</sect1>

	<sect1 id="setup">
	<title>Jail Build Environment Setup</title>

	<para>Package builds are performed by the clients in a
	<literal>jail</literal> populated by the
	<filename>portbuild</filename> script using the
	<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/bindist.tar</filename>
	file.</para>

	<para>On the server, use the
	<command>makeworld</command> command to build a world from the
	<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/src/</filename>
	tree and install it into
	<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/bindist.tar</filename>.
	The tree will
	be updated first unless <literal>-novcs</literal> is
	specified.</para>

	<screen>&prompt.root; <userinput>/a/portbuild/admin/scripts/makeworld <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> [-novcs]</userinput></screen>

	<para>Similiarly on the server, the
	<filename>bindist.tar</filename> tarball is created from the
	previously installed world by the <command>mkbindist</command>
	script.</para>

	<screen>&prompt.root; <userinput>/a/portbuild/admin/scripts/mkbindist <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable></userinput></screen>

	<para>The per-machine tarballs are located on the server in
	<filename><replaceable>${arch}</replaceable>/clients</filename>.</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>

	<para>For both commands above, if
	<replaceable>${buildid}</replaceable> is
	<literal>latest</literal>, it may be omitted.</para>

	<note>
	<para>Currently the above two scripts must be run as
	<username>root</username>; otherwise, the install scripts
	lack sufficient permissions. This is undesirable for
	security reasons. Work is in progress in -HEAD to allow
	users to do installations; once that is committed, the
	intention is to use that and run these two commands as
	<username>srcbuild</username>.</para>
	</note>
	</sect1>

	<sect1 id="customizing">
	<title>Customizing Your Build</title>

	<para>You can customize your build by providing local versions of
	<filename>make.conf</filename> and/or
	<filename>src.conf</filename>,
	named
	<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/make.conf.server</filename>
	and
	<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/src.conf.server</filename>,
	respectively. These will be used in lieu of the default-named
	files on the server side.</para>

	<para>Similarly, if you wish to also affect the <emphasis>client-side</emphasis>
	<filename>make.conf</filename>, you may use
	<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/make.conf.client</filename>.
	</para>

	<note>
	<para>Due to the fact that individual clients may each have
	their own per-host <filename>make.conf</filename>, the
	contents of
	<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/make.conf.client</filename>
	will be <emphasis>appended</emphasis> to that
	<filename>make.conf</filename>, not supplant it, as is done
	for
	<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/make.conf.server</filename>.</para>
	</note>

	<note>
	<para>There is no similar functionality for
	<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/src.conf.client</filename>
	(what effect would it have?).</para>
	</note>

	<example>
	<title>Sample
	<filename>make.conf.<replaceable>target</replaceable></filename>
	to test new default <application>ruby</application>
	version</title>

	<para>(For this case, the contents are identical for both server
	and client.)</para>

	<programlisting>RUBY_DEFAULT_VER= 1.9</programlisting>
	</example>

	<example>
	<title>Sample
	<filename>make.conf.<replaceable>target</replaceable></filename>
	for <application>clang</application> builds</title>

	<para>(For this case, the contents are also identical for both
	server and client.)</para>

	<programlisting>.if !defined(CC) \|\| ${CC} == "cc"
	CC=clang
	.endif
	.if !defined(CXX) \|\| ${CXX} == "c++"
	CXX=clang++
	.endif
	.if !defined(CPP) \|\| ${CPP} == "cpp"
	CPP=clang-cpp
	.endif
	# Do not die on warnings
	NO_WERROR=
	WERROR=</programlisting>
	</example>

	<example>
	<title>Sample <filename>make.conf.server</filename> for
	<application>pkgng</application></title>

	<programlisting>WITH_PKGNG=yes
	PKG_BIN=/usr/local/sbin/pkg</programlisting>
	</example>

	<example>
	<title>Sample <filename>make.conf.client</filename> for
	<application>pkgng</application></title>

	<programlisting>WITH_PKGNG=yes</programlisting>
	</example>

	<example>
	<title>Sample <filename>src.conf.server</filename>
	to test new <application>sort</application> codebase</title>

	<programlisting>WITH_BSD_SORT=yes</programlisting>
	</example>
	</sect1>

	<sect1 id="starting">
	<title>Starting the Build</title>

	<para>Separate builds for various combinations of architecture and branch
	are supported. All data private to a build (ports tree, src tree,
	packages, distfiles, log files, bindist, Makefile, etc) are located under the
	<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/</filename>
	directory.
	The most recently created build can be alternatively referenced using buildid
	<literal>latest</literal>, and the one before using
	<literal>previous</literal>.</para>

	<para>New builds are cloned from the <literal>latest</literal>, which is
	fast since it uses ZFS.</para>

	<sect2 id="build-dopackages">
	<title><command>dopackages</command> scripts</title>

	<para>The <filename>scripts/dopackages.wrapper</filename> script
	is used to perform the builds.</para>

	<screen>&prompt.root; <userinput>dopackages.wrapper <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> <option>[-options]</option></userinput></screen>

	<para>Most often, you will be using <literal>latest</literal> for
	the value of <replaceable>buildid</replaceable>.</para>

	<para><literal>[-options]</literal> may be zero or more of the
	following:</para>

	<itemizedlist>
	<listitem>
	<para><option>-keep</option> - Do not delete this build in the
	future, when it would be normally deleted as part of the
	<literal>latest</literal> - <literal>previous</literal> cycle.
	Do not forget to clean it up manually when you no longer need it.</para>
	</listitem>

	<listitem>
	<para><option>-nofinish</option> - 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. If you use this option, do not forget to cleanup
	the clients when you do not need the build any more.</para>
	</listitem>

	<listitem>
	<para><option>-finish</option> - Perform
	post-processing only.</para>
	</listitem>

	<listitem>
	<para><option>-nocleanup</option> - By default, when the
	<option>-finish</option> stage of the build is complete, the build
	data will be deleted from the clients. This option will prevent
	that.</para>
	</listitem>

	<listitem>
	<para><option>-restart</option> - 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><option>-continue</option> - Restart an interrupted
	(or non-<literal>finish</literal>ed) build. Will not
	rebuild ports that failed on the previous build.</para>
	</listitem>

	<listitem>
	<para><option>-incremental</option> - Compare the
	interesting fields of the new
	<filename>INDEX</filename> 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 every time.</para>
	</listitem>

	<listitem>
	<para><option>-cdrom</option> - This package build is
	intended to end up on a CD-ROM, so
	<makevar>NO_CDROM</makevar> packages and distfiles
	should be deleted in post-processing.</para>
	</listitem>

	<listitem>
	<para><option>-nobuild</option> - Perform all
	the preprocessing steps, but do not actually do
	the package build.</para>
	</listitem>

	<listitem>
	<para><option>-noindex</option> - Do not rebuild
	<filename>INDEX</filename> during preprocessing.</para>
	</listitem>

	<listitem>
	<para><option>-noduds</option> - Do not rebuild the
	<filename>duds</filename> file (ports that are never
	built, e.g., those marked <literal>IGNORE</literal>,
	<makevar>NO_PACKAGE</makevar>, etc.) during
	preprocessing.</para>
	</listitem>

	<listitem>
	<para><option>-nochecksubdirs</option> - Do not check the
	<makevar>SUBDIRS</makevar> for ports that are not connected
	to the build.</para>
	</listitem>

	<listitem>
	<para><option>-trybroken</option> - Try to build
	<makevar>BROKEN</makevar> ports (off by default
	because the amd64/&i386; clusters are 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 <makevar>BROKEN</makevar> ports).</para>

	<note>
	<para>With <option>-trybroken</option>, you probably
	also want to use <option>-fetch-original</option>
	and
	<option>-unlimited-errors</option>.</para>
	</note>
	</listitem>

	<listitem>
	<para><option>-nosrc</option> - Do not update the
	<filename>src</filename> tree from the ZFS snapshot, keep the tree from
	previous build instead.</para>
	</listitem>

	<listitem>
	<para><option>-srcvcs</option> - Do not update the
	<filename>src</filename> tree from the ZFS snapshot, update it with
	a fresh checkout instead.</para>
	</listitem>

	<listitem>
	<para><option>-noports</option> - Do not update the
	<filename>ports</filename> tree from the ZFS snapshot, keep the tree from
	previous build instead.</para>
	</listitem>

	<listitem>
	<para><option>-portsvcs</option> - Do not update the
	<filename>ports</filename> tree from the ZFS snapshot, update it with
	a fresh checkout instead.</para>
	</listitem>

	<listitem>
	<para><option>-norestr</option> - Do not attempt to build
	<makevar>RESTRICTED</makevar> ports.</para>
	</listitem>

	<listitem>
	<para><option>-noplistcheck</option> - Do not make it fatal for
	ports to leave behind files after deinstallation.</para>
	</listitem>

	<listitem>
	<para><option>-nodistfiles</option> - Do not collect distfiles
	that pass <command>make checksum</command> for later
	uploading to <hostid>ftp-master</hostid>.</para>
	</listitem>

	<listitem>
	<para><option>-fetch-original</option> - Fetch the
	distfile from the original <makevar>MASTER_SITES</makevar>
	rather than any cache such as on <hostid>ftp-master</hostid>.</para>
	</listitem>

	<listitem>
	<para><option>-unlimited-errors</option>
	- defeat the "qmanager threshhold" check for runaway
	builds. You want this primarily when doing a
	<option>-restart</option> of a build that you expect to mostly
	fail, or perhaps a <option>-trybroken</option> run. By default,
	the threshhold check is done.</para>
	</listitem>
	</itemizedlist>

	<para>Unless you specify <option>-restart</option>,
	<option>-continue</option>, or <option>-finish</option>,
	the symlinks for the existing builds will be rotated. i.e,
	the existing symlink for <filename>previous</filename> will
	be deleted; the most recent build will have its symlink changed
	to <filename>previous/</filename>; and a new build will be
	created and symlinked into <filename>latest/</filename>.</para>

	<para>If the last build finished cleanly you do not need to delete
	anything. If it was interrupted, or you selected
	<option>-nocleanup</option>, you need to clean up clients by running</para>

	<screen>&prompt.user; <userinput>build cleanup <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> -full</userinput></screen>

	<para>When a new build is created, the directories <filename>errors/</filename>,
	<filename>logs/</filename>, <filename>packages/</filename>, and so
	forth, are cleaned by the scripts. If you are short of space,
	you can also clean out <filename>ports/distfiles/</filename>.
	Leave the <filename>latest/</filename> directory alone; it is
	a symlink for the webserver.</para>

	<note>
	<para><literal>dosetupnodes</literal> is supposed to be run from
	the <literal>dopackages</literal> script in the
	<option>-restart</option> case, but it can be a good idea to
	run it by hand and then verify that the clients all have the
	expected job load. Sometimes,
	<filename>dosetupnode</filename> cannot clean up a build and you
	need to do it by hand. (This is a bug.)</para>
	</note>

	<para>Make sure the <replaceable>${arch}</replaceable> build
	is run as the <username>portbuild</username> 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 a 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 an -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>/journal</filename>:</para>

	<screen>don't know how to make dns-all(continuing)</screen>

	<para>To correct this problem, simply comment out or remove
	the <makevar>SUBDIR</makevar> entries that point to empty
	subdirectories. After doing this, you can restart the build
	by running the proper <command>dopackages</command> command
	with the <option>-restart</option> option.</para>

	<note>
	<para>This problem also appears if you create a new category
	<filename>Makefile</filename> with no <makevar>SUBDIR</makevar>s
	in it. This is probably a bug.</para>
	</note>

	<example>
	<title>Update the i386-7 tree and do a complete build</title>

	- <screen>&prompt.user; <userinput>dopackages.wrapper i386 7 -nosrc -norestr -nofinish</userinput></screen>
	+ <screen>&prompt.user; <userinput>dopackages.wrapper i386 8 latest -nosrc -norestr -nofinish</userinput></screen>
	</example>

	<example>
	<title>Restart an interrupted amd64-8 build without updating</title>

	- <screen>&prompt.user; <userinput>dopackages.wrapper amd64 8 -nosrc -noports -norestr -continue -noindex -noduds -nofinish</userinput></screen>
	+ <screen>&prompt.user; <userinput>dopackages.wrapper amd64 8 latest -nosrc -noports -norestr -continue -noindex -noduds -nofinish</userinput></screen>
	</example>

	<example>
	- <title>Post-process a completed sparc64-7 tree</title>
	+ <title>Post-process a completed sparc64-8 tree</title>

	- <screen>&prompt.user; <userinput>dopackages.wrapper sparc64 7 -finish</userinput></screen>
	+ <screen>&prompt.user; <userinput>dopackages.wrapper sparc64 8 -finish</userinput></screen>
	</example>

	<para>Hint: it is usually best to run the <command>dopackages</command>
	command inside of <command>screen(1)</command>.</para>
	</sect2>

	<sect2 id="build-command">
	<title><command>build</command> command</title>

	<para>You may need to manipulate the build data before starting it,
	especially for experimental builds. This is done with
	the <command>build</command> command. Here are the useful
	options for creation:</para>

	<itemizedlist>
	<listitem>
	<para><literal>build create <replaceable>arch</replaceable>
	<replaceable>branch</replaceable>
	[<replaceable>newid</replaceable>]</literal> - Creates
	<replaceable>newid</replaceable> (or a datestamp if not specified).
	Only needed when bringing up a new branch or a new architecture.</para>
	</listitem>

	<listitem>
	<para><literal>build clone <replaceable>arch</replaceable>
	<replaceable>branch</replaceable> <replaceable>oldid</replaceable>
	[<replaceable>newid</replaceable>]</literal> - Clones
	<replaceable>oldid</replaceable> to
	<replaceable>newid</replaceable> (or a datestamp if not specified).</para>
	</listitem>

	<listitem>
	<para><literal>build srcupdate <replaceable>arch</replaceable>
	<replaceable>branch</replaceable>
	<replaceable>buildid</replaceable></literal> - Replaces the src
	tree with a new ZFS snapshot. Do not forget to use
	<literal>-nosrc</literal> flag to <command>dopackages</command>
	later!</para>
	</listitem>

	<listitem>
	<para><literal>build portsupdate <replaceable>arch</replaceable>
	<replaceable>branch</replaceable>
	<replaceable>buildid</replaceable></literal> - Replaces the ports
	tree with a new ZFS snapshot. Do not forget to use
	<literal>-noports</literal> flag to <command>dopackages</command>
	later!</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2 id="build-one">
	<title>Building a single package</title>

	<para>Sometimes there is a need to rebuild a single package from the
	package set. This can be accomplished with the following
	invocation:</para>

	<screen>&prompt.root; <command><replaceable>path</replaceable>/qmanager/packagebuild <replaceable>amd64</replaceable> <replaceable>7-exp</replaceable> <replaceable>20080904212103</replaceable> <replaceable>aclock-0.2.3_2.tbz</replaceable></command></screen>
	</sect2>
	</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>An update of the current <filename>ports</filename>
	tree from the ZFS snapshot<footnote id="footnote-status1">
	<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></footnote></para>
	</listitem>

	<listitem>
	<para>An update of the running branch's
	<filename>src</filename> tree from the ZFS snapshot<footnoteref linkend='footnote-status1'></footnoteref></para>
	</listitem>

	<listitem>
	<para>Checks which ports do not have a
	<makevar>SUBDIR</makevar> entry in their respective
	category's <filename>Makefile</filename><footnoteref linkend='footnote-status1'></footnoteref></para>
	</listitem>

	<listitem>
	<para>Creates the <filename>duds</filename> file, which
	is a list of ports not to build<footnoteref linkend='footnote-status1'></footnoteref><footnote id="footnote-buildstop">
	<para>If any of these steps fail, the build will stop
	cold in its tracks.</para></footnote></para>
	</listitem>

	<listitem>
	<para>Generates a fresh <filename>INDEX</filename>
	file<footnoteref linkend='footnote-status1'></footnoteref><footnoteref linkend='footnote-buildstop'></footnoteref></para>
	</listitem>

	<listitem>
	<para>Sets up the nodes that will be used in the
	build<footnoteref linkend='footnote-status1'></footnoteref><footnoteref linkend='footnote-buildstop'></footnoteref></para>
	</listitem>

	<listitem>
	<para>Builds a list of restricted ports<footnoteref linkend='footnote-status1'></footnoteref><footnoteref linkend='footnote-buildstop'></footnoteref></para>
	</listitem>

	<listitem>
	<para>Builds packages (phase 1)<footnote id="footnote-status2"><para>Status of these steps can be found in
	<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/journal</filename>.
	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></footnote></para>
	</listitem>

	<listitem>
	<para>Performs another node setup<footnoteref linkend='footnote-status1'></footnoteref></para>
	</listitem>

	<listitem>
	<para>Builds packages (phase 2)<footnoteref linkend='footnote-status2'></footnoteref></para>
	</listitem>
	</orderedlist>
	</sect1>

	<sect1 id="build-maintenance">
	<title>Build Maintenance</title>

	<para>There are several cases where you will need to manually clean
	up a build:</para>

	<orderedlist>
	<listitem>
	<para>You have manually interrupted it.</para>
	</listitem>

	<listitem>
	<para>The head node has been rebooted while
	a build was running.</para>
	</listitem>

	<listitem>
	<para><filename>qmanager</filename> has crashed and
	has been restarted.</para>
	</listitem>
	</orderedlist>

	<sect2 id="interrupting">
	<title>Interrupting a Build</title>

	<para>Manually interrupting a build is a bit messy. First you need to
	identify the tty in which it's running (either record the output
	of &man.tty.1; when you start the build, or use <command>ps x</command>
	to identify it. You need to make sure that nothing else important
	is running in this tty, e.g., <userinput>ps -t p1</userinput> or whatever.
	If there is not, you can just kill off the whole term easily with
	<userinput>pkill -t pts/1</userinput>; otherwise issue a
	<userinput>kill -HUP</userinput> in there by, for example,
	<userinput>ps -t pts/1 -o pid= \| xargs kill -HUP</userinput>. Replace
	<replaceable>p1</replaceable> by whatever the tty is, of course.</para>

	<para>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).</para>

	<para>If you do not kill &man.make.1;, then it will spawn more jobs.
	If you do not kill <command>dopackages</command>, then it will restart
	the entire build. If you do not kill the <command>pdispatch</command>
	processes, they'll keep going (or respawn) until they've built their
	package.</para>
	</sect2>

	<sect2 id="cleanup">
	<title>Cleaning up a Build</title>

	<para>To free up resources, you will need to clean up client machines by
	running <command>build cleanup</command> command. For example:</para>

	<screen>&prompt.user; <userinput>/a/portbuild/scripts/build cleanup i386 8-exp 20080714120411 -full</userinput></screen>

	<para>If you forget to do this, then the old build
	<literal>jail</literal>s will not be cleaned up for 24 hours, and no
	new jobs will be dispatched in their place since
	<hostid>pointyhat</hostid> thinks the job slot is still occupied.</para>

	<para>To check, <userinput>cat ~/loads/*</userinput> to display the
	status of client machines; the first column is the number of jobs
	it thinks is running, and this should be roughly concordant
	with the load average. <literal>loads</literal> is refreshed
	every 2 minutes. If you do <userinput>ps x \| grep pdispatch</userinput>
	and it is less than the number of jobs that <literal>loads</literal>
	thinks are in use, you are in trouble.</para>

	<note>
	<para>The following notes about mounting only apply to
	<literal>connected</literal> nodes.</para>
	</note>

	<para>You may have problem with the <command>umount</command>
	commands hanging. If so, you are going to have to use the
	<command>allgohans</command> script to run an &man.ssh.1;
	command across all clients for that buildenv. For example:</para>

	<screen>&prompt.user; ssh gohan24 df</screen>

	<para>will get you a df, and</para>

	<screen>&prompt.user; allgohans "umount -f pointyhat.freebsd.org:/var/portbuild/i386/8-exp/ports"
	&prompt.user; allgohans "umount -f pointyhat.freebsd.org:/var/portbuild/i386/8-exp/src"</screen>

	<para>are supposed to get rid of the hanging mounts. You will have to
	keep doing them since there can be multiple mounts.</para>

	<note>
	<para>Ignore the following:</para>

	<screen>umount: pointyhat.freebsd.org:/var/portbuild/i386/8-exp/ports: statfs: No such file or directory
	umount: pointyhat.freebsd.org:/var/portbuild/i386/8-exp/ports: unknown file system
	umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed!
	/x/tmp/8-exp/chroot/53837/compat/linux/proc: not a file system root directory</screen>

	<para>The former two mean that the client did not have those mounted;
	the latter two are a bug.</para>

	<para>You may also see messages about <literal>procfs</literal>.</para>
	</note>

	<note>
	<para>The above is the end of the notes that apply only to
	<literal>connected</literal> nodes.</para>
	</note>

	<para>After you have done all the above, remove the
	<filename><replaceable>${arch}</replaceable>/lock</filename>
	file before trying to restart the build. If you do not,
	<filename>dopackages</filename> will simply exit.</para>

	<para>If you have to do a ports tree update before
	restarting, you may have to rebuild either <filename>duds</filename>,
	<filename>INDEX</filename>, or both.</para>
	</sect2>

	<sect2 id="build-command-2">
	<title>Maintaining builds with the <command>build</command>
	command</title>

	<para>Here are the rest of the options for the <command>build</command>
	command:</para>

	<itemizedlist>
	<listitem>
	<para><literal>build destroy <replaceable>arch</replaceable>
	<replaceable>branch</replaceable></literal> - Destroy the
	build id.</para>
	</listitem>

	<listitem>
	<para><literal>build list <replaceable>arch</replaceable>
	<replaceable>branch</replaceable></literal> - Shows the current set
	of build ids.</para>
	</listitem>
	</itemizedlist>
	</sect2>
	</sect1>

	<sect1 id="monitoring">
	<title>Monitoring the Build</title>

	<para>You can use <command>qclient</command> command to monitor the status
	of build nodes, and to list the currently scheduled jobs:</para>

	<screen>&prompt.user; <userinput>python <replaceable>path</replaceable>/qmanager/qclient jobs</userinput>
	&prompt.user; <userinput>python <replaceable>path</replaceable>/qmanager/qclient status</userinput></screen>

	<para>The
	<userinput>scripts/stats <replaceable>${branch}</replaceable></userinput>
	command shows the number of packages already built.</para>

	<para>Running <userinput>cat /a/portbuild//loads/</userinput>
	shows the client loads and number of concurrent builds in
	progress. The files that have been recently updated are the clients
	that are online; the others are the offline clients.</para>

	<note>
	<para>The <command>pdispatch</command> command does the dispatching
	of work onto the client, and post-processing.
	<command>ptimeout.host</command> is a watchdog that kills a build
	after timeouts. So, having 50 <command>pdispatch</command>
	processes but only 4 &man.ssh.1; processes means 46
	<command>pdispatch</command>es are idle, waiting to get an
	idle node.</para>
	</note>

	<para>Running <userinput>tail -f <replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/build.log</userinput>
	shows the overall build progress.</para>

	<para>If a port build is failing, and it is not immediately obvious
	from the log as to why, you can preserve the
	<makevar>WRKDIR</makevar> 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 <makevar>WRKDIR</makevar>
	to
	<filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/wrkdirs/</filename>.</para>

	<para>If you find that the system is looping trying to build the
	same package over and over again, you may be able to fix the
	problem by rebuilding the offending package by hand.</para>

	<para>If all the builds start failing with complaints that they
	cannot load the dependent packages, check to see that
	<application>httpd</application> is still running, and restart
	it if not.</para>

	<para>Keep an eye on &man.df.1; output. If the
	<filename>/a/portbuild</filename> file system becomes full
	then <trademark>Bad Things</trademark> happen.</para>

	<para>The status of all current builds is generated periodically
	into the <filename>packagestats.html</filename> file, e.g.,
	<ulink url="http://pointyhat.FreeBSD.org/errorlogs/packagestats.html"></ulink>.
	For each <literal>buildenv</literal>, the following is displayed:</para>

	<itemizedlist>
	<listitem>
	<para><literal>updated</literal> is the contents of
	<filename>.updated</filename>. This is why we recommend that you
	update <filename>.updated</filename> for <literal>-exp</literal>
	runs (see below).</para>
	</listitem>

	<listitem>
	<para>date of <literal>latest log</literal></para>
	</listitem>

	<listitem>
	<para>number of lines in <filename>INDEX</filename></para>
	</listitem>

	<listitem>
	<para>the number of current <literal>build logs</literal></para>
	</listitem>

	<listitem>
	<para>the number of completed <literal>packages</literal></para>
	</listitem>

	<listitem>
	<para>the number of <literal>errors</literal></para>
	</listitem>

	<listitem>
	<para>the number of duds (shown as <literal>skipped</literal>)</para>
	</listitem>

	<listitem>
	<para><literal>missing</literal> shows the difference between
	<filename>INDEX</filename> and the other columns. If you have
	restarted a run after a ports tree update, there
	will likely be duplicates in the packages and error columns,
	and this column will be meaningless. (The script is naive).</para>
	</listitem>

	<listitem>
	<para><literal>running</literal> and <literal>completed</literal>
	are guesses based on a &man.grep.1; of <filename>build.log</filename>.
	</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="errors">
	<title>Dealing With Build Errors</title>

	<para>The easiest way to track build failures is to receive
	the emailed logs and sort them to a folder, so you can maintain a
	running list of current failures and detect new ones easily.
	To do this, add an email address to
	<filename><replaceable>${branch}</replaceable>/portbuild.conf</filename>.
	You can easily bounce the new ones to maintainers.</para>

	<para>After a port appears broken on every build combination
	multiple times, it is time to mark it <makevar>BROKEN</makevar>.
	Two weeks' notification for the maintainers seems fair.</para>

	<note>
	<para>To avoid build errors with ports that need to be manually
	fetched, put the distfiles into
	<filename>~ftp/pub/FreeBSD/distfiles</filename>.
	Access restrictions are in place to make sure that only the
	build clients can access this directory.</para>
	</note>
	</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 <filename>src</filename> trees to the release tag and use
	<option>-novcs</option> and
	<option>-noportsvcs</option>.</para>

	<para>To build package sets intended for use on a CD-ROM,
	use the <option>-cdrom</option> option to
	<command>dopackages</command>.</para>

	<para>If the disk space is not available on the cluster, use
	<option>-nodistfiles</option> to avoid collecting distfiles.</para>

	<para>After the initial build completes, restart the build
	with
	<option>-restart -fetch-original</option>
	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>You should use that output to periodically clean 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>

	<note>
	<para>For FreeBSD.org as of 2013, the instructions
	about uploading to <hostid>ftp-master</hostid> are obsolete.
	In the future, <hostid>ftp-master</hostid> will pull
	from <hostid>pointyhat</hostid>, using a mechanism yet
	to be implemented. However, the instructions about
	<makevar>RESTRICTED</makevar> and <makevar>NO_CDROM</makevar>
	must still be <emphasis>carefully</emphasis> followed.</para>
	</note>

	<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 <option>-nofinish</option>, then make sure to
	follow up with
	<command>dopackages -finish</command> to post-process the
	packages (removes <makevar>RESTRICTED</makevar> and
	<makevar>NO_CDROM</makevar> 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
	<makevar>RESTRICTED</makevar> and <makevar>NO_CDROM</makevar>
	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>The package subdirectories are named by whether they are for
	<filename>release</filename>, <filename>stable</filename>, or
	<filename>current</filename>. Examples:</para>

	<itemizedlist>
	<listitem>
	<para><filename>packages-7.2-release</filename></para>
	</listitem>

	<listitem>
	<para><filename>packages-7-stable</filename></para>
	</listitem>

	<listitem>
	<para><filename>packages-8-stable</filename></para>
	</listitem>

	<listitem>
	<para><filename>packages-9-stable</filename></para>
	</listitem>

	<listitem>
	<para><filename>packages-10-current</filename></para>
	</listitem>
	</itemizedlist>

	<note>
	<para>Some of the directories on
	<hostid>ftp-master</hostid> are, in fact, symlinks. Examples:</para>

	<itemizedlist>
	<listitem>
	<para><filename>packages-stable</filename></para>
	</listitem>

	<listitem>
	<para><filename>packages-current</filename></para>
	</listitem>
	</itemizedlist>

	<para> 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>If you are doing a completely new package set (e.g., for
	a new release), copy packages to the staging area on
	<hostid>ftp-master</hostid> with something like the following:</para>

	<screen>&prompt.root; <userinput>cd /a/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>${subdir}</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. (<filename>w/</filename> is
	merely a shortcut.)</para>

	<para>For incremental builds, packages should be uploaded
	using <command>rsync</command> so we do not put too much
	strain on the mirrors.</para>

	<para><emphasis>ALWAYS</emphasis> use <option>-n</option>
	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 <option>-n</option>
	option.</para>

	<para>Example <command>rsync</command> command for incremental
	package upload:</para>

	<screen>&prompt.root; <userinput>rsync -n -r -v -l -t -p --delete packages/ portmgr@ftp-master:w/ports/<replaceable>${arch}</replaceable>/<replaceable>${subdir}</replaceable>/ \| tee log</userinput></screen>

	<para>Distfiles should be transferred with the
	<command>cpdistfiles</command> script:</para>

	<screen>&prompt.root; <userinput>/a/portbuild/scripts/cpdistfiles <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> [-yesreally] \| tee log2</userinput></screen>

	<para>Doing it by hand is deprecated.</para>
	</sect1>

	<sect1 id="expbuilds">
	<title>Experimental Patches Builds</title>

	<note>
	<para>Most of the information in this section is obsolete
	as of 2013 and needs to be rewritten.</para>
	</note>

	<para>Experimental patches builds are run from time to time to
	new features or bugfixes to the ports infrastructure (i.e.
	<filename>bsd.port.mk</filename>), or to test large sweeping
	upgrades. At any given time there may be several simultaneous
	experimental patches branches, such as
	<literal>8-exp</literal> on the amd64
	architecture.</para>

	<para>In general, an experimental patches build is run the same
	way as any other build, except that you should first update the
	ports tree to the latest version and then apply your patches.
	To do the former, you can use the following:</para>

	<note>
	<para>The following example is obsolete</para>
	</note>

	<screen>&prompt.user; <userinput>cvs -R update -dP > update.out</userinput>
	&prompt.user; <userinput>date > .updated</userinput></screen>

	<para>This will most closely simulate what the <literal>dopackages</literal>
	script does. (While <filename>.updated</filename> is merely
	informative, it can be a help.)</para>

	<para>You will need to edit <filename>update.out</filename> to look
	for lines beginning with <literal>^M</literal>, <literal>^C</literal>,
	or <literal>^?</literal> and then deal with them.</para>

	<para>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, to make sure you are committing exactly what you
	tested.</para>

	<para>Since the machine is shared, someone else may delete your
	changes by mistake, so keep a copy of them in e.g., your home
	directory on <hostid>freefall</hostid>. Do not use
	<filename>tmp/</filename>; since <hostid>pointyhat</hostid>
	itself runs some version of <literal>-CURRENT</literal>, you
	can expect reboots (if nothing else, for updates).</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>8</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>

	<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>8</literal>
	branch is the control branch, and the <literal>8-exp</literal>
	branch is the experimental patches branch):</para>

	<screen>&prompt.user; <userinput>cd /a/portbuild/i386/8-exp/errors</userinput>
	&prompt.user; <userinput>find . -name \.log\ \| sort > /tmp/8-exp-errs</userinput>
	&prompt.user; <userinput>cd /a/portbuild/i386/8/errors</userinput>
	&prompt.user; <userinput>find . -name \.log\ \| sort > /tmp/8-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 <userinput>sort \| sed
	's,\.bz2,,g'</userinput> instead.</para>
	</note>

	<screen>&prompt.user; <userinput>comm -3 /tmp/8-errs /tmp/8-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 id="broken-by-exp-patches" xreflabel="broken by experimental patches">
	<para>Port was broken by the experimental patches</para>
	</listitem>

	<listitem id="broken-by-upgrading" xreflabel="broken by upgrading">
	<para>Port was upgraded since the control build and has become
	broken</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 <xref
	linkend="broken-by-exp-patches"></xref> and <xref
	linkend="broken-by-upgrading"></xref> above, you can do a
	rebuild of the affected packages under the control
	branch:</para>

	<screen>&prompt.user; <userinput>cd /a/portbuild/i386/8/ports</userinput></screen>

	<note>
	<para>The following example is obsolete</para>
	</note>

	<note>
	<para>Be sure to <userinput>cvs update</userinput> this tree to the same date as
	the experimental patches tree.</para>
	</note>

	<!-- XXX MCL fix -->
	<para>The following command will set up the control branch for
	the partial build:</para>

	- <screen>&prompt.user; <userinput>/a/portbuild/scripts/dopackages.wrapper i386 8 -noportsvcs -nobuild -novcs -nofinish</userinput></screen>
	+ <screen>&prompt.user; <userinput>/a/portbuild/scripts/dopackages.wrapper i386 8 latest -noportsvcs -nobuild -novcs -nofinish</userinput></screen>

	<!-- XXX MCL obsolete -->
	<para>The builds must be performed from the
	<filename>packages/All</filename> 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 /a/portbuild/i386/8/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>/a/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 <makevar>PKGSUFFIX</makevar>
	(i.e., <filename>.tgz</filename> or <filename>.tbz</filename>) is optional.</para>
	</note>

	<para>This will build only those packages listed as well as all
	of their dependencies.</para>

	<para>You can check the progress of this
	partial build the same way you would a regular build.</para>

	<para>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>

	<sect1 id="new-node">
	<title>How to configure a new package building node</title>

	<para>Before following these steps, please coordinate with
	<literal>portmgr</literal>.</para>

	<sect2 id="node-requirements">
	<title>Node requirements</title>

	<note>
	<para>This section is only of interest when considering
	tier-2 architectures.</para>
	</note>

	<para>Here are the requirement for
	what a node needs to be generally useful.</para>

	<itemizedlist>
	<listitem>
	<para>CPU capacity: anything less than 500MHz is generally
	not useful for package building.</para>

	<note>
	<para>We are able to adjust the number of jobs
	dispatched to each machine, and we generally tune
	the number to use 100% of CPU.</para>
	</note>
	</listitem>

	<listitem>
	<para>RAM: Less than 2G is not very useful; 8G or more
	is preferred. We have been tuning to one job
	per 512M of RAM.</para>
	</listitem>

	<listitem>
	<para>disk: at least 20G is needed for filesystem; 32G is
	needed for swap. Best performance will be if multiple
	disks are used, and configured as <literal>geom</literal>
	stripes. Performance numbers are also TBA.</para>

	<note>
	<para>Package building will test disk drives to destruction.
	Be aware of what you are signing up for!</para>
	</note>
	</listitem>

	<listitem>
	<para>network bandwidth: TBA. However, an 8-job machine
	has been shown to saturate a cable modem line.</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2 id="node-preparation">
	<title>Preparation</title>

	<procedure>
	<step>
	<para>Pick a unique hostname. It does not have to be
	a publicly resolvable hostname (it can be a name on
	your internal network).</para>
	</step>

	<step>
	<para>By default, package building requires the following TCP
	ports to be accessible: 22 (<literal>ssh</literal>), 414
	(<literal>infoseek</literal>), and 8649
	(<literal>ganglia</literal>). If these are not accessible,
	pick others and ensure that an <command>ssh</command> tunnel
	is set up (see below).</para>

	<para>(Note: if you have more than one machine at your site,
	you will need an individual TCP port for each service on
	each machine, and thus <command>ssh</command> tunnels
	will be necessary. As such, you will probably need to
	configure port forwarding on your firewall.)</para>
	</step>

	<step>
	<para>Decide if you will be booting natively or via
	<literal>pxeboot</literal>. You will find that it is
	easier to keep up with changes to <literal>-current</literal>
	with the latter, especially if you have multiple machines
	at your site.</para>
	</step>

	<step>
	<para>Pick a directory to hold ports configuration and
	<filename>chroot</filename> subdirectories. It may be
	best to put it this on its own partition. (Example:
	<filename>/usr2/</filename>.)</para>
	<note>
	<para>The filename <filename>chroot</filename> is a
	historical remnant. The <command>chroot</command>
	command is no longer used.</para>
	</note>
	</step>
	+
	+ <step>
	+ <para>Decide if you will be using a local
	+ <application>squid</application> cache on the client,
	+ instead of the server. It is more efficient to run it
	+ on the server. If you are doing that, skip the "squid"
	+ steps below.)</para>
	+ </step>
	</procedure>
	</sect2>

	<sect2 id="node-src">
	<title>Configuring <filename>src</filename></title>

	<procedure>
	<step>
	<para>Create a directory to contain the latest
	<literal>-current</literal> source tree and check it
	out. (Since your machine will likely be asked to build
	packages for <literal>-current</literal>, the kernel it
	runs should be reasonably up-to-date with the
	<literal>bindist</literal> that will be exported
	by our scripts.)</para>
	</step>

	<step>
	<para>If you are using <filename>pxeboot</filename>: create a
	directory to contain the install bits. You will probably
	want to use a subdirectory of <filename>/pxeroot</filename>,
	e.g.,
	<filename>/pxeroot/<replaceable>${arch}</replaceable>-<replaceable>${branch}</replaceable></filename>.
	Export that as <makevar>DESTDIR</makevar>.</para>
	</step>

	<step>
	<para>If you are cross-building, export
	<makevar>TARGET_ARCH</makevar>=<replaceable>${arch}</replaceable>.</para>

	<note>
	<para>The procedure for cross-building ports is not yet
	defined.</para>
	</note>
	</step>

	<step>
	<para>Generate a kernel config file. Include
	<filename>GENERIC</filename> (or, if on &i386, and
	you are using more than
	3.5G, <filename>PAE</filename>).</para>

	<para>Required options:</para>

	<programlisting>options NULLFS
	options TMPFS</programlisting>

	<para>Suggested options:</para>

	<programlisting>options GEOM_CONCAT
	options GEOM_STRIPE
	options SHMMAXPGS=65536
	options SEMMNI=40
	options SEMMNS=240
	options SEMUME=40
	options SEMMNU=120</programlisting>

	<para>If you are interested in debugging general
	problems, you may wish to use the following.
	However, for unattended operations, it is best
	to leave it out:</para>

	<programlisting>options ALT_BREAK_TO_DEBUGGER</programlisting>

	<para>For <filename>PAE</filename>, it is not currently possible
	to load modules. Therefore, if you are running an architecture
	that supports Linux emulation, you will need to add:</para>

	<programlisting>options COMPAT_LINUX
	options LINPROCFS</programlisting>

	<para>Also for <filename>PAE</filename>, as of 20110912 you need
	the following. This needs to be investigated:</para>

	<programlisting>nooption NFSD # New Network Filesystem Server
	options NFSCLIENT # Network Filesystem Client
	options NFSSERVER # Network Filesystem Server</programlisting>
	</step>

	<step>
	<para>As root, do the usual build steps, e.g.:</para>

	<screen>&prompt.root; <userinput>make -j4 buildworld</userinput>
	&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>${kernconf}</replaceable></userinput>
	&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>${kernconf}</replaceable></userinput>
	&prompt.root; <userinput>make installworld</userinput></screen>

	<para>The install steps use <makevar>DESTDIR</makevar>.</para>
	</step>

	<step>
	<para>Customize files in <filename>etc/</filename>.
	Whether you do this on the client itself, or another
	machine, will depend on whether you are using
	<filename>pxeboot</filename>.</para>

	<para>If you are using <filename>pxeboot</filename>: create
	a subdirectory of
	<filename><replaceable>${DESTDIR}</replaceable></filename>
	called <filename>conf/</filename>. Create one subdirectory
	<filename>default/etc/</filename>, and (if your site will host
	multiple nodes), subdirectories
	<filename><replaceable>${ip-address}</replaceable>/etc/</filename>
	to contain override files for individual hosts. (You may find
	it handy to symlink each of those directories to a hostname.)
	Copy the entire contents of
	<filename><replaceable>${DESTDIR}</replaceable>/etc/</filename>
	to <filename>default/etc/</filename>; that is where you will
	edit your files. The by-ip-address
	<filename>etc/</filename> directories will probably only need
	customized <filename>rc.conf</filename> files.</para>

	<para>In either case, apply the following steps:</para>

	<itemizedlist>
	<listitem>
	<para>Create a
	<literal>portbuild</literal>
	user and group. It can have the <literal>'*'</literal> password.</para>

	<para>Create
	<filename>/home/portbuild/.ssh/</filename>
	and populate <filename>authorized_keys</filename>. </para>
	</listitem>

	<listitem>
	- <para>Also add the following users:</para>
	+ <para>If you are using <application>ganglia</application>
	+ for monitoring, add the following user:</para>

	- <programlisting>squid:*:100:100::0:0:User &:/usr/local/squid:/bin/sh
	-ganglia:*:102:102::0:0:User &:/usr/local/ganglia:/bin/sh</programlisting>
	+ <programlisting>ganglia:*:102:102::0:0:User &:/usr/local/ganglia:/bin/sh</programlisting>

	- <para>Add them to <filename>etc/group</filename> as well.</para>
	+ <para>Add it to <filename>etc/group</filename> as well.</para>
	</listitem>

	<listitem>
	+ <para>If you are using a local <application>squid</application>
	+ cache on the client, add the following user:</para>
	+
	+ <programlisting>squid:*:100:100::0:0:User &:/usr/local/squid:/bin/sh</programlisting>
	+
	+ <para>Add it to <filename>etc/group</filename> as well.</para>
	+ </listitem>
	+
	+ <listitem>
	<para>Create the appropriate files in
	<filename>etc/.ssh/</filename>.</para>
	</listitem>

	<listitem>
	<para>In <filename>etc/crontab</filename>: add</para>

	<programlisting>* * * * * root /var/portbuild/scripts/client-metrics</programlisting>
	</listitem>

	<listitem>
	<para>Create the appropriate
	<filename>etc/fstab</filename>. (If you have multiple,
	different, machines, you will need to put those in
	the override directories.)</para>
	</listitem>

	<listitem>
	<para>In <filename>etc/inetd.conf</filename>: add</para>

	<programlisting>infoseek stream tcp nowait nobody /var/portbuild/scripts/reportload</programlisting>
	</listitem>

	<listitem>
	<para>You should run the cluster on UTC. If you have not set the clock
	to UTC:</para>

	<programlisting>&prompt.root; cp -p /usr/share/zoneinfo/Etc/UTC etc/localtime</programlisting>
	</listitem>

	<listitem>
	<para>Create the appropriate
	<filename>etc/rc.conf</filename>. (If you are using
	<literal>pxeboot</literal>, and have multiple,
	different, machines, you will need to put those in
	the override directories.)</para>

	<para>Recommended entries for physical nodes:</para>

	<programlisting>hostname="<replaceable>${hostname}</replaceable>"
	inetd_enable="YES"
	linux_enable="YES"
	nfs_client_enable="YES"
	ntpd_enable="YES"
	sendmail_enable="NONE"
	sshd_enable="YES"
	-sshd_program="/usr/local/sbin/sshd"
	+sshd_program="/usr/local/sbin/sshd"</programlisting>

	-gmond_enable="YES"
	-squid_enable="YES"
	-squid_chdir="<filename>/<replaceable>usr2</replaceable>/squid/logs</filename>"
	-squid_pidfile="<filename>/<replaceable>usr2</replaceable>/squid/logs/squid.pid</filename>"</programlisting>
	+ <para>If you are using <application>ganglia</application>
	+ for monitoring, add the following</para>

	+ <programlisting>gmond_enable="YES"</programlisting>
	+
	+ <para>If you are using a local <application>squid</application>
	+ cache on the client, add the following</para>
	+
	+ <programlisting>squid_enable="YES"
	+squid_chdir="<filename>/<replaceable>a</replaceable>/squid/logs</filename>"
	+squid_pidfile="<filename>/<replaceable>a</replaceable>/squid/logs/squid.pid</filename>"</programlisting>
	<para>Required entries for VMWare-based nodes:</para>

	<programlisting>vmware_guest_vmmemctl_enable="YES"
	vmware_guest_guestd_enable="YES"</programlisting>

	<para>Recommended entries for VMWare-based nodes:</para>

	<programlisting>hostname=""
	ifconfig_em0="DHCP"
	fsck_y_enable="YES"

	inetd_enable="YES"
	linux_enable="YES"
	nfs_client_enable="YES"
	sendmail_enable="NONE"
	sshd_enable="YES"
	sshd_program="/usr/local/sbin/sshd"

	gmond_enable="YES"
	squid_enable="YES"
	-squid_chdir="<filename>/<replaceable>usr2</replaceable>/squid/logs</filename>"
	-squid_pidfile="<filename>/<replaceable>usr2</replaceable>/squid/logs/squid.pid</filename>"</programlisting>
	+squid_chdir="<filename>/<replaceable>a</replaceable>/squid/logs</filename>"
	+squid_pidfile="<filename>/<replaceable>a</replaceable>/squid/logs/squid.pid</filename>"</programlisting>

	<para>&man.ntpd.8; should <emphasis>not</emphasis>
	be enabled for VMWare instances.</para>

	<para>Also, it may be possible to leave
	<application>squid</application> disabled by default
	so as to not have
	- <filename>/<replaceable>usr2</replaceable></filename>
	+ <filename>/<replaceable>a</replaceable></filename>
	persistent (which should save instantiation time.)
	Work is still ongoing.
	</para>
	</listitem>

	<listitem>
	<para>Create <filename>etc/resolv.conf</filename>, if
	necessary.</para>
	</listitem>

	<listitem>
	<para>Modify <filename>etc/sysctl.conf</filename>:</para>

	<screen>9a10,30
	-> kern.corefile=<filename>/<replaceable>usr2</replaceable>/%N.core</filename>
	+> kern.corefile=<filename>/<replaceable>a</replaceable>/%N.core</filename>
	> kern.sugid_coredump=1
	> #debug.witness_ddb=0
	> #debug.witness_watch=0
	>
	> # squid needs a lot of fds (leak?)
	> kern.maxfiles=40000
	> kern.maxfilesperproc=30000
	>
	> # Since the NFS root is static we do not need to check frequently for file changes
	> # This saves >75% of NFS traffic
	> vfs.nfs.access_cache_timeout=300
	> debug.debugger_on_panic=1
	>
	> # For jailing
	> security.jail.sysvipc_allowed=1
	> security.jail.allow_raw_sockets=1
	> security.jail.chflags_allowed=1
	> security.jail.enforce_statfs=1
	>
	> vfs.lookup_shared=1</screen>
	</listitem>

	<listitem>
	<para>If desired, modify <filename>etc/syslog.conf</filename>
	to change the logging destinations to
	<literal>@pointyhat.freebsd.org</literal>.</para>
	</listitem>
	</itemizedlist>
	</step>
	</procedure>
	</sect2>

	<sect2 id="node-ports">
	<title>Configuring <filename>ports</filename></title>

	<procedure>
	<step>
	<para>Install the following ports:</para>

	<programlisting>net/rsync
	-security/openssh-portable (with HPN on)
	-security/sudo
	-sysutils/ganglia-monitor-core (with GMETAD off)
	-www/squid (with SQUID_AUFS on)</programlisting>
	+security/sudo</programlisting>

	- <para>There is a WIP to create a meta-port, but it is not yet
	- complete.</para>
	+ <para>You may also wish to install:</para>
	+
	+ <programlisting>security/openssh-portable (with HPN on)</programlisting>
	+
	+ <para>If you are using <application>ganglia</application>
	+ for monitoring, install the following:</para>
	+
	+ <programlisting>sysutils/ganglia-monitor-core (with GMETAD off)</programlisting>
	+
	+ <para>If you are using a local <application>squid</application>
	+ cache on the client, install the following</para>
	+
	+ <programlisting>www/squid31 (with SQUID_AUFS on)</programlisting>
	</step>

	<step>
	<para>Customize files in <filename>usr/local/etc/</filename>.
	Whether you do this on the client itself, or another
	machine, will depend on whether you are using
	<filename>pxeboot</filename>.</para>

	<note>
	<para>The trick of using <filename>conf</filename>
	override subdirectories is less effective here, because
	you would need to copy over all subdirectories of
	<filename>usr/</filename>. This is an implementation
	detail of how the pxeboot works.</para>
	</note>

	<para>Apply the following steps:</para>

	<itemizedlist>
	<listitem>
	- <para>Modify
	+ <para>If you are using <application>ganglia</application>,
	+ modify
	<filename>usr/local/etc/gmond.conf</filename>:</para>

	<screen>21,22c21,22
	< name = "unspecified"
	< owner = "unspecified"
	---
	> name = "<replaceable>${arch}</replaceable> package build cluster"
	> owner = "portmgr@FreeBSD.org"
	24c24
	< url = "unspecified"
	---
	> url = "http://pointyhat.freebsd.org"</screen>

	<!-- XXX MCL adapted literally from krismail; I do not understand it -->
	<para>If there are machines from more than one cluster in the
	same multicast domain (basically = LAN) then change the
	multicast groups to different values (.71, .72, etc).</para>
	</listitem>

	<listitem>
	<!-- XXX MCL get latest patches from narutos -->
	<para>Create
	<filename>usr/local/etc/rc.d/portbuild.sh</filename>,
	using the appropriate value for
	<literal>scratchdir</literal>:</para>

	<programlisting>#!/bin/sh
	#
	# Configure a package build system post-boot

	-scratchdir=<filename>/<replaceable>usr2</replaceable></filename>
	+scratchdir=<filename>/<replaceable>a</replaceable></filename>

	ln -sf ${scratchdir}/portbuild /var/

	# Identify builds ready for use
	cd /var/portbuild/<replaceable>arch</replaceable>
	for i in /builds/; do
	if [ -f ${i}/.ready ]; then
	mkdir /tmp/.setup-${i##*/}
	fi
	done

	# Flag that we are ready to accept jobs
	touch /tmp/.boot_finished</programlisting>
	</listitem>

	<listitem>
	- <para>Modify
	+ <para>If you are using a local <application>squid</application>
	+ cache, modify,
	<filename>usr/local/etc/squid/squid.conf</filename>:</para>

	<screen>288,290c288,290
	< #auth_param basic children 5
	< #auth_param basic realm Squid proxy-caching web server
	< #auth_param basic credentialsttl 2 hours
	---
	> auth_param basic children 5
	> auth_param basic realm Squid proxy-caching web server
	> auth_param basic credentialsttl 2 hours
	611a612
	> acl localnet src 127.0.0.0/255.0.0.0
	655a657
	> http_access allow localnet
	2007a2011
	> maximum_object_size 400 MB
	2828a2838
	> negative_ttl 0 minutes</screen>

	<para>Also, change <filename>usr/local</filename>
	to <filename><replaceable>usr2</replaceable></filename> in
	<literal>cache_dir</literal>,
	<literal>access_log</literal>,
	<literal>cache_log</literal>,
	<literal>cache_store_log</literal>,
	<literal>pid_filename</literal>,
	<literal>netdb_filename</literal>,
	<literal>coredump_dir</literal>.</para>

	<para>Finally, change the <literal>cache_dir</literal>
	storage scheme from <literal>ufs</literal> to
	<literal>aufs</literal> (offers better performance).</para>
	</listitem>

	<listitem>
	<para>Configure <command>ssh</command>: copy
	<filename>etc/ssh</filename> to
	<filename>usr/local/etc/ssh</filename> and add
	<literal>NoneEnabled yes</literal> to
	<filename>sshd_config</filename>.</para>
	</listitem>

	<listitem>
	<note>
	<para>This step is under review.</para>
	</note>

	<para>Create
	<filename>usr/local/etc/sudoers/sudoers.d/portbuild</filename>:</para>

	<programlisting># local changes for package building
	portbuild ALL=(ALL) NOPASSWD: ALL</programlisting>
	</listitem>
	</itemizedlist>
	</step>
	</procedure>
	</sect2>

	<sect2 id="node-configuration">
	<title>Configuration on the client itself</title>

	<procedure>
	<step>
	<para>Change into the port/package directory you picked
	above, e.g.,
	<command>cd <filename>/<replaceable>usr2</replaceable></filename></command>.</para>
	</step>

	<step>
	<para>As root:</para>

	<screen>&prompt.root; <userinput>mkdir portbuild</userinput>
	&prompt.root; <userinput>chown portbuild:portbuild portbuild</userinput>
	&prompt.root; <userinput>mkdir pkgbuild</userinput>
	-&prompt.root; <userinput>chown portbuild:portbuild pkgbuild</userinput>
	-&prompt.root; <userinput>mkdir squid</userinput>
	+&prompt.root; <userinput>chown portbuild:portbuild pkgbuild</userinput></screen>
	+
	+ <para>If you are using a local <application>squid</application>
	+ cache:</para>
	+
	+ <screen>&prompt.root; <userinput>mkdir squid</userinput>
	&prompt.root; <userinput>mkdir squid/cache</userinput>
	&prompt.root; <userinput>mkdir squid/logs</userinput>
	&prompt.root; <userinput>chown -R squid:squid squid</userinput></screen>
	</step>

	<!-- XXX MCL adapted literally from krismail; I do not understand it -->
	<step>
	<para>If clients preserve <filename>/var/portbuild</filename>
	between boots then they must either preserve their
	<filename>/tmp</filename>, or revalidate their available
	builds at boot time (see the script on the <literal>amd64</literal>
	machines). They must also clean up stale jails from previous
	builds before creating <filename>/tmp/.boot_finished</filename>.</para>
	</step>

	<step>
	<para>Boot the client.</para>
	</step>

	<step>
	- <para>As root, initialize the <command>squid</command>
	+ <para>If you are using a local <application>squid</application>
	+ cache, as root, initialize the <command>squid</command>
	directories:</para>

	<screen><userinput>squid -z</userinput></screen>
	</step>
	</procedure>
	</sect2>

	<sect2 id="pointyhat-configuration">
	<title>Configuration on the server</title>

	<para>These steps need to be taken by a <literal>portmgr</literal>
	acting as <literal>portbuild</literal>
	on the server.</para>

	<procedure>
	<step>
	<para>If any of the default TCP ports is not available (see
	above), you will need to create an <command>ssh</command>
	tunnel for them and include its invocation command in
	<literal>portbuild</literal>'s
	<filename>crontab</filename>.</para>
	</step>

	<step>
	<para>Unless you can use the defaults, add an entry to
	<filename>/home/portbuild/.ssh/config</filename>
	to specify the public IP address, TCP port for
	<command>ssh</command>, username, and any other necessary
	information.</para>
	</step>

	<step>
	<para>Create
	<filename>/a/portbuild/<replaceable>${arch}</replaceable>/clients/bindist-<replaceable>${hostname}</replaceable>.tar</filename>.</para>

	<itemizedlist>
	<listitem>
	<para>Copy one of the existing ones as a template and unpack it
	in a temporary directory.</para>
	</listitem>

	<listitem>
	<para>Customize <filename>etc/resolv.conf</filename>
	for the local site.</para>
	</listitem>

	<listitem>
	<para>Customize <filename>etc/make.conf</filename> for
	FTP fetches for the local site. Note: the nulling-out
	of <makevar>MASTER_SITE_BACKUP</makevar> must be common
	to all nodes, but the first entry in
	<makevar>MASTER_SITE_OVERRIDE</makevar> should be the
	nearest local FTP mirror. Example:</para>

	<programlisting>.if defined(FETCH_ORIGINAL)
	MASTER_SITE_BACKUP=
	.else
	MASTER_SITE_OVERRIDE= \
	ftp://<replaceable>friendly-local-ftp-mirror</replaceable>/pub/FreeBSD/ports/distfiles/${DIST_SUBDIR}/ \
	ftp://${BACKUP_FTP_SITE}/pub/FreeBSD/distfiles/${DIST_SUBDIR}/
	.endif</programlisting>
	</listitem>

	<listitem>
	<para><command>tar</command> it up and move it to the right
	location.</para>
	</listitem>
	</itemizedlist>

	<para>Hint: you will need one of these for each machine;
	however, if you have multiple machines at one site, you
	should create a site-specific one (e.g., in
	<filename>/a/portbuild/conf/clients/</filename>)
	and symlink to it.</para>
	</step>

	<step>
	<para>Create
	<filename>/a/portbuild/<replaceable>${arch}</replaceable>/portbuild-<replaceable>${hostname}</replaceable></filename>
	using one of the existing ones as a guide. This
	file contains overrides to
	<filename>/a/portbuild/<replaceable>${arch}</replaceable>/portbuild.conf</filename>.</para>

	<para>Suggested values:</para>

	<programlisting>disconnected=1
	-http_proxy="http://localhost:3128/"
	-squid_dir=<filename>/<replaceable>usr2</replaceable>/squid</filename>
	scratchdir=<filename>/<replaceable>usr2</replaceable>/pkgbuild</filename>
	client_user=portbuild
	sudo_cmd="sudo -H"
	rsync_gzip=-z

	infoseek_host=localhost
	infoseek_port=<replaceable>${tunelled-tcp-port}</replaceable></programlisting>

	+ <para>If you will be using <application>squid</application>
	+ on the client:</para>
	+
	+ <programlisting>http_proxy="http://localhost:3128/"
	+squid_dir=<filename>/<replaceable>usr2</replaceable>/squid</filename></programlisting>
	+
	+ <para>If, instead, you will be using <application>squid</application>
	+ on the server:</para>
	+
	+ <programlisting>
	+http_proxy="http://<replaceable>servername</replaceable>:3128/"</programlisting>
	+
	<para>Possible other values:</para>

	<programlisting>use_md_swap=1
	md_size=9g
	use_zfs=1
	scp_cmd="/usr/local/bin/scp"
	ssh_cmd="/usr/local/bin/ssh"</programlisting>
	</step>
	</procedure>

	<para>These steps need to be taken by a <literal>portmgr</literal>
	acting as <literal>root</literal> on <hostid>pointyhat</hostid>.</para>

	<procedure>
	<step>
	<para>Add the public IP address to
	<filename>/etc/hosts.allow</filename>. (Remember, multiple
	machines can be on the same IP address.)</para>
	</step>

	<step>
	- <para>Add an appropriate <literal>data_source</literal> entry to
	+ <para>If you are using <application>ganglia</application>,
	+ add an appropriate <literal>data_source</literal> entry to
	<filename>/usr/local/etc/gmetad.conf</filename>:</para>

	<programlisting>data_source "<replaceable>arch</replaceable>/<replaceable>location</replaceable> Package Build Cluster" 30 <replaceable>hostname</replaceable></programlisting>

	<para>You will need to restart <filename>gmetad</filename>.</para>
	</step>
	</procedure>
	</sect2>

	<sect2 id="node-enabling">
	<title>Enabling the node</title>

	<para>These steps need to be taken by a <literal>portmgr</literal>
	acting as <literal>portbuild</literal>:</para>

	<procedure>
	<step>
	<para>Ensure that <literal>ssh</literal> to the client
	is working by executing
	<userinput>ssh <replaceable>hostname</replaceable> uname -a</userinput>.
	The actual command is not important; what is important is to
	confirm the setup, and also add an entry into
	<filename>known_hosts</filename>, once you have confirmed the
	node's identity.</para>
	</step>

	<step>
	<para>Populate the client's copy of
	<filename>/var/portbuild/scripts/</filename> by something like
	<userinput>/a/portbuild/scripts/dosetupnode <replaceable>arch</replaceable> <replaceable>major</replaceable> latest <replaceable>hostname</replaceable></userinput>.
	Verify that you now have files in that directory.</para>
	</step>

	<step>
	<para>Test the other TCP ports by executing
	<userinput>telnet <replaceable>hostname</replaceable> <replaceable>portnumber</replaceable></userinput>.
	<literal>414</literal> (or its tunnel) should give you a few lines of status
	information including <literal>arch</literal> and
	<literal>osversion</literal>; <literal>8649</literal> should
	give you an <literal>XML</literal> response from
	<literal>ganglia</literal>.</para>
	</step>
	</procedure>

	<para>This step needs to be taken by a <literal>portmgr</literal>
	- acting as <literal>root</literal>:</para>
	+ acting as <literal>portbuild</literal>:</para>

	<procedure>
	<step>
	<para>Tell <filename>qmanager</filename> about the node. Example:</para>

	<para><userinput>python <replaceable>path</replaceable>/qmanager/qclient add
	name=<replaceable>uniquename</replaceable>
	arch=<replaceable>arch</replaceable>
	osversion=<replaceable>osversion</replaceable>
	numcpus=<replaceable>number</replaceable>
	haszfs=0
	online=1
	domain=<replaceable>domain</replaceable>
	primarypool=package
	pools="package all" maxjobs=1
	acl="ports-<replaceable>arch</replaceable>,deny_all"
	</userinput></para>
	</step>
	</procedure>

	<para>Finally, again as <literal>portmgr</literal>
	acting as <literal>portbuild</literal>:</para>

	<procedure>
	<step>
	<para>Once you are sure that the client is working, tell
	<application>pollmachine</application> about it by adding
	it to
	<filename>/a/portbuild/<replaceable>${arch}</replaceable>/mlist</filename>.</para>
	</step>
	</procedure>
	</sect2>
	</sect1>

	<sect1 id="new-branch">
	<title>How to configure a new &os; branch</title>

	<sect2 id="new-branch-pre-qmanager">
	<title>Steps necessary before <application>qmanager</application> is started</title>

	<para>When a new branch is created, some work needs to
	be done to specify that the previous branch is no longer
	equivalent to <literal>HEAD</literal>.</para>

	<note>
	<para>As
	<literal>srcbuild</literal>:</para>
	</note>

	<itemizedlist>
	<listitem>
	<para>
	Edit <filename>/a/portbuild/conf/admin/admin.conf</filename>
	with the following changes:</para>

	<itemizedlist>
	<listitem>
	<para>Add <replaceable>new-branch</replaceable> to
	<makevar>SRC_BRANCHES</makevar>.</para>
	</listitem>

	<listitem>
	<para>For what was previously head, change
	<makevar>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</makevar> to
	<literal>releng/<replaceable>branch</replaceable>.0</literal>
	(literal zero).</para>
	</listitem>

	<listitem>
	<para>Add
	<makevar>SRC_BRANCH_<replaceable>new-branch</replaceable>_SUBDIR</makevar>
	<literal>=head</literal>.</para>
	</listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<para>Run <command>/a/portbuild/admin/scripts/updatesnap</command> manually.</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2 id="new-branch-post-qmanager">
	<title>Steps necessary after <application>qmanager</application> is started</title>

	<itemizedlist>
	<listitem>
	<para>For each branch that will be supported, do the following:</para>

	<itemizedlist>
	<listitem>
	<para>As <literal>portbuild</literal>,
	kick-start the build for the branch with:</para>

	<screen>build create <replaceable>arch</replaceable> <replaceable>branch</replaceable></screen>
	</listitem>

	<listitem>
	<para>As <literal>srcbuild</literal>,
	<link linkend="setup">create
	<filename>bindist.tar</filename></link>.</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</itemizedlist>
	</sect2>
	</sect1>

	<sect1 id="old-branch">
	<title>How to delete an unsupported &os; branch</title>

	<para>When an old branch goes out of support, there are some
	things to garbage-collect.</para>

	<itemizedlist>
	<listitem>
	<para>Edit <filename>/a/portbuild/admin/conf/admin.conf</filename>
	with the following changes:</para>

	<itemizedlist>
	<listitem>
	<para>Delete <replaceable>old-branch</replaceable> from
	<makevar>SRC_BRANCHES</makevar>.</para>
	</listitem>

	<listitem>
	<para>Delete
	<makevar>SRC_BRANCH_<replaceable>old-branch</replaceable>_SUBDIR</makevar><literal>=</literal>
	<replaceable>whatever</replaceable></para>
	</listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<screen>umount a/snap/src-<replaceable>old-branch</replaceable>/src;
	umount a/snap/src-<replaceable>old-branch</replaceable>;
	zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></screen>
	</listitem>
	</itemizedlist>

	<itemizedlist>
	<listitem>
	<para>You will probably find that the following files and
	symlinks in <filename>/a/portbuild/errorlogs/</filename>
	can be removed:</para>

	<itemizedlist>
	<listitem>
	<para>Files named
	<filename>*-<replaceable>old_branch</replaceable>-failure.html</filename></para>
	</listitem>

	<listitem>
	<para>Files named
	<filename>buildlogs_-<replaceable>old_branch</replaceable>--logs.txt</filename></para>
	</listitem>

	<listitem>
	<para>Symlinks named
	<filename>-<replaceable>old_branch</replaceable>-previous</filename></para>
	</listitem>

	<listitem>
	<para>Symlinks named
	<filename>-<replaceable>old_branch</replaceable>-latest</filename></para>
	</listitem>
	</itemizedlist>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="rebase-branch">
	<title>How to rebase on a supported &os; branch</title>

	<para>As of 2011, the philosophy of package building is to build
	packages based on <emphasis>the earliest supported release</emphasis>
	of each branch. e.g.: if on <literal>RELENG-8</literal>, the
	following releases are supported: 8.1, 8.2, 8.3; then
	<literal>packages-8-stable</literal> should be built from 8.1.</para>

	<para>As releases go End-Of-Life (see
	<ulink url="http://www.freebsd.org/security/index.html#supported-branches">chart</ulink>),
	a full (not incremental!) package build should be done and uploaded.</para>

	<para>The procedure is as follows:</para>

	<itemizedlist>
	<listitem>
	<para>Edit <filename>/a/portbuild/admin/conf/admin.conf</filename>
	with the following changes:</para>

	<itemizedlist>
	<listitem>
	<para>Change the value of
	<makevar>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</makevar> to
	<literal>releng/</literal><replaceable>branch</replaceable>.<replaceable>N</replaceable>
	where <literal>N</literal> is the newest 'oldest' release
	for that branch.</para>
	</listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<para>Run <command>/a/portbuild/admin/scripts/updatesnap</command> manually.</para>
	</listitem>

	<listitem>
	<para>Run <command>dopackages</command> with <literal>-nobuild</literal>.</para>
	</listitem>

	<listitem>
	<para>Follow the <link linkend="setup">setup procedure</link>.</para>
	</listitem>

	<listitem>
	<para>Now you can run <command>dopackages</command> without <literal>-nobuild</literal>.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="new-arch">
	<title>How to configure a new architecture</title>

	<sect2 id="new-arch-pre-qmanager">
	<title>Steps necessary before <application>qmanager</application> is started</title>

	<note>
	<para>The next steps are most easily done as user
	<literal>portbuild</literal>.</para>
	</note>

	<note>
	<para>The following assumes you have already run
	<literal>mkportbuild</literal>.</para>
	</note>

	<itemizedlist>
	<listitem>
	<para>As the <literal>portbuild</literal> user, run</para>

	- <screen>&prompt.user; /a/portbuild/admin/tools/addarch <replaceable>arch</replaceable></screen>
	+ <screen>&prompt.user; /a/portbuild/tools/addarch <replaceable>arch</replaceable></screen>
	</listitem>
	</itemizedlist>

	<itemizedlist>
	<listitem>
	<para>For each branch that will be supported, do the following:</para>

	<itemizedlist>
	<listitem>
	<para>Kick-start the build for the branch with</para>

	<screen>&prompt.root; build create <replaceable>arch</replaceable> <replaceable>branch</replaceable></screen>
	</listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<para>If you are going to store your historical buildlogs and
	errorlogs on your head node's hard drive, you may skip this step.
	Otherwise:</para>

	<para>Create an external directory and link to it:</para>

	<example>
	<title>Creating and linking an external archive directory</title>

	<screen>&prompt.root; mkdir /dumpster/pointyhat/<replaceable>arch</replaceable>/archive
	&prompt.root; ln -s /dumpster/pointyhat/<replaceable>arch</replaceable>/archive archive</screen>
	</example>

	<note>
	<para>(Historical note that only applied to the original
	<hostid>pointyhat.FreeBSD.org</hostid> installation)</para>

	<para>It is possible that <filename>/dumpster/pointyhat</filename>
	will not have enough space. In that case, create the archive
	directory as
	<filename>/dumpster/pointyhat/<replaceable>arch</replaceable>/archive</filename>
	and symlink to that.</para>
	</note>
	</listitem>

	<listitem>
	<para>Populate <filename>clients</filename> as usual.</para>
	</listitem>

	<listitem>
	<para>Edit <filename>portbuild.conf</filename>
	from one of the ones for another architecture.
	<literal>addarch</literal> will have created a default
	one for you.</para>
	</listitem>

	<listitem>
	<para>Create customized
	<filename>portbuild.<replaceable>machinename</replaceable>.conf</filename>
	files as appropriate.</para>
	</listitem>

	<listitem>
	<para>If you need to create any tunnels:</para>

	<procedure>
	<step>
	<para>Make a private configuration directory:</para>

	<screen>&prompt.root; mkdir /a/portbuild/conf/<replaceable>arch</replaceable></screen>
	</step>

	<step>
	<para>In that directory: create any <filename>dotunnel.*</filename>
	scripts needed.</para>
	</step>
	</procedure>
	</listitem>
	</itemizedlist>

	<note>
	<para>As <literal>srcbuild</literal>:</para>
	</note>

	<itemizedlist>
	<listitem>
	<para>Add <replaceable>arch</replaceable> to <makevar>SUPPORTED_ARCHS</makevar> in
	<filename>/a/portbuild/admin/conf/admin.conf</filename>.</para>
	</listitem>

	<listitem>
	<para>Add the <replaceable>arch</replaceable> directory to
	<filename>/a/portbuild/admin/scripts/zbackup</filename>.
	(This is a hack and should go away.)</para>
	</listitem>
	</itemizedlist>

	<itemizedlist>
	<listitem>
	<para>Enable the appropriate <replaceable>arch</replaceable> entry for
	<filename>/a/portbuild/scripts/dologs</filename> to the portbuild
	<filename>crontab</filename>. (This is a hack and should go away.)</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2 id="new-arch-post-qmanager">
	<title>Steps necessary after <application>qmanager</application> is started</title>

	<note>
	<para>Again as <literal>srcbuild</literal>:</para>
	</note>

	<itemizedlist>
	<listitem>
	<para>For each branch that will be supported, do the following:</para>

	<itemizedlist>
	<listitem>
	<para><link linkend="setup">Create
	<filename>bindist.tar</filename></link>.</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</itemizedlist>
	</sect2>
	</sect1>

	<sect1 id="new-head-node">
	<title>How to configure a new head node (pointyhat instance)</title>

	- <para>Please talk to Mark Linimon before making any changes
	- to this section.</para>
	-
	<sect2 id="pointyhat-basics">
	<title>Basic installation</title>

	<procedure>
	<step>
	<para>Install FreeBSD.</para>
	</step>

	<step>
	<para>Create a user to own the <application>portbuild</application>
	repository, such as <literal>portbuild</literal>. It should have the
	<literal>'*'</literal> password.</para>
	</step>

	<step>
	<para>Similarly, create a user to own the administration functions
	and manage the <application>svn</application>
	repositories, such as <literal>srcbuild</literal>. It should have the
	<literal>'*'</literal> password.</para>
	</step>

	<step>
	<para>Add the following to <filename>/boot/loader.conf</filename>:</para>

	<programlisting>console="vidconsole,comconsole"</programlisting>
	</step>

	<step>
	<para>You should run the cluster on UTC. If you have not set the clock
	to UTC:</para>

	<programlisting>&prompt.root; cp -p /usr/share/zoneinfo/Etc/UTC /etc/localtime</programlisting>
	</step>

	<step>
	<para>Create the appropriate
	<filename>/etc/rc.conf</filename>.</para>

	<para>Required entries:</para>

	<programlisting>hostname="<replaceable>${hostname}</replaceable>"
	sshd_enable="YES"
	zfs_enable="YES"</programlisting>

	<para>Recommended entries:</para>

	<programlisting>background_fsck="NO"
	clear_tmp_enable="YES"
	dumpdev="AUTO"
	fsck_y_enable="YES"

	apache22_enable="YES"
	apache_flags=""
	apache_pidfile="/var/run/httpd.pid"
	-gmetad_enable="YES"
	-gmond_enable="YES"
	inetd_enable="YES"
	inetd_flags="-l -w"
	mountd_enable="YES"
	nfs_server_enable="YES"
	nfs_server_flags="-u -t -n 12"
	nfs_remote_port_only="YES"
	ntpd_enable="YES"
	rpcbind_enable="YES"
	rpc_lockd_enable="NO"
	rpc_statd_enable="YES"
	sendmail_enable="NONE"
	smartd_enable="YES"</programlisting>
	+
	+ <para>If you are using <application>ganglia</application>,
	+ add:</para>
	+
	+ <programlisting>gmetad_enable="YES"
	+gmond_enable="YES"</programlisting>
	+
	+ <para>If you will be using a <application>squid</application>
	+ cache on the server, rather than the clients:</para>
	+
	+ <programlisting>squid_enable="YES"</programlisting>
	</step>

	<step>
	<para>Create <filename>/etc/resolv.conf</filename>, if
	necessary.</para>
	</step>

	<step>
	<para>Create the appropriate files in
	<filename>/etc/ssh/</filename>.</para>
	</step>

	<step>
	<para>Add the following to <filename>/etc/sysctl.conf</filename>:</para>

	<programlisting>kern.maxfiles=40000
	kern.maxfilesperproc=38000
	sysctl vfs.usermount=1
	sysctl vfs.zfs.super_owner=1</programlisting>
	</step>

	<step>
	<para>Make sure the following change is made to
	<filename>/etc/ttys</filename>:</para>

	<programlisting>ttyu0 "/usr/libexec/getty std.9600" vt100 on secure</programlisting>
	</step>
	</procedure>
	</sect2>

	<sect2 id="pointyhat-src">
	<title>Configuring <filename>src</filename></title>

	<para>You should be able to install from the most recent release
	using only the default kernel configuration.</para>
	</sect2>

	<sect2 id="pointyhat-ports">
	<title>Configuring <filename>ports</filename></title>

	<procedure>
	<step>
	<para>The following ports (or their latest successors) are required:</para>

	<programlisting>databases/py-sqlite3
	databases/py-sqlalchemy (only SQLITE is needed)
	devel/git (WITH_SVN)
	devel/py-configobj
	devel/py-setuptools
	devel/subversion
	net/nc
	net/rsync
	-sysutils/ganglia-monitor-core (with GMETAD off)
	-sysutils/ganglia-webfrontend (compile with -DWITHOUT_X11)
	www/apache22 (with EXT_FILTER)</programlisting>

	<para>Expect those to bring in, among others:</para>

	<programlisting>databases/sqlite3
	lang/perl-5.14 (or successor)
	lang/python27 (or sucessor)</programlisting>

	+ <para>If you are using <application>ganglia</application>,
	+ add:</para>
	+
	+ <programlisting>sysutils/ganglia-monitor-core (with GMETAD off)
	+sysutils/ganglia-webfrontend (compile with -DWITHOUT_X11)</programlisting>
	+
	+ <para>If you will be using a <application>squid</application>
	+ cache on the server, rather than the clients:</para>
	+
	+ <programlisting>www/squid (with SQUID_AUFS on)</programlisting>
	+
	<para>The following ports (or their latest successors) are strongly suggested:</para>

	<programlisting>devel/ccache
	mail/postfix
	net/isc-dhcp41-server
	ports-mgmt/pkg
	ports-mgmt/portaudit
	ports-mgmt/portmaster
	shells/bash
	shells/zsh
	sysutils/screen</programlisting>

	<note>
	<para>The use of <application>sudo</application> on the master,
	which was formerly required, is
	<emphasis>no longer recommended</emphasis>.
	</para>
	</note>

	<para>The following ports (or their latest successors) are handy:</para>

	<programlisting>benchmarks/bonnie++
	ports-mgmt/pkg_tree
	sysutils/dmidecode
	sysutils/smartmontools
	sysutils/zfs-stats</programlisting>
	</step>
	</procedure>
	</sect2>

	<sect2 id="pointyhat-zfs-volume">
	<title>Configuring the zfs volume and setting up the repository</title>

	<para>The following steps need to be done as euid root.</para>

	<para>Here is a quick example:</para>

	<example>
	<title>The contents of example file <filename>portbuild/tools/example_install</filename></title>

	<screen>
	#!/bin/sh
	#
	# example script to drive the "mkportbuild" kickstart file
	#
	export PORTBUILD_USER=portbuild
	export SRCBUILD_USER=srcbuild
	export ZFS_VOLUME=a
	export ZFS_MOUNTPOINT=/a
	export VCS_REPOSITORY=svn://svn0.us-east.FreeBSD.org

	#
	# create the zpool. the examples here are just suggestions and need to be
	# customized for your site.
	#
	# simple examples:
	# zpool create ${ZFS_VOLUME} da1
	# zpool create ${ZFS_VOLUME} gprootfs
	# more complex example:
	# zpool create ${ZFS_VOLUME} mirror da1 da2 mirror da3 da4 mirror da5 da6 mirror da7 da8

	#
	# check out the kickstart file and run it
	#
	mkdir -p tmp
	svn checkout ${VCS_REPOSITORY}/base/projects/portbuild/admin/tools tmp
	sh -x ./tmp/mkportbuild
	</screen>
	</example>

	<para>Here is a detailed explanation of the example:</para>

	<procedure>
	<step>
	<para>Export the value of <makevar>PORTBUILD_USER</makevar>:</para>

	<screen>&prompt.root; export PORTBUILD_USER=<replaceable>portbuild</replaceable></screen>
	</step>

	<step>
	<para>Export the value of <makevar>SRCBUILD_USER</makevar>:</para>

	<screen>&prompt.root; export SRCBUILD_USER=<replaceable>srcbuild</replaceable></screen>
	</step>

	<step>
	<para>Pick a <application>zfs</application> volume name and export
	it. We have used <replaceable>a</replaceable> so far to date.</para>

	<programlisting>&prompt.root; export ZFS_VOLUME=<replaceable>a</replaceable></programlisting>
	</step>

	<step>
	<para>Pick a mountpoint and export it. We have used
	<filename>/<replaceable>a</replaceable></filename> so far to date.</para>

	<screen>&prompt.root; export ZFS_MOUNTPOINT=/<replaceable>a</replaceable></screen>
	</step>

	<step>
	<para>Create the <application>zfs</application> volume
	and mount it.</para>

	<example>
	<title>Creating a <application>zfs</application> volume for portbuild</title>

	<screen>&prompt.root; zpool create ${ZFS_VOLUME} mirror da1 da2 mirror da3 da4 mirror da5 da6 mirror da7 da8</screen>
	</example>

	<note>
	<para>The kickstart script defines <application>zfs</application>
	<literal>permission sets</literal>, so that the
	<replaceable>srcbuild</replaceable> user and
	<replaceable>portbuild</replaceable> user may administer
	subdirectories of this
	volume without having to have root privileges.</para>
	</note>
	</step>

	<step>
	<para>Select an <application>svn</application> repository
	and export it. See the
	- <ulink url="&url.books.handbook;/mirrors-svn.html">&os; Handbook</ulink>
	+ <ulink url="&url.books.handbook;/svn-mirrors.html">&os; Handbook</ulink>
	for the currently supported list.</para>

	<screen>&prompt.root; export VCS_REPOSITORY=<replaceable>svn://svn0.us-east.FreeBSD.org</replaceable></screen>
	</step>

	<step>
	<para>Obtain a copy of the kickstart script into a
	temporary directory. (You will not need to keep this
	directory later.)</para>

	<screen>&prompt.root; mkdir -p /home/<replaceable>portbuild</replaceable>/<replaceable>tmp</replaceable>
	&prompt.root; svn checkout ${VCS_REPOSITORY}/base/projects/portbuild/admin/tools /home/<replaceable>portbuild</replaceable>/<replaceable>tmp</replaceable></screen>
	</step>

	<step>
	<para>Run the kickstart script:</para>

	<screen>&prompt.root; sh /home/<replaceable>portbuild</replaceable>/<replaceable>tmp</replaceable>/mkportbuild</screen>

	<para>This will accomplish all the following steps:</para>

	<procedure>

	<!-- begin of whitespace-broken area -->
	<step>
	<para>Create the <filename>portbuild</filename> directory</para>
	</step>

	<step>
	<para>Create and mount a new <application>zfs</application>
	filesystem on it</para>
	</step>

	<step>
	<para>Set up the directory</para>
	</step>

	<step>
	<para>Set up the initial repository:</para>
	</step>
	<!-- end of whitespace-broken area -->

	<step>
	<para>Set up the <application>zfs</application>
	<literal>permission sets</literal>.</para>
	</step>

	<step>
	<para>Split ownerships of subdirectories such that
	<replaceable>PORTBUILD_USER</replaceable> owns, and
	only owns, files that are used to manage builds and
	interact with slaves. The more trustable user
	<replaceable>SRCBUILD_USER</replaceable> now owns
	everything else.</para>
	</step>
	</procedure>

	</step>
	</procedure>
	</sect2>

	<sect2 id="srcbuild-user-configuration">
	<title>Configuring the <application>srcbuild</application>-owned files</title>

	<procedure>
	<step>
	<para>Configure the server by making the following changes to
	<filename>/<replaceable>a</replaceable>/portbuild/admin/conf/admin.conf</filename>:</para>

	<itemizedlist>
	<listitem>
	<para>Set <makevar>SUPPORTED_ARCHS</makevar> to the
	list of architectures you wish to build packages for.</para>
	</listitem>

	<listitem>
	<para>For each source branch you will be building for, set
	<makevar>SRC_BRANCHES</makevar> and
	<makevar>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</makevar>
	as detailed in <xref linkend="new-branch-pre-qmanager"/>.
	You should not need to change
	<makevar>SRC_BRANCHES_PATTERN</makevar>.</para>
	</listitem>

	<listitem>
	<para>Set <makevar>ZFS_VOLUME</makevar> and
	<makevar>ZFS_MOUNTPOINT</makevar> to whatever you
	chose above.</para>
	</listitem>

	<listitem>
	<para>Set <makevar>VCS_REPOSITORY</makevar> to whatever
	you chose above.</para>
	</listitem>

	<listitem>
	<para>Set <makevar>MASTER_URL</makevar> to the http
	URL of your server. This will be stamped into the
	package build logs and the indices thereof.</para>
	</listitem>
	</itemizedlist>

	<para>Most of the other default values should be fine.</para>
	</step>
	</procedure>
	</sect2>

	<sect2 id="portbuild-user-configuration">
	<title>Configuring the <application>portbuild</application>-owned files</title>

	<procedure>
	<step>
	<para>Configure how build slaves will talk to your server
	by making the following changes to
	<filename>/<replaceable>a</replaceable>/portbuild/conf/client.conf</filename>:</para>

	<itemizedlist>
	<listitem>
	<para>Set <makevar>CLIENT_NFS_MASTER</makevar> to wherever
	your build slaves will PXE boot from. (Possibly, the
	hostname of your server.)</para>
	</listitem>

	<listitem>
	<para>Set <makevar>CLIENT_BACKUP_FTP_SITE</makevar>
	to a backup site for FTP fetches; again, possibly
	the hostname of your server.</para>
	</listitem>

	<listitem>
	<para>Set <makevar>CLIENT_UPLOAD_HOST</makevar> to
	where completed packages will be uploaded.</para>
	</listitem>
	</itemizedlist>

	<para>Most of the other default values should be fine.</para>
	</step>

	<step>
	<para>Most of the default values in
	<filename>/<replaceable>a</replaceable>/portbuild/conf/common.conf</filename>
	should be fine. This file holds definitions used by
	both the server and all its clients.</para>
	</step>

	<step>
	<para>Configure the server by making the following changes to
	<filename>/<replaceable>a</replaceable>/portbuild/conf/server.conf</filename>:</para>

	<itemizedlist>
	<!--
	<listitem>
	<para>For each source branch you will be building for, set
	<makevar>SRC_BRANCHES</makevar> and
	<makevar>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</makevar>
	as detailed in <xref linkend="new-branch-pre-qmanager"/>.
	You should not need to change
	<makevar>SRC_BRANCHES_PATTERN</makevar>.</para>
	</listitem>

	<listitem>
	<para>Set <makevar>ZFS_VOLUME</makevar> and
	<makevar>ZFS_MOUNTPOINT</makevar> to whatever you
	chose above.</para>
	</listitem>
	-->

	<listitem>
	<para>Set <makevar>UPLOAD_DIRECTORY</makevar>,
	<makevar>UPLOAD_TARGET</makevar>, and
	<makevar>UPLOAD_USER</makevar> as appropriate
	for your site.</para>
	</listitem>

	<!--
	<listitem>
	<para>Set <makevar>VCS_REPOSITORY</makevar> to whatever
	you chose above.</para>
	</listitem>

	<listitem>
	<para>Set <makevar>MASTER_URL</makevar> to the http
	URL of your server. This will be stamped into the
	package build logs and the indices thereof.</para>
	</listitem>
	-->
	</itemizedlist>

	<para>Most of the other default values should be fine.</para>
	</step>
	</procedure>
	</sect2>

	<sect2 id="pointyhat-pre-qmanager">
	<title>pre-<application>qmanager</application></title>

	<procedure>
	<step>
	<para>For each architecture, follow the steps in
	<xref linkend="new-arch-pre-qmanager"/>.</para>
	</step>
	</procedure>
	</sect2>

	<sect2 id="pointyhat-qmanager">
	<title><application>qmanager</application></title>

	<procedure>
	<step>
	<para>As <literal>root</literal>, copy the following files from
	<filename>/a/portbuild/admin/etc/rc.d/</filename> to
	<filename>/usr/local/etc/rc.d/</filename>:</para>

	<programlisting>pollmachine
	qmanager</programlisting>

	<para>As root, start each one of them. You may find it handy
	to start each under <application>screen</application> for
	debugging purposes.</para>
	</step>

	<step>
	<para>Initialize the <application>qmanager</application>
	database's acl list:</para>

	<note>
	<para>This should now be automatically done for you by
	the first <command>build</command> command.</para>
	</note>

	<screen>&prompt.root; python /<replaceable>a</replaceable>/portbuild/qmanager/qclient add_acl name=deny_all uidlist= gidlist= sense=0</screen>
	</step>
	</procedure>
	</sect2>

	<sect2 id="pointyhat-src-ports-repos">
	<title>Creating src and ports repositories</title>

	<procedure>
	<step>
	<para>As the <replaceable>srcbuild</replaceable> user,
	run the following commands manually to create the
	<literal>src</literal> and <literal>ports</literal>
	repositories, respectively:</para>

	<screen>&prompt.user; /<replaceable>a</replaceable>/portbuild/admin/scripts/updatesnap.ports
	&prompt.user; /<replaceable>a</replaceable>/portbuild/admin/scripts/updatesnap</screen>

	<para>These will be periodically run from the
	<replaceable>srcbuild</replaceable>
	<filename>crontab</filename>, which you will
	install below.</para>
	</step>
	</procedure>
	</sect2>

	<sect2 id="pointyhat-other-services">
	<title>Other services</title>

	<procedure>
	<step>
	<para>Configure
	<filename>/usr/local/etc/apache22/httpd.conf</filename>
	as appropriate for your site.</para>
	</step>

	<step>
	<para>Copy <filename>/a/portbuild/admin/conf/apache.conf</filename>
	to the appropriate <filename>Includes/</filename> subdirectory, e.g.,
	<filename>/usr/local/etc/apache22/Includes/portbuild.conf</filename>.
	Configure it as appropriate for your site.</para>
	</step>

	<step>
	<para>Install <filename>/a/portbuild/admin/crontabs/portbuild</filename> as
	the <username>portbuild</username> crontab via
	<command>crontab -u portbuild -e</command>. If you do
	not support all the archs listed there, make sure to comment out
	the appropriate <application>dologs</application> entries.</para>
	</step>

	<step>
	- <para>Install <filename>/a/srcbuild/admin/crontabs/portbuild</filename> as
	+ <para>Install <filename>/a/portbuild/admin/crontabs/srcbuild</filename> as
	the <username>srcbuild</username> crontab via
	<command>crontab -u srcbuild -e</command>.</para>
	</step>

	<step>
	<para>If your build slaves will be pxebooted, make sure to
	enable the <application>tftp</application> entries in
	<filename>/etc/inetd.conf</filename>.</para>
	</step>

	<step>
	<para>Configure mail by doing the following:</para>

	<para><command>newaliases</command>.</para>
	</step>
	</procedure>
	</sect2>

	<sect2 id="pointyhat-finishing-up">
	<title>Finishing up</title>

	<procedure>
	<step>
	<para>For each architecture, follow the steps in
	<xref linkend="new-arch-post-qmanager"/>.</para>
	</step>

	<step>
	<para>You will probably find it handy to append
	the following to the <makevar>PATH</makevar> definition for
	the <replaceable>portbuild</replaceable> user:</para>

	<programlisting>/<replaceable>a</replaceable>/portbuild/scripts:/<replaceable>a</replaceable>/portbuild/tools</programlisting>
	</step>

	<step>
	<para>You will also probably find it handy to append
	the following to the <makevar>PATH</makevar> definition for
	the <replaceable>srcbuild</replaceable> user:</para>

	<programlisting>/<replaceable>a</replaceable>/portbuild/admin/scripts:/<replaceable>a</replaceable>/portbuild/admin/tools</programlisting>
	</step>
	</procedure>

	<para>You should now be ready to build packages.</para>
	</sect2>
	</sect1>

	<sect1 id="disk-failure">
	<title>Procedures for dealing with disk failures</title>

	<note>
	<para>The following section is particular to <hostid>freebsd.org</hostid>
	and is somewhat obsolete.</para>
	</note>

	<para>When a machine has a disk failure (e.g., panics due to read errors,
	etc), then we should do the following steps:</para>

	<itemizedlist>
	<listitem>
	<para>Note the time and failure mode (e.g., paste in the
	relevant console output) in
	<filename>/a/portbuild/<replaceable>${arch}</replaceable>/reboots</filename></para>
	</listitem>

	<listitem>
	<para>For i386 gohan clients, scrub the disk by touching
	<filename>/SCRUB</filename> in the nfsroot (e.g.,
	<filename>/a/nfs/8.dir1/SCRUB</filename>) and rebooting. This will
	<command>dd if=/dev/zero of=/dev/ad0</command> and force the drive to
	remap any bad sectors it finds, if it has enough spares left. This is
	a temporary measure to extend the lifetime of a drive that is on the
	way out.</para>

	<note>
	<para>For the i386 blade systems another signal of a failing
	disk seems to be that the blade will completely hang and be
	unresponsive to either console break, or even NMI.</para>
	</note>

	<para>For other build systems that do not newfs their disk at boot (e.g.,
	amd64 systems) this step has to be skipped.</para>
	</listitem>

	<listitem>
	<para>If the problem recurs, then the disk is probably toast.
	Take the machine out of <filename>mlist</filename> and (for ata disks)
	run <command>smartctl</command> on the drive:</para>

	<screen>smartctl -t long /dev/ad0</screen>

	<para>It will take about 1/2 hour:</para>

	<screen>gohan51# smartctl -t long /dev/ad0
	smartctl version 5.38 [i386-portbld-freebsd8.0] Copyright (C) 2002-8
	Bruce Allen
	Home page is http://smartmontools.sourceforge.net/

	=== START OF OFFLINE IMMEDIATE AND SELF-TEST SECTION ===
	Sending command: "Execute SMART Extended self-test routine immediately in off-line mode".
	Drive command "Execute SMART Extended self-test routine immediately in off-line mode" successful.
	Testing has begun.
	Please wait 31 minutes for test to complete.
	Test will complete after Fri Jul 4 03:59:56 2008

	Use smartctl -X to abort test.</screen>

	<para>Then <command>smartctl -a /dev/ad0</command> shows the status
	after it finishes:</para>

	<screen># SMART Self-test log structure revision number 1
	# Num Test_Description Status Remaining
	LifeTime(hours) LBA_of_first_error
	# 1 Extended offline Completed: read failure 80% 15252 319286</screen>

	<para>It will also display other data including a log of previous drive
	errors. It is possible for the drive to show previous DMA errors
	without failing the self-test though (because of sector
	remapping).</para>
	</listitem>
	</itemizedlist>

	<para>When a disk has failed, please inform the cluster administrators
	so we can try to get it replaced.</para>
	</sect1>
	</article>
	Index: projects/entities/en_US.ISO8859-1/articles/pr-guidelines/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/pr-guidelines/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/pr-guidelines/article.xml (revision 41355)
	@@ -1,1088 +1,1088 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	<!ENTITY man.edit-pr.1 "<citerefentry><refentrytitle>edit-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
	<!ENTITY man.query-pr.1 "<citerefentry><refentrytitle>query-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
	]>

	<article lang='en'>
	<!-- :START of Article Metadata -->
	<articleinfo>
	<title>Problem Report Handling Guidelines</title>

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	&tm-attrib.opengroup;
	&tm-attrib.general;
	</legalnotice>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>

	<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>repocopy (obsolete)</glossterm>
	<glossdef>
	<para>The resolution of the problem report is dependent on a
	repository copy, or repocopy, operation within the CVS
	repository which is awaiting completion.</para>

	<para>Given that all repositories now use Subversion, there is
	no need for this state anymore. Subversion has native
	support for copying and moving files.</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-unassigned">PRs not yet assigned to anyone.</link></para>
	</listitem>
	<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-unassigned">
	<title>Unassigned PRs</title>

	<para>When PRs arrive, they are initially assigned to a generic
	(placeholder) assignee. These are always prepended with
	<literal>freebsd-</literal>. The exact value for this default
	depends on the category; in most cases, it corresponds to a
	specific &os; mailing list. Here is the current list, with
	the most common ones listed first:</para>

	<table id="default-assignees-common">
	<title>Default Assignees — most common</title>
	<tgroup cols="3">
	<thead>
	<row>
	<entry>Type</entry>
	<entry>Categories</entry>
	<entry>Default Assignee</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>base system</entry>
	<entry>bin, conf, gnu, kern, misc</entry>
	<entry>freebsd-bugs</entry>
	</row>

	<row>
	<entry>architecture-specific</entry>
	<entry>alpha, amd64, arm, i386, ia64, powerpc, sparc64</entry>
	<entry>freebsd-<replaceable>arch</replaceable></entry>
	</row>

	<row>
	<entry>ports collection</entry>
	<entry>ports</entry>
	<entry>freebsd-ports-bugs</entry>
	</row>

	<row>
	<entry>documentation shipped with the system</entry>
	<entry>docs</entry>
	<entry>freebsd-doc</entry>
	</row>

	<row>
	<entry>&os; web pages (not including docs)</entry>
	<entry>www</entry>
	<entry>freebsd-www</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<table id="default-assignees-other">
	<title>Default Assignees — other</title>
	<tgroup cols="3">
	<thead>
	<row>
	<entry>Type</entry>
	<entry>Categories</entry>
	<entry>Default Assignee</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>advocacy efforts</entry>
	<entry>advocacy</entry>
	<entry>freebsd-advocacy</entry>
	</row>

	<row>
	<entry>&java.virtual.machine; problems</entry>
	<entry>java</entry>
	<entry>freebsd-java</entry>
	</row>

	<row>
	<entry>standards compliance</entry>
	<entry>standards</entry>
	<entry>freebsd-standards</entry>
	</row>

	<row>
	<entry>threading libraries</entry>
	<entry>threads</entry>
	<entry>freebsd-threads</entry>
	</row>

	<row>
	<entry>&man.usb.4; subsystem</entry>
	<entry>usb</entry>
	<entry>freebsd-usb</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>Do not be surprised to find that the submitter of the
	PR has assigned it to the wrong category. If you fix the
	category, do not forget to fix the assignment as well.
	(In particular, our submitters seem to have a hard time
	understanding that just because their problem manifested
	on an i386 system, that it might be generic to all of &os;,
	and thus be more appropriate for <literal>kern</literal>.
	The converse is also true, of course.)</para>

	<para>Certain PRs may be reassigned away from these generic
	assignees by anyone. There are several types of assignees:
	specialized mailing lists; mail aliases (used for certain
	limited-interest items); and individuals.</para>

	<para>For assignees which are mailing lists,
	please use the long form when making the assignment (e.g.,
	<literal>freebsd-foo</literal> instead of <literal>foo</literal>);
	this will avoid duplicate emails sent to the mailing list.</para>

	<note>
	<para>Since the list of individuals who have volunteered to
	be the default assignee for certain types of PRs changes
	so often, it is much more suitable for <ulink
	url="http://wiki.freebsd.org/AssigningPRs">the FreeBSD wiki</ulink>.
	</para>
	</note>

	<para>Here is a sample list of such entities; it is probably
	not complete.</para>

	<table id="common-assignees-base">
	<title>Common Assignees — base system</title>
	<tgroup cols="4">
	<thead>
	<row>
	<entry>Type</entry>
	<entry>Suggested Category</entry>
	<entry>Suggested Assignee</entry>
	<entry>Assignee Type</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>problem specific to the &arm; architecture</entry>
	<entry>arm</entry>
	<entry>freebsd-arm</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem specific to the &mips; architecture</entry>
	<entry>kern</entry>
	<entry>freebsd-mips</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem specific to the &powerpc; architecture</entry>
	<entry>kern</entry>
	<entry>freebsd-ppc</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with Advanced Configuration and Power
	Management (&man.acpi.4;)</entry>
	<entry>kern</entry>
	<entry>freebsd-acpi</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with Asynchronous Transfer Mode (ATM)
	drivers</entry>
	<entry>kern</entry>
	<entry>freebsd-atm</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with embedded or small-footprint &os;
	systems (e.g., NanoBSD/PicoBSD/FreeBSD-arm)</entry>
	<entry>kern</entry>
	<entry>freebsd-embedded</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with &firewire; drivers</entry>
	<entry>kern</entry>
	<entry>freebsd-firewire</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with the filesystem code</entry>
	<entry>kern</entry>
	<entry>freebsd-fs</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with the &man.geom.4; subsystem</entry>
	<entry>kern</entry>
	<entry>freebsd-geom</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with the &man.ipfw.4; subsystem</entry>
	<entry>kern</entry>
	<entry>freebsd-ipfw</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with Integrated Services Digital Network
	(ISDN) drivers</entry>
	<entry>kern</entry>
	<entry>freebsd-isdn</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>&man.jail.8; subsystem</entry>
	<entry>kern</entry>
	<entry>freebsd-jail</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with &linux; or SVR4 emulation</entry>
	<entry>kern</entry>
	<entry>freebsd-emulation</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with the networking stack</entry>
	<entry>kern</entry>
	<entry>freebsd-net</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with the &man.pf.4; subsystem</entry>
	<entry>kern</entry>
	<entry>freebsd-pf</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with the &man.scsi.4; subsystem</entry>
	<entry>kern</entry>
	<entry>freebsd-scsi</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with the &man.sound.4; subsystem</entry>
	<entry>kern</entry>
	<entry>freebsd-multimedia</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problems with the &man.wlan.4; subsystem and
	wireless drivers</entry>
	<entry>kern</entry>
	<entry>freebsd-wireless</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with &man.sysinstall.8; or
	&man.bsdinstall.8;</entry>
	<entry>bin</entry>
	<entry>freebsd-sysinstall</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with the system startup scripts
	(&man.rc.8;)</entry>
	<entry>kern</entry>
	<entry>freebsd-rc</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with VIMAGE or VNET functionality and
	related code</entry>
	<entry>kern</entry>
	<entry>freebsd-virtualization</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>problem with Xen emulation</entry>
	<entry>kern</entry>
	<entry>freebsd-xen</entry>
	<entry>mailing list</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<table id="common-assignees-ports">
	<title>Common Assignees — Ports Collection</title>
	<tgroup cols="4">
	<thead>
	<row>
	<entry>Type</entry>
	<entry>Suggested Category</entry>
	<entry>Suggested Assignee</entry>
	<entry>Assignee Type</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>problem with the ports framework
	(<emphasis>not</emphasis> with an individual port!)</entry>
	<entry>ports</entry>
	<entry>portmgr</entry>
	<entry>alias</entry>
	</row>

	<row>
	<entry>port which is maintained by apache@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>apache</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>port which is maintained by autotools@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>autotools</entry>
	<entry>alias</entry>
	</row>

	<row>
	<entry>port which is maintained by doceng@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>doceng</entry>
	<entry>alias</entry>
	</row>

	<row>
	<entry>port which is maintained by eclipse@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>freebsd-eclipse</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>port which is maintained by gecko@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>gecko</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>port which is maintained by gnome@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>gnome</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>port which is maintained by hamradio@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>hamradio</entry>
	<entry>alias</entry>
	</row>

	<row>
	<entry>port which is maintained by haskell@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>haskell</entry>
	<entry>alias</entry>
	</row>

	<row>
	<entry>port which is maintained by java@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>freebsd-java</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>port which is maintained by kde@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>kde</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>port which is maintained by mono@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>mono</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>port which is maintained by
	office@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>freebsd-office</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>port which is maintained by perl@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>perl</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>port which is maintained by python@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>freebsd-python</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>port which is maintained by ruby@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>freebsd-ruby</entry>
	<entry>mailing list</entry>
	</row>

	<row>
	<entry>port which is maintained by secteam@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>secteam</entry>
	<entry>alias</entry>
	</row>

	<row>
	<entry>port which is maintained by vbox@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>vbox</entry>
	<entry>alias</entry>
	</row>

	<row>
	<entry>port which is maintained by x11@FreeBSD.org</entry>
	<entry>ports</entry>
	<entry>freebsd-x11</entry>
	<entry>mailing list</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>Ports PRs which have a maintainer who is a ports committer
	may be reassigned by anyone (but note that not every &os;
	committer is necessarily a ports committer, so you cannot
	simply go by the email address alone.)
	</para>

	<para>For other PRs, please do not reassign them to individuals
	(other than yourself) unless you are certain that the assignee
	really wants to track the PR. This will help to avoid the
	case where no one looks at fixing a particular problem
	because everyone assumes that the assignee is already working
	on it.</para>

	<table id="common-assignees-other">
	<title>Common Assignees — Other</title>
	<tgroup cols="4">
	<thead>
	<row>
	<entry>Type</entry>
	<entry>Suggested Category</entry>
	<entry>Suggested Assignee</entry>
	<entry>Assignee Type</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>problem with GNATS itself (&man.send-pr.1;)</entry>
	<entry>bin</entry>
	<entry>bugmeister</entry>
	<entry>alias</entry>
	</row>

	<row>
	<entry>problem with GNATS web form</entry>
	<entry>www</entry>
	<entry>bugmeister</entry>
	<entry>alias</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	</section>

	<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 or bugmeister. 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>patched</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>A submitter sent a Cc: to a mailing list and someone
	followed up to that post instead of the email issued by
	GNATS after processing. The email to the list will not
	have the category/PRnumber tracking tag. (This is why we
	discourage submitters from doing this exact thing.)</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>When completing the &man.send-pr.1; template, the submitter
	set Confidential to <literal>yes</literal>. (Since we allow
	- anyone to mirror GNATS via <application>cvsup</application>,
	+ anyone to mirror GNATS via <application>rsync</application>,
	our PRs are public information. Security alerts should
	therefore not be sent via GNATS but instead via email to
	the Security Team.)</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 &a.bugfollowup;). 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 did not 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 does not 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. Spam messages
	that reach GNATS are promptly filed
	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, please do the following:</para>

	<itemizedlist>
	<listitem>
	<para>Set Category to <literal>junk</literal>.</para>
	</listitem>

	<listitem>
	<para>Set Confidential to <literal>no</literal>.</para>
	</listitem>

	<listitem>
	<para>Set Responsible to <literal>gnats-admin</literal>.</para>
	</listitem>

	<listitem>
	<para>Set State to <literal>closed</literal>.</para>
	</listitem>
	</itemizedlist>

	<para>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. If you merely close them without changing the
	category, they remain both in the master database and in
	any copies of the database mirrored through
	<application>cvsup</application>.</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>
	Index: projects/entities/en_US.ISO8859-1/articles/releng/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/releng/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/releng/article.xml (revision 41355)
	@@ -1,1148 +1,1051 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	<!ENTITY art.re.pkgs '<ulink url="&url.articles.releng-packages;/article.html">The Release Engineering of Third Party Packages</ulink>'>
	]>

	<article lang='en'>
	<title>&os; Release Engineering</title>
	<articleinfo>

	<!-- This paper was presented at BSDCon Europe in Brighton, UK on
	- November 11, 2001 -->
	+ November 11, 2001. -->
	+ <!-- The content in this paper was updated in March 2013 to
	+ reflect the current FreeBSD Release process. -->
	<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 &os; based products
	since 1997 at Walnut Creek CDROM, BSDi, and now Wind River Systems.
	&os; 4.4 was the first official release of &os; 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>

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	&tm-attrib.cvsup;
	&tm-attrib.intel;
	&tm-attrib.general;
	</legalnotice>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>

	<abstract>
	+ <para>
	+ <warning>
	+ <para>2013/02/26: This document is outdated and does not
	+ accurately describe the current release procedures of the
	+ &os; Release Engineering team. The &os; Release
	+ Engineering team is currently reviewing this document and
	+ will publish updated content soon.
	+ </para>
	+ </warning>
	+ </para>
	<para>This paper describes the approach used by the &os;
	release engineering team to make production quality releases
	of the &os; Operating System. It details the methodology
	used for the official &os; releases and describes the tools
	available for those interested in producing customized &os;
	releases for corporate rollouts or commercial
	productization.</para>
	</abstract>

	</articleinfo>

	<!-- Introduction -->
	<sect1 id="introduction">
	<title>Introduction</title>

	<para>The development of &os; is a very open process. &os; is
	comprised of contributions from thousands of people around the
	- world. The &os; Project provides anonymous
	- <acronym>CVS</acronym>[1] access to the general public so that
	+ world. The &os; Project provides
	+ Subversion
	+ <footnote>
	+ <simpara>
	+ Subversion, <ulink url="http://subversion.apache.org"></ulink>
	+ </simpara>
	+ </footnote>
	+ 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 &os;. 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[5]</emphasis> are responsible for the bulk of
	- &os; development. An elected <emphasis>core-team[6]</emphasis>
	+ access to the Subversion repository. These
	+ <ulink url="&url.articles.contributors;/article.html#staff-committers">committers</ulink>
	+ <footnote>
	+ <simpara>
	+ <ulink url="&url.articles.contributors;/article.html#staff-committers">FreeBSD committers</ulink>
	+ </simpara>
	+ </footnote>
	+ are responsible for the bulk of &os; development. An elected
	+ <ulink url="&url.base;/administration.html#t-core">Core Team</ulink>
	+ <footnote>
	+ <simpara>
	+ <ulink url="&url.base;/administration.html#t-core">&os; Core Team</ulink>
	+ </simpara>
	+ </footnote>
	of very senior developers provides some level of direction over
	the project.</para>

	<para>The rapid pace of <systemitem
	class="osname">&os;</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
	+ <emphasis>HEAD</emphasis> or <emphasis>trunk</emphasis> of our Subversion
	tree, known as <quote>&os;-CURRENT</quote> or
	<quote>-CURRENT</quote> for short.</para>

	<para>A more stable branch is maintained, known as
	<quote>&os;-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. &os;-CURRENT[7] is the <quote>bleeding-edge</quote> of
	+ Both branches live in a master Subversion repository on a machine
	+ maintained by the &os; Project.
	+ &os;-CURRENT is the <quote>bleeding-edge</quote> of
	&os; development where all new changes first enter the system.
	&os;-STABLE is the development branch from which major releases
	are made. Changes go into this branch at a different pace, and
	with the general assumption that they have first gone into
	&os;-CURRENT and have been thoroughly tested by our user
	community.</para>

	<para>In the interim period between releases, monthly snapshots are
	built automatically by the &os; Project build machines and made
	available for download from <systemitem
	class="resource">ftp://ftp.freebsd.org/pub/FreeBSD/snapshots/</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>[7] helps to keep
	+ with Subversion and <quote><command>make</command>
	+ <maketarget>buildworld</maketarget></quote>
	+ <footnote>
	+ <simpara>
	+ <ulink url="&url.books.handbook;/makeworld.html">Rebuilding "world"</ulink>
	+ </simpara>
	+ </footnote>
	+ helps to keep
	&os;-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>[8] database
	+ <application class="software">GNATS</application> database
	+ <footnote>
	+ <simpara>
	+ GNATS: The GNU Bug Tracking System
	+ <ulink url="http://www.gnu.org/software/gnats"></ulink>
	+ </simpara>
	+ </footnote>
	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>.</para>
	-
	+
	<para>To service our most conservative users, individual release
	branches were introduced with &os; 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
	+ In addition to source updates via Subversion, binary patchkits are
	available to keep systems on the
	<emphasis>RELENG_<replaceable>X</replaceable>_<replaceable>Y</replaceable></emphasis>
	branches updated.</para>
	-
	+
	<sect2>
	<title>What this article describes</title>
	-
	+
	<para>The following sections of this article describe:</para>
	-
	+
	<variablelist>
	<varlistentry>
	<term><xref linkend="release-proc"/></term>
	-
	+
	<listitem>
	<para>The different phases of the release engineering process
	leading up to the actual system build.</para>
	</listitem>
	</varlistentry>
	-
	+
	<varlistentry>
	<term><xref linkend="release-build"/></term>
	-
	+
	<listitem>
	<para>The actual build process.</para>
	</listitem>
	</varlistentry>
	-
	+
	<varlistentry>
	<term><xref linkend="extensibility"/></term>

	<listitem>
	<para>How the base release may be extended by third parties.</para>
	</listitem>
	</varlistentry>
	-
	+
	<varlistentry>
	<term><xref linkend="lessons-learned"/></term>

	<listitem>
	<para>Some of the lessons learned through the release of &os; 4.4.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><xref linkend="future"/></term>

	<listitem>
	<para>Future directions of development.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect2>
	</sect1>

	<!-- Release Process -->
	<sect1 id="release-proc">
	<title>Release Process</title>

	<para>New releases of &os; are released from the -STABLE branch
	at approximately four month intervals. The &os; 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 id="rel-branch">
	<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
	+ <note>
	+ <para>In all examples below, <literal>&dollar;FSVN</literal>
	+ refers to the location of the &os; Subversion repository,
	+ <literal>svn+ssh://svn.freebsd.org/base/</literal>.</para>
	+ </note>
	+
	+ <para>The layout of &os; branches in Subversion is
	+ described in the <ulink url="&url.articles.committers-guide;/subversion-primer.html#subversion-primer-base-layout">Committer's Guide</ulink>.
	+ The first step in creating a branch is to
	+ identify the revision of the
	+ <literal>stable/<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>
	+ <screen>&prompt.root; <userinput>svn log -v $FSVN/stable/9</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>
	+ <para>The next step is to create the <emphasis>release branch</emphasis>
	+ </para>
	+
	+ <screen>&prompt.root; <userinput>svn cp $FSVN/stable/9@REVISION $FSVN/releng/9.2</userinput></screen>

	- <screen>/usr/src&prompt.root; <userinput>cvs rtag -rRELENG_4 RELENG_4_8_BP src</userinput></screen>
	+ <para>This branch can be checked out:</para>
	+
	+ <screen>&prompt.root; <userinput>svn co $FSVN/releng/9.2 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>
	+ <para>Creating <literal>releng</literal> branch and <literal>release</literal>
	+ tags are restricted to
	+ <ulink url="&url.base;/administration.html#t-subversion">Subversion administrators</ulink>
	+ and the <ulink url="&url.base;/administration.html#t-re">Release Engineering Team</ulink>.
	+ </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 &os; Project releases.</para>
	- </sidebar>
	-
	<mediaobject>
	<imageobject>
	<imagedata fileref="branches-head" align="center"/>
	</imageobject>

	<textobject>
	<phrase>&os; Development Branch</phrase>
	</textobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="branches-releng3" align="center"/>
	</imageobject>

	<textobject>
	<phrase>&os; 3.x STABLE Branch</phrase>
	</textobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="branches-releng4" align="center"/>
	</imageobject>

	<textobject>
	<phrase>&os; 4.x STABLE Branch</phrase>
	</textobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="branches-releng5" align="center"/>
	</imageobject>

	<textobject>
	<phrase>&os; 5.x STABLE Branch</phrase>
	</textobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="branches-releng6" align="center"/>
	</imageobject>

	<textobject>
	<phrase>&os; 6.x STABLE Branch</phrase>
	</textobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="branches-releng7" align="center"/>
	</imageobject>

	<textobject>
	<phrase>&os; 7.x STABLE Branch</phrase>
	</textobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="branches-releng8" align="center"/>
	</imageobject>

	<textobject>
	<phrase>&os; 8.x STABLE Branch</phrase>
	</textobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="branches-releng9" align="center"/>
	</imageobject>

	<textobject>
	<phrase>&os; 9.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 &os;:</para>

	<itemizedlist>
	<listitem>
	<para><filename>doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml
	</filename></para>
	</listitem>

	<listitem>
	<para><filename>doc/en_US.ISO8859-1/books/porters-handbook/book.xml
	</filename></para>
	</listitem>

	<listitem>
	<para><filename>doc/share/xml/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/xml/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/xml/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/man.xml</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.xml
	</filename></para>
	</listitem>

	<listitem>
	<para><filename>src/release/doc/en_US.ISO8859-1/errata/article.xml
	</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[4]. This information is currently kept in
	+ for the Ports Collection.
	+ <footnote>
	+ <simpara>
	+ &os; Ports Collection
	+ <ulink url="http://www.FreeBSD.org/ports"></ulink>
	+ </simpara>
	+ </footnote>
	+ This information is currently kept in
	<filename>src/usr.sbin/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>doc/share/images/articles/releng/branches-releng<replaceable>X</replaceable>.pic</filename></para>
	</listitem>

	<listitem>
	<para><filename>www/share/xml/advisories.xml</filename></para>
	</listitem>

	<listitem>
	<para><filename>www/share/xml/includes.release.xml</filename></para>
	</listitem>

	<listitem>
	<para><filename>www/share/xml/includes.release.xsl</filename></para>
	</listitem>

	<listitem>
	<para><filename>www/en/releases/*</filename></para>
	</listitem>

	<listitem>
	<para><filename>www/en/releng/index.xml</filename></para>
	</listitem>

	<listitem>
	<para><filename>www/en/news/news.xml</filename></para>
	</listitem>

	<listitem>
	<para><filename>www/en/search/web.atoz</filename></para>
	</listitem>

	<listitem>
	<para><filename>src/share/misc/bsd-family-tree</filename></para>
	</listitem>

	</itemizedlist>

	</sect3>

	- <sect3 id="versionbump-major">
	- <title>Preparing a new major release branch
	- (RELENG_<replaceable>X</replaceable>)</title>
	-
	- <para>When a new major release branch, such as
	- <literal>RELENG_6</literal> is branched from HEAD, some
	- additional files must be updated before releases can be made
	- from this new branch.</para>
	-
	- <itemizedlist>
	- <listitem>
	- <para><filename>src/share/examples/cvsup/stable-supfile</filename>
	-- must be updated to point to the new -STABLE branch, when
	-applicable.</para>
	- </listitem>
	- </itemizedlist>
	-
	- </sect3>
	-
	<sect3>
	- <title>Creating Release Tags</title>
	+ <title>Creating the Release Tag</title>

	<para>When the final release is ready, the following command
	- will create the <literal>RELENG_4_8_0_RELEASE</literal>
	+ will create the <literal>release/9.2.0</literal>
	tag.</para>

	- <screen>/usr/src&prompt.root; <userinput>cvs rtag -rRELENG_4_8 RELENG_4_8_0_RELEASE src</userinput></screen>
	+ <screen>&prompt.root; <userinput>svn cp $FSVN/releng/9.2 $FSVN/release/9.2.0</userinput></screen>

	<para>The Documentation and Ports managers are responsible for
	- tagging the respective trees with the <literal>RELEASE_4_8_0</literal>
	+ tagging their respective trees with the <literal>tags/RELEASE_9_2_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 is not 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. &os; releases must
	- always be reproducible. Local hacks in the release
	- engineer's environment are not acceptable.</para>
	+ <sidebar>
	+ <para>When the Subversion <command>svn cp</command> command
	+ is used to create a <emphasis>release tag</emphasis>,
	+ this identifies the source at a specific point in time.
	+ By creating tags, we ensure that future release builders
	+ will always be able to use the exact same source we used to create the
	+ official &os; Project releases.</para>
	+ </sidebar>
	+
	+
	</sect3>
	</sect2>
	</sect1>

	<!-- Release Building -->
	<sect1 id="release-build">
	<title>Release Building</title>

	<para>&os; <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
	+ everyone, since we offer Subversion access !
	+ See the
	+ <ulink url="&url.books.handbook;/svn.html">Subversion section
	+ in the Handbook</ulink> for
	details.) The <emphasis>only</emphasis> special requirement is
	that the &man.md.4; device must be available. If the
	device is not loaded into your kernel, then the kernel module
	should be automatically loaded when &man.mdconfig.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
	+ to build a release are available from the Subversion repository in
	<filename>src/release</filename>. These tools aim to provide a
	consistent way to build &os; 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>
	+ CDROM or DVD, and an FTP install directory. &man.release.7; fully
	+ documents the <command>src/release/generate-release.sh</command>
	+ script which is used to build a release. <command>generate-release.sh</command>
	+ is a wrapper around the Makefile target: <command>make release</command>.</para>

	<sect2>
	- <title><command>make release</command></title>
	+ <title>Building a Release</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>
	+ <para>&man.release.7; documents the exact commands required to
	+ build a &os; release. The following sequences of commands can build
	+ an 9.2.0 release:</para>

	- <itemizedlist>
	- <listitem>
	- <para><makevar>CHROOTDIR</makevar> - The directory to be used as the
	- chroot environment for the entire release build.</para>
	- </listitem>
	+ <screen>&prompt.root; <userinput>cd /usr/src/release</userinput></screen>
	+ <screen>&prompt.root; <userinput>sh generate-release.sh release/9.2.0 /local3/release</userinput></screen>

	- <listitem>
	- <para><makevar>BUILDNAME</makevar> - The name of the release to be
	- built.</para>
	- </listitem>
	+ <para>After running these commands, all prepared release
	+ files are available in <filename>/local3/release/R</filename>
	+ directory.</para>

	- <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> (aka -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 &os; 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,
	+ <para>Checkout from Subversion 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>

	<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">&os; Ports
	collection</ulink> is a collection of over &os.numports;
	third-party software packages available for &os;. The &a.portmgr;
	is responsible for maintaining a consistent ports tree that can be used
	to create the binary packages that accompany official &os;
	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 &os; 4.4, the &os; 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, 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 a custom kernel of &os; is to be included, then
	&man.sysinstall.8; and &man.release.7; must be updated to
	include installation instructions. The relevant code is contained
	in <filename>src/release</filename> and <filename>src/usr.sbin/sysinstall</filename>.
	Specifically, the file <filename>src/release/Makefile</filename>, and
	<filename>dist.c</filename>, <filename>dist.h</filename>,
	<filename>menus.c</filename>, <filename>install.c</filename>, and
	<filename>Makefile</filename> will need to be updated under
	<filename>src/usr.sbin/sysinstall</filename>. Optionally, you may choose
	to update <filename>sysinstall.8</filename>.</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 &os; 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 &os;. 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>

	<sect3>
	<title>Multi-volume support</title>

	<para><application>Sysinstall</application> supports multiple
	volume package installations. This requires that each disc
	have an <filename>INDEX</filename> file containing all of the
	packages on all volumes of a set, along with an extra field
	that indicates which volume that particular package is on.
	Each volume in the set must also have the
	<literal>CD_VOLUME</literal> variable set in the
	<filename>cdrom.inf</filename> file so that sysinstall can
	tell which volume is which. When a user attempts to install a
	package that is not on the current disc, sysinstall will
	prompt the user to insert the appropriate one.</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
	&os; 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 &os; FTP sites, please see the <ulink
	url="&url.articles.hubs;/">Mirroring &os;</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 &os; ISOs to a replicator
	and quality assurance measures to be taken.</para>
	</sect2>

	</sect1>

	<!-- Extensibility -->
	<sect1 id="extensibility">
	<title>Extensibility</title>

	<para>Although &os; 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 &os; with non-trivial changes, we
	encourage you to document your enhancements! The &os; 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 cannot
	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 &os; 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[12] 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/usr.sbin/sysinstall/install.cfg</filename>.</para>
	+ with &intel; PXE
	+ <footnote>
	+ <simpara>
	+ <ulink url="&url.books.handbook;/network-pxe-nfs.html"></ulink>
	+ </simpara>
	+ </footnote>
	+ to bootstrap systems from the network.
	+ </para>
	</sect2>
	</sect1>

	<!-- Lessons Learned -->
	<sect1 id="lessons-learned">
	<title>Lessons Learned from &os; 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 &os; 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 &os; release should not be sacrificed for
	any self-imposed deadlines or target release dates. The &os;
	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 &os; 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 &os;
	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 &os;.</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. The libh project was one
	such project that aimed 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 &os; 4.4 and also for all of his work
	throughout the years making &os; what it is today. Of course
	the release would not have been possible without all of the
	release-related work done by &a.asami.email;, &a.steve.email;, &a.bmah.email;, &a.nik.email;,
	&a.obrien.email;, &a.kris.email;, &a.jhb.email; and the rest of the &os; development
	community. I would also like to thank &a.rgrimes.email;, &a.phk.email;, and others
	who worked on the release engineering tools in the very early days
	of &os;. This article was influenced by release engineering
	- documents from the CSRG[13], the NetBSD Project[10], and John
	- Baldwin's proposed release engineering process notes[11].</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>
	+ documents from the CSRG
	+ <footnote>
	+ <simpara>
	+ 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>
	+ </simpara>
	+ </footnote>
	+ ,
	+ the NetBSD Project ,
	+ <footnote>
	+ <simpara>
	+ NetBSD Developer Documentation: Release Engineering
	+ <ulink url="http://www.NetBSD.org/developers/releng/index.html"></ulink>
	+ </simpara>
	+ </footnote>
	+ , and John
	+ Baldwin's proposed release engineering process notes.
	+ <footnote>
	+ <simpara>
	+ John Baldwin's &os; Release Engineering Proposal
	+ <ulink url="http://people.FreeBSD.org/~jhb/docs/releng.txt"></ulink>
	+ </simpara>
	+ </footnote>
	</para>
	-
	- <para>[3] <ulink url="http://pointyhat.FreeBSD.org"></ulink></para>
	-
	- <para>[4] &os; Ports Collection
	- <ulink url="http://www.FreeBSD.org/ports"></ulink></para>
	-
	- <para>[5] &os; Committers <ulink
	- url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/contributors/staff-committers.html"></ulink>
	- </para>
	-
	- <para>[6] &os; Core Team
	- <ulink url="&url.base;/administration.html#t-core"></ulink></para>
	-
	- <para>[7] &os; Handbook
	- <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook"></ulink>
	- </para>
	-
	- <para>[8] GNATS: The GNU Bug Tracking System
	- <ulink url="http://www.gnu.org/software/gnats"></ulink>
	- </para>
	-
	- <para>[9] &os; PR Statistics
	- <ulink url="http://www.FreeBSD.org/prstats/index.html"></ulink></para>
	-
	- <para>[10] NetBSD Developer Documentation: Release Engineering
	- <ulink url="http://www.NetBSD.org/developers/releng/index.html"></ulink>
	- </para>
	-
	- <para>[11] John Baldwin's &os; Release Engineering Proposal
	- <ulink url="http://people.FreeBSD.org/~jhb/docs/releng.txt"></ulink>
	- </para>
	-
	- <para>[12] PXE Jumpstart Guide
	- <ulink
	- url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/pxe/index.html"></ulink>
	- </para>
	-
	- <para>[13] 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>
	Index: projects/entities/en_US.ISO8859-1/articles/wp-toolbox/article.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/articles/wp-toolbox/article.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/articles/wp-toolbox/article.xml (revision 41355)
	@@ -1,461 +1,460 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	<!ENTITY ports "Ports Collection">
	<!ENTITY os.ports "&os; &ports;">
	<!ENTITY frisbee "<application>Frisbee</application>">
	<!ENTITY ghost "<application>Ghost</application>">
	<!ENTITY nessus "<application>Nessus</application>">
	]>

	<article lang='en'>
	<title>Creating a Software Testing Environment Using &os;</title>
	<articleinfo>

	<authorgroup>
	<author>
	<firstname>Chris</firstname>
	<surname>McMahon</surname>
	<affiliation>
	<address><email>christopher.mcmahon@gmail.com</email></address>
	</affiliation>
	</author>
	</authorgroup>

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	- &tm-attrib.cvsup;
	&tm-attrib.intel;
	&tm-attrib.microsoft;
	&tm-attrib.symantec;
	&tm-attrib.general;
	</legalnotice>

	<pubdate>$FreeBSD$</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>

	<abstract><para>A slightly altered version of this paper was first
	published in the Pacific Northwest Software Quality Conference
	Proceedings, 2005.</para></abstract>

	</articleinfo>


	<sect1 id="overview">
	<title>Overview</title>

	<para>From late 2003 until early 2005, I was a tester in an
	all-&windows; environment. Although unlikely on the face of it,
	&os; became a valuable test tool platform in that context.
	&os; contains useful and powerful applications for any tester
	in any environment.</para>

	<para>Unlike Linux, &os; is a single monolithic project, rather
	than a collection of disparate parts assembled into a
	distribution. And the most attractive part of &os; for a
	software tester is the &os.ports;—a very large,
	managed set of software applications with a single, simple, and
	uniform installation procedure.</para>

	<para>This paper describes several software test tools from the
	&os.ports; that I used to test software and
	systems in an all-Windows environment.</para>

	</sect1>

	<sect1 id="challenge">
	<title>The Challenge</title>

	<para>Software testing environments are radically more complex
	than software development environments. Interconnected systems
	to test, network entities, databases, and filesystems present
	challenges to testers that developers can, for the most part, mock
	out and essentially ignore. Software testers need more tools,
	and more complex tools, than do software developers.</para>

	<para>On the other hand, software development tools are much more
	highly evolved than software testing tools. There is no Eclipse,
	or IntelliJ, or even Visual Studio aimed at testing. Testers
	struggle and scratch to find tools appropriate to their test
	environments and appropriate to their Systems Under Test (SUTs).</para>

	<para>Every test environment is different. Finding appropriate
	test tools is challenging. And when a tester has identified a
	set of useful tools, introducing them to the test environment
	and integrating them with the test environment is a challenge.</para>

	</sect1>

	<sect1 id="freebsd-solution">
	<title>The &os; Solution</title>

	<sect2 id="freebsd-intro">
	<title>Introduction</title>

	<para>The set of tools available with the &os; Operating
	System is amazing. The &os; <ulink
	url="http://www.freebsd.org/ports">&ports;</ulink>
	contains more than thirteen thousand separate applications,
	all of which have a standard installation procedure and
	conform to a set of guidelines that make them reliable without
	the need to manage dependencies, appropriate versions, and all
	of the other problems that affect even the most well-managed
	Linux distribution or the various versions of Microsoft
	Windows. The monolithic nature of &os; and the &os.ports;
	removes much of the trouble of integrating
	tools with the test environment, regardless of the OS under
	which the SUT runs. &os; is a highly evolved server
	environment, and contains so many reliable applications, that
	every tester should consider adding a &os; machine (or
	several) to their test environment.</para>

	<para>Of course, all of the applications available in the
	&os.ports; will not be appropriate for any single
	test environment. Some of the obvious choices for software and
	systems testing are the six hundred or so system utilities,
	the more than one thousand network tools, and the fifty-odd
	benchmarking tools. Whether your test environment is Windows,
	UNIX, Linux, Mac OS, &os; itself, or some combination of
	any of them, &os; and the &os.ports; is a
	great place to look first.</para>

	</sect2>

	<sect2 id="freebsd-ports">
	<title>How To Use The Ports System</title>

	<para>Installing an application from the &os.ports; is a simple matter of: </para>

	<screen>&prompt.root; <userinput>cd /usr/ports/foo</userinput>
	&prompt.root; <userinput>make install</userinput></screen>

	<para>and the system does the rest. It reports build status and
	test status, and installs all the relevant documentation as
	well. This aspect of &os; is very attractive to a tester,
	who typically is pressed for time!</para>
	</sect2>

	<sect2 id="freebsd-testing">
	<title>&os; For Testing</title>

	<para>The test environment should be more stable than the SUT.
	Once the tester decides to use the tools available on &os;,
	&os;'s long record of reliability makes it an easy choice
	for a test tools platform.</para>

	<para>My own introduction to &os; occurred when I was hired
	by a major vendor of large-scale network security video
	services to be their network-testing person in an all-Windows
	environment. My first assignment was to replace the obsolete,
	buggy, disk imaging system. I chose to do that with an Open
	Source disk imaging system called <ulink
	url="http://www.cs.utah.edu/flux/papers/frisbee-usenix03-base.html">&frisbee;</ulink>
	which was implemented originally on &os;. I built the
	system—a feature-for-feature replacement for an expensive
	proprietary system—but we never actually used it in our
	production system.</para>

	<para>In the meantime, I had discovered the &os.ports;
	and started to use some of those tools for testing;
	and I had discovered the power of disk imaging with &frisbee;,
	especially for smoke testing and installation testing; and
	&os; became a permanent part of my test lab. The test lab
	I built, and the &os; systems I created still exist, and
	still provide value to the testers there.</para>

	</sect2>

	<sect2 id="freebsd-collab">
	<title>&os; For Collaboration: Twiki</title>

	<para>A wiki is a simple set of web pages to allow many users to
	share information and collaborate on any sort of documents.
	<ulink url="http://twiki.org">Twiki</ulink> is a wiki fine-tuned for
	document management. It has built-in version control and
	security implemented at the user/password level. I used it
	for requirements management and traceability.</para>

	<para>The company I worked for managed their requirements in a
	proprietary tool with a truly byzantine hierarchical
	structure. Although the tool was fine for generating
	requirements, it was horrible for testing. Also
	unfortunately, the tool supported very few export mechanisms.
	From the proprietary tool, I had to:</para>

	<itemizedlist>
	<listitem><simpara>Export to Access</simpara></listitem>
	<listitem><simpara>Export from Access to Excel</simpara></listitem>
	<listitem><simpara>Export from Excel to a delimited file</simpara></listitem>
	<listitem><simpara>Import the delimited file to the wiki by means of a Perl script</simpara></listitem>
	</itemizedlist>

	<para>And in Twiki I was able to implement version control,
	traceability, and test coverage, all features missing from the
	proprietary tool. This gave me a remarkable ability to trace
	requirements coverage with my tests. Having imported a
	complex hierarchy of sets of requirements, I could use Twiki's
	simple markup features to show each requirement as tested,
	passed, or failed. I could attach test documentation to wiki
	pages, and since I had already scripted the process, it was
	easy to update the requirements as they changed. And Twiki
	itself handled version control for such updates.</para>

	<para>As with all of the examples in this paper, installing
	Twiki on &os; is fairly simple. It takes just a few
	minutes on a &os; system. However, if you want to use Twiki
	on a Microsoft Windows platform, I strongly suggest you read
	the Twiki documentation extremely carefully. I know someone
	who installed Twiki on Windows, and it took him several days.
	Twiki on Windows requires not only knowledge of Windows, but
	also deep knowledge of Cygwin and Perl.</para>

	<para>Furthermore, at one point in the project I had to migrate
	my wiki from a machine running &os; 4.8 to one running
	&os; 5.3. The migration consisted merely of installing
	Twiki on &os; 5.3; using <command>tar</command> on the &os; 4.8
	machine to gather all of the Twiki data files specific to my
	testing; FTPing the gathered files to the new &os; 5.3
	machine; and untarring the file. The complete set of Twiki
	documents migrated with no issues or problems at all. That is
	the power of a unified system like &os;.</para>
	</sect2>

	<sect2 id="freebsd-frisbee">
	<title>&os; For Disk Imaging: Frisbee</title>

	<para>A disk imaging system is a mechanism for saving and
	restoring all of the data on a physical disk. The most
	popular commercial system for doing this is probably the
	product &ghost;™ from Symantec.</para>

	<para>The &frisbee; enterprise disk imaging system mentioned above
	had a lot of features I never implemented in the test lab.
	Using &frisbee; and an Open Source tool called <application>PXELINUX</application>, I was
	able to:</para>

	<itemizedlist>
	<listitem><simpara>Boot the Windows client machines from the network</simpara></listitem>
	<listitem><simpara>Make an image of the client</simpara></listitem>
	<listitem><simpara>Update the BIOS on the client</simpara></listitem>
	<listitem><simpara>Lay down an existing image on the client machine</simpara></listitem>
	<listitem><simpara>Make a set of restore CDs for the client</simpara></listitem>
	</itemizedlist>

	<para>In the test lab, I only needed to boot from the &frisbee; CD,
	make an image, or lay down an image on the client machine.
	Both &frisbee; and proprietary imaging systems allow the user to
	image individual drives on the client, but I never had a need
	to do this.</para>

	<para>Installation testing was a large part of my duties at the
	company where I used &os;. To do this testing, I would
	typically use &frisbee; to make an image of a machine containing
	only a Windows OS, install the SUT, and run a smoke test. The
	smoke test typically left the test machine in a very bad
	state. But instead of having to painstakingly clean up the
	mess left by the failed installation, I simply re-imaged the
	machine in question with the bare OS image and started over.
	A typical re-image containing only the Windows OS and a few
	test tools took less than three minutes. Using &frisbee;, we
	could run smoke tests on about six builds per day; before
	&frisbee;, we could run smoke tests on about three builds per
	week.</para>

	<para>Of course, &ghost; or other proprietary tools also image
	machines quickly under these circumstances: once you buy the
	tool, license the software, install it on an appropriate
	server, and configure it properly. I prefer &frisbee; to &ghost;
	because: &frisbee; is marginally faster; &frisbee; is very easy to
	install on &os;; and &frisbee; is very efficient. Adding a
	couple of small Perl scripts to the normal &frisbee;
	distribution gave me an imaging environment tailored for the
	test lab.</para>

	<para>I also used &frisbee; to preserve the state of a machine
	after I had uncovered particularly complex defects. That is,
	if it took a large effort (many steps and/or a long duration
	of time) to demonstrate a defect, I could make an image of the
	machine at the point at which the defect was visible, and
	restore the image at will to demonstrate the defect to
	developers or managers.</para>
	</sect2>

	<sect2 id="freebsd-nessus">
	<title>&os; Security Testing: &nessus;</title>

	<para>Whenever you have more than one entity on a network, and
	whenever you expose a server to the wider Internet, security
	of the machine itself is always a concern. <ulink
	url="http://www.nessus.org">&nessus;</ulink> is an Open Source
	remote vulnerability scanner for security and penetration
	testing that consistently is rated among the top products of
	its type throughout the security industry.</para>

	<para>&nessus; probes a remote machine over the network for
	security vulnerabilities. It does a port scan, finds which
	ports are open, and investigates the software that has those
	ports open for a huge number of security risks, for all major
	OSs. It generates detailed reports in a number of formats
	that anyone can understand. The number of security probes
	available in the default installation of &nessus; is very large,
	but sophisticated security and penetration testers take
	advantage of NASL, the &nessus; Attack Scripting Language, to
	craft their own attacks using &nessus;' available features.</para>

	<para>Of interest is that, while &nessus; is a free download for
	UNIX-like systems (and is available in the &ports; of
	&os;), it is available on Windows only as a commercial
	product from a company called <emphasis>Tenable</emphasis>. The Tenable product is
	<application>NeWT</application>, <quote>Nessus on Windows Technology</quote>.</para>
	</sect2>

	<sect2 id="freebsd-network">
	<title>&os; Network Tools</title>

	<para>&os; is most widely used as a robust server platform.
	It follows, then, that tools related to network analysis and
	performance will be highly evolved on &os;. Here is a
	brief description of network diagnostic tools that I found
	invaluable in testing in a networked environment.</para>

	<para>From the name, one would assume that <ulink
	url="http://www.ntop.org">ntop</ulink> emulates the functions of
	the UNIX &man.top.1; command, but for the network
	rather than for the local machine. Perhaps the first version
	did; currently, <application>ntop</application> is capable of providing detailed
	information about a huge number of hosts and their status and
	activities on the network.</para>

	<para>For testing, two features I found very powerful: at a high
	level, <application>ntop</application> shows the amount of network
	traffic on the entire network segment minute-by-minute,
	hour-by-hour, and day-by-day in a graphical format. Also,
	<application>ntop</application> shows information about recent connections between
	individual hosts on the network.</para>

	<para>It is easy to see traffic trends on the network as they
	are occurring; also, if something anomalous appears, <application>ntop</application>
	records detailed information about network connections between
	hosts, including the ports over which the connection happened.
	This was critically important when analyzing software
	issues. If <application>ntop</application> showed a period of time for which traffic was
	particularly high, I would find out which host was generating
	the traffic. I would examine the software running on that
	host, over that port. Often it was a new build with a
	bug.</para>

	<para><ulink url="http://ettercap.sourceforge.net">Ettercap</ulink> is
	a tool for ARP poisoning which can also decipher passwords on
	the fly and corrupt IP traffic by means of a Man In The Middle
	(MITM) attack. However, I used <application>Ettercap</application> as a performance tool.
	In my test labs, all of my &os; machines ran on discarded
	hardware, Pentium II processors. I found that when I used
	<application>Ettercap</application> to sniff traffic between two hosts, the lack of
	processing power caused <application>Ettercap</application> on the slow MITM machine to
	start dropping packets, making it look to the client machine
	in the SUT as if there was interference or other trouble on
	the network. And by varying the load on the &os; machine,
	I could in fact control the number of packets being dropped:
	running <application>Ettercap</application> and the UNIX <command>yes</command> utility
	caused 100% packet loss.</para>

	<para>This was my most creative use of a &os; tool for
	testing. In a more straightforward application, any time a
	tester needs to eavesdrop on traffic between two hosts on a
	network, <application>Ettercap</application> is an excellent choice because of its power
	and ease of use.</para>

	<para>Perl gets a special mention here because Perl's network
	utilities are outstandingly good compared to other
	languages. Perl <literal>Net::*</literal> modules and
	<literal>IO::Socket::*</literal> modules are robust and
	powerful—but they often fail to compile on Windows. It is
	the ease of use of Perl's network utilities on &os; that
	gets Perl the mention in this section.</para>

	<para>I use Perl's network utilities to impersonate network
	clients and servers for test purposes. On one occasion, I was
	required to test software that was a client to an interface on
	the <emphasis>New York Stock Exchange</emphasis>. Unfortunately, the NYSE test
	server was down about nine days out of ten. I wrote a little
	network server in Perl to emulate simple functions of the NYSE
	server in order to test the client software.</para>

	<para>On another occasion, I had to test some functions on a web
	server. It was not difficult to write a simple Perl HTTP
	client to validate that the server was functioning properly.</para>

	<para>I have also used Perl to validate the output from a server
	sending to a multicast address. I wrote a simple Perl
	multicast client on &os; to monitor the traffic on a
	multicast address. Lincoln Stein's excellent
	<literal>IO::Socket::Multicast</literal> module made it easy.
	(Note: I never got <literal>IO::Socket::Multicast</literal> to
	compile on Windows. I tried it on Windows 2000 and on Windows
	XP.)</para>
	</sect2>
	</sect1>

	<sect1 id="conclusion">
	<title>Conclusion</title>

	<para>I used tools from the &os.ports; in four
	areas: in the network, where the operating system has very
	little impact on how software behaves; for remote security
	testing and performance testing in order to manipulate remote
	machines over the network, regardless of the operating system;
	for disk imaging of Windows, Linux, and &os; machines; and on
	the webserver, where Twiki was my collaboration tool of choice.</para>

	<para>Because the installation procedure for all of these tools is
	standard, I spent relatively little time installing and
	configuring my tools. Because all the tools were hosted on a
	single platform, I had all of my configuration and diagnostic
	information located in just a few places. I kept all of my
	potentially dangerous security tools on a single machine, which
	made my presence on the network tolerable to the company's
	network management staff. And the compatibility between &os;
	versions made it fairly simple to upgrade and to manage multiple
	&os; machines. And of course, I could rely on the
	correctness of my test results, because the system itself is so
	reliable.</para>

	<para>I have tried using Linux in a similar way, but my experience
	is that package management quickly becomes tedious if not
	overwhelming. The &os.ports; handled that for me.
	And many of these tools are simply not available on Microsoft
	Windows. And when they (or their equivalents) are available,
	their cost, both financial and in terms of overhead, was simply
	too high.</para>

	<para>&os;'s simple installation procedures and robust &ports;
	makes it easy to experiment with the huge number of
	tools available. I often find myself browsing the &ports;
	looking for interesting applications to install, just
	to see how they work. (I found <application>Ettercap</application> by browsing the &ports;,
	a tool that became very useful very quickly.) It
	became clear that the more tools I used on &os;, the more
	economical became the management of those tools.</para>

	<para>The next time you need to reach into your toolbox for some
	sophisticated, reliable, and powerful testing tools, I hope you
	find them in &os;.</para>
	</sect1>

	<!--
	<sect1>
	<title>Biography</title>

	<para>Chris McMahon has been for nearly a decade a tester of library
	software, telecom, stock trading, and networked video systems. He
	has published a number of articles aimed at technical testers, but
	his true career is at being an enthusiastic beginner. Chris works
	for ThoughtWorks, Inc. as a tester, and can be reached at
	christopher.mcmahon@gmail.com.</para>
	</sect1>
	-->

	</article>
	Index: projects/entities/en_US.ISO8859-1/books/arch-handbook/book.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/arch-handbook/book.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/arch-handbook/book.xml (revision 41355)
	@@ -1,182 +1,182 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	<!ENTITY % chapters SYSTEM "chapters.ent">
	%chapters;
	<!ENTITY % mac-entities SYSTEM "mac.ent">
	%mac-entities;
	]>

	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<book lang='en'>
	<bookinfo>
	<title>&os; Architecture Handbook</title>

	<corpauthor>The FreeBSD Documentation Project</corpauthor>

	<pubdate>August 2000</pubdate>

	<copyright>
	<year>2000</year>
	<year>2001</year>
	<year>2002</year>
	<year>2003</year>
	<year>2004</year>
	<year>2005</year>
	<year>2006</year>
	<year>2012</year>
	<year>2013</year>
	<holder>The FreeBSD Documentation Project</holder>
	</copyright>

	&trademarks;
	&legalnotice;

	<releaseinfo>$FreeBSD$</releaseinfo>

	<abstract>
	- <para>Welcome to the &os; Architecture Handbook. This manual is a
	+ <para>Welcome to the &os; Architecture Handbook. This manual is
	+ a
	<emphasis>work in progress</emphasis> and is the work of many
	individuals. Many sections do not yet exist and some of those
	that do exist need to be updated. If you are interested in
	helping with this project, send email to the &a.doc;.</para>

	<para>The latest version of this document is always available
	- from the <ulink url="&url.base;/index.html">FreeBSD World
	- Wide Web server</ulink>. It may also be downloaded in a
	- variety of formats and compression options from the <ulink
	- url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP
	- server</ulink> or one of the numerous <ulink
	- url="&url.books.handbook;/mirrors-ftp.html">mirror
	- sites</ulink>.</para>
	+ from the <ulink url="&url.base;/index.html">FreeBSD World
	+ Wide Web server</ulink>. It may also be downloaded in a
	+ variety of formats and compression options from the <ulink
	+ url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP server</ulink>
	+ or one of the numerous <ulink
	+ url="&url.books.handbook;/mirrors-ftp.html">mirror sites</ulink>.</para>
	</abstract>
	</bookinfo>

	<part id="kernel">
	<title>Kernel</title>

	&chap.boot;
	&chap.locking;
	&chap.kobj;
	&chap.jail;
	&chap.sysinit;
	&chap.mac;
	&chap.vm;
	&chap.smp;

	</part>

	<part id="devicedrivers">
	<title>Device Drivers</title>

	&chap.driverbasics;
	&chap.isa;
	&chap.pci;
	&chap.scsi;
	&chap.usb;
	&chap.newbus;

	&chap.snd;
	&chap.pccard;

	</part>

	<!-- XXX - finish me
	<part id="architectures">
	<title>Architectures</title>

	<chapter id="i386">
	<title>* I386</title>

	<para>Talk about <literal>i386</literal> specific &os;
	- architecture.</para>
	+ architecture.</para>
	</chapter>

	- <chapter id="alpha">
	- <title>* Alpha</title>
	-
	- <para>Talk about the architectural specifics of
	- FreeBSD/alpha.</para>
	- </chapter>
	-
	<chapter id="ia64">
	<title>* IA-64</title>

	<para>Talk about the architectural specifics of
	FreeBSD/ia64.</para>

	</chapter>

	<chapter id="sparc64">
	<title>* SPARC64</title>

	<para>Talk about <literal>SPARC64</literal> specific &os;
	- architecture.</para>
	+ architecture.</para>
	</chapter>

	<chapter id="amd64">
	<title>* AMD64</title>

	<para>Talk about <literal>AMD64</literal> specific &os;
	- architecture.</para>
	+ architecture.</para>
	</chapter>

	<chapter id="powerpc">
	<title>* PowerPC</title>

	<para>Talk about <literal>PowerPC</literal> specific &os;
	- architecture.</para>
	+ architecture.</para>
	</chapter>
	</part>
	-->

	<part id="appendices">
	<title>Appendices</title>

	- <bibliography>
	+ <bibliography>

	<biblioentry xreflabel="1">
	- <authorgroup>
	- <author>
	- <firstname>Marshall</firstname>
	- <othername role="Middle">Kirk</othername>
	- <surname>McKusick</surname>
	- </author>
	- <author>
	- <firstname>Keith</firstname>
	- <surname>Bostic</surname>
	- </author>
	- <author>
	- <firstname>Michael</firstname>
	- <othername role="MI">J</othername>
	- <surname>Karels</surname>
	- </author>
	- <author>
	- <firstname>John</firstname>
	- <othername role="MI">S</othername>
	- <surname>Quarterman</surname>
	- </author>
	- </authorgroup>
	- <copyright><year>1996</year><holder>Addison-Wesley Publishing Company,
	- Inc.</holder></copyright>
	- <isbn>0-201-54979-4</isbn>
	- <publisher>
	- <publishername>Addison-Wesley Publishing Company, Inc.</publishername>
	- </publisher>
	- <title>The Design and Implementation of the 4.4 BSD Operating System</title>
	- <pagenums>1-2</pagenums>
	+ <authorgroup>
	+ <author>
	+ <firstname>Marshall</firstname>
	+ <othername role="Middle">Kirk</othername>
	+ <surname>McKusick</surname>
	+ </author>
	+ <author>
	+ <firstname>Keith</firstname>
	+ <surname>Bostic</surname>
	+ </author>
	+ <author>
	+ <firstname>Michael</firstname>
	+ <othername role="MI">J</othername>
	+ <surname>Karels</surname>
	+ </author>
	+ <author>
	+ <firstname>John</firstname>
	+ <othername role="MI">S</othername>
	+ <surname>Quarterman</surname>
	+ </author>
	+ </authorgroup>
	+
	+ <copyright>
	+ <year>1996</year>
	+ <holder>Addison-Wesley Publishing Company, Inc.</holder>
	+ </copyright>
	+
	+ <isbn>0-201-54979-4</isbn>
	+
	+ <publisher>
	+ <publishername>Addison-Wesley Publishing Company, Inc.</publishername>
	+ </publisher>
	+
	+ <title>The Design and Implementation of the 4.4 BSD Operating System</title>
	+
	+ <pagenums>1-2</pagenums>
	</biblioentry>

	- </bibliography>
	+ </bibliography>
	</part>

	&chap.index;

	</book>
	Index: projects/entities/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.xml (revision 41355)
	@@ -1,402 +1,395 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="driverbasics">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Murray</firstname>
	<surname>Stokely</surname>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Jörg</firstname>
	<surname>Wunsch</surname>
	<contrib>Based on intro(4) manual page by </contrib>
	</author>
	</authorgroup>
	</chapterinfo>
	<title>Writing FreeBSD Device Drivers</title>

	<sect1 id="driverbasics-intro">
	<title>Introduction</title>

	<indexterm><primary>device driver</primary></indexterm>
	<indexterm><primary>pseudo-device</primary></indexterm>

	<para>This chapter provides a brief introduction to writing device
	drivers for FreeBSD. A device in this context is a term used
	mostly for hardware-related stuff that belongs to the system,
	like disks, printers, or a graphics display with its keyboard.
	A device driver is the software component of the operating
	system that controls a specific device. There are also
	so-called pseudo-devices where a device driver emulates the
	behavior of a device in software without any particular
	underlying hardware. Device drivers can be compiled into the
	system statically or loaded on demand through the dynamic kernel
	linker facility `kld'.</para>

	<indexterm><primary>device nodes</primary></indexterm>

	<para>Most devices in a &unix;-like operating system are accessed
	through device-nodes, sometimes also called special files.
	These files are usually located under the directory
	<filename>/dev</filename> in the filesystem hierarchy.</para>

	<para>Device drivers can roughly be broken down into two
	categories; character and network device drivers.</para>

	</sect1>

	<sect1 id="driverbasics-kld">
	<title>Dynamic Kernel Linker Facility - KLD</title>

	<indexterm><primary>kernel linking</primary><secondary>dynamic</secondary></indexterm>
	<indexterm><primary>kernel loadable modules (KLD)</primary></indexterm>

	<para>The kld interface allows system administrators to
	dynamically add and remove functionality from a running system.
	This allows device driver writers to load their new changes into
	a running kernel without constantly rebooting to test
	changes.</para>

	<indexterm>
	<primary>kernel modules</primary>
	<secondary>loading</secondary>
	</indexterm>
	<indexterm><primary>kernel modules</primary><secondary>unloading</secondary></indexterm>
	<indexterm><primary>kernel modules</primary><secondary>listing</secondary></indexterm>

	<para>The kld interface is used through:</para>

	<itemizedlist>
	<listitem>
	<simpara><command>kldload</command> - loads a new kernel
	module</simpara></listitem>
	<listitem>
	<simpara><command>kldunload</command> - unloads a kernel
	module</simpara></listitem>
	<listitem>
	<simpara><command>kldstat</command> - lists loaded
	modules</simpara></listitem>
	</itemizedlist>

	<para>Skeleton Layout of a kernel module</para>

	<programlisting>/*
	* KLD Skeleton
	* Inspired by Andrew Reiter's Daemonnews article
	*/

	#include <sys/types.h>
	#include <sys/module.h>
	#include <sys/systm.h> /* uprintf */
	#include <sys/errno.h>
	#include <sys/param.h> /* defines used in kernel.h */
	#include <sys/kernel.h> /* types used in module initialization */

	/*
	* Load handler that deals with the loading and unloading of a KLD.
	*/

	static int
	skel_loader(struct module m, int what, void arg)
	{
	int err = 0;

	switch (what) {
	case MOD_LOAD: /* kldload */
	uprintf("Skeleton KLD loaded.\n");
	break;
	case MOD_UNLOAD:
	uprintf("Skeleton KLD unloaded.\n");
	break;
	default:
	err = EOPNOTSUPP;
	break;
	}
	return(err);
	}

	/* Declare this module to the rest of the kernel */

	static moduledata_t skel_mod = {
	"skel",
	skel_loader,
	NULL
	};

	DECLARE_MODULE(skeleton, skel_mod, SI_SUB_KLD, SI_ORDER_ANY);</programlisting>


	<sect2>
	<title>Makefile</title>

	<para>&os; provides a system makefile to simplify compiling a
	kernel module.</para>

	<programlisting>SRCS=skeleton.c
	KMOD=skeleton

	.include <bsd.kmod.mk></programlisting>

	<para>Running <command>make</command> with this makefile
	will create a file <filename>skeleton.ko</filename> that can
	be loaded into the kernel by typing:</para>

	<screen>&prompt.root; <userinput>kldload -v ./skeleton.ko</userinput></screen>
	</sect2>
	</sect1>

	<sect1 id="driverbasics-char">
	<title>Character Devices</title>

	<indexterm><primary>character devices</primary></indexterm>
	<para>A character device driver is one that transfers data
	directly to and from a user process. This is the most common
	type of device driver and there are plenty of simple examples in
	the source tree.</para>

	<para>This simple example pseudo-device remembers whatever values
	are written to it and can then echo them back when
	read.</para>

	<example>
	<title>Example of a Sample Echo Pseudo-Device Driver for
	&os; 10.X</title>

	<programlisting>/*
	* Simple Echo pseudo-device KLD
	*
	* Murray Stokely
	* Søren (Xride) Straarup
	* Eitan Adler
	*/

	#include <sys/types.h>
	#include <sys/module.h>
	#include <sys/systm.h> /* uprintf */
	#include <sys/param.h> /* defines used in kernel.h */
	#include <sys/kernel.h> /* types used in module initialization */
	#include <sys/conf.h> /* cdevsw struct */
	#include <sys/uio.h> /* uio struct */
	#include <sys/malloc.h>

	-#define BUFFERSIZE 256
	+#define BUFFERSIZE 255

	/* Function prototypes */
	static d_open_t echo_open;
	static d_close_t echo_close;
	static d_read_t echo_read;
	static d_write_t echo_write;

	/* Character device entry points */
	static struct cdevsw echo_cdevsw = {
	.d_version = D_VERSION,
	.d_open = echo_open,
	.d_close = echo_close,
	.d_read = echo_read,
	.d_write = echo_write,
	.d_name = "echo",
	};

	struct s_echo {
	- char msg[BUFFERSIZE];
	+ char msg[BUFFERSIZE + 1];
	int len;
	};

	/* vars */
	static struct cdev *echo_dev;
	static struct s_echo *echomsg;

	MALLOC_DECLARE(M_ECHOBUF);
	MALLOC_DEFINE(M_ECHOBUF, "echobuffer", "buffer for echo module");

	/*
	* This function is called by the kld[un]load(2) system calls to
	* determine what actions to take when a module is loaded or unloaded.
	*/
	-
	static int
	echo_loader(struct module m __unused, int what, void arg __unused)
	{
	int error = 0;

	switch (what) {
	case MOD_LOAD: /* kldload */
	error = make_dev_p(MAKEDEV_CHECKNAME \| MAKEDEV_WAITOK,
	&echo_dev,
	&echo_cdevsw,
	0,
	UID_ROOT,
	GID_WHEEL,
	0600,
	"echo");
	if (error != 0)
	break;

	- /* kmalloc memory for use by this driver */
	- echomsg = malloc(sizeof(*echomsg), M_ECHOBUF, M_WAITOK);
	+ echomsg = malloc(sizeof(*echomsg), M_ECHOBUF, M_WAITOK \|
	+ M_ZERO);
	printf("Echo device loaded.\n");
	break;
	case MOD_UNLOAD:
	destroy_dev(echo_dev);
	free(echomsg, M_ECHOBUF);
	printf("Echo device unloaded.\n");
	break;
	default:
	error = EOPNOTSUPP;
	break;
	}
	return (error);
	}

	static int
	-echo_open(struct cdev dev __unused, int oflags __unused, int devtype __unused, struct thread p __unused)
	+echo_open(struct cdev *dev __unused, int oflags __unused, int devtype __unused,
	+ struct thread *td __unused)
	{
	int error = 0;

	uprintf("Opened device \"echo\" successfully.\n");
	return (error);
	}

	static int
	-echo_close(struct cdev dev __unused, int fflag __unused, int devtype __unused, struct thread p __unused)
	+echo_close(struct cdev *dev __unused, int fflag __unused, int devtype __unused,
	+ struct thread *td __unused)
	{

	uprintf("Closing device \"echo\".\n");
	return (0);
	}

	/*
	* The read function just takes the buf that was saved via
	* echo_write() and returns it to userland for accessing.
	* uio(9)
	*/
	-
	static int
	echo_read(struct cdev dev __unused, struct uio uio, int ioflag __unused)
	{
	- int error, amt;
	+ size_t amt;
	+ int error;

	/*
	* How big is this read operation? Either as big as the user wants,
	- * or as big as the remaining data
	+ * or as big as the remaining data. Note that the 'len' does not
	+ * include the trailing null character.
	*/
	+ amt = MIN(uio->uio_resid, uio->uio_offset >= echomsg->len + 1 ? 0 :
	+ echomsg->len + 1 - uio->uio_offset);

	- amt = MIN(uio->uio_resid, echomsg->len - uio->uio_offset);
	- uio->uio_offset += amt;
	if ((error = uiomove(echomsg->msg, amt, uio)) != 0)
	uprintf("uiomove failed!\n");

	return (error);
	}

	/*
	* echo_write takes in a character string and saves it
	* to buf for later accessing.
	*/
	-
	static int
	echo_write(struct cdev dev __unused, struct uio uio, int ioflag __unused)
	{
	- int error, amt;
	+ size_t amt;
	+ int error;

	- /* Copy the string in from user memory to kernel memory */
	-
	/*
	* We either write from the beginning or are appending -- do
	* not allow random access.
	*/
	if (uio->uio_offset != 0 && (uio->uio_offset != echomsg->len))
	return (EINVAL);

	- /*
	- * This is new message, reset length
	- */
	+ /* This is a new message, reset length */
	if (uio->uio_offset == 0)
	echomsg->len = 0;

	- /* NULL character should be overridden */
	- if (echomsg->len != 0)
	- echomsg->len--;
	-
	/* Copy the string in from user memory to kernel memory */
	amt = MIN(uio->uio_resid, (BUFFERSIZE - echomsg->len));

	error = uiomove(echomsg->msg + uio->uio_offset, amt, uio);

	- /* Now we need to null terminate, then record the length */
	- echomsg->len += amt + 1;
	- uio->uio_offset += amt + 1;
	- echomsg->msg[echomsg->len - 1] = 0;
	+ /* Now we need to null terminate and record the length */
	+ echomsg->len = uio->uio_offset;
	+ echomsg->msg[echomsg->len] = 0;

	if (error != 0)
	uprintf("Write failed: bad address!\n");
	return (error);
	}

	-DEV_MODULE(echo,echo_loader,NULL);</programlisting>
	+DEV_MODULE(echo, echo_loader, NULL);</programlisting>
	</example>

	<para>With this driver loaded try:</para>

	<screen>&prompt.root; <userinput>echo -n "Test Data" > /dev/echo</userinput>
	&prompt.root; <userinput>cat /dev/echo</userinput>
	Opened device "echo" successfully.
	Test Data
	Closing device "echo".</screen>

	<para>Real hardware devices are described in the next chapter.</para>
	</sect1>

	<sect1 id="driverbasics-block">
	<title>Block Devices (Are Gone)</title>

	<indexterm><primary>block devices</primary></indexterm>

	<para>Other &unix; systems may support a second type of disk
	device known as block devices. Block devices are disk devices
	for which the kernel provides caching. This caching makes
	block-devices almost unusable, or at least dangerously
	unreliable. The caching will reorder the sequence of write
	operations, depriving the application of the ability to know
	the exact disk contents at any one instant in time. This
	makes predictable and reliable crash recovery of on-disk data
	structures (filesystems, databases etc.) impossible.
	Since writes may be delayed, there is no way the kernel can
	report to the application which particular write operation
	encountered a write error, this further compounds the
	consistency problem. For this reason, no serious applications
	rely on block devices, and in fact, almost all applications
	which access disks directly take great pains to specify that
	character (or <quote>raw</quote>) devices should always be
	used. Because the implementation of the aliasing of each disk
	(partition) to two devices with different semantics significantly
	complicated the relevant kernel code &os; dropped support for
	cached disk devices as part of the modernization of the disk I/O
	infrastructure.</para>
	</sect1>

	<sect1 id="driverbasics-net">
	<title>Network Drivers</title>

	<indexterm><primary>network devices</primary></indexterm>
	<para>Drivers for network devices do not use device nodes in order
	to be accessed. Their selection is based on other decisions
	made inside the kernel and instead of calling open(), use of a
	network device is generally introduced by using the system call
	socket(2).</para>

	<para>For more information see ifnet(9), the source of the
	loopback device, and Bill Paul's network drivers.</para>

	</sect1>

	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml (revision 41355)
	@@ -1,1205 +1,1205 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="kerneldebug">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Paul</firstname>
	<surname>Richards</surname>
	<contrib>Contributed by </contrib>
	</author>
	<author>
	<firstname>Jörg</firstname>
	<surname>Wunsch</surname>
	</author>
	<author>
	<firstname>Robert</firstname>
	<surname>Watson</surname>
	</author>
	</authorgroup>
	</chapterinfo>

	<title>Kernel Debugging</title>

	<sect1 id="kerneldebug-obtain">
	<title>Obtaining a Kernel Crash Dump</title>

	<para>When running a development kernel (e.g., &os.current;), such as a
	kernel under extreme conditions (e.g., very high load averages,
	tens of thousands of connections, exceedingly high number of
	concurrent users, hundreds of &man.jail.8;s, etc.), or using a
	new feature or device driver on &os.stable; (e.g.,
	<acronym>PAE</acronym>), sometimes a kernel will panic. In the
	event that it does, this chapter will demonstrate how to extract
	useful information out of a crash.</para>

	<para>A system reboot is inevitable once a kernel panics. Once a
	system is rebooted, the contents of a system's physical memory
	(<acronym>RAM</acronym>) is lost, as well as any bits that are
	on the swap device before the panic. To preserve the bits in
	physical memory, the kernel makes use of the swap device as a
	temporary place to store the bits that are in RAM across a
	reboot after a crash. In doing this, when &os; boots after a
	crash, a kernel image can now be extracted and debugging can
	take place.</para>

	<note><para>A swap device that has been configured as a dump
	device still acts as a swap device. Dumps to non-swap devices
	(such as tapes or CDRWs, for example) are not supported at this time. A
	<quote>swap device</quote> is synonymous with a <quote>swap
	partition.</quote></para></note>

	<para>Several types of kernel crash dumps are available: full memory
	dumps, which hold the complete contents of physical memory,
	minidumps, which hold only memory pages in use by the kernel
	(&os;  6.2 and higher), and textdumps, which hold captured
	scripted or interactive debugger output (&os; 7.1 and higher).
	Minidumps are the default dump type as of &os; 7.0, and in most
	cases will capture all necessary information present in a full
	memory dump, as most problems can be isolated only using kernel
	state.</para>

	<sect2 id="config-dumpdev">
	<title>Configuring the Dump Device</title>

	<para>Before the kernel will dump the contents of its physical
	memory to a dump device, a dump device must be configured. A
	dump device is specified by using the &man.dumpon.8; command
	to tell the kernel where to save kernel crash dumps. The
	&man.dumpon.8; program must be called after the swap partition
	has been configured with &man.swapon.8;. This is normally
	handled by setting the <varname>dumpdev</varname> variable in
	&man.rc.conf.5; to the path of the swap device (the
	recommended way to extract a kernel dump) or
	<literal>AUTO</literal> to use the first configured swap
	device. The default for <varname>dumpdev</varname> is
	<literal>AUTO</literal> in HEAD, and changed to
	<literal>NO</literal> on RELENG_* branches (except for RELENG_7,
	which was left set to <literal>AUTO</literal>).
	On &os; 9.0-RELEASE and later versions,
	<application>bsdinstall</application> will ask whether crash dumps
	should be enabled on the target system during the install process.</para>

	<tip><para>Check <filename>/etc/fstab</filename> or
	&man.swapinfo.8; for a list of swap devices.</para></tip>

	<important><para>Make sure the <varname>dumpdir</varname>
	specified in &man.rc.conf.5; exists before a kernel
	crash!</para>

	<screen>&prompt.root; <userinput>mkdir /var/crash</userinput>
	&prompt.root; <userinput>chmod 700 /var/crash</userinput></screen>

	<para>Also, remember that the contents of
	<filename>/var/crash</filename> is sensitive and very likely
	contains confidential information such as passwords.</para>
	</important>
	</sect2>

	<sect2 id="extract-dump">
	<title>Extracting a Kernel Dump</title>

	<para>Once a dump has been written to a dump device, the dump
	must be extracted before the swap device is mounted.
	To extract a dump
	from a dump device, use the &man.savecore.8; program. If
	<varname>dumpdev</varname> has been set in &man.rc.conf.5;,
	&man.savecore.8; will be called automatically on the first
	multi-user boot after the crash and before the swap device
	is mounted. The location of the extracted core is placed in
	the &man.rc.conf.5; value <varname>dumpdir</varname>, by
	default <filename>/var/crash</filename> and will be named
	<filename>vmcore.0</filename>.</para>

	<para>In the event that there is already a file called
	<filename>vmcore.0</filename> in
	<filename>/var/crash</filename> (or whatever
	<varname>dumpdir</varname> is set to), the kernel will
	increment the trailing number for every crash to avoid
	overwriting an existing <filename>vmcore</filename> (e.g.,
	<filename>vmcore.1</filename>). While debugging, it is
	highly likely that you will want to use the highest version
	<filename>vmcore</filename> in
	<filename>/var/crash</filename> when searching for the right
	<filename>vmcore</filename>.</para>

	<tip>
	<para>If you are testing a new kernel but need to boot a different one in
	order to get your system up and running again, boot it only into single
	user mode using the <option>-s</option> flag at the boot prompt, and
	then perform the following steps:</para>

	<screen>&prompt.root; <userinput>fsck -p</userinput>
	&prompt.root; <userinput>mount -a -t ufs</userinput> # make sure /var/crash is writable
	&prompt.root; <userinput>savecore /var/crash /dev/ad0s1b</userinput>
	&prompt.root; <userinput>exit</userinput> # exit to multi-user</screen>

	<para>This instructs &man.savecore.8; to extract a kernel dump
	from <filename>/dev/ad0s1b</filename> and place the contents in
	<filename>/var/crash</filename>. Do not forget to make sure the
	destination directory <filename>/var/crash</filename> has enough
	space for the dump. Also, do not forget to specify the correct path to your swap
	device as it is likely different than
	<filename>/dev/ad0s1b</filename>!</para></tip>
	</sect2>
	</sect1>

	<sect1 id="kerneldebug-gdb">
	<title>Debugging a Kernel Crash Dump with <command>kgdb</command></title>

	<note>
	<para>This section covers &man.kgdb.1; as found in &os; 5.3
	and later. In previous versions, one must use
	<command>gdb -k</command> to read a core dump file.</para>
	</note>

	<para>Once a dump has been obtained, getting useful information
	out of the dump is relatively easy for simple problems. Before
	launching into the internals of &man.kgdb.1; to debug
	the crash dump, locate the debug version of your kernel
	(normally called <filename>kernel.debug</filename>) and the path
	to the source files used to build your kernel (normally
	<filename>/usr/obj/usr/src/sys/<replaceable>KERNCONF</replaceable></filename>,
	where <filename><replaceable>KERNCONF</replaceable></filename>
	is the <varname>ident</varname> specified in a kernel
	&man.config.5;). With those two pieces of info, let the
	debugging commence!</para>

	<para>To enter into the debugger and begin getting information
	from the dump, the following steps are required at a minimum:</para>

	<screen>&prompt.root; <userinput>cd /usr/obj/usr/src/sys/<replaceable>KERNCONF</replaceable></userinput>
	&prompt.root; <userinput>kgdb kernel.debug /var/crash/vmcore.0</userinput></screen>

	<para>You can debug the crash dump using the kernel sources just like
	you can for any other program.</para>

	<para>This first dump is from a 5.2-BETA kernel and the crash
	comes from deep within the kernel. The output below has been
	modified to include line numbers on the left. This first trace
	inspects the instruction pointer and obtains a back trace. The
	address that is used on line 41 for the <command>list</command>
	command is the instruction pointer and can be found on line
	17. Most developers will request having at least this
	information sent to them if you are unable to debug the problem
	yourself. If, however, you do solve the problem, make sure that
	your patch winds its way into the source tree via a problem
	report, mailing lists, or by being able to commit it!</para>

	<screen> 1:&prompt.root; <userinput>cd /usr/obj/usr/src/sys/<replaceable>KERNCONF</replaceable></userinput>
	2:&prompt.root; <userinput>kgdb kernel.debug /var/crash/vmcore.0</userinput>
	3:GNU gdb 5.2.1 (FreeBSD)
	4:Copyright 2002 Free Software Foundation, Inc.
	5:GDB is free software, covered by the GNU General Public License, and you are
	6:welcome to change it and/or distribute copies of it under certain conditions.
	7:Type "show copying" to see the conditions.
	8:There is absolutely no warranty for GDB. Type "show warranty" for details.
	9:This GDB was configured as "i386-undermydesk-freebsd"...
	10:panic: page fault
	11:panic messages:
	12:---
	13:Fatal trap 12: page fault while in kernel mode
	14:cpuid = 0; apic id = 00
	15:fault virtual address = 0x300
	16:fault code: = supervisor read, page not present
	17:instruction pointer = 0x8:0xc0713860
	18:stack pointer = 0x10:0xdc1d0b70
	19:frame pointer = 0x10:0xdc1d0b7c
	20:code segment = base 0x0, limit 0xfffff, type 0x1b
	21: = DPL 0, pres 1, def32 1, gran 1
	22:processor eflags = resume, IOPL = 0
	23:current process = 14394 (uname)
	24:trap number = 12
	25:panic: page fault
	26 cpuid = 0;
	27:Stack backtrace:
	28
	29:syncing disks, buffers remaining... 2199 2199 panic: mi_switch: switch in a critical section
	30:cpuid = 0;
	31:Uptime: 2h43m19s
	32:Dumping 255 MB
	33: 16 32 48 64 80 96 112 128 144 160 176 192 208 224 240
	34:---
	35:Reading symbols from /boot/kernel/snd_maestro3.ko...done.
	36:Loaded symbols for /boot/kernel/snd_maestro3.ko
	37:Reading symbols from /boot/kernel/snd_pcm.ko...done.
	38:Loaded symbols for /boot/kernel/snd_pcm.ko
	39:#0 doadump () at /usr/src/sys/kern/kern_shutdown.c:240
	40:240 dumping++;
	41:<prompt>(kgdb)</prompt> <userinput>list *0xc0713860</userinput>
	42:0xc0713860 is in lapic_ipi_wait (/usr/src/sys/i386/i386/local_apic.c:663).
	43:658 incr = 0;
	44:659 delay = 1;
	45:660 } else
	46:661 incr = 1;
	47:662 for (x = 0; x < delay; x += incr) {
	48:663 if ((lapic->icr_lo & APIC_DELSTAT_MASK) == APIC_DELSTAT_IDLE)
	49:664 return (1);
	50:665 ia32_pause();
	51:666 }
	52:667 return (0);
	53:<prompt>(kgdb)</prompt> <userinput>backtrace</userinput>
	54:#0 doadump () at /usr/src/sys/kern/kern_shutdown.c:240
	55:#1 0xc055fd9b in boot (howto=260) at /usr/src/sys/kern/kern_shutdown.c:372
	56:#2 0xc056019d in panic () at /usr/src/sys/kern/kern_shutdown.c:550
	57:#3 0xc0567ef5 in mi_switch () at /usr/src/sys/kern/kern_synch.c:470
	58:#4 0xc055fa87 in boot (howto=256) at /usr/src/sys/kern/kern_shutdown.c:312
	59:#5 0xc056019d in panic () at /usr/src/sys/kern/kern_shutdown.c:550
	60:#6 0xc0720c66 in trap_fatal (frame=0xdc1d0b30, eva=0)
	61: at /usr/src/sys/i386/i386/trap.c:821
	62:#7 0xc07202b3 in trap (frame=
	63: {tf_fs = -1065484264, tf_es = -1065484272, tf_ds = -1065484272, tf_edi = 1, tf_esi = 0, tf_ebp = -602076292, tf_isp = -602076324, tf_ebx = 0, tf_edx = 0, tf_ecx = 1000000, tf_eax = 243, tf_trapno = 12, tf_err = 0, tf_eip = -1066321824, tf_cs = 8, tf_eflags = 65671, tf_esp = 243, tf_ss = 0})
	64: at /usr/src/sys/i386/i386/trap.c:250
	65:#8 0xc070c9f8 in calltrap () at {standard input}:94
	66:#9 0xc07139f3 in lapic_ipi_vectored (vector=0, dest=0)
	67: at /usr/src/sys/i386/i386/local_apic.c:733
	68:#10 0xc0718b23 in ipi_selected (cpus=1, ipi=1)
	69: at /usr/src/sys/i386/i386/mp_machdep.c:1115
	70:#11 0xc057473e in kseq_notify (ke=0xcc05e360, cpu=0)
	71: at /usr/src/sys/kern/sched_ule.c:520
	72:#12 0xc0575cad in sched_add (td=0xcbcf5c80)
	73: at /usr/src/sys/kern/sched_ule.c:1366
	74:#13 0xc05666c6 in setrunqueue (td=0xcc05e360)
	75: at /usr/src/sys/kern/kern_switch.c:422
	76:#14 0xc05752f4 in sched_wakeup (td=0xcbcf5c80)
	77: at /usr/src/sys/kern/sched_ule.c:999
	78:#15 0xc056816c in setrunnable (td=0xcbcf5c80)
	79: at /usr/src/sys/kern/kern_synch.c:570
	80:#16 0xc0567d53 in wakeup (ident=0xcbcf5c80)
	81: at /usr/src/sys/kern/kern_synch.c:411
	82:#17 0xc05490a8 in exit1 (td=0xcbcf5b40, rv=0)
	83: at /usr/src/sys/kern/kern_exit.c:509
	84:#18 0xc0548011 in sys_exit () at /usr/src/sys/kern/kern_exit.c:102
	85:#19 0xc0720fd0 in syscall (frame=
	86: {tf_fs = 47, tf_es = 47, tf_ds = 47, tf_edi = 0, tf_esi = -1, tf_ebp = -1077940712, tf_isp = -602075788, tf_ebx = 672411944, tf_edx = 10, tf_ecx = 672411600, tf_eax = 1, tf_trapno = 12, tf_err = 2, tf_eip = 671899563, tf_cs = 31, tf_eflags = 642, tf_esp = -1077940740, tf_ss = 47})
	87: at /usr/src/sys/i386/i386/trap.c:1010
	88:#20 0xc070ca4d in Xint0x80_syscall () at {standard input}:136
	89:---Can't read userspace from dump, or kernel process---
	90:<prompt>(kgdb)</prompt> <userinput>quit</userinput></screen>


	<para>This next trace is an older dump from the FreeBSD 2 time
	frame, but is more involved and demonstrates more of the
	features of <command>gdb</command>. Long lines have been folded
	to improve readability, and the lines are numbered for
	reference. Despite this, it is a real-world error trace taken
	during the development of the pcvt console driver.</para>

	<screen> 1:Script started on Fri Dec 30 23:15:22 1994
	2:&prompt.root; <userinput>cd /sys/compile/URIAH</userinput>
	3:&prompt.root; <userinput>gdb -k kernel /var/crash/vmcore.1</userinput>
	4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel
	...done.
	5:IdlePTD 1f3000
	6:panic: because you said to!
	7:current pcb at 1e3f70
	8:Reading in symbols for ../../i386/i386/machdep.c...done.
	9:<prompt>(kgdb)</prompt> <userinput>backtrace</userinput>
	10:#0 boot (arghowto=256) (../../i386/i386/machdep.c line 767)
	11:#1 0xf0115159 in panic ()
	12:#2 0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698)
	13:#3 0xf010185e in db_fncall ()
	14:#4 0xf0101586 in db_command (-266509132, -266509516, -267381073)
	15:#5 0xf0101711 in db_command_loop ()
	16:#6 0xf01040a0 in db_trap ()
	17:#7 0xf0192976 in kdb_trap (12, 0, -272630436, -266743723)
	18:#8 0xf019d2eb in trap_fatal (...)
	19:#9 0xf019ce60 in trap_pfault (...)
	20:#10 0xf019cb2f in trap (...)
	21:#11 0xf01932a1 in exception:calltrap ()
	22:#12 0xf0191503 in cnopen (...)
	23:#13 0xf0132c34 in spec_open ()
	24:#14 0xf012d014 in vn_open ()
	25:#15 0xf012a183 in open ()
	26:#16 0xf019d4eb in syscall (...)
	27:<prompt>(kgdb)</prompt> <userinput>up 10</userinput>
	28:Reading in symbols for ../../i386/i386/trap.c...done.
	29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\
	30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\
	31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\
	32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\
	33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\
	34:ss = -266427884}) (../../i386/i386/trap.c line 283)
	35:283 (void) trap_pfault(&frame, FALSE);
	36:<prompt>(kgdb)</prompt> <userinput>frame frame->tf_ebp frame->tf_eip</userinput>
	37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done.
	38:#0 0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\
	39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403)
	40:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
	41:<prompt>(kgdb)</prompt> <userinput>list</userinput>
	42:398
	43:399 tp->t_state \|= TS_CARR_ON;
	44:400 tp->t_cflag \|= CLOCAL; /* cannot be a modem (:-) */
	45:401
	46:402 #if PCVT_NETBSD \|\| (PCVT_FREEBSD >= 200)
	47:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
	48:404 #else
	49:405 return ((*linesw[tp->t_line].l_open)(dev, tp, flag));
	50:406 #endif /* PCVT_NETBSD \|\| (PCVT_FREEBSD >= 200) */
	51:407 }
	52:<prompt>(kgdb)</prompt> <userinput>print tp</userinput>
	53:Reading in symbols for ../../i386/i386/cons.c...done.
	54:$1 = (struct tty *) 0x1bae
	55:<prompt>(kgdb)</prompt> <userinput>print tp->t_line</userinput>
	56:$2 = 1767990816
	57:<prompt>(kgdb)</prompt> <userinput>up</userinput>
	58:#1 0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\
	59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126)
	60: return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p));
	61:<prompt>(kgdb)</prompt> <userinput>up</userinput>
	62:#2 0xf0132c34 in spec_open ()
	63:<prompt>(kgdb)</prompt> <userinput>up</userinput>
	64:#3 0xf012d014 in vn_open ()
	65:<prompt>(kgdb)</prompt> <userinput>up</userinput>
	66:#4 0xf012a183 in open ()
	67:<prompt>(kgdb)</prompt> <userinput>up</userinput>
	68:#5 0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\
	69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\
	70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \
	71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \
	72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673)
	73:673 error = (*callp->sy_call)(p, args, rval);
	74:<prompt>(kgdb)</prompt> <userinput>up</userinput>
	75:Initial frame selected; you cannot go up.
	76:<prompt>(kgdb)</prompt> <userinput>quit</userinput></screen>
	<para>Comments to the above script:</para>

	<variablelist>
	<varlistentry>
	<term>line 6:</term>

	<listitem>
	<para>This is a dump taken from within DDB (see below), hence the
	panic comment <quote>because you said to!</quote>, and a rather
	long stack trace; the initial reason for going into DDB has been a
	page fault trap though.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>line 20:</term>

	<listitem>
	<para>This is the location of function <function>trap()</function>
	in the stack trace.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>line 36:</term>

	<listitem>
	<para>Force usage of a new stack frame; this is no longer necessary.
	The stack frames are supposed to point to the right
	locations now, even in case of a trap.
	From looking at the code in source line 403, there is a
	high probability that either the pointer access for
	<quote>tp</quote> was messed up, or the array access was out of
	bounds.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>line 52:</term>

	<listitem>
	<para>The pointer looks suspicious, but happens to be a valid
	address.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>line 56:</term>

	<listitem>
	<para>However, it obviously points to garbage, so we have found our
	error! (For those unfamiliar with that particular piece of code:
	<literal>tp->t_line</literal> refers to the line discipline of
	the console device here, which must be a rather small integer
	number.)</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<tip><para>If your system is crashing regularly and you are running
	out of disk space, deleting old <filename>vmcore</filename>
	files in <filename>/var/crash</filename> could save a
	considerable amount of disk space!</para></tip>
	</sect1>

	<sect1 id="kerneldebug-ddd">
	<title>Debugging a Crash Dump with DDD</title>

	<para>Examining a kernel crash dump with a graphical debugger like
	<command>ddd</command> is also possible (you will need to install
	the <filename role="package">devel/ddd</filename> port in order to use the
	<command>ddd</command> debugger). Add the <option>-k</option>
	option to the <command>ddd</command> command line you would use
	normally. For example;</para>

	<screen>&prompt.root; <userinput>ddd --debugger kgdb kernel.debug /var/crash/vmcore.0</userinput></screen>

	<para>You should then be able to go about looking at the crash dump using
	<command>ddd</command>'s graphical interface.</para>
	</sect1>

	<sect1 id="kerneldebug-online-ddb">
	<title>On-Line Kernel Debugging Using DDB</title>

	<para>While <command>kgdb</command> as an off-line debugger provides a very
	high level of user interface, there are some things it cannot do. The
	most important ones being breakpointing and single-stepping kernel
	code.</para>

	<para>If you need to do low-level debugging on your kernel, there is an
	on-line debugger available called DDB. It allows setting of
	breakpoints, single-stepping kernel functions, examining and changing
	kernel variables, etc. However, it cannot access kernel source files,
	and only has access to the global and static symbols, not to the full
	debug information like <command>gdb</command> does.</para>

	<para>To configure your kernel to include DDB, add the options

	<programlisting>options KDB</programlisting>
	<programlisting>options DDB</programlisting>

	to your config file, and rebuild. (See <ulink
	url="&url.books.handbook;/index.html">The FreeBSD Handbook</ulink> for details on
	configuring the FreeBSD kernel).</para>

	<note>
	<para>If you have an older version of the boot blocks, your
	debugger symbols might not be loaded at all. Update the boot blocks;
	the recent ones load the DDB symbols automatically.</para>
	</note>

	<para>Once your DDB kernel is running, there are several ways to enter
	DDB. The first, and earliest way is to type the boot flag
	<option>-d</option> right at the boot prompt. The kernel will start up
	in debug mode and enter DDB prior to any device probing. Hence you can
	even debug the device probe/attach functions. Users of &os.current;
	will need to use the boot menu option, six, to escape to a command
	prompt.</para>

	<para>The second scenario is to drop to the debugger once the
	system has booted. There are two simple ways to accomplish
	this. If you would like to break to the debugger from the
	command prompt, simply type the command:</para>

	<screen>&prompt.root; <userinput>sysctl debug.kdb.enter=1</userinput></screen>
	<note>
	<para>To force a panic on the fly, issue the following command:</para>
	<screen>&prompt.root; <userinput>sysctl debug.kdb.panic=1</userinput></screen>
	</note>

	<para>Alternatively, if you are at the system console, you may use
	a hot-key on the keyboard. The default break-to-debugger
	sequence is <keycombo action="simul"><keycap>Ctrl</keycap>
	<keycap>Alt</keycap><keycap>ESC</keycap></keycombo>. For
	syscons, this sequence can be remapped and some of the
	distributed maps out there do this, so check to make sure you
	know the right sequence to use. There is an option available
	for serial consoles that allows the use of a serial line BREAK on the
	console line to enter DDB (<literal>options BREAK_TO_DEBUGGER</literal>
	in the kernel config file). It is not the default since there are a lot
	of serial adapters around that gratuitously generate a BREAK
	condition, for example when pulling the cable.</para>

	<para>The third way is that any panic condition will branch to DDB if the
	kernel is configured to use it. For this reason, it is not wise to
	configure a kernel with DDB for a machine running unattended.</para>

	<para>To obtain the unattended functionality, add:</para>

	<programlisting>options KDB_UNATTENDED</programlisting>

	<para>to the kernel configuration file and rebuild/reinstall.</para>

	<para>The DDB commands roughly resemble some <command>gdb</command>
	commands. The first thing you probably need to do is to set a
	breakpoint:</para>

	<screen><userinput>break function-name address</userinput></screen>

	<para>Numbers are taken hexadecimal by default, but to make them distinct
	from symbol names; hexadecimal numbers starting with the letters
	<literal>a-f</literal> need to be preceded with <literal>0x</literal>
	(this is optional for other numbers). Simple expressions are allowed,
	for example: <literal>function-name + 0x103</literal>.</para>

	<para>To exit the debugger and continue execution,
	type:</para>

	<screen><userinput>continue</userinput></screen>

	<para>To get a stack trace, use:</para>

	<screen><userinput>trace</userinput></screen>

	<note>
	<para>Note that when entering DDB via a hot-key, the kernel is currently
	servicing an interrupt, so the stack trace might be not of much use
	to you.</para>
	</note>

	<para>If you want to remove a breakpoint, use</para>

	<screen><userinput>del</userinput>
	<userinput>del address-expression</userinput></screen>

	<para>The first form will be accepted immediately after a breakpoint hit,
	and deletes the current breakpoint. The second form can remove any
	breakpoint, but you need to specify the exact address; this can be
	obtained from:</para>

	<screen><userinput>show b</userinput></screen>

	<para>or:</para>

	<screen><userinput>show break</userinput></screen>

	<para>To single-step the kernel, try:</para>

	<screen><userinput>s</userinput></screen>

	<para>This will step into functions, but you can make DDB trace them until
	the matching return statement is reached by:</para>

	<screen><userinput>n</userinput></screen>

	<note>
	<para>This is different from <command>gdb</command>'s
	<command>next</command> statement; it is like <command>gdb</command>'s
	<command>finish</command>. Pressing <keycap>n</keycap> more than once
	will cause a continue.</para>
	</note>

	<para>To examine data from memory, use (for example):

	<screen><userinput>x/wx 0xf0133fe0,40</userinput>
	<userinput>x/hd db_symtab_space</userinput>
	<userinput>x/bc termbuf,10</userinput>
	<userinput>x/s stringbuf</userinput></screen>

	for word/halfword/byte access, and hexadecimal/decimal/character/ string
	display. The number after the comma is the object count. To display
	the next 0x10 items, simply use:</para>

	<screen><userinput>x ,10</userinput></screen>

	<para>Similarly, use

	<screen><userinput>x/ia foofunc,10</userinput></screen>

	to disassemble the first 0x10 instructions of
	<function>foofunc</function>, and display them along with their offset
	from the beginning of <function>foofunc</function>.</para>

	<para>To modify memory, use the write command:</para>

	<screen><userinput>w/b termbuf 0xa 0xb 0</userinput>
	<userinput>w/w 0xf0010030 0 0</userinput></screen>

	<para>The command modifier
	(<literal>b</literal>/<literal>h</literal>/<literal>w</literal>)
	specifies the size of the data to be written, the first following
	expression is the address to write to and the remainder is interpreted
	as data to write to successive memory locations.</para>

	<para>If you need to know the current registers, use:</para>

	<screen><userinput>show reg</userinput></screen>

	<para>Alternatively, you can display a single register value by e.g.

	<screen><userinput>p $eax</userinput></screen>

	and modify it by:</para>

	<screen><userinput>set $eax new-value</userinput></screen>

	<para>Should you need to call some kernel functions from DDB, simply
	say:</para>

	<screen><userinput>call func(arg1, arg2, ...)</userinput></screen>

	<para>The return value will be printed.</para>

	<para>For a &man.ps.1; style summary of all running processes, use:</para>

	<screen><userinput>ps</userinput></screen>

	<para>Now you have examined why your kernel failed, and you wish to
	reboot. Remember that, depending on the severity of previous
	malfunctioning, not all parts of the kernel might still be working as
	expected. Perform one of the following actions to shut down and reboot
	your system:</para>

	<screen><userinput>panic</userinput></screen>

	<para>This will cause your kernel to dump core and reboot, so you can
	later analyze the core on a higher level with <command>gdb</command>.
	This command
	usually must be followed by another <command>continue</command>
	statement.</para>

	<screen><userinput>call boot(0)</userinput></screen>

	<para>Might be a good way to cleanly shut down the running system,
	<function>sync()</function> all disks, and finally, in some cases,
	reboot. As long as
	the disk and filesystem interfaces of the kernel are not damaged, this
	could be a good way for an almost clean shutdown.</para>

	<screen><userinput>call cpu_reset()</userinput></screen>

	<para>This is the final way out of disaster and almost the same as hitting the
	Big Red Button.</para>

	<para>If you need a short command summary, simply type:</para>

	<screen><userinput>help</userinput></screen>

	<para>It is highly recommended to have a printed copy of the
	&man.ddb.4; manual page ready for a debugging
	session. Remember that it is hard to read the on-line manual while
	single-stepping the kernel.</para>
	</sect1>

	<sect1 id="kerneldebug-online-gdb">
	<title>On-Line Kernel Debugging Using Remote GDB</title>

	<para>This feature has been supported since FreeBSD 2.2, and it is
	actually a very neat one.</para>

	<para>GDB has already supported <emphasis>remote debugging</emphasis> for
	a long time. This is done using a very simple protocol along a serial
	line. Unlike the other methods described above, you will need two
	machines for doing this. One is the host providing the debugging
	environment, including all the sources, and a copy of the kernel binary
	with all the symbols in it, and the other one is the target machine that
	simply runs a similar copy of the very same kernel (but stripped of the
	debugging information).</para>

	<para>You should configure the kernel in question with <command>config
	-g</command> if building the <quote>traditional</quote> way. If
	building the <quote>new</quote> way, make sure that
	<literal>makeoptions DEBUG=-g</literal> is in the configuration.
	In both cases, include <option>DDB</option> in the configuration, and
	compile it as usual. This gives a large binary, due to the
	debugging information. Copy this kernel to the target machine, strip
	the debugging symbols off with <command>strip -x</command>, and boot it
	using the <option>-d</option> boot option. Connect the serial line
	- of the target machine that has "flags 080" set on its sio device
	- to any serial line of the debugging host. See &man.sio.4; for
	- information on how to set the flags on an sio device.
	+ of the target machine that has "flags 080" set on its uart device
	+ to any serial line of the debugging host. See &man.uart.4; for
	+ information on how to set the flags on an uart device.
	Now, on the debugging machine, go to the compile directory of the target
	kernel, and start <command>gdb</command>:</para>

	<screen>&prompt.user; <userinput>kgdb kernel</userinput>
	GDB is free software and you are welcome to distribute copies of it
	under certain conditions; type "show copying" to see the conditions.
	There is absolutely no warranty for GDB; type "show warranty" for details.
	GDB 4.16 (i386-unknown-freebsd),
	Copyright 1996 Free Software Foundation, Inc...
	<prompt>(kgdb)</prompt> </screen>

	<para>Initialize the remote debugging session (assuming the first serial
	port is being used) by:</para>

	- <screen><prompt>(kgdb)</prompt> <userinput>target remote /dev/cuaa0</userinput></screen>
	+ <screen><prompt>(kgdb)</prompt> <userinput>target remote /dev/cuau0</userinput></screen>

	<para>Now, on the target host (the one that entered DDB right before even
	starting the device probe), type:</para>

	<screen>Debugger("Boot flags requested debugger")
	Stopped at Debugger+0x35: movb $0, edata+0x51bc
	<prompt>db></prompt> <userinput>gdb</userinput></screen>

	<para>DDB will respond with:</para>

	<screen>Next trap will enter GDB remote protocol mode</screen>

	<para>Every time you type <command>gdb</command>, the mode will be toggled
	between remote GDB and local DDB. In order to force a next trap
	immediately, simply type <command>s</command> (step). Your hosting GDB
	will now gain control over the target kernel:</para>

	- <screen>Remote debugging using /dev/cuaa0
	+ <screen>Remote debugging using /dev/cuau0
	Debugger (msg=0xf01b0383 "Boot flags requested debugger")
	at ../../i386/i386/db_interface.c:257
	<prompt>(kgdb)</prompt></screen>

	<para>You can use this session almost as any other GDB session, including
	full access to the source, running it in gud-mode inside an Emacs window
	(which gives you an automatic source code display in another Emacs
	window), etc.</para>
	</sect1>

	<sect1 id="kerneldebug-console">
	<title>Debugging a Console Driver</title>

	<para>Since you need a console driver to run DDB on, things are more
	complicated if the console driver itself is failing. You might remember
	the use of a serial console (either with modified boot blocks, or by
	specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt),
	and hook up a standard terminal onto your first serial port. DDB works
	on any configured console driver, including a serial
	console.</para>
	</sect1>

	<sect1 id="kerneldebug-deadlocks">
	<title>Debugging Deadlocks</title>

	<para>You may experience so called deadlocks, the situation where
	a system stops doing useful work. To provide a helpful bug report
	in this situation, use &man.ddb.4; as described above.
	Include the output of <command>ps</command> and
	<command>trace</command> for suspected processes in the
	report.</para>

	<para>If possible, consider doing further investigation. The receipt
	below is especially useful if you suspect that a deadlock occurs in the
	VFS layer. Add the following options
	<programlisting>makeoptions DEBUG=-g
	options INVARIANTS
	options INVARIANT_SUPPORT
	options WITNESS
	options DEBUG_LOCKS
	options DEBUG_VFS_LOCKS
	options DIAGNOSTIC</programlisting>

	to the kernel configuration file. When a deadlock occurs, in addition to the
	output of the <command>ps</command> command, provide information
	from the <command>show pcpu</command>, <command>show allpcpu</command>,
	<command>show locks</command>, <command>show alllocks</command>,
	<command>show lockedvnods</command> and <command>alltrace</command>.
	</para>

	<para>To obtain meaningful backtraces for threaded processes, use
	<command>thread thread-id</command> to switch to the thread
	stack, and do a backtrace with <command>where</command>.</para>
	</sect1>

	<sect1 id="kerneldebug-dcons">
	<title>Kernel debugging with Dcons</title>

	<para>&man.dcons.4; is a very simple console driver that is
	not directly connected with any physical devices. It just reads
	and writes characters from and to a buffer in a kernel or
	loader. Due to its simple nature, it is very useful for kernel
	debugging, especially with a &firewire; device. Currently, &os;
	provides two ways to interact with the buffer from outside of
	the kernel using &man.dconschat.8;.</para>

	<sect2>
	<title>Dcons over &firewire;</title>

	<para>Most &firewire; (IEEE1394) host controllers are
	based on the <acronym>OHCI</acronym> specification that
	supports physical access to the host memory. This means that
	once the host controller is initialized, we can access the
	host memory without the help of software (kernel). We can
	exploit this facility for interaction with &man.dcons.4;.
	&man.dcons.4; provides similar functionality as a serial
	console. It emulates two serial ports, one for the console
	and <acronym>DDB</acronym>, the other for
	<acronym>GDB</acronym>. Because remote memory access is fully
	handled by the hardware, the &man.dcons.4; buffer is
	accessible even when the system crashes.</para>

	<para>&firewire; devices are not limited to those
	integrated into motherboards. <acronym>PCI</acronym> cards
	exist for desktops, and a cardbus interface can be purchased
	for laptops.</para>

	<sect3>
	<title>Enabling &firewire; and Dcons support on the target
	machine</title>

	<para>To enable &firewire; and Dcons support in the kernel of
	the <emphasis>target machine</emphasis>:</para>

	<itemizedlist>
	<listitem>
	<para>Make sure your kernel supports
	<literal>dcons</literal>, <literal>dcons_crom</literal>
	and <literal>firewire</literal>.
	<literal>Dcons</literal> should be statically linked
	with the kernel. For <literal>dcons_crom</literal> and
	<literal>firewire</literal>, modules should be
	OK.</para>
	</listitem>
	<listitem>
	<para>Make sure physical <acronym>DMA</acronym> is enabled.
	You may need to add
	<literal>hw.firewire.phydma_enable=1</literal> to
	<filename>/boot/loader.conf</filename>.</para>
	</listitem>
	<listitem>
	<para>Add options for debugging.</para>
	</listitem>
	<listitem>
	<para>Add <literal>dcons_gdb=1</literal> in
	<filename>/boot/loader.conf</filename> if you use GDB
	over &firewire;.</para>
	</listitem>
	<listitem>
	<para>Enable <literal>dcons</literal> in
	<filename>/etc/ttys</filename>.</para>
	</listitem>
	<listitem>
	<para>Optionally, to force <literal>dcons</literal> to
	be the high-level console, add
	<literal>hw.firewire.dcons_crom.force_console=1</literal>
	to <filename>loader.conf</filename>.</para>
	</listitem>
	</itemizedlist>

	<para>To enable &firewire; and Dcons support in &man.loader.8;
	on i386 or amd64:</para>

	<para>Add
	<literal>LOADER_FIREWIRE_SUPPORT=YES</literal> in
	<filename>/etc/make.conf</filename> and rebuild
	&man.loader.8;:</para>

	<screen>&prompt.root; <userinput>cd /sys/boot/i386 && make clean && make && make install</userinput></screen>

	<para>To enable &man.dcons.4; as an active low-level
	console, add <literal>boot_multicons="YES"</literal> to
	<filename>/boot/loader.conf</filename>.</para>

	<para>Here are a few configuration examples. A sample kernel
	configuration file would contain:</para>

	<screen>device dcons
	device dcons_crom
	options KDB
	options DDB
	options GDB
	options ALT_BREAK_TO_DEBUGGER</screen>

	<para>And a sample <filename>/boot/loader.conf</filename>
	would contain:</para>

	<screen>dcons_crom_load="YES"
	dcons_gdb=1
	boot_multicons="YES"
	hw.firewire.phydma_enable=1
	hw.firewire.dcons_crom.force_console=1</screen>

	</sect3>

	<sect3>
	<title>Enabling &firewire; and Dcons support on the host
	machine</title>

	<para>To enable &firewire; support in the kernel on the
	<emphasis>host machine</emphasis>:</para>

	<screen>&prompt.root; <userinput>kldload firewire</userinput></screen>

	<para>Find out the <acronym>EUI64</acronym> (the unique 64
	bit identifier) of the &firewire; host controller, and
	use &man.fwcontrol.8; or <command>dmesg</command> to
	find the <acronym>EUI64</acronym> of the target machine.</para>

	<para>Run &man.dconschat.8;, with:</para>

	<screen>&prompt.root; <userinput>dconschat -e \# -br -G 12345 -t <replaceable>00-11-22-33-44-55-66-77</replaceable></userinput></screen>

	<para>The following key combinations can be used once
	&man.dconschat.8; is running:</para>

	<informaltable pgwide="1">
	<tgroup cols="2">
	<tbody>
	<row>
	<entry>
	<keycombo action="seq">
	<keycap>~</keycap>
	<keycap>.</keycap>
	</keycombo>
	</entry>
	<entry>Disconnect</entry>
	</row>
	<row>
	<entry>
	<keycombo action="seq">
	<keycap>~</keycap>
	<keycombo action="simul">
	<keycap>Ctrl</keycap>
	<keycap>B</keycap>
	</keycombo>
	</keycombo>
	</entry>
	<entry>ALT BREAK</entry>
	</row>
	<row>
	<entry>
	<keycombo action="seq">
	<keycap>~</keycap>
	<keycombo action="simul">
	<keycap>Ctrl</keycap>
	<keycap>R</keycap>
	</keycombo>
	</keycombo>
	</entry>
	<entry>RESET target</entry>
	</row>
	<row>
	<entry>
	<keycombo action="seq">
	<keycap>~</keycap>
	<keycombo action="simul">
	<keycap>Ctrl</keycap>
	<keycap>Z</keycap>
	</keycombo>
	</keycombo>
	</entry>
	<entry>Suspend dconschat</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>Attach remote <acronym>GDB</acronym> by starting
	&man.kgdb.1; with a remote debugging session:</para>

	<screen><userinput>kgdb -r :12345 kernel</userinput></screen>

	</sect3>
	<sect3>
	<title>Some general tips</title>

	<para>Here are some general tips:</para>

	<para>To take full advantage of the speed of &firewire;,
	disable other slow console drivers:</para>

	<screen>&prompt.root; conscontrol delete ttyd0 # serial console
	&prompt.root; conscontrol delete consolectl # video/keyboard</screen>

	<para>There exists a <acronym>GDB</acronym> mode for
	&man.emacs.1;; this is what you will need to add to your
	<filename>.emacs</filename>:</para>

	<screen><userinput>(setq gud-gdba-command-name "kgdb -a -a -a -r :12345")
	(setq gdb-many-windows t)
	(xterm-mouse-mode 1)
	M-x gdba</userinput></screen>

	<para>And for <acronym>DDD</acronym> (<filename>devel/ddd</filename>):</para>

	<screen># remote serial protocol
	LANG=C ddd --debugger kgdb -r :12345 kernel
	# live core debug
	LANG=C ddd --debugger kgdb kernel /dev/fwmem0.2</screen>
	</sect3>
	</sect2>

	<sect2>
	<title>Dcons with KVM</title>

	<para>We can directly read the &man.dcons.4; buffer via
	<filename>/dev/mem</filename> for live systems, and in the
	core dump for crashed systems. These give you similar output
	to <command>dmesg -a</command>, but the &man.dcons.4; buffer
	includes more information.</para>

	<sect3>
	<title>Using Dcons with KVM</title>

	<para>To use &man.dcons.4; with <acronym>KVM</acronym>:</para>

	<para>Dump a &man.dcons.4; buffer of a live system:</para>

	<screen>&prompt.root; <userinput>dconschat -1</userinput></screen>

	<para>Dump a &man.dcons.4; buffer of a crash dump:</para>

	<screen>&prompt.root; <userinput>dconschat -1 -M vmcore.XX</userinput></screen>

	<para>Live core debugging can be done via:</para>

	<screen>&prompt.root; <userinput>fwcontrol -m target_eui64</userinput>
	&prompt.root; <userinput>kgdb kernel /dev/fwmem0.2</userinput></screen>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="kerneldebug-options">
	<title>Glossary of Kernel Options for Debugging</title>

	<para>This section provides a brief glossary of compile-time kernel
	options used for debugging:</para>

	<itemizedlist>
	<listitem>
	<para><literal>options KDB</literal>: compiles in the kernel
	debugger framework. Required for <literal>options DDB</literal>
	and <literal>options GDB</literal>. Little or no performance
	overhead. By default, the debugger will be entered on panic
	instead of an automatic reboot.</para>
	</listitem>

	<listitem>
	<para><literal>options KDB_UNATTENDED</literal>: change the default
	value of the <literal>debug.debugger_on_panic</literal> sysctl to
	0, which controls whether the debugger is entered on panic. When
	<literal>options KDB</literal> is not compiled into the kernel, the
	behavior is to automatically reboot on panic; when it is compiled
	into the kernel, the default behavior is to drop into the debugger
	unless <literal>options KDB_UNATTENDED</literal> is compiled in.
	If you want to leave the kernel debugger compiled into the kernel
	but want the system to come back up unless you're on-hand to use
	the debugger for diagnostics, use this option.</para>
	</listitem>

	<listitem>
	<para><literal>options KDB_TRACE</literal>: change the default value
	of the <literal>debug.trace_on_panic</literal> sysctl to 1, which
	controls whether the debugger automatically prints a stack trace
	on panic. Especially if running with <literal>options
	KDB_UNATTENDED</literal>, this can be helpful to gather basic
	debugging information on the serial or firewire console while
	still rebooting to recover.</para>
	</listitem>

	<listitem>
	<para><literal>options DDB</literal>: compile in support for the
	console debugger, DDB. This interactive debugger runs on whatever
	the active low-level console of the system is, which includes the
	video console, serial console, or firewire console. It provides
	basic integrated debugging facilities, such as stack tracing,
	process and thread listing, dumping of lock state, VM state, file
	system state, and kernel memory management. DDB does not require
	software running on a second machine or being able to generate a
	core dump or full debugging kernel symbols, and provides detailed
	diagnostics of the kernel at run-time. Many bugs can be fully
	diagnosed using only DDB output. This option depends on
	<literal>options KDB</literal>.</para>
	</listitem>

	<listitem>
	<para><literal>options GDB</literal>: compile in support for the
	remote debugger, GDB, which can operate over serial cable or
	firewire. When the debugger is entered, GDB may be attached to
	inspect structure contents, generate stack traces, etc. Some
	kernel state is more awkward to access than in DDB, which is able
	to generate useful summaries of kernel state automatically, such
	as automatically walking lock debugging or kernel memory
	management structures, and a second machine running the debugger
	is required. On the other hand, GDB combines information from
	the kernel source and full debugging symbols, and is aware of full
	data structure definitions, local variables, and is scriptable.
	This option is not required to run GDB on a kernel core dump.
	This option depends on <literal>options KDB</literal>.
	</para>
	</listitem>

	<listitem>
	<para><literal>options BREAK_TO_DEBUGGER</literal>, <literal>options
	ALT_BREAK_TO_DEBUGGER</literal>: allow a break signal or
	alternative signal on the console to enter the debugger. If the
	system hangs without a panic, this is a useful way to reach the
	debugger. Due to the current kernel locking, a break signal
	generated on a serial console is significantly more reliable at
	getting into the debugger, and is generally recommended. This
	option has little or no performance impact.</para>
	</listitem>

	<listitem>
	<para><literal>options INVARIANTS</literal>: compile into the kernel
	a large number of run-time assertion checks and tests, which
	constantly test the integrity of kernel data structures and the
	invariants of kernel algorithms. These tests can be expensive, so
	are not compiled in by default, but help provide useful "fail stop"
	behavior, in which certain classes of undesired behavior enter the
	debugger before kernel data corruption occurs, making them easier
	to debug. Tests include memory scrubbing and use-after-free
	testing, which is one of the more significant sources of overhead.
	This option depends on <literal>options INVARIANT_SUPPORT</literal>.
	</para>
	</listitem>

	<listitem>
	<para><literal>options INVARIANT_SUPPORT</literal>: many of the tests
	present in <literal>options INVARIANTS</literal> require modified
	data structures or additional kernel symbols to be defined.</para>
	</listitem>

	<listitem>
	<para><literal>options WITNESS</literal>: this option enables run-time
	lock order tracking and verification, and is an invaluable tool for
	deadlock diagnosis. WITNESS maintains a graph of acquired lock
	orders by lock type, and checks the graph at each acquire for
	cycles (implicit or explicit). If a cycle is detected, a warning
	and stack trace are generated to the console, indicating that a
	potential deadlock might have occurred. WITNESS is required in
	order to use the <command>show locks</command>, <command>show
	witness</command> and <command>show alllocks</command> DDB
	commands. This debug option has significant performance overhead,
	which may be somewhat mitigated through the use of <literal>options
	WITNESS_SKIPSPIN</literal>. Detailed documentation may be found in
	&man.witness.4;.</para>
	</listitem>

	<listitem>
	<para><literal>options WITNESS_SKIPSPIN</literal>: disable run-time
	checking of spinlock lock order with WITNESS. As spin locks are
	acquired most frequently in the scheduler, and scheduler events
	occur often, this option can significantly speed up systems
	running with WITNESS. This option depends on <literal>options
	WITNESS</literal>.</para>
	</listitem>

	<listitem>
	<para><literal>options WITNESS_KDB</literal>: change the default
	value of the <literal>debug.witness.kdb</literal> sysctl to 1,
	which causes WITNESS to enter the debugger when a lock order
	violation is detected, rather than simply printing a warning. This
	option depends on <literal>options WITNESS</literal>.</para>
	</listitem>

	<listitem>
	<para><literal>options SOCKBUF_DEBUG</literal>: perform extensive
	run-time consistency checking on socket buffers, which can be
	useful for debugging both socket bugs and race conditions in
	protocols and device drivers that interact with sockets. This
	option significantly impacts network performance, and may change
	the timing in device driver races.</para>
	</listitem>

	<listitem>
	<para><literal>options DEBUG_VFS_LOCKS</literal>: track lock
	acquisition points for lockmgr/vnode locks, expanding the amount
	of information displayed by <command>show lockedvnods</command>
	in DDB. This option has a measurable performance impact.</para>
	</listitem>

	<listitem>
	<para><literal>options DEBUG_MEMGUARD</literal>: a replacement for
	the &man.malloc.9; kernel memory allocator that uses the VM system
	to detect reads or writes from allocated memory after free.
	Details may be found in &man.memguard.9;. This option has a
	significant performance impact, but can be very helpful in
	debugging kernel memory corruption bugs.</para>
	</listitem>

	<listitem>
	<para><literal>options DIAGNOSTIC</literal>: enable additional, more
	expensive diagnostic tests along the lines of <literal>options
	INVARIANTS</literal>.</para>
	</listitem>

	</itemizedlist>
	</sect1>

	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/developers-handbook/l10n/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/developers-handbook/l10n/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/developers-handbook/l10n/chapter.xml (revision 41355)
	@@ -1,328 +1,328 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="l10n">
	<title>Localization and Internationalization - L10N and I18N</title>

	<sect1 id="l10n-programming">
	<title>Programming I18N Compliant Applications</title>
	<indexterm><primary>Qt</primary></indexterm>
	<indexterm><primary>GTK</primary></indexterm>
	<para>To make your application more useful for speakers of other
	languages, we hope that you will program I18N compliant. The GNU
	gcc compiler and GUI libraries like QT and GTK support I18N through
	special handling of strings. Making a program I18N compliant is
	very easy. It allows contributors to port your application to
	other languages quickly. Refer to the library specific I18N
	documentation for more details.</para>

	<para>In contrast with common perception, I18N compliant code is
	easy to write. Usually, it only involves wrapping your strings
	with library specific functions. In addition, please be sure to
	allow for wide or multibyte character support.</para>

	<sect2>
	<title>A Call to Unify the I18N Effort</title>

	<para>It has come to our attention that the individual I18N/L10N
	efforts for each country has been repeating each others'
	efforts. Many of us have been reinventing the wheel repeatedly
	and inefficiently. We hope that the various major groups in
	I18N could congregate into a group effort similar to the Core
	Team's responsibility.</para>

	<para>Currently, we hope that, when you write or port I18N
	programs, you would send it out to each country's related
	FreeBSD mailing list for testing. In the future, we hope to
	create applications that work in all the languages
	out-of-the-box without dirty hacks.</para>

	<para>The &a.i18n; has been established. If you are an I18N/L10N
	developer, please send your comments, ideas, questions, and
	anything you deem related to it.</para>
	</sect2>

	<sect2>
	<title>Perl and Python</title>
	<indexterm>
	<primary>Perl</primary>
	</indexterm>
	<indexterm>
	<primary>Python</primary>
	</indexterm>

	<para>Perl and Python have I18N and wide character handling
	libraries. Please use them for I18N compliance.</para>
	</sect2>
	</sect1>

	<sect1 id="posix-nls">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Gábor</firstname>
	<surname>Kövesdán</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>Localized Messages with POSIX.1 Native Language Support (NLS)</title>

	<para>Beyond the basic I18N functions, like supporting various input
	encodings or supporting national conventions, such as the different
	decimal separators, at a higher level of I18N, it is possible to localize the
	messages written to the output by the various programs. A common way of doing
	this is using the POSIX.1 NLS functions, which are provided as a part
	of the &os; base system.</para>

	<sect2 id="nls-catalogs">
	<title>Organizing Localized Messages into Catalog Files</title>

	<para>POSIX.1 NLS is based on catalog files, which contain the
	localized messages in the desired encoding. The messages are
	organized into sets and each message is identified by an integer
	number in the containing set. The catalog files are conventionally
	named after the locale they contain localized messages for, followed
	by the <literal>.msg</literal> extension. For instance, the
	Hungarian messages for ISO8859-2 encoding should be stored in a file
	called <filename>hu_HU.ISO8859-2</filename>.</para>

	<para>These catalog files are common text files that contain the
	numbered messages. It is possible to write comments by starting
	the line with a <literal>$</literal> sign. Set boundaries are also separated by
	special comments, where the keyword <literal>set</literal> must
	directly follow the <literal>$</literal> sign. The <literal>set</literal> keyword
	is then followed by the set number. For example:</para>

	<programlisting>$set 1</programlisting>

	<para>The actual message entries start with the message number and
	followed by the localized message. The well-known
	modifiers from &man.printf.3; are accepted:</para>

	<programlisting>15 "File not found: %s\n"</programlisting>

	<para>The language catalog files have to be compiled into a binary
	form before they can be opened from the program. This conversion
	is done with the &man.gencat.1; utility. Its first argument is the
	filename of the compiled catalog and its further arguments are the
	input catalogs. The localized messages can also be organized into
	more catalog files and then all of them can be processed with
	&man.gencat.1;.</para>
	</sect2>

	<sect2 id="nls-using">
	<title>Using the Catalog Files from the Source Code</title>

	<para>Using the catalog files is simple. To use
	the related functions, <filename
	class="headerfile">nl_types.h</filename> must be included. Before
	using a catalog, it has to be opened with &man.catopen.3;.
	The function takes two arguments. The first parameter is the name of the
	installed and compiled catalog. Usually, the name of the
	program is used, such as <application>grep</application>.
	This name will be used when looking for the compiled
	catalog file. The &man.catopen.3; call looks for this file
	in <filename
	class="directory">/usr/share/nls/<replaceable>locale</replaceable>/<replaceable>catname</replaceable></filename>
	and in <filename
	class="directory">/usr/local/share/nls/<replaceable>locale</replaceable>/<replaceable>catname</replaceable></filename>,
	where <literal>locale</literal> is the locale set and
	<literal>catname</literal> is the catalog name being
	discussed. The second parameter is a constant, which can have
	two values:</para>

	<itemizedlist>
	<listitem>
	<para><literal>NL_CAT_LOCALE</literal>, which means that
	the used catalog file will be based on
	<envar>LC_MESSAGES</envar>.</para>
	</listitem>
	<listitem>
	<para><literal>0</literal>, which means that
	<envar>LANG</envar> has to be used to open
	the proper catalog.</para>
	</listitem>
	</itemizedlist>

	<para>The &man.catopen.3; call returns a catalog identifier of
	type <literal>nl_catd</literal>. Please refer to the manual page for a list of possible returned error
	codes.</para>

	<para>After opening a catalog &man.catgets.3; can be used to retrieve
	a message. The first parameter is the catalog identifier returned
	by &man.catopen.3;, the second one is the number of the set, the
	third one is the number of the messages, and the fourth one is a
	fallback message, which will be returned if the requested message
	cannot be retrieved from the catalog file.</para>

	<para>After using the catalog file, it must be closed by calling
	&man.catclose.3;, which has one argument, the catalog id.</para>
	</sect2>

	<sect2 id="nls-example">
	<title>A Practical Example</title>

	<para>The following example will demonstrate an easy solution on how to
	use NLS catalogs in a flexible way.</para>

	<para>The below lines need to be put into a common header file of
	the program, which is included into all source files where
	localized messages are necessary:</para>

	<programlisting>
	#ifdef WITHOUT_NLS
	#define getstr(n) nlsstr[n]
	#else
	#include <nl_types.h>

	extern nl_catd catalog;
	#define getstr(n) catgets(catalog, 1, n, nlsstr[n])
	#endif

	extern char *nlsstr[];</programlisting>

	<para>Next, put these lines into the global declaration part of the
	main source file:</para>

	<programlisting>
	#ifndef WITHOUT_NLS
	#include <nl_types.h>
	nl_catd catalog;
	#endif

	/*
	* Default messages to use when NLS is disabled or no catalog
	* is found.
	*/
	char *nlsstr[] = {
	"",
	/* 1*/ "some random message",
	/* 2*/ "some other message"
	};</programlisting>

	<para>Next come the real code snippets, which open, read, and
	close the catalog:</para>

	<programlisting>
	#ifndef WITHOUT_NLS
	catalog = catopen("myapp", NL_CAT_LOCALE);
	#endif

	...

	printf(getstr(1));

	...

	#ifndef WITHOUT_NLS
	catclose(catalog);
	#endif</programlisting>

	<sect3>
	<title>Reducing Strings to Localize</title>

	<para>There is a good way of reducing the strings that
	need to be localized by using <application>libc</application>
	error messages. This is also useful to just avoid duplication
	and provide consistent error messages for the common errors
	that can be encountered by a great many of programs.</para>

	<para>First, here is an example that does not use
	<application>libc</application> error messages:</para>

	<programlisting>
	#include <err.h>
	...
	if (!S_ISDIR(st.st_mode))
	- err(1, "argument is not a directory");
	+ errx(1, "argument is not a directory");
	</programlisting>

	<para>This can be transformed to print an error message by
	reading <varname>errno</varname> and printing an error message
	accordingly:</para>

	<programlisting>
	#include <err.h>
	#include <errno.h>
	...
	if (!S_ISDIR(st.st_mode)) {
	errno = ENOTDIR;
	err(1, NULL);
	}
	</programlisting>

	<para>In this example, the custom string is eliminated, thus
	translators will have less work when localizing the program
	and users will see the usual <quote>Not a directory</quote>
	error message when they encounter this error. This message
	will probably seem more familiar to them. Please note that
	it was necessary to include <filename
	class="headerfile">errno.h</filename> in order to directly
	access <varname>errno</varname>.</para>

	<para>It is worth to note that there are cases when
	<varname>errno</varname> is set automatically by a preceding
	call, so it is not necessary to set it explicitly:</para>

	<programlisting>
	#include <err.h>
	...
	if ((p = malloc(size)) == NULL)
	err(1, NULL);
	</programlisting>
	</sect3>
	</sect2>

	<sect2 id="nls-mk">
	<title>Making use of <filename>bsd.nls.mk</filename></title>

	<para>Using the catalog files requires few repeatable steps,
	such as compiling the catalogs and installing them to the
	proper location. In order to simplify this process even
	more, <filename>bsd.nls.mk</filename> introduces some macros.
	It is not necessary to include <filename>bsd.nls.mk</filename>
	explicitly, it is pulled in from the common Makefiles,
	such as <filename>bsd.prog.mk</filename> or
	<filename>bsd.lib.mk</filename>.</para>

	<para>Usually it is enough to define <makevar>NLSNAME</makevar>,
	which should have the catalog name mentioned as the first
	argument of &man.catopen.3; and list the catalog files in
	<makevar>NLS</makevar> without their <literal>.msg</literal>
	extension. Here is an example, which makes it possible to
	to disable NLS when used with the code examples before.
	The <makevar>WITHOUT_NLS</makevar> &man.make.1; variable has
	to be defined in order to build the program without NLS
	support.</para>

	<programlisting>
	.if !defined(WITHOUT_NLS)
	NLS= es_ES.ISO8859-1
	NLS+= hu_HU.ISO8859-2
	NLS+= pt_BR.ISO8859-1
	.else
	CFLAGS+= -DWITHOUT_NLS
	.endif</programlisting>

	<para>Conventionally, the catalog files are placed under the
	<filename class="directory">nls</filename> subdirectory and
	this is the default behaviour of <filename>bsd.nls.mk</filename>.
	It is possible, though to override the location of the
	catalogs with the <makevar>NLSSRCDIR</makevar> &man.make.1;
	variable. The default name of the precompiled catalog files
	also follow the naming convention mentioned before. It can be
	overridden by setting the <makevar>NLSNAME</makevar> variable.
	There are other options to fine tune the processing of the catalog
	files but usually it is not needed, thus they are not described
	here. For further information on <filename>bsd.nls.mk</filename>,
	please refer to the file itself, it is short and easy to
	understand.</para>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml (revision 41355)
	@@ -1,2321 +1,2308 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="tools">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>James</firstname>
	<surname>Raynard</surname>
	<contrib>Contributed by </contrib>
	</author>
	<author>
	<firstname>Murray</firstname>
	<surname>Stokely</surname>
	</author>
	</authorgroup>
	</chapterinfo>

	<title>Programming Tools</title>
	<sect1 id="tools-synopsis"><title>Synopsis</title>

	<para>This chapter is an introduction to using some of the
	programming tools supplied with FreeBSD, although much of it
	will be applicable to many other versions of &unix;. It does
	<emphasis>not</emphasis> attempt to describe coding in any
	detail. Most of the chapter assumes little or no previous
	programming knowledge, although it is hoped that most
	programmers will find something of value in it.</para>

	</sect1>

	<sect1 id="tools-intro"><title>Introduction</title>

	<para>FreeBSD offers an excellent development environment.
	Compilers for C and C++ and an assembler come with the
	basic system, not to mention classic &unix;
	tools such as <command>sed</command> and <command>awk</command>.
	If that is not enough, there are many more compilers and
	interpreters in the Ports collection. The following section,
	<link linkend="tools-programming">Introduction to Programming</link>,
	lists some of the available options. FreeBSD is very
	compatible with standards such as <acronym>&posix;</acronym> and
	<acronym>ANSI</acronym> C, as well with its own BSD heritage, so
	it is possible to write applications that will compile and run
	with little or no modification on a wide range of
	platforms.</para>

	<para>However, all this power can be rather overwhelming at first
	if you have never written programs on a &unix; platform before.
	This document aims to help you get up and running, without
	getting too deeply into more advanced topics. The intention is
	that this document should give you enough of the basics to be
	able to make some sense of the documentation.</para>

	<para>Most of the document requires little or no knowledge of
	programming, although it does assume a basic competence with
	using &unix; and a willingness to learn!</para>

	</sect1>

	<sect1 id="tools-programming">
	<title>Introduction to Programming</title>

	<para>A program is a set of instructions that tell the computer to
	do various things; sometimes the instruction it has to perform
	depends on what happened when it performed a previous
	instruction. This section gives an overview of the two main
	ways in which you can give these instructions, or
	<quote>commands</quote> as they are usually called. One way
	uses an <firstterm>interpreter</firstterm>, the other a
	<firstterm>compiler</firstterm>. As human languages are too
	difficult for a computer to understand in an unambiguous way,
	commands are usually written in one or other languages specially
	designed for the purpose.</para>

	<sect2>
	<title>Interpreters</title>

	<para>With an interpreter, the language comes as an environment,
	where you type in commands at a prompt and the environment
	executes them for you. For more complicated programs, you can
	type the commands into a file and get the interpreter to load
	the file and execute the commands in it. If anything goes
	wrong, many interpreters will drop you into a debugger to help
	you track down the problem.</para>

	<para>The advantage of this is that you can see the results of
	your commands immediately, and mistakes can be corrected
	readily. The biggest disadvantage comes when you want to
	share your programs with someone. They must have the same
	interpreter, or you must have some way of giving it to them,
	and they need to understand how to use it. Also users may not
	appreciate being thrown into a debugger if they press the
	wrong key! From a performance point of view, interpreters can
	use up a lot of memory, and generally do not generate code as
	efficiently as compilers.</para>

	<para>In my opinion, interpreted languages are the best way to
	start if you have not done any programming before. This kind
	of environment is typically found with languages like Lisp,
	Smalltalk, Perl and Basic. It could also be argued that the
	&unix; shell (<command>sh</command>, <command>csh</command>) is itself an
	interpreter, and many people do in fact write shell
	<quote>scripts</quote> to help with various
	<quote>housekeeping</quote> tasks on their machine. Indeed, part
	of the original &unix; philosophy was to provide lots of small
	utility programs that could be linked together in shell
	scripts to perform useful tasks.</para>
	</sect2>

	<sect2>
	<title>Interpreters available with FreeBSD</title>

	<para>Here is a list of interpreters that are available from
	the &os; Ports Collection, with a brief discussion of
	some of the more popular interpreted languages.</para>

	<para>Instructions on how to get and install applications
	from the Ports Collection can be found in the
	<ulink url="&url.books.handbook;/ports-using.html">
	Ports section</ulink> of the handbook.</para>

	<variablelist>
	<varlistentry>
	<term><acronym>BASIC</acronym></term>

	<listitem>
	<para>Short for Beginner's All-purpose Symbolic
	Instruction Code. Developed in the 1950s for teaching
	University students to program and provided with every
	self-respecting personal computer in the 1980s,
	<acronym>BASIC</acronym> has been the first programming
	language for many programmers. It is also the foundation
	for Visual Basic.</para>

	<para>The Bywater Basic Interpreter can be found in the
	Ports Collection as
	<filename role="package">lang/bwbasic</filename>
	and the Phil Cockroft's Basic Interpreter
	(formerly Rabbit Basic) is available as
	<filename role="package">lang/pbasic</filename>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Lisp</term>

	<listitem>
	<para>A language that was developed in the late 1950s as
	an alternative to the <quote>number-crunching</quote>
	languages that were popular at the time. Instead of
	being based on numbers, Lisp is based on lists; in fact
	the name is short for <quote>List Processing</quote>.
	Very popular in <acronym>AI</acronym> (Artificial Intelligence)
	circles.</para>

	<para>Lisp is an extremely powerful and sophisticated
	language, but can be rather large and unwieldy.</para>

	<para>Various implementations of Lisp that can run on &unix;
	systems are available in the Ports Collection for &os;.
	GNU Common Lisp can be found as
	<filename role="package">lang/gcl</filename>. CLISP
	by Bruno Haible and Michael Stoll is available as
	<filename role="package">lang/clisp</filename>.
	For CMUCL, which includes a highly-optimizing compiler too, or
	simpler Lisp implementations like SLisp, which implements most
	of the Common Lisp constructs in a few hundred lines of C code,
	<filename role="package">lang/cmucl</filename> and
	<filename role="package">lang/slisp</filename> are available
	respectively.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Perl</term>

	<listitem>
	<para>Very popular with system administrators for writing
	scripts; also often used on World Wide Web servers for
	writing <acronym>CGI</acronym> scripts.</para>

	<para>Perl is available in the Ports Collection as
	- <filename role="package">lang/perl5.8</filename> for all
	- &os; releases, and is installed as <command>/usr/bin/perl</command>
	- in the base system 4.X releases.</para>
	+ <filename role="package">lang/perl5.16</filename> for all
	+ &os; releases.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Scheme</term>

	<listitem>
	<para>A dialect of Lisp that is rather more compact and
	cleaner than Common Lisp. Popular in Universities as it
	is simple enough to teach to undergraduates as a first
	language, while it has a high enough level of
	abstraction to be used in research work.</para>

	<para>Scheme is available from the Ports Collection as
	<filename role="package">lang/elk</filename> for the
	Elk Scheme Interpreter. The MIT Scheme Interpreter
	can be found in
	<filename role="package">lang/mit-scheme</filename>
	and the SCM Scheme Interpreter in
	<filename role="package">lang/scm</filename>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Icon</term>

	<listitem>
	<para>Icon is a high-level language with extensive
	facilities for processing strings and structures.
	The version of Icon for &os; can be found in the
	Ports Collection as
	<filename role="package">lang/icon</filename>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Logo</term>

	<listitem>
	<para>Logo is a language that is easy to learn, and has
	been used as an introductory programming language in
	various courses. It is an excellent tool to work with
	when teaching programming in small ages, as it makes the
	creation of elaborate geometric shapes an easy task even
	for very small children.</para>

	<para>The latest version of Logo for &os; is available from
	the Ports Collection in
	<filename role="package">lang/logo</filename>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Python</term>

	<listitem>
	<para>Python is an Object-Oriented, interpreted language.
	Its advocates argue that it is one of the best languages
	to start programming with, since it is relatively easy
	to start with, but is not limited in comparison to other
	popular interpreted languages that are used for the
	development of large, complex applications (Perl and
	Tcl are two other languages that are popular for such tasks).</para>

	<para>The latest version of Python is available from the
	Ports Collection in
	<filename role="package">lang/python</filename>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Ruby</term>

	<listitem>
	<para>Ruby is an interpreter, pure object-oriented programming
	language. It has become widely popular because of its easy
	to understand syntax, flexibility when writing code, and the
	ability to easily develop and maintain large, complex
	programs.</para>

	<para>Ruby is available from the Ports Collection as
	<filename role="package">lang/ruby18</filename>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Tcl and Tk</term>

	<listitem>
	<para>Tcl is an embeddable, interpreted language, that has
	become widely used and became popular mostly because of its portability to many
	platforms. It can be used both for quickly writing
	small, prototype applications, or (when combined with
	Tk, a GUI toolkit) fully-fledged, featureful
	programs.</para>

	<para>Various versions of Tcl are available as ports
	for &os;. The latest version, Tcl 8.5, can be found in
	<filename role="package">lang/tcl85</filename>.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect2>

	<sect2>
	<title>Compilers</title>

	<para>Compilers are rather different. First of all, you write
	your code in a file (or files) using an editor. You then run
	the compiler and see if it accepts your program. If it did
	not compile, grit your teeth and go back to the editor; if it
	did compile and gave you a program, you can run it either at a
	shell command prompt or in a debugger to see if it works
	properly.

	<footnote>
	<para>If you run it in the shell, you may get a core
	dump.</para>
	</footnote></para>

	<para>Obviously, this is not quite as direct as using an
	interpreter. However it allows you to do a lot of things
	which are very difficult or even impossible with an
	interpreter, such as writing code which interacts closely with
	the operating system—or even writing your own operating
	system! It is also useful if you need to write very efficient
	code, as the compiler can take its time and optimize the code,
	which would not be acceptable in an interpreter. Moreover,
	distributing a program written for a compiler is usually more
	straightforward than one written for an interpreter—you
	can just give them a copy of the executable, assuming they
	have the same operating system as you.</para>

	- <para>Compiled languages include Pascal, C and C++. C and C++
	- are rather unforgiving languages, and best suited to more
	- experienced programmers; Pascal, on the other hand, was
	- designed as an educational language, and is quite a good
	- language to start with. FreeBSD does not include Pascal
	- support in the base system, but
	- the Free Pascal Compiler is
	- available in the Ports Collection as
	- <filename role="package">lang/fpc</filename>.</para>
	-
	<para>As the edit-compile-run-debug cycle is rather tedious when
	using separate programs, many commercial compiler makers have
	produced Integrated Development Environments
	(<acronym>IDE</acronym>s for short). FreeBSD does not include
	an IDE in the base system, but <filename role="package">devel/kdevelop</filename> is
	available in the Ports Collection and many use
	<application>Emacs</application> for this purpose. Using
	<application>Emacs</application> as an IDE is discussed in
	<xref linkend="emacs"/>.</para>
	</sect2>
	-
	-
	</sect1>


	<sect1 id="tools-compiling">
	<title>Compiling with <command>cc</command></title>

	<para>This section deals with the <application>gcc</application>
	and <application>clang</application> compilers for C and C++,
	since they come with the &os; base system. Starting with
	&os; 10.X <command>clang</command> is installed as
	<command>cc</command>. The
	details of producing a program with an interpreter vary
	considerably between interpreters, and are usually well covered
	in the documentation and on-line help for the
	interpreter.</para>

	<para>Once you have written your masterpiece, the next step is to
	convert it into something that will (hopefully!) run on FreeBSD.
	This usually involves several steps, each of which is done by a
	separate program.</para>

	<procedure>
	<step>
	<para>Pre-process your source code to remove comments and do
	other tricks like expanding macros in C.</para>
	</step>

	<step>
	<para>Check the syntax of your code to see if you have obeyed
	the rules of the language. If you have not, it will
	complain!</para>
	</step>

	<step>
	<para>Convert the source code into assembly
	language—this is very close to machine code, but still
	understandable by humans. Allegedly.</para>
	</step>

	<step>
	<para>Convert the assembly language into machine
	code—yep, we are talking bits and bytes, ones and
	zeros here.</para>
	</step>

	<step>
	<para>Check that you have used things like functions and
	global variables in a consistent way. For example, if you
	have called a non-existent function, it will
	complain.</para>
	</step>

	<step>
	<para>If you are trying to produce an executable from several
	source code files, work out how to fit them all
	together.</para>
	</step>

	<step>
	<para>Work out how to produce something that the system's
	run-time loader will be able to load into memory and
	run.</para>
	</step>

	<step>
	<para>Finally, write the executable on the filesystem.</para>
	</step>
	</procedure>

	<para>The word <firstterm>compiling</firstterm> is often used to refer to
	just steps 1 to 4—the others are referred to as
	<firstterm>linking</firstterm>. Sometimes step 1 is referred to as
	<firstterm>pre-processing</firstterm> and steps 3-4 as
	<firstterm>assembling</firstterm>.</para>

	<para>Fortunately, almost all this detail is hidden from you, as
	<command>cc</command> is a front end that manages calling all these
	programs with the right arguments for you; simply typing</para>

	<screen>&prompt.user; <userinput>cc foobar.c</userinput></screen>

	<para>will cause <filename>foobar.c</filename> to be compiled by all the
	steps above. If you have more than one file to compile, just do
	something like</para>

	<screen>&prompt.user; <userinput>cc foo.c bar.c</userinput></screen>

	<para>Note that the syntax checking is just that—checking
	the syntax. It will not check for any logical mistakes you may
	have made, like putting the program into an infinite loop, or
	using a bubble sort when you meant to use a binary
	sort.

	<footnote>
	<para>In case you did not know, a binary sort is an efficient
	way of sorting things into order and a bubble sort
	is not.</para>
	</footnote></para>

	<para>There are lots and lots of options for <command>cc</command>, which
	are all in the manual page. Here are a few of the most important
	ones, with examples of how to use them.</para>

	<variablelist>
	<varlistentry>
	<term><option>-o <replaceable>filename</replaceable></option></term>

	<listitem>
	<para>The output name of the file. If you do not use this
	option, <command>cc</command> will produce an executable called
	<filename>a.out</filename>.

	<footnote>
	<para>The reasons for this are buried in the mists of
	history.</para>
	</footnote></para>

	<informalexample>
	<screen>&prompt.user; <userinput>cc foobar.c</userinput> <lineannotation>executable is <filename>a.out</filename></lineannotation>
	&prompt.user; <userinput>cc -o foobar foobar.c</userinput> <lineannotation>executable is <filename>foobar</filename></lineannotation>
	</screen>
	</informalexample>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-c</option></term>

	<listitem>
	<para>Just compile the file, do not link it. Useful for toy
	programs where you just want to check the syntax, or if
	you are using a <filename>Makefile</filename>.</para>

	<informalexample>
	<screen>&prompt.user; <userinput>cc -c foobar.c</userinput>
	</screen>
	</informalexample>

	<para>This will produce an <firstterm>object file</firstterm> (not an
	executable) called <filename>foobar.o</filename>. This
	can be linked together with other object files into an
	executable.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-g</option></term>

	<listitem>
	<para>Create a debug version of the executable. This makes
	the compiler put information into the executable about
	which line of which source file corresponds to which
	function call. A debugger can use this information to show
	the source code as you step through the program, which is
	<emphasis>very</emphasis> useful; the disadvantage is that
	all this extra information makes the program much bigger.
	Normally, you compile with <option>-g</option> while you
	are developing a program and then compile a <quote>release
	version</quote> without <option>-g</option> when you are
	satisfied it works properly.</para>

	<informalexample>
	<screen>&prompt.user; <userinput>cc -g foobar.c</userinput>
	</screen>
	</informalexample>

	<para>This will produce a debug version of the
	program.

	<footnote>
	<para>Note, we did not use the <option>-o</option> flag
	to specify the executable name, so we will get an
	executable called <filename>a.out</filename>.
	Producing a debug version called
	<filename>foobar</filename> is left as an exercise for
	the reader!</para>
	</footnote></para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-O</option></term>

	<listitem>
	<para>Create an optimized version of the executable. The
	compiler performs various clever tricks to try to produce
	an executable that runs faster than normal. You can add a
	number after the <option>-O</option> to specify a higher
	level of optimization, but this often exposes bugs in the
	compiler's optimizer.</para>

	<informalexample>
	<screen>&prompt.user; <userinput>cc -O -o foobar foobar.c</userinput>
	</screen>
	</informalexample>

	<para>This will produce an optimized version of
	<filename>foobar</filename>.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>The following three flags will force <command>cc</command>
	to check that your code complies to the relevant international
	standard, often referred to as the <acronym>ANSI</acronym>
	standard, though strictly speaking it is an
	<acronym>ISO</acronym> standard.</para>

	<variablelist>
	<varlistentry>
	<term><option>-Wall</option></term>

	<listitem>
	<para>Enable all the warnings which the authors of
	<command>cc</command> believe are worthwhile. Despite the
	name, it will not enable all the warnings
	<command>cc</command> is capable of.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-ansi</option></term>

	<listitem>
	<para>Turn off most, but not all, of the
	non-<acronym>ANSI</acronym> C features provided by
	<command>cc</command>. Despite the name, it does not
	guarantee strictly that your code will comply to the
	standard.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-pedantic</option></term>

	<listitem>
	<para>Turn off <emphasis>all</emphasis>
	<command>cc</command>'s non-<acronym>ANSI</acronym> C
	features.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>Without these flags, <command>cc</command> will allow you to
	use some of its non-standard extensions to the standard. Some
	of these are very useful, but will not work with other
	compilers—in fact, one of the main aims of the standard is
	to allow people to write code that will work with any compiler
	on any system. This is known as <firstterm>portable
	code</firstterm>.</para>

	<para>Generally, you should try to make your code as portable as
	possible, as otherwise you may have to completely rewrite the
	program later to get it to work somewhere else—and who
	knows what you may be using in a few years time?</para>

	<informalexample>
	<screen>&prompt.user; <userinput>cc -Wall -ansi -pedantic -o foobar foobar.c</userinput></screen>
	</informalexample>

	<para>This will produce an executable <filename>foobar</filename>
	after checking <filename>foobar.c</filename> for standard
	compliance.</para>

	<variablelist>
	<varlistentry>
	<term><option>-l<replaceable>library</replaceable></option></term>

	<listitem>
	<para>Specify a function library to be used at link time.</para>

	<para>The most common example of this is when compiling a
	program that uses some of the mathematical functions in C.
	Unlike most other platforms, these are in a separate
	library from the standard C one and you have to tell the
	compiler to add it.</para>

	<para>The rule is that if the library is called
	<filename>lib<replaceable>something</replaceable>.a</filename>,
	you give <command>cc</command> the argument
	<option>-l<replaceable>something</replaceable></option>.
	For example, the math library is
	<filename>libm.a</filename>, so you give
	<command>cc</command> the argument <option>-lm</option>.
	A common <quote>gotcha</quote> with the math library is
	that it has to be the last library on the command
	line.</para>

	<informalexample>
	<screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput>
	</screen>
	</informalexample>

	<para>This will link the math library functions into
	<filename>foobar</filename>.</para>

	<para>If you are compiling C++ code, you need to add
	<option>-lg++</option>, or <option>-lstdc++</option> if
	you are using FreeBSD 2.2 or later, to the command line
	argument to link the C++ library functions.
	Alternatively, you can run <command>c++</command> instead
	of <command>cc</command>, which does this for you.
	<command>c++</command> can also be invoked as
	<command>g++</command> on FreeBSD.</para>

	<informalexample>
	<screen>&prompt.user; <userinput>cc -o foobar foobar.cc -lg++</userinput> <lineannotation>For FreeBSD 2.1.6 and earlier</lineannotation>
	&prompt.user; <userinput>cc -o foobar foobar.cc -lstdc++</userinput> <lineannotation>For FreeBSD 2.2 and later</lineannotation>
	&prompt.user; <userinput>c++ -o foobar foobar.cc</userinput>
	</screen>
	</informalexample>

	<para>Each of these will both produce an executable
	<filename>foobar</filename> from the C++ source file
	<filename>foobar.cc</filename>. Note that, on &unix;
	systems, C++ source files traditionally end in
	<filename>.C</filename>, <filename>.cxx</filename> or
	<filename>.cc</filename>, rather than the
	&ms-dos; style
	<filename>.cpp</filename> (which was already used for
	something else). <command>gcc</command> used to rely on
	this to work out what kind of compiler to use on the
	source file; however, this restriction no longer applies,
	so you may now call your C++ files
	<filename>.cpp</filename> with impunity!</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<sect2>
	<title>Common <command>cc</command> Queries and Problems</title>

	<qandaset>
	<qandaentry>
	<question>
	<para>I am trying to write a program which uses the
	<function>sin()</function> function and I get an error
	like this. What does it mean?</para>

	<informalexample>
	<screen>/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment
	</screen>
	</informalexample>
	</question>

	<answer>
	<para>When using mathematical functions like
	<function>sin()</function>, you have to tell
	<command>cc</command> to link in the math library, like
	so:</para>

	<informalexample>
	<screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput>
	</screen>
	</informalexample>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>All right, I wrote this simple program to practice
	using <option>-lm</option>. All it does is raise 2.1 to
	the power of 6.</para>

	<informalexample>
	<programlisting>#include <stdio.h>

	int main() {
	float f;

	f = pow(2.1, 6);
	printf("2.1 ^ 6 = %f\n", f);
	return 0;
	}
	</programlisting>
	</informalexample>

	<para>and I compiled it as:</para>

	<informalexample>
	<screen>&prompt.user; <userinput>cc temp.c -lm</userinput>
	</screen>
	</informalexample>

	<para>like you said I should, but I get this when I run
	it:</para>

	<informalexample>
	<screen>&prompt.user; <userinput>./a.out</userinput>
	2.1 ^ 6 = 1023.000000
	</screen>
	</informalexample>

	<para>This is <emphasis>not</emphasis> the right answer!
	What is going on?</para>
	</question>

	<answer>
	<para>When the compiler sees you call a function, it
	checks if it has already seen a prototype for it. If it
	has not, it assumes the function returns an
	<type>int</type>, which is definitely not what you want
	here.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>So how do I fix this?</para>
	</question>

	<answer>
	<para>The prototypes for the mathematical functions are in
	<filename>math.h</filename>. If you include this file,
	the compiler will be able to find the prototype and it
	will stop doing strange things to your
	calculation!</para>

	<informalexample>
	<programlisting>#include <math.h>
	#include <stdio.h>

	int main() {
	...
	</programlisting>
	</informalexample>

	<para>After recompiling it as you did before, run
	it:</para>

	<informalexample>
	<screen>&prompt.user; <userinput>./a.out</userinput>
	2.1 ^ 6 = 85.766121
	</screen>
	</informalexample>

	<para>If you are using any of the mathematical functions,
	<emphasis>always</emphasis> include
	<filename>math.h</filename> and remember to link in the
	math library.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>I compiled a file called
	<filename>foobar.c</filename> and I cannot find an
	executable called <filename>foobar</filename>. Where has
	it gone?</para>
	</question>

	<answer>
	<para>Remember, <command>cc</command> will call the
	executable <filename>a.out</filename> unless you tell it
	differently. Use the
	<option>-o <replaceable>filename</replaceable></option>
	option:</para>

	<informalexample>
	<screen>&prompt.user; <userinput>cc -o foobar foobar.c</userinput>
	</screen>
	</informalexample>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>OK, I have an executable called
	<filename>foobar</filename>, I can see it when I run
	<command>ls</command>, but when I type in
	<command>foobar</command> at the command prompt it tells
	me there is no such file. Why can it not find
	it?</para>
	</question>

	<answer>
	<para>Unlike &ms-dos;, &unix; does not
	look in the current directory when it is trying to find
	out which executable you want it to run, unless you tell
	it to. Either type <command>./foobar</command>, which
	means <quote>run the file called
	<filename>foobar</filename> in the current
	directory</quote>, or change your <envar>PATH</envar>
	environment
	variable so that it looks something like</para>

	<informalexample>
	<screen>bin:/usr/bin:/usr/local/bin:.
	</screen>
	</informalexample>

	<para>The dot at the end means <quote>look in the current
	directory if it is not in any of the
	others</quote>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>I called my executable <filename>test</filename>,
	but nothing happens when I run it. What is going
	on?</para>
	</question>

	<answer>
	<para>Most &unix; systems have a program called
	<command>test</command> in <filename>/usr/bin</filename>
	and the shell is picking that one up before it gets to
	checking the current directory. Either type:</para>

	<informalexample>
	<screen>&prompt.user; <userinput>./test</userinput>
	</screen>
	</informalexample>

	<para>or choose a better name for your program!</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>I compiled my program and it seemed to run all right
	at first, then there was an error and it said something
	about <errorname>core dumped</errorname>. What does that
	mean?</para>
	</question>

	<answer>
	<para>The name <firstterm>core dump</firstterm> dates back
	to the very early days of &unix;, when the machines used
	core memory for storing data. Basically, if the program
	failed under certain conditions, the system would write
	the contents of core memory to disk in a file called
	<filename>core</filename>, which the programmer could
	then pore over to find out what went wrong.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>Fascinating stuff, but what I am supposed to do
	now?</para>
	</question>

	<answer>
	<para>Use <command>gdb</command> to analyze the core (see
	<xref linkend="debugging"/>).</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>When my program dumped core, it said something about
	a <errorname>segmentation fault</errorname>. What is
	that?</para>
	</question>

	<answer>
	<para>This basically means that your program tried to
	perform some sort of illegal operation on memory; &unix;
	is designed to protect the operating system and other
	programs from rogue programs.</para>

	<para>Common causes for this are:</para>

	<itemizedlist>
	<listitem>
	<para>Trying to write to a <symbol>NULL</symbol>
	pointer, eg</para>

	<programlisting>char *foo = NULL;
	strcpy(foo, "bang!");
	</programlisting>
	</listitem>

	<listitem>
	<para>Using a pointer that has not been initialized,
	eg</para>

	<programlisting>char *foo;
	strcpy(foo, "bang!");
	</programlisting>

	<para>The pointer will have some random value that,
	with luck, will point into an area of memory that
	is not available to your program and the kernel will
	kill your program before it can do any damage. If
	you are unlucky, it will point somewhere inside your
	own program and corrupt one of your data structures,
	causing the program to fail mysteriously.</para>
	</listitem>

	<listitem>
	<para>Trying to access past the end of an array,
	eg</para>

	<programlisting>int bar[20];
	bar[27] = 6;
	</programlisting>
	</listitem>

	<listitem>
	<para>Trying to store something in read-only memory,
	eg</para>

	<programlisting>char *foo = "My string";
	strcpy(foo, "bang!");
	</programlisting>

	<para>&unix; compilers often put string literals like
	<literal>"My string"</literal> into read-only areas
	of memory.</para>
	</listitem>

	<listitem>
	<para>Doing naughty things with
	<function>malloc()</function> and
	<function>free()</function>, eg</para>

	<programlisting>char bar[80];
	free(bar);
	</programlisting>

	<para>or</para>

	<programlisting>char *foo = malloc(27);
	free(foo);
	free(foo);
	</programlisting>
	</listitem>
	</itemizedlist>

	<para>Making one of these mistakes will not always lead to
	an error, but they are always bad practice. Some
	systems and compilers are more tolerant than others,
	which is why programs that ran well on one system can
	crash when you try them on an another.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>Sometimes when I get a core dump it says
	<errorname>bus error</errorname>. It says in my &unix;
	book that this means a hardware problem, but the
	computer still seems to be working. Is this
	true?</para>
	</question>

	<answer>
	<para>No, fortunately not (unless of course you really do
	have a hardware problem…). This is usually
	another way of saying that you accessed memory in a way
	you should not have.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>This dumping core business sounds as though it could
	be quite useful, if I can make it happen when I want to.
	Can I do this, or do I have to wait until there is an
	error?</para>
	</question>

	<answer>
	<para>Yes, just go to another console or xterm, do</para>

	<screen>&prompt.user; <userinput>ps</userinput>
	</screen>

	<para>to find out the process ID of your program, and
	do</para>

	<screen>&prompt.user; <userinput>kill -ABRT <replaceable>pid</replaceable></userinput>
	</screen>

	<para>where
	<parameter><replaceable>pid</replaceable></parameter> is
	the process ID you looked up.</para>

	<para>This is useful if your program has got stuck in an
	infinite loop, for instance. If your program happens to
	trap <symbol>SIGABRT</symbol>, there are several other
	signals which have a similar effect.</para>

	<para>Alternatively, you can create a core dump from
	inside your program, by calling the
	<function>abort()</function> function. See the manual page
	of &man.abort.3; to learn more.</para>

	<para>If you want to create a core dump from outside your
	program, but do not want the process to terminate, you
	can use the <command>gcore</command> program. See the
	manual page of &man.gcore.1; for more information.</para>

	</answer>
	</qandaentry>
	</qandaset>
	</sect2>
	</sect1>

	<sect1 id="tools-make">
	<title>Make</title>

	<sect2>
	<title>What is <command>make</command>?</title>

	<para>When you are working on a simple program with only one or
	two source files, typing in</para>

	<screen>&prompt.user; <userinput>cc file1.c file2.c</userinput></screen>

	<para>is not too bad, but it quickly becomes very tedious when
	there are several files—and it can take a while to
	compile, too.</para>

	<para>One way to get around this is to use object files and only
	recompile the source file if the source code has changed. So
	we could have something like:</para>

	<screen>&prompt.user; <userinput>cc file1.o file2.o</userinput> … <userinput>file37.c</userinput> …</screen>

	<para>if we had changed <filename>file37.c</filename>, but not any
	of the others, since the last time we compiled. This may
	speed up the compilation quite a bit, but does not solve the
	typing problem.</para>

	<para>Or we could write a shell script to solve the typing
	problem, but it would have to re-compile everything, making it
	very inefficient on a large project.</para>

	<para>What happens if we have hundreds of source files lying
	about? What if we are working in a team with other people who
	forget to tell us when they have changed one of their source
	files that we use?</para>

	<para>Perhaps we could put the two solutions together and write
	something like a shell script that would contain some kind of
	magic rule saying when a source file needs compiling. Now all
	we need now is a program that can understand these rules, as
	it is a bit too complicated for the shell.</para>

	<para>This program is called <command>make</command>. It reads
	in a file, called a <firstterm>makefile</firstterm>, that
	tells it how different files depend on each other, and works
	out which files need to be re-compiled and which ones do not.
	For example, a rule could say something like <quote>if
	<filename>fromboz.o</filename> is older than
	<filename>fromboz.c</filename>, that means someone must have
	changed <filename>fromboz.c</filename>, so it needs to be
	re-compiled.</quote> The makefile also has rules telling
	make <emphasis>how</emphasis> to re-compile the source file,
	making it a much more powerful tool.</para>

	<para>Makefiles are typically kept in the same directory as the
	source they apply to, and can be called
	<filename>makefile</filename>, <filename>Makefile</filename>
	or <filename>MAKEFILE</filename>. Most programmers use the
	name <filename>Makefile</filename>, as this puts it near the
	top of a directory listing, where it can easily be
	seen.

	<footnote>
	<para>They do not use the <filename>MAKEFILE</filename> form
	as block capitals are often used for documentation files
	like <filename>README</filename>.</para>
	</footnote></para>
	</sect2>

	<sect2>
	<title>Example of using <command>make</command></title>

	<para>Here is a very simple make file:</para>

	<programlisting>foo: foo.c
	cc -o foo foo.c</programlisting>

	<para>It consists of two lines, a dependency line and a creation
	line.</para>

	<para>The dependency line here consists of the name of the
	program (known as the <firstterm>target</firstterm>), followed
	by a colon, then whitespace, then the name of the source file.
	When <command>make</command> reads this line, it looks to see
	if <filename>foo</filename> exists; if it exists, it compares
	the time <filename>foo</filename> was last modified to the
	time <filename>foo.c</filename> was last modified. If
	<filename>foo</filename> does not exist, or is older than
	<filename>foo.c</filename>, it then looks at the creation line
	to find out what to do. In other words, this is the rule for
	working out when <filename>foo.c</filename> needs to be
	re-compiled.</para>

	<para>The creation line starts with a <token>tab</token> (press
	the <keycap>tab</keycap> key) and then the command you would
	type to create <filename>foo</filename> if you were doing it
	at a command prompt. If <filename>foo</filename> is out of
	date, or does not exist, <command>make</command> then executes
	this command to create it. In other words, this is the rule
	which tells make how to re-compile
	<filename>foo.c</filename>.</para>

	<para>So, when you type <userinput>make</userinput>, it will
	make sure that <filename>foo</filename> is up to date with
	respect to your latest changes to <filename>foo.c</filename>.
	This principle can be extended to
	<filename>Makefile</filename>s with hundreds of
	targets—in fact, on FreeBSD, it is possible to compile
	the entire operating system just by typing <userinput>make
	world</userinput> in the appropriate directory!</para>

	<para>Another useful property of makefiles is that the targets
	do not have to be programs. For instance, we could have a make
	file that looks like this:</para>

	<programlisting>foo: foo.c
	cc -o foo foo.c

	install:
	cp foo /home/me</programlisting>

	<para>We can tell make which target we want to make by
	typing:</para>

	<screen>&prompt.user; <userinput>make <replaceable>target</replaceable></userinput></screen>

	<para><command>make</command> will then only look at that target
	and ignore any others. For example, if we type
	<userinput>make foo</userinput> with the makefile above, make
	will ignore the <maketarget>install</maketarget> target.</para>

	<para>If we just type <userinput>make</userinput> on its own,
	make will always look at the first target and then stop
	without looking at any others. So if we typed
	<userinput>make</userinput> here, it will just go to the
	<maketarget>foo</maketarget> target, re-compile
	<filename>foo</filename> if necessary, and then stop without
	going on to the <maketarget>install</maketarget> target.</para>

	<para>Notice that the <maketarget>install</maketarget> target does not
	actually depend on anything! This means that the command on
	the following line is always executed when we try to make that
	target by typing <userinput>make install</userinput>. In this
	case, it will copy <filename>foo</filename> into the user's
	home directory. This is often used by application makefiles,
	so that the application can be installed in the correct
	directory when it has been correctly compiled.</para>

	<para>This is a slightly confusing subject to try to explain.
	If you do not quite understand how <command>make</command>
	works, the best thing to do is to write a simple program like
	<quote>hello world</quote> and a make file like the one above
	and experiment. Then progress to using more than one source
	file, or having the source file include a header file. The
	<command>touch</command> command is very useful here—it
	changes the date on a file without you having to edit
	it.</para>
	</sect2>

	<sect2>
	<title>Make and include-files</title>

	<para>C code often starts with a list of files to include, for
	example stdio.h. Some of these files are system-include
	files, some of them are from the project you are now working
	on:
	</para>

	<programlisting>#include <stdio.h>
	#include "foo.h"

	int main(....</programlisting>

	<para>To make sure that this file is recompiled the moment
	<filename>foo.h</filename> is changed, you have to add it in
	your <filename>Makefile</filename>:</para>

	<programlisting>foo: foo.c foo.h</programlisting>

	<para>The moment your project is getting bigger and you have
	more and more own include-files to maintain, it will be a
	pain to keep track of all include files and the files which
	are depending on it. If you change an include-file but
	forget to recompile all the files which are depending on
	it, the results will be devastating. <command>gcc</command>
	has an option to analyze your files and to produce a list
	of include-files and their dependencies: <option>-MM</option>.
	</para>

	<para>If you add this to your Makefile:</para>

	<programlisting>depend:
	gcc -E -MM *.c > .depend</programlisting>

	<para>and run <userinput>make depend</userinput>, the file
	<filename>.depend</filename> will appear with a list of
	object-files, C-files and the include-files:</para>

	<programlisting>foo.o: foo.c foo.h</programlisting>

	<para>If you change <filename>foo.h</filename>, next time
	you run <command>make</command> all files depending on
	<filename>foo.h</filename> will be recompiled.</para>

	<para>Do not forget to run <command>make depend</command> each
	time you add an include-file to one of your files.</para>
	</sect2>

	<sect2>
	<title>FreeBSD Makefiles</title>

	<para>Makefiles can be rather complicated to write. Fortunately,
	BSD-based systems like FreeBSD come with some very powerful
	ones as part of the system. One very good example of this is
	the FreeBSD ports system. Here is the essential part of a
	typical ports <filename>Makefile</filename>:</para>

	<programlisting>MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/
	DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz

	.include <bsd.port.mk></programlisting>

	<para>Now, if we go to the directory for this port and type
	<userinput>make</userinput>, the following happens:</para>

	<procedure>
	<step>
	<para>A check is made to see if the source code for this
	port is already on the system.</para>
	</step>

	<step>
	<para>If it is not, an FTP connection to the URL in
	<symbol>MASTER_SITES</symbol> is set up to download the
	source.</para>
	</step>

	<step>
	<para>The checksum for the source is calculated and compared
	it with one for a known, good, copy of the source. This
	is to make sure that the source was not corrupted while in
	transit.</para>
	</step>

	<step>
	<para>Any changes required to make the source work on
	FreeBSD are applied—this is known as
	<firstterm>patching</firstterm>.</para>
	</step>

	<step>
	<para>Any special configuration needed for the source is
	done. (Many &unix; program distributions try to work out
	which version of &unix; they are being compiled on and which
	optional &unix; features are present—this is where
	they are given the information in the FreeBSD ports
	scenario).</para>
	</step>

	<step>
	<para>The source code for the program is compiled. In
	effect, we change to the directory where the source was
	unpacked and do <command>make</command>—the
	program's own make file has the necessary information to
	build the program.</para>
	</step>

	<step>
	<para>We now have a compiled version of the program. If we
	wish, we can test it now; when we feel confident about the
	program, we can type <userinput>make install</userinput>.
	This will cause the program and any supporting files it
	needs to be copied into the correct location; an entry is
	also made into a <database>package database</database>, so
	that the port can easily be uninstalled later if we change
	our mind about it.</para>
	</step>
	</procedure>

	<para>Now I think you will agree that is rather impressive for a
	four line script!</para>

	<para>The secret lies in the last line, which tells
	<command>make</command> to look in the system makefile called
	<filename>bsd.port.mk</filename>. It is easy to overlook this
	line, but this is where all the clever stuff comes
	from—someone has written a makefile that tells
	<command>make</command> to do all the things above (plus a
	couple of other things I did not mention, including handling
	any errors that may occur) and anyone can get access to that
	just by putting a single line in their own make file!</para>

	<para>If you want to have a look at these system makefiles,
	they are in <filename>/usr/share/mk</filename>, but it is
	probably best to wait until you have had a bit of practice with
	makefiles, as they are very complicated (and if you do look at
	them, make sure you have a flask of strong coffee
	handy!)</para>
	</sect2>

	<sect2>
	<title>More advanced uses of <command>make</command></title>

	<para><command>Make</command> is a very powerful tool, and can
	do much more than the simple example above shows.
	Unfortunately, there are several different versions of
	<command>make</command>, and they all differ considerably.
	The best way to learn what they can do is probably to read the
	documentation—hopefully this introduction will have
	given you a base from which you can do this.</para>

	<para>The version of make that comes with FreeBSD is the
	<application>Berkeley make</application>; there is a tutorial
	for it in <filename>/usr/share/doc/psd/12.make</filename>. To
	view it, do</para>

	<screen>&prompt.user; <userinput>zmore paper.ascii.gz</userinput></screen>

	<para>in that directory.</para>

	<para>Many applications in the ports use <application>GNU
	make</application>, which has a very good set of
	<quote>info</quote> pages. If you have installed any of these
	ports, <application>GNU make</application> will automatically
	have been installed as <command>gmake</command>. It is also
	available as a port and package in its own right.</para>

	<para>To view the info pages for <application>GNU
	make</application>, you will have to edit the
	<filename>dir</filename> file in the
	<filename>/usr/local/info</filename> directory to add an entry
	for it. This involves adding a line like</para>

	<programlisting> * Make: (make). The GNU Make utility.</programlisting>

	<para>to the file. Once you have done this, you can type
	<userinput>info</userinput> and then select
	<guimenuitem>make</guimenuitem> from the menu (or in
	<application>Emacs</application>, do <userinput>C-h
	i</userinput>).</para>
	</sect2>
	</sect1>

	<sect1 id="debugging">
	<title>Debugging</title>

	<sect2>
	<title>The Debugger</title>

	<para>The debugger that comes with FreeBSD is called
	<command>gdb</command> (<application>GNU
	debugger</application>). You start it up by typing</para>

	<screen>&prompt.user; <userinput>gdb <replaceable>progname</replaceable></userinput></screen>

	<para>although many people prefer to run it inside
	<application>Emacs</application>. You can do this by:</para>

	<screen><userinput>M-x gdb RET <replaceable>progname</replaceable> RET</userinput></screen>

	<para>Using a debugger allows you to run the program under more
	controlled circumstances. Typically, you can step through the
	program a line at a time, inspect the value of variables,
	change them, tell the debugger to run up to a certain point
	and then stop, and so on. You can even attach to a program
	that is already running, or load a core file to investigate why
	the program crashed. It is even possible to debug the kernel,
	though that is a little trickier than the user applications
	we will be discussing in this section.</para>

	<para><command>gdb</command> has quite good on-line help, as
	well as a set of info pages, so this section will concentrate
	on a few of the basic commands.</para>

	<para>Finally, if you find its text-based command-prompt style
	off-putting, there is a graphical front-end for it
	(<filename role="package">devel/xxgdb</filename>) in the Ports
	Collection.</para>

	<para>This section is intended to be an introduction to using
	<command>gdb</command> and does not cover specialized topics
	such as debugging the kernel.</para>
	</sect2>

	<sect2>
	<title>Running a program in the debugger</title>

	<para>You will need to have compiled the program with the
	<option>-g</option> option to get the most out of using
	<command>gdb</command>. It will work without, but you will only
	see the name of the function you are in, instead of the source
	code. If you see a line like:</para>

	<screen>… (no debugging symbols found) …</screen>

	<para>when <command>gdb</command> starts up, you will know that
	the program was not compiled with the <option>-g</option>
	option.</para>

	<para>At the <command>gdb</command> prompt, type
	<userinput>break main</userinput>. This will tell the
	debugger that you are not interested in watching the
	preliminary set-up code in the program being run, and that it
	should stop execution at the beginning of your code. Now type
	<userinput>run</userinput> to start the program—it will
	start at the beginning of the set-up code and then get stopped
	by the debugger when it calls <function>main()</function>.
	(If you have ever wondered where <function>main()</function>
	gets called from, now you know!).</para>

	<para>You can now step through the program, a line at a time, by
	pressing <command>n</command>. If you get to a function call,
	you can step into it by pressing <command>s</command>. Once
	you are in a function call, you can return from stepping into a
	function call by pressing <command>f</command>. You can also
	use <command>up</command> and <command>down</command> to take
	a quick look at the caller.</para>

	<para>Here is a simple example of how to spot a mistake in a
	program with <command>gdb</command>. This is our program
	(with a deliberate mistake):</para>

	<programlisting>#include <stdio.h>

	int bazz(int anint);

	main() {
	int i;

	printf("This is my program\n");
	bazz(i);
	return 0;
	}

	int bazz(int anint) {
	printf("You gave me %d\n", anint);
	return anint;
	}</programlisting>

	<para>This program sets <symbol>i</symbol> to be
	<literal>5</literal> and passes it to a function
	<function>bazz()</function> which prints out the number we
	gave it.</para>

	<para>When we compile and run the program we get</para>

	<screen>&prompt.user; <userinput>cc -g -o temp temp.c</userinput>
	&prompt.user; <userinput>./temp</userinput>
	This is my program
	anint = 4231</screen>

	<para>That was not what we expected! Time to see what is going
	on!</para>

	<screen>&prompt.user; <userinput>gdb temp</userinput>
	GDB is free software and you are welcome to distribute copies of it
	under certain conditions; type "show copying" to see the conditions.
	There is absolutely no warranty for GDB; type "show warranty" for details.
	GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc.
	(gdb) <userinput>break main</userinput> <lineannotation>Skip the set-up code</lineannotation>
	Breakpoint 1 at 0x160f: file temp.c, line 9. <lineannotation><command>gdb</command> puts breakpoint at <function>main()</function></lineannotation>
	(gdb) <userinput>run</userinput> <lineannotation>Run as far as <function>main()</function></lineannotation>
	Starting program: /home/james/tmp/temp <lineannotation>Program starts running</lineannotation>

	Breakpoint 1, main () at temp.c:9 <lineannotation><command>gdb</command> stops at <function>main()</function></lineannotation>
	(gdb) <userinput>n</userinput> <lineannotation>Go to next line</lineannotation>
	This is my program <lineannotation>Program prints out</lineannotation>
	(gdb) <userinput>s</userinput> <lineannotation>step into <function>bazz()</function></lineannotation>
	bazz (anint=4231) at temp.c:17 <lineannotation><command>gdb</command> displays stack frame</lineannotation>
	(gdb)</screen>

	<para>Hang on a minute! How did <symbol>anint</symbol> get to be
	<literal>4231</literal>? Did we not we set it to be
	<literal>5</literal> in <function>main()</function>? Let's
	move up to <function>main()</function> and have a look.</para>

	<screen>(gdb) <userinput>up</userinput> <lineannotation>Move up call stack</lineannotation>
	#1 0x1625 in main () at temp.c:11 <lineannotation><command>gdb</command> displays stack frame</lineannotation>
	(gdb) <userinput>p i</userinput> <lineannotation>Show us the value of <symbol>i</symbol></lineannotation>
	$1 = 4231 <lineannotation><command>gdb</command> displays <literal>4231</literal></lineannotation></screen>

	<para>Oh dear! Looking at the code, we forgot to initialize
	<symbol>i</symbol>. We meant to put</para>

	<programlisting><lineannotation>…</lineannotation>
	main() {
	int i;

	i = 5;
	printf("This is my program\n");
	<lineannotation>…</lineannotation></programlisting>

	<para>but we left the <literal>i=5;</literal> line out. As we
	did not initialize <symbol>i</symbol>, it had whatever number
	happened to be in that area of memory when the program ran,
	which in this case happened to be
	<literal>4231</literal>.</para>

	<note>
	<para><command>gdb</command> displays the stack frame every
	time we go into or out of a function, even if we are using
	<command>up</command> and <command>down</command> to move
	around the call stack. This shows the name of the function
	and the values of its arguments, which helps us keep track
	of where we are and what is going on. (The stack is a
	storage area where the program stores information about the
	arguments passed to functions and where to go when it
	returns from a function call).</para>
	</note>
	</sect2>

	<sect2>
	<title>Examining a core file</title>

	<para>A core file is basically a file which contains the
	complete state of the process when it crashed. In <quote>the
	good old days</quote>, programmers had to print out hex
	listings of core files and sweat over machine code manuals,
	but now life is a bit easier. Incidentally, under FreeBSD and
	other 4.4BSD systems, a core file is called
	<filename><replaceable>progname</replaceable>.core</filename> instead of just
	<filename>core</filename>, to make it clearer which program a
	core file belongs to.</para>

	<para>To examine a core file, start up <command>gdb</command> in
	the usual way. Instead of typing <command>break</command> or
	<command>run</command>, type</para>

	<screen>(gdb) <userinput>core <replaceable>progname</replaceable>.core</userinput></screen>

	<para>If you are not in the same directory as the core file,
	you will have to do <userinput>dir
	/path/to/core/file</userinput> first.</para>

	<para>You should see something like this:</para>

	<screen>&prompt.user; <userinput>gdb a.out</userinput>
	GDB is free software and you are welcome to distribute copies of it
	under certain conditions; type "show copying" to see the conditions.
	There is absolutely no warranty for GDB; type "show warranty" for details.
	GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc.
	(gdb) <userinput>core a.out.core</userinput>
	Core was generated by `a.out'.
	Program terminated with signal 11, Segmentation fault.
	Cannot access memory at address 0x7020796d.
	#0 0x164a in bazz (anint=0x5) at temp.c:17
	(gdb)</screen>

	<para>In this case, the program was called
	<filename>a.out</filename>, so the core file is called
	<filename>a.out.core</filename>. We can see that the program
	crashed due to trying to access an area in memory that was not
	available to it in a function called
	<function>bazz</function>.</para>

	<para>Sometimes it is useful to be able to see how a function was
	called, as the problem could have occurred a long way up the
	call stack in a complex program. The <command>bt</command>
	command causes <command>gdb</command> to print out a
	back-trace of the call stack:</para>

	<screen>(gdb) <userinput>bt</userinput>
	#0 0x164a in bazz (anint=0x5) at temp.c:17
	#1 0xefbfd888 in end ()
	#2 0x162c in main () at temp.c:11
	(gdb)</screen>

	<para>The <function>end()</function> function is called when a
	program crashes; in this case, the <function>bazz()</function>
	function was called from <function>main()</function>.</para>
	</sect2>

	<sect2>
	<title>Attaching to a running program</title>

	<para>One of the neatest features about <command>gdb</command>
	is that it can attach to a program that is already running. Of
	course, that assumes you have sufficient permissions to do so.
	A common problem is when you are stepping through a program
	that forks, and you want to trace the child, but the debugger
	will only let you trace the parent.</para>

	<para>What you do is start up another <command>gdb</command>,
	use <command>ps</command> to find the process ID for the
	child, and do</para>

	<screen>(gdb) <userinput>attach <replaceable>pid</replaceable></userinput></screen>

	<para>in <command>gdb</command>, and then debug as usual.</para>

	<para><quote>That is all very well,</quote> you are probably
	thinking, <quote>but by the time I have done that, the child
	process will be over the hill and far away</quote>. Fear
	not, gentle reader, here is how to do it (courtesy of the
	<command>gdb</command> info pages):</para>

	<screen><lineannotation>…</lineannotation>
	if ((pid = fork()) < 0) /* _Always_ check this */
	error();
	else if (pid == 0) { /* child */
	int PauseMode = 1;

	while (PauseMode)
	sleep(10); /* Wait until someone attaches to us */
	<lineannotation>…</lineannotation>
	} else { /* parent */
	<lineannotation>…</lineannotation></screen>

	<para>Now all you have to do is attach to the child, set
	<symbol>PauseMode</symbol> to <literal>0</literal>, and wait
	for the <function>sleep()</function> call to return!</para>
	</sect2>
	</sect1>

	<sect1 id="emacs">
	<title>Using Emacs as a Development Environment</title>

	<sect2>
	<title>Emacs</title>

	<para>Emacs is a highly customizable
	editor—indeed, it has been customized to the point where
	it is more like an operating system than an editor! Many
	developers and sysadmins do in fact spend practically all
	their time working inside Emacs, leaving it only to log
	out.</para>

	<para>It is impossible even to summarize everything Emacs can do
	here, but here are some of the features of interest to
	developers:</para>

	<itemizedlist>
	<listitem>
	<para>Very powerful editor, allowing search-and-replace on
	both strings and regular expressions (patterns), jumping
	to start/end of block expression, etc, etc.</para>
	</listitem>

	<listitem>
	<para>Pull-down menus and online help.</para>
	</listitem>

	<listitem>
	<para>Language-dependent syntax highlighting and
	indentation.</para>
	</listitem>

	<listitem>
	<para>Completely customizable.</para>
	</listitem>

	<listitem>
	<para>You can compile and debug programs within
	Emacs.</para>
	</listitem>

	<listitem>
	<para>On a compilation error, you can jump to the offending
	line of source code.</para>
	</listitem>

	<listitem>
	<para>Friendly-ish front-end to the <command>info</command>
	program used for reading GNU hypertext documentation,
	including the documentation on Emacs itself.</para>
	</listitem>

	<listitem>
	<para>Friendly front-end to <command>gdb</command>, allowing
	you to look at the source code as you step through your
	program.</para>
	</listitem>
	</itemizedlist>

	<para>And doubtless many more that have been overlooked.</para>

	<para>Emacs can be installed on &os; using
	the <filename role="package">editors/emacs</filename>
	port.</para>

	<para>Once it is installed, start it up and do <userinput>C-h
	t</userinput> to read an Emacs tutorial—that means
	hold down the <keycap>control</keycap> key, press
	<keycap>h</keycap>, let go of the <keycap>control</keycap>
	key, and then press <keycap>t</keycap>. (Alternatively, you
	can use the mouse to select <guimenuitem>Emacs
	Tutorial</guimenuitem> from the <guimenu>Help</guimenu>
	menu.)</para>

	<para>Although Emacs does have menus, it is well worth learning
	the key bindings, as it is much quicker when you are editing
	something to press a couple of keys than to try to find the
	mouse and then click on the right place. And, when you are
	talking to seasoned Emacs users, you will find they often
	casually throw around expressions like <quote><literal>M-x
	replace-s RET foo RET bar RET</literal></quote> so it is
	useful to know what they mean. And in any case, Emacs has far
	too many useful functions for them to all fit on the menu
	bars.</para>

	<para>Fortunately, it is quite easy to pick up the key-bindings,
	as they are displayed next to the menu item. My advice is to
	use the menu item for, say, opening a file until you
	understand how it works and feel confident with it, then try
	doing C-x C-f. When you are happy with that, move on to
	another menu command.</para>

	<para>If you can not remember what a particular combination of
	keys does, select <guimenuitem>Describe Key</guimenuitem> from
	the <guimenu>Help</guimenu> menu and type it in—Emacs
	will tell you what it does. You can also use the
	<guimenuitem>Command Apropos</guimenuitem> menu item to find
	out all the commands which contain a particular word in them,
	with the key binding next to it.</para>

	<para>By the way, the expression above means hold down the
	<keysym>Meta</keysym> key, press <keysym>x</keysym>, release
	the <keysym>Meta</keysym> key, type
	<userinput>replace-s</userinput> (short for
	<literal>replace-string</literal>—another feature of
	Emacs is that you can abbreviate commands), press the
	<keysym>return</keysym> key, type <userinput>foo</userinput>
	(the string you want replaced), press the
	<keysym>return</keysym> key, type bar (the string you want to
	replace <literal>foo</literal> with) and press
	<keysym>return</keysym> again. Emacs will then do the
	search-and-replace operation you have just requested.</para>

	<para>If you are wondering what on earth the
	<keysym>Meta</keysym> key is, it is a special key that many
	&unix; workstations have. Unfortunately, PC's do not have one,
	so it is usually the <keycap>alt</keycap> key (or if you are
	unlucky, the <keysym>escape</keysym> key).</para>

	<para>Oh, and to get out of Emacs, do <command>C-x C-c</command>
	(that means hold down the <keysym>control</keysym> key, press
	<keysym>x</keysym>, press <keysym>c</keysym> and release the
	<keysym>control</keysym> key). If you have any unsaved files
	open, Emacs will ask you if you want to save them. (Ignore
	the bit in the documentation where it says
	<command>C-z</command> is the usual way to leave
	Emacs—that leaves Emacs hanging around in the
	background, and is only really useful if you are on a system
	which does not have virtual terminals).</para>
	</sect2>

	<sect2>
	<title>Configuring Emacs</title>

	<para>Emacs does many wonderful things; some of them are built
	in, some of them need to be configured.</para>

	<para>Instead of using a proprietary macro language for
	configuration, Emacs uses a version of Lisp specially adapted
	for editors, known as Emacs Lisp. Working with Emacs Lisp can
	be quite helpful if you want to go on and learn something like
	Common Lisp. Emacs Lisp has many features of Common Lisp,
	although it is considerably smaller (and thus easier to
	master).</para>

	<para>The best way to learn Emacs Lisp is to download the <ulink
	url="ftp://ftp.gnu.org/old-gnu/emacs/elisp-manual-19-2.4.tar.gz">Emacs
	Tutorial</ulink></para>

	<para>However, there is no need to actually know any Lisp to get
	started with configuring Emacs, as I have included a sample
	<filename>.emacs</filename> file, which should be enough to
	get you started. Just copy it into your home directory and
	restart Emacs if it is already running; it will read the
	commands from the file and (hopefully) give you a useful basic
	setup.</para>
	</sect2>

	<sect2>
	<title>A sample <filename>.emacs</filename> file</title>

	<para>Unfortunately, there is far too much here to explain it in
	detail; however there are one or two points worth
	mentioning.</para>

	<itemizedlist>
	<listitem>
	<para>Everything beginning with a <literal>;</literal> is a comment
	and is ignored by Emacs.</para>
	</listitem>

	<listitem>
	<para>In the first line, the
	<literal>-- Emacs-Lisp --</literal> is so that
	we can edit the <filename>.emacs</filename> file itself
	within Emacs and get all the fancy features for editing
	Emacs Lisp. Emacs usually tries to guess this based on
	the filename, and may not get it right for
	<filename>.emacs</filename>.</para>
	</listitem>

	<listitem>
	<para>The <keysym>tab</keysym> key is bound to an
	indentation function in some modes, so when you press the
	tab key, it will indent the current line of code. If you
	want to put a <token>tab</token> character in whatever
	you are writing, hold the <keysym>control</keysym> key down
	while you are pressing the <keysym>tab</keysym> key.</para>
	</listitem>

	<listitem>
	<para>This file supports syntax highlighting for C, C++,
	Perl, Lisp and Scheme, by guessing the language from the
	filename.</para>
	</listitem>

	<listitem>
	<para>Emacs already has a pre-defined function called
	<function>next-error</function>. In a compilation output
	window, this allows you to move from one compilation error
	to the next by doing <command>M-n</command>; we define a
	complementary function,
	<function>previous-error</function>, that allows you to go
	to a previous error by doing <command>M-p</command>. The
	nicest feature of all is that <command>C-c C-c</command>
	will open up the source file in which the error occurred
	and jump to the appropriate line.</para>
	</listitem>

	<listitem>
	<para>We enable Emacs's ability to act as a server, so that
	if you are doing something outside Emacs and you want to
	edit a file, you can just type in</para>

	<screen>&prompt.user; <userinput>emacsclient <replaceable>filename</replaceable></userinput>
	</screen>

	<para>and then you can edit the file in your
	Emacs!

	<footnote>
	<para>Many Emacs users set their <envar>EDITOR</envar>
	environment to
	<literal>emacsclient</literal> so this happens every
	time they need to edit a file.</para>
	</footnote></para>
	</listitem>
	</itemizedlist>

	<example>
	<title>A sample <filename>.emacs</filename> file</title>

	<programlisting>;; --Emacs-Lisp--

	;; This file is designed to be re-evaled; use the variable first-time
	;; to avoid any problems with this.
	(defvar first-time t
	"Flag signifying this is the first time that .emacs has been evaled")

	;; Meta
	(global-set-key "\M- " 'set-mark-command)
	(global-set-key "\M-\C-h" 'backward-kill-word)
	(global-set-key "\M-\C-r" 'query-replace)
	(global-set-key "\M-r" 'replace-string)
	(global-set-key "\M-g" 'goto-line)
	(global-set-key "\M-h" 'help-command)

	;; Function keys
	(global-set-key [f1] 'manual-entry)
	(global-set-key [f2] 'info)
	(global-set-key [f3] 'repeat-complex-command)
	(global-set-key [f4] 'advertised-undo)
	(global-set-key [f5] 'eval-current-buffer)
	(global-set-key [f6] 'buffer-menu)
	(global-set-key [f7] 'other-window)
	(global-set-key [f8] 'find-file)
	(global-set-key [f9] 'save-buffer)
	(global-set-key [f10] 'next-error)
	(global-set-key [f11] 'compile)
	(global-set-key [f12] 'grep)
	(global-set-key [C-f1] 'compile)
	(global-set-key [C-f2] 'grep)
	(global-set-key [C-f3] 'next-error)
	(global-set-key [C-f4] 'previous-error)
	(global-set-key [C-f5] 'display-faces)
	(global-set-key [C-f8] 'dired)
	(global-set-key [C-f10] 'kill-compilation)

	;; Keypad bindings
	(global-set-key [up] "\C-p")
	(global-set-key [down] "\C-n")
	(global-set-key [left] "\C-b")
	(global-set-key [right] "\C-f")
	(global-set-key [home] "\C-a")
	(global-set-key [end] "\C-e")
	(global-set-key [prior] "\M-v")
	(global-set-key [next] "\C-v")
	(global-set-key [C-up] "\M-\C-b")
	(global-set-key [C-down] "\M-\C-f")
	(global-set-key [C-left] "\M-b")
	(global-set-key [C-right] "\M-f")
	(global-set-key [C-home] "\M-<")
	(global-set-key [C-end] "\M->")
	(global-set-key [C-prior] "\M-<")
	(global-set-key [C-next] "\M->")

	;; Mouse
	(global-set-key [mouse-3] 'imenu)

	;; Misc
	(global-set-key [C-tab] "\C-q\t") ; Control tab quotes a tab.
	(setq backup-by-copying-when-mismatch t)

	;; Treat 'y' or <CR> as yes, 'n' as no.
	(fset 'yes-or-no-p 'y-or-n-p)
	(define-key query-replace-map [return] 'act)
	(define-key query-replace-map [?\C-m] 'act)

	;; Load packages
	(require 'desktop)
	(require 'tar-mode)

	;; Pretty diff mode
	(autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t)
	(autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t)
	(autoload 'ediff-files-remote "ediff"
	"Intelligent Emacs interface to diff")

	(if first-time
	(setq auto-mode-alist
	(append '(("\\.cpp$" . c++-mode)
	("\\.hpp$" . c++-mode)
	("\\.lsp$" . lisp-mode)
	("\\.scm$" . scheme-mode)
	("\\.pl$" . perl-mode)
	) auto-mode-alist)))

	;; Auto font lock mode
	(defvar font-lock-auto-mode-list
	(list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode)
	"List of modes to always start in font-lock-mode")

	(defvar font-lock-mode-keyword-alist
	'((c++-c-mode . c-font-lock-keywords)
	(perl-mode . perl-font-lock-keywords))
	"Associations between modes and keywords")

	(defun font-lock-auto-mode-select ()
	"Automatically select font-lock-mode if the current major mode is in font-lock-auto-mode-list"
	(if (memq major-mode font-lock-auto-mode-list)
	(progn
	(font-lock-mode t))
	)
	)

	(global-set-key [M-f1] 'font-lock-fontify-buffer)

	;; New dabbrev stuff
	;(require 'new-dabbrev)
	(setq dabbrev-always-check-other-buffers t)
	(setq dabbrev-abbrev-char-regexp "\\sw\\\|\\s_")
	(add-hook 'emacs-lisp-mode-hook
	'(lambda ()
	(set (make-local-variable 'dabbrev-case-fold-search) nil)
	(set (make-local-variable 'dabbrev-case-replace) nil)))
	(add-hook 'c-mode-hook
	'(lambda ()
	(set (make-local-variable 'dabbrev-case-fold-search) nil)
	(set (make-local-variable 'dabbrev-case-replace) nil)))
	(add-hook 'text-mode-hook
	'(lambda ()
	(set (make-local-variable 'dabbrev-case-fold-search) t)
	(set (make-local-variable 'dabbrev-case-replace) t)))

	;; C++ and C mode...
	(defun my-c++-mode-hook ()
	(setq tab-width 4)
	(define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent)
	(define-key c++-mode-map "\C-ce" 'c-comment-edit)
	(setq c++-auto-hungry-initial-state 'none)
	(setq c++-delete-function 'backward-delete-char)
	(setq c++-tab-always-indent t)
	(setq c-indent-level 4)
	(setq c-continued-statement-offset 4)
	(setq c++-empty-arglist-indent 4))

	(defun my-c-mode-hook ()
	(setq tab-width 4)
	(define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent)
	(define-key c-mode-map "\C-ce" 'c-comment-edit)
	(setq c-auto-hungry-initial-state 'none)
	(setq c-delete-function 'backward-delete-char)
	(setq c-tab-always-indent t)
	;; BSD-ish indentation style
	(setq c-indent-level 4)
	(setq c-continued-statement-offset 4)
	(setq c-brace-offset -4)
	(setq c-argdecl-indent 0)
	(setq c-label-offset -4))

	;; Perl mode
	(defun my-perl-mode-hook ()
	(setq tab-width 4)
	(define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent)
	(setq perl-indent-level 4)
	(setq perl-continued-statement-offset 4))

	;; Scheme mode...
	(defun my-scheme-mode-hook ()
	(define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent))

	;; Emacs-Lisp mode...
	(defun my-lisp-mode-hook ()
	(define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent)
	(define-key lisp-mode-map "\C-i" 'lisp-indent-line)
	(define-key lisp-mode-map "\C-j" 'eval-print-last-sexp))

	;; Add all of the hooks...
	(add-hook 'c++-mode-hook 'my-c++-mode-hook)
	(add-hook 'c-mode-hook 'my-c-mode-hook)
	(add-hook 'scheme-mode-hook 'my-scheme-mode-hook)
	(add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook)
	(add-hook 'lisp-mode-hook 'my-lisp-mode-hook)
	(add-hook 'perl-mode-hook 'my-perl-mode-hook)

	;; Complement to next-error
	(defun previous-error (n)
	"Visit previous compilation error message and corresponding source code."
	(interactive "p")
	(next-error (- n)))

	;; Misc...
	(transient-mark-mode 1)
	(setq mark-even-if-inactive t)
	(setq visible-bell nil)
	(setq next-line-add-newlines nil)
	(setq compile-command "make")
	(setq suggest-key-bindings nil)
	(put 'eval-expression 'disabled nil)
	(put 'narrow-to-region 'disabled nil)
	(put 'set-goal-column 'disabled nil)
	(if (>= emacs-major-version 21)
	(setq show-trailing-whitespace t))

	;; Elisp archive searching
	(autoload 'format-lisp-code-directory "lispdir" nil t)
	(autoload 'lisp-dir-apropos "lispdir" nil t)
	(autoload 'lisp-dir-retrieve "lispdir" nil t)
	(autoload 'lisp-dir-verify "lispdir" nil t)

	;; Font lock mode
	(defun my-make-face (face color &optional bold)
	"Create a face from a color and optionally make it bold"
	(make-face face)
	(copy-face 'default face)
	(set-face-foreground face color)
	(if bold (make-face-bold face))
	)

	(if (eq window-system 'x)
	(progn
	(my-make-face 'blue "blue")
	(my-make-face 'red "red")
	(my-make-face 'green "dark green")
	(setq font-lock-comment-face 'blue)
	(setq font-lock-string-face 'bold)
	(setq font-lock-type-face 'bold)
	(setq font-lock-keyword-face 'bold)
	(setq font-lock-function-name-face 'red)
	(setq font-lock-doc-string-face 'green)
	(add-hook 'find-file-hooks 'font-lock-auto-mode-select)

	(setq baud-rate 1000000)
	(global-set-key "\C-cmm" 'menu-bar-mode)
	(global-set-key "\C-cms" 'scroll-bar-mode)
	(global-set-key [backspace] 'backward-delete-char)
	; (global-set-key [delete] 'delete-char)
	(standard-display-european t)
	(load-library "iso-transl")))

	;; X11 or PC using direct screen writes
	(if window-system
	(progn
	;; (global-set-key [M-f1] 'hilit-repaint-command)
	;; (global-set-key [M-f2] [?\C-u M-f1])
	(setq hilit-mode-enable-list
	'(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode
	scheme-mode)
	hilit-auto-highlight nil
	hilit-auto-rehighlight 'visible
	hilit-inhibit-hooks nil
	hilit-inhibit-rebinding t)
	(require 'hilit19)
	(require 'paren))
	(setq baud-rate 2400) ; For slow serial connections
	)

	;; TTY type terminal
	(if (and (not window-system)
	(not (equal system-type 'ms-dos)))
	(progn
	(if first-time
	(progn
	(keyboard-translate ?\C-h ?\C-?)
	(keyboard-translate ?\C-? ?\C-h)))))

	;; Under UNIX
	(if (not (equal system-type 'ms-dos))
	(progn
	(if first-time
	(server-start))))

	;; Add any face changes here
	(add-hook 'term-setup-hook 'my-term-setup-hook)
	(defun my-term-setup-hook ()
	(if (eq window-system 'pc)
	(progn
	;; (set-face-background 'default "red")
	)))

	;; Restore the "desktop" - do this as late as possible
	(if first-time
	(progn
	(desktop-load-default)
	(desktop-read)))

	;; Indicate that this file has been read at least once
	(setq first-time nil)

	;; No need to debug anything now

	(setq debug-on-error nil)

	;; All done
	(message "All done, %s%s" (user-login-name) ".")
	</programlisting>
	</example>
	</sect2>

	<sect2>
	<title>Extending the Range of Languages Emacs Understands</title>

	<para>Now, this is all very well if you only want to program in
	the languages already catered for in the
	<filename>.emacs</filename> file (C, C++, Perl, Lisp and
	Scheme), but what happens if a new language called
	<quote>whizbang</quote> comes out, full of exciting
	features?</para>

	<para>The first thing to do is find out if whizbang comes with
	any files that tell Emacs about the language. These usually
	end in <filename>.el</filename>, short for <quote>Emacs
	Lisp</quote>. For example, if whizbang is a FreeBSD port, we
	can locate these files by doing</para>

	<screen>&prompt.user; <userinput>find /usr/ports/lang/whizbang -name "*.el" -print</userinput></screen>

	<para>and install them by copying them into the Emacs site Lisp
	directory. On &os;, this is
	<filename>/usr/local/share/emacs/site-lisp</filename>.</para>

	<para>So for example, if the output from the find command
	was</para>

	<screen>/usr/ports/lang/whizbang/work/misc/whizbang.el</screen>

	<para>we would do</para>

	<screen>&prompt.root; <userinput>cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp</userinput></screen>

	<para>Next, we need to decide what extension whizbang source
	files have. Let's say for the sake of argument that they all
	end in <filename>.wiz</filename>. We need to add an entry to
	our <filename>.emacs</filename> file to make sure Emacs will
	be able to use the information in
	<filename>whizbang.el</filename>.</para>

	<para>Find the <symbol>auto-mode-alist entry</symbol> in
	<filename>.emacs</filename> and add a line for whizbang, such
	as:</para>

	<programlisting><lineannotation>…</lineannotation>
	("\\.lsp$" . lisp-mode)
	("\\.wiz$" . whizbang-mode)
	("\\.scm$" . scheme-mode)
	<lineannotation>…</lineannotation></programlisting>

	<para>This means that Emacs will automatically go into
	<function>whizbang-mode</function> when you edit a file ending
	in <filename>.wiz</filename>.</para>

	<para>Just below this, you will find the
	<symbol>font-lock-auto-mode-list</symbol> entry. Add
	<function>whizbang-mode</function> to it like so:</para>

	<programlisting>;; Auto font lock mode
	(defvar font-lock-auto-mode-list
	(list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode)
	"List of modes to always start in font-lock-mode")</programlisting>

	<para>This means that Emacs will always enable
	<function>font-lock-mode</function> (ie syntax highlighting)
	when editing a <filename>.wiz</filename> file.</para>

	<para>And that is all that is needed. If there is anything else
	you want done automatically when you open up a
	<filename>.wiz</filename> file, you can add a
	<function>whizbang-mode hook</function> (see
	<function>my-scheme-mode-hook</function> for a simple example
	that adds <function>auto-indent</function>).</para>
	</sect2>
	</sect1>

	<sect1 id="tools-reading">
	<title>Further Reading</title>

	<para>For information about setting up a development environment
	for contributing fixes to FreeBSD itself, please see
	&man.development.7;.</para>

	<itemizedlist>
	<listitem>
	<para>Brian Harvey and Matthew Wright
	<emphasis>Simply Scheme</emphasis>
	MIT 1994.<!-- <br> -->
	ISBN 0-262-08226-8</para>
	</listitem>

	<listitem>
	<para>Randall Schwartz
	<emphasis>Learning Perl</emphasis>
	O'Reilly 1993<!-- <br> -->
	ISBN 1-56592-042-2</para>
	</listitem>

	<listitem>
	<para>Patrick Henry Winston and Berthold Klaus Paul Horn
	<emphasis>Lisp (3rd Edition)</emphasis>
	Addison-Wesley 1989<!-- <br> -->
	ISBN 0-201-08319-1</para>
	</listitem>

	<listitem>
	<para>Brian W. Kernighan and Rob Pike
	<emphasis>The Unix Programming Environment</emphasis>
	Prentice-Hall 1984<!-- <br> -->
	ISBN 0-13-937681-X</para>
	</listitem>

	<listitem>
	<para>Brian W. Kernighan and Dennis M. Ritchie
	<emphasis>The C Programming Language (2nd Edition)</emphasis>
	Prentice-Hall 1988<!-- <br> -->
	ISBN 0-13-110362-8</para>
	</listitem>

	<listitem>
	<para>Bjarne Stroustrup
	<emphasis>The C++ Programming Language</emphasis>
	Addison-Wesley 1991<!-- <br> -->
	ISBN 0-201-53992-6</para>
	</listitem>

	<listitem>
	<para>W. Richard Stevens
	<emphasis>Advanced Programming in the Unix Environment</emphasis>
	Addison-Wesley 1992<!-- <br> -->
	ISBN 0-201-56317-7</para>
	</listitem>

	<listitem>
	<para>W. Richard Stevens
	<emphasis>Unix Network Programming</emphasis>
	Prentice-Hall 1990<!-- <br> -->
	ISBN 0-13-949876-1</para>
	</listitem>
	</itemizedlist>
	</sect1>

	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/faq/book.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/faq/book.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/faq/book.xml (revision 41355)
	@@ -1,8390 +1,8246 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	<!ENTITY bibliography SYSTEM "../../../share/xml/bibliography.xml">
	<!ENTITY rel.head "<emphasis>10-CURRENT</emphasis>">
	<!ENTITY rel.head.relx "10.<replaceable>X</replaceable>">
	<!ENTITY rel.head.releng "<symbol>HEAD</symbol>">
	<!ENTITY rel.head.packages "packages-10-current">
	<!ENTITY rel.relx "9.<replaceable>X</replaceable>">
	<!ENTITY rel.stable "<emphasis>9-STABLE</emphasis>">
	<!ENTITY rel.releng "<symbol>RELENG_9</symbol>">
	<!ENTITY rel.relengdate "September 2011">
	<!ENTITY rel.packages "packages-9-stable">
	<!ENTITY rel2.relx "8.<replaceable>X</replaceable>">
	<!ENTITY rel2.stable "<emphasis>8-STABLE</emphasis>">
	<!ENTITY rel2.releng "<symbol>RELENG_8</symbol>">
	<!ENTITY rel2.relengdate "August 2009">
	<!ENTITY rel2.packages "packages-8-stable">
	-<!ENTITY rel3.current "7.4">
	-<!ENTITY rel3.relx "7.<replaceable>X</replaceable>">
	-<!ENTITY rel3.stable "<emphasis>7-STABLE</emphasis>">
	-<!ENTITY rel3.releng "<symbol>RELENG_7</symbol>">
	-<!ENTITY rel3.relengdate "October 2007">
	-<!ENTITY rel3.packages "packages-7-stable">
	]>

	<book lang='en'>
	<bookinfo>
	<title>Frequently Asked Questions for &os;
	- &rel3.relx;, &rel2.relx;, and &rel.relx;</title>
	+ &rel2.relx;, and &rel.relx;</title>

	<corpauthor>The &os; Documentation Project</corpauthor>

	<copyright>
	<year>1995</year>
	<year>1996</year>
	<year>1997</year>
	<year>1998</year>
	<year>1999</year>
	<year>2000</year>
	<year>2001</year>
	<year>2002</year>
	<year>2003</year>
	<year>2004</year>
	<year>2005</year>
	<year>2006</year>
	<year>2007</year>
	<year>2008</year>
	<year>2009</year>
	<year>2010</year>
	<year>2011</year>
	<year>2012</year>
	<year>2013</year>
	<holder>The &os; Documentation Project</holder>
	</copyright>

	&legalnotice;

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	&tm-attrib.adobe;
	&tm-attrib.ibm;
	&tm-attrib.ieee;
	&tm-attrib.intel;
	&tm-attrib.linux;
	&tm-attrib.microsoft;
	- &tm-attrib.mips;
	+ &tm-attrib.netbsd;
	&tm-attrib.opengroup;
	- &tm-attrib.oracle;
	&tm-attrib.sgi;
	- &tm-attrib.sparc;
	&tm-attrib.sun;
	&tm-attrib.general;
	</legalnotice>

	<releaseinfo>$FreeBSD$</releaseinfo>

	<abstract>
	- <para>This is the FAQ for &os; versions
	- &rel3.relx;, &rel2.relx; and &rel.relx;.
	- All entries are assumed to be
	- relevant to &os; &rel3.relx; and later,
	- unless otherwise noted. If you are interested in helping with
	- this project, send email to the &a.doc;. The latest version of
	+ <para>This is the FAQ for &os; versions &rel2.relx; and
	+ &rel.relx;. Every effort has been made to make this FAQ as
	+ informative as possible; if you have any suggestions as to how
	+ it may be improved, please feel free to mail them to the
	+ &a.doc;.</para>
	+
	+ <para>The latest version of
	this document is always available from the <ulink
	url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/index.html">&os; website</ulink>.
	It may also be downloaded as one large <ulink
	url="book.html">HTML</ulink> file with HTTP or as a variety
	of other formats 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>
	+ server</ulink>.</para>
	</abstract>
	</bookinfo>

	<chapter id="introduction">
	<title>Introduction</title>

	- <para>Welcome to the &os;
	- &rel3.relx; -, &rel2.relx; - and &rel.relx; -
	- FAQ!</para>
	-
	- <para>As is usual with Usenet FAQs, this document aims to cover the
	- most frequently asked questions concerning the &os; operating
	- system (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>Every effort has been made to make this FAQ as informative as
	- possible; if you have any suggestions as to how it may be
	- improved, please feel free to mail them to the &a.doc;.</para>
	-
	<qandaset>
	<qandaentry>
	<question id="what-is-FreeBSD">
	<para>What is &os;?</para>
	</question>

	<answer>
	<para>&os; is a modern operating system for desktops,
	laptops, servers, and embedded systems with
	support for a large number of <ulink
	url="http://www.FreeBSD.org/platforms/">platforms</ulink>.</para>

	<para>It is based on U.C.
	Berkeley's <quote>4.4BSD-Lite</quote> release, with some
	<quote>4.4BSD-Lite2</quote> enhancements. It is also based
	indirectly on William Jolitz's port of U.C. Berkeley's
	<quote>Net/2</quote> to the &i386;, known as
	<quote>386BSD</quote>, though very little of the 386BSD code
	remains.</para>

	<para>&os; is used by companies, Internet Service Providers,
	researchers, computer professionals, students and home users
	all over the world in their work, education and
	recreation.</para>

	<para>For more detailed information on &os;, please see the
	<ulink
	url="&url.books.handbook;/index.html">&os; Handbook</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="FreeBSD-goals">
	<para>What is the goal of the &os; Project?</para>
	</question>

	<answer>
	<para>The goal of the &os; Project is to provide a
	stable and fast general purpose
	operating system that may
	be used for any purpose
	without strings attached.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="bsd-license-restrictions">
	<para>Does the &os; license have any restrictions?</para>
	</question>

	<answer>
	<para>Yes. Those restrictions do not control how you use the
	code, merely how you treat the &os; Project itself. If you
	have serious license concerns, read the actual <ulink
	url="http://www.FreeBSD.org/copyright/freebsd-license.html">license</ulink>.
	For the simply curious, the license can be summarized like
	this.</para>

	<itemizedlist>
	<listitem>
	<para>Do not claim that you wrote this.</para>
	</listitem>

	<listitem>
	<para>Do not sue us if it breaks.</para>
	</listitem>

	<listitem>
	<para>Do not remove or modify the license.</para>
	</listitem>
	</itemizedlist>

	<para>Many of us have a significant investment in the
	project
	and would certainly not mind a little financial
	compensation now and then, but we definitely do not insist
	on it. We believe that our first and foremost
	<quote>mission</quote> is to provide code to any and all
	comers, and for whatever purpose, so that the code gets
	the
	widest possible use and provides the widest possible
	benefit. This, we believe, is one of the most
	fundamental
	goals of Free Software and one that we enthusiastically
	support.</para>

	<para>Code in our source tree which falls under the
	<ulink
	url="http://www.FreeBSD.org/copyright/COPYING">GNU General Public License (GPL)</ulink>
	or <ulink
	url="http://www.FreeBSD.org/copyright/COPYING.LIB">GNU Library General Public License (LGPL)</ulink>
	comes with slightly more strings attached, though at least
	on the side of enforced access rather than the usual
	opposite. Due to the additional complexities that can
	evolve in the commercial use of GPL software, we do,
	however, endeavor to replace such software with submissions
	under the more relaxed <ulink
	url="http://www.FreeBSD.org/copyright/freebsd-license.html">&os; license</ulink>
	whenever possible.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="replace-current-OS">
	<para>Can &os; replace my current operating system?</para>
	</question>

	<answer>
	<para>For most people, yes. But this question is not quite
	that cut-and-dried.</para>

	<para>Most people do not actually use an operating system.
	They use applications. The applications are what really use
	the operating system. &os; is designed to provide a robust
	and full-featured environment for applications. It supports
	a wide variety of web browsers, office suites, email
	readers, graphics programs, programming environments,
	network servers, and just about everything else you might
	want. Most of these applications can be managed through the
	<ulink
	url="http://www.FreeBSD.org/ports/">Ports Collection</ulink>.</para>

	<para>If you need to use an application that is only available
	on one operating system, you simply cannot replace that
	operating system. Chances are there is a very similar
	application on &os;, however. If you want a solid office or
	Internet server, a reliable workstation, or just the ability
	to do your job without interruptions, &os; will almost
	certainly do everything you need. Many computer users
	across the world, including both novices and experienced
	&unix; administrators, use &os; as their only desktop
	operating system.</para>

	<para>If you are migrating to &os; from some other &unix;
	environment, you already know most of what you need to. If
	your background is in graphic-driven operating systems such
	as &windows; and &macos;, you may be interested in using
	<ulink
	url="http://www.pcbsd.org/">PC-BSD</ulink>, a &os; based
	distribution, instead. If you have not used &unix; before
	expect to invest
	additional time learning the &unix; way of doing things.
	This FAQ and the <ulink
	url="&url.books.handbook;/index.html">&os; Handbook</ulink>
	are excellent places to start.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="why-called-FreeBSD">
	<para>Why is it called &os;?</para>
	</question>

	<answer>
	<itemizedlist>
	<listitem>
	<para>It may be used free of charge, even by commercial
	users.</para>
	</listitem>

	<listitem>
	<para>Full source for the operating system is freely
	available, and the minimum possible restrictions have
	been placed upon its use, distribution and incorporation
	into other work (commercial or non-commercial).</para>
	</listitem>

	<listitem>
	<para>Anyone who has an improvement or bug fix is free to
	submit their code and have it added to the source tree
	(subject to one or two obvious provisions).</para>
	</listitem>
	</itemizedlist>

	<para>It is worth pointing out that the word
	<quote>free</quote> is being used in two ways here, one
	meaning <quote>at no cost</quote>, the other meaning
	<quote>you can do whatever you like</quote>. Apart from one
	or two things you <emphasis>cannot</emphasis> do with the
	&os; code, for example pretending you wrote it, you can
	really do whatever you like with it.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="differences-to-other-bsds">
	<para>What are the differences between &os; and NetBSD,
	OpenBSD, and other open source BSD operating systems?</para>
	</question>

	<answer>
	<para>James Howard wrote a good explanation of the history and
	differences between the various projects,
	called <ulink
	url="http://www.freebsdworld.gr/freebsd/bsd-family-tree.html">The BSD Family Tree</ulink>
	which goes a fair way to answering this question.
	Some of the information is out of date, but the history
	portion in particular remains accurate.</para>

	<para>Most of the BSDs share patches and code, even today.
	All of the BSDs have common ancestry.</para>

	<para>The design goals of &os; are described in
	<xref linkend="FreeBSD-goals"/>, above. The design goals
	of the other most popular BSDs may be summarized as
	follows:</para>

	<itemizedlist>
	<listitem>
	<para>OpenBSD aims for operating system security above
	all else. The OpenBSD team wrote &man.ssh.1; and
	&man.pf.4;, which have both been ported to &os;.</para>
	</listitem>

	<listitem>
	<para>NetBSD aims to be easily ported to other hardware
	platforms.</para>
	</listitem>

	<listitem>
	- <para>DragonFlyBSD is a fork of &os; 4.8 that has
	+ <para>DragonFly BSD is a fork of &os; 4.8 that has
	since developed many interesting features of its own,
	including the HAMMER file system and support for
	user-mode <quote>vkernels</quote>.</para>
	</listitem>
	</itemizedlist>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="latest-version">
	<para>What is the latest version of &os;?</para>
	</question>

	<answer>
	<para>At any point in the development of &os;, there can be
	multiple parallel branches. &rel.relx; releases are
	made from the &rel.stable; branch, and &rel2.relx;
	releases are made from the &rel2.stable; branch.</para>

	- <para>Up until the release of 8.0, the
	- &rel3.relx; series was the one known as
	- <emphasis>-STABLE</emphasis>. However, as of 8.0, the
	- &rel3.relx; branch will be designated for
	+ <para>Up until the release of 9.0, the
	+ &rel2.relx; series was the one known as
	+ <emphasis>-STABLE</emphasis>. However, as of
	+ &rel.head.relx;, the
	+ &rel2.relx; branch will be designated for
	an <quote>extended support</quote> status and receive only
	fixes for major problems, such as security-related fixes.
	- There will be no more releases made from the
	- &rel3.stable; branch, and it is considered a
	+ <!--There will be no more releases made from the
	+ &rel2.stable; branch, and it is considered a
	<quote>legacy</quote> branch and most current work will only
	- become a part of &rel.stable; and &rel2.stable;.</para>
	+ become a part of &rel.stable; and &rel2.stable;.--></para>

	<para>Version <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/i386/&rel.current;-RELEASE/">&rel.current;</ulink>
	is the latest release from the &rel.stable;
	branch; it was released in &rel.current.date;. Version
	<ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/">&rel2.current;</ulink>
	is the latest release from the &rel2.stable;
	branch; it was released in &rel2.current.date;.</para>

	<para>Briefly, <emphasis>-STABLE</emphasis> is aimed at the
	ISP, corporate user, or any user who wants stability and a
	minimal number of changes compared to the new (and possibly
	unstable) features of the latest
	<emphasis>-CURRENT</emphasis> snapshot. Releases can come
	from either branch, but <emphasis>-CURRENT</emphasis> should
	only be used if you are prepared for its increased
	volatility (relative to <emphasis>-STABLE</emphasis>, that
	is).</para>

	<para>Releases are made <link
	linkend="release-freq">every few months</link>. While
	many people stay more up-to-date with the &os; sources (see
	the questions on <link
	linkend="current">&os.current;</link> and <link
	linkend="stable">&os.stable;</link>) than that, doing so
	is more of a commitment, as the sources are a moving
	target.</para>

	<para>More information on &os; releases can be found on the
	<ulink
	- url="http://www.FreeBSD.org/releng/index.html">Release Engineering page</ulink>
	- on the &os; Web site.</para>
	+ url="http://www.FreeBSD.org/releng/index.html#release-build">Release Engineering page</ulink>
	+ and in &man.release.7;.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="current">
	<para>What is <emphasis>&os;-CURRENT</emphasis>?</para>
	</question>

	<answer>
	<para><ulink
	url="&url.books.handbook;/current-stable.html#current">&os.current;</ulink>
	is the development version of the operating system, which
	will in due course become the new &os.stable; branch. As
	such, it is really only of interest to developers working on
	the system and die-hard hobbyists. See the <ulink
	url="&url.books.handbook;/current-stable.html#current">relevant section</ulink>
	in the <ulink
	url="&url.books.handbook;/index.html">Handbook</ulink> for
	details on running <emphasis>-CURRENT</emphasis>.</para>

	<para>If you are not familiar with &os;
	you should not use
	&os.current;. This branch sometimes evolves quite quickly
	and due to mistake can be un-buildable at times.
	People that use &os.current; are expected to be able to
	analyze, debug, and report problems.</para>

	<para>&os; <ulink
	url="&url.base;/snapshots/">snapshot</ulink>
	releases are made based on the current state of the
	<emphasis>-CURRENT</emphasis> and
	<emphasis>-STABLE</emphasis> branches. The goals behind
	each snapshot release are:</para>

	<itemizedlist>
	<listitem>
	<para>To test the latest version of the installation
	software.</para>
	</listitem>

	<listitem>
	<para>To give people who would like to run
	<emphasis>-CURRENT</emphasis> or
	<emphasis>-STABLE</emphasis> but who do not have the
	time or bandwidth to follow it on a day-to-day basis an
	easy way of bootstrapping it onto their systems.</para>
	</listitem>

	<listitem>
	<para>To preserve a fixed reference point for the code in
	question, just in case we break something really badly
	later. (Although Subversion normally prevents anything
	horrible like this happening.)</para>
	</listitem>

	<listitem>
	<para>To ensure that all new features and fixes in need of
	testing have the greatest possible number of potential
	testers.</para>
	</listitem>
	</itemizedlist>

	<para>No claims are made that any
	<emphasis>-CURRENT</emphasis> snapshot can be considered
	<quote>production quality</quote> for any purpose. If you
	want to run a stable and fully tested system, you will have
	to stick to full releases, or use the
	<emphasis>-STABLE</emphasis> snapshots.</para>

	<para>Snapshot releases are directly available from <ulink
	url="&url.base;/snapshots/">snapshot</ulink>.</para>

	<para>Official snapshots are generated on a regular
	basis for all actively developed branches.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="stable">
	<para>What is the <emphasis>&os;-STABLE</emphasis>
	concept?</para>
	</question>

	<answer>
	<para>Back when &os; 2.0.5 was released, &os; development
	branched in two. One branch was named <ulink
	url="&url.books.handbook;/current-stable.html#stable">-STABLE</ulink>,
	one <ulink
	url="&url.books.handbook;/current-stable.html#current">-CURRENT</ulink>.
	<emphasis>&os;-STABLE</emphasis> is intended for Internet
	Service Providers and other commercial enterprises for whom
	sudden shifts or experimental features are quite
	undesirable. It receives only well-tested bug fixes and
	other small incremental enhancements.
	<emphasis>&os;-CURRENT</emphasis>, on the other hand, has
	been one unbroken line since 2.0 was released, leading
	towards &rel.current;-RELEASE and beyond. For more detailed
	information on branches see <quote><ulink
	url="&url.articles.releng;/release-proc.html#rel-branch">&os; Release Engineering: Creating the Release Branch</ulink></quote>,
	the status of the branches and the upcoming release schedule
	can be found on the <ulink
	url="http://www.FreeBSD.org/releng">Release Engineering Information</ulink> page.</para>

	<para>&rel.current;-STABLE is the actively developed
	<emphasis>-STABLE</emphasis> branch. The latest release on
	the &rel.current;-STABLE branch is &rel.current;-RELEASE,
	which was released in &rel.current.date;.</para>

	<para>The &rel.head; branch is the actively developed
	<emphasis>-CURRENT</emphasis> branch toward the next
	generation of &os;. See <link
	linkend="current">What is &os;-CURRENT?</link> for more
	information on this branch.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="release-freq">
	<para>When are &os; releases made?</para>
	</question>

	<answer>
	<para>The &a.re; releases a new major version of &os; about
	every 18 months and a new minor version about every 8 months,
	on average. Release dates are announced well in advance, so
	that the people working on the system know when their
	projects need to be finished and tested. A testing period
	precedes each release, to ensure that the addition
	of new features does not compromise the stability of the
	release. Many users regard this caution as one of the best
	things about &os;, even though waiting for all the latest
	goodies to reach <emphasis>-STABLE</emphasis> can be a
	little frustrating.</para>

	<para>More information on the release engineering process
	(including a schedule of upcoming releases) can be found on
	the <ulink
	url="http://www.FreeBSD.org/releng/index.html">release engineering</ulink>
	pages on the &os; Web site.</para>

	<para>For people who need or want a little more excitement,
	- binary snapshots are made daily as discussed above.</para>
	+ binary snapshots are made weekly as discussed above.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="responsible">
	<para>Who is responsible for &os;?</para>
	</question>

	<answer>
	<para>The key decisions concerning the &os; project, such as
	the overall direction of the project and who is allowed to
	add code to the source tree, are made by a <ulink
	url="&url.base;/administration.html#t-core">core team</ulink> of
	9 people. There is a much larger team of more than 350
	<ulink
	url="&url.articles.contributors;/article.html#staff-committers">committers</ulink>
	who are authorized to make changes directly to the &os;
	source tree.</para>

	<para>However, most non-trivial changes are discussed in
	advance in the <link linkend="mailing">mailing lists</link>,
	and there are no restrictions on who may take part in the
	discussion.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="where-get">
	<para>Where can I get &os;?</para>
	</question>

	<answer>
	<para>Every significant release of &os; is available via
	anonymous FTP from the <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/"> &os; FTP site</ulink>:</para>

	<itemizedlist>
	<listitem>
	<para>The latest &rel.stable; release, &rel.current;-RELEASE
	can be found in the <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/i386/&rel.current;-RELEASE/">&rel.current;-RELEASE directory</ulink>.</para>
	</listitem>

	<listitem>
	<para><ulink url="&url.base;/snapshots/"> Snapshot</ulink>
	releases are made monthly for the <link
	linkend="current">-CURRENT</link> and <link
	linkend="stable">-STABLE</link> branch, these being of
	service purely to bleeding-edge testers and
	developers.</para>
	</listitem>

	<listitem>
	<para>The latest &rel2.stable; release, &rel2.current;-RELEASE
	can be found in the <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/">&rel2.current;-RELEASE directory</ulink>.</para>
	</listitem>
	</itemizedlist>

	<para>Information about obtaining &os; on CD, DVD, and other
	media can be found in <ulink
	url="&url.books.handbook;/mirrors.html">the Handbook</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="access-pr">
	<para>How do I access the Problem Report database?</para>
	</question>

	<answer>
	<para>The Problem Report database of all user change requests
	may be queried by using our web-based PR <ulink
	url="http://www.FreeBSD.org/cgi/query-pr.cgi?query">query</ulink>
	interface.</para>

	<para>The &man.send-pr.1; command can be used to submit
	problem reports and change requests via electronic mail.
	Alternatively, the <ulink
	url="http://www.freebsd.org/send-pr.html">web-based problem report submission interface</ulink>
	can be used to submit problem reports through a web
	browser.</para>

	<para>Before submitting a problem report, please read <ulink
	url="&url.articles.problem-reports;/article.html">Writing &os; Problem Reports</ulink>,
	an article on how to write good problem reports.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="support">
	<title>Documentation and Support</title>

	<qandaset>
	<qandaentry>
	<question id="books">
	<para>What good books are there about &os;?</para>
	</question>

	<answer>
	<para>The project produces a wide range of documentation,
	available online from this link: <ulink
	url="http://www.FreeBSD.org/docs.html"></ulink>. In addition, <link
	linkend="bibliography">the Bibliography</link> at the end of this
	FAQ, and <ulink
	url="&url.books.handbook;/bibliography.html">the one in the Handbook</ulink>
	reference other recommended books.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="doc-formats">
	<para>Is the documentation available in other formats, such as
	plain text (ASCII), or &postscript;?</para>
	</question>

	<answer>
	<para>Yes. The documentation is available in a number of
	different formats and compression schemes on the &os; FTP
	site, in the <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">/pub/FreeBSD/doc/</ulink>
	directory.</para>

	<para>The documentation is categorized in a number of
	different ways. These include:</para>

	<itemizedlist>
	<listitem>
	<para>The document's name, such as <literal>faq</literal>,
	or <literal>handbook</literal>.</para>
	</listitem>

	<listitem>
	<para>The document's language and encoding. These are
	based on the locale names you will find under
	<filename class="directory">/usr/share/locale</filename> on your &os;
	system. The current languages and encodings that we
	have for documentation are as follows:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Name</entry>

	<entry>Meaning</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>en_US.ISO8859-1</literal></entry>

	<entry>English (United States)</entry>
	</row>

	<row>
	<entry><literal>bn_BD.ISO10646-1</literal></entry>

	<entry>Bengali or Bangla (Bangladesh)</entry>
	</row>

	<row>
	<entry><literal>da_DK.ISO8859-1</literal></entry>

	<entry>Danish (Denmark)</entry>
	</row>

	<row>
	<entry><literal>de_DE.ISO8859-1</literal></entry>

	<entry>German (Germany)</entry>
	</row>

	<row>
	<entry><literal>el_GR.ISO8859-7</literal></entry>

	<entry>Greek (Greece)</entry>
	</row>

	<row>
	<entry><literal>es_ES.ISO8859-1</literal></entry>

	<entry>Spanish (Spain)</entry>
	</row>

	<row>
	<entry><literal>fr_FR.ISO8859-1</literal></entry>

	<entry>French (France)</entry>
	</row>

	<row>
	<entry><literal>hu_HU.ISO8859-2</literal></entry>

	<entry>Hungarian (Hungary)</entry>
	</row>

	<row>
	<entry><literal>it_IT.ISO8859-15</literal></entry>

	<entry>Italian (Italy)</entry>
	</row>

	<row>
	<entry><literal>ja_JP.eucJP</literal></entry>

	<entry>Japanese (Japan, EUC encoding)</entry>
	</row>

	<row>
	<entry><literal>mn_MN.UTF-8</literal></entry>

	<entry>Mongolian (Mongolia, UTF-8 encoding)</entry>
	</row>

	<row>
	<entry><literal>nl_NL.ISO8859-1</literal></entry>

	<entry>Dutch (Netherlands)</entry>
	</row>

	<row>
	<entry><literal>no_NO.ISO8859-1</literal></entry>

	<entry>Norwegian (Norway)</entry>
	</row>

	<row>
	<entry><literal>pl_PL.ISO8859-2</literal></entry>

	<entry>Polish (Poland)</entry>
	</row>

	<row>
	<entry><literal>pt_BR.ISO8859-1</literal></entry>

	<entry>Portuguese (Brazil)</entry>
	</row>

	<row>
	<entry><literal>ru_RU.KOI8-R</literal></entry>

	<entry>Russian (Russia, KOI8-R encoding)</entry>
	</row>

	<row>
	<entry><literal>sr_YU.ISO8859-2</literal></entry>

	<entry>Serbian (Serbia)</entry>
	</row>

	<row>
	<entry><literal>tr_TR.ISO8859-9</literal></entry>

	<entry>Turkish (Turkey)</entry>
	</row>

	<row>
	<entry><literal>zh_CN.GB2312</literal></entry>

	<entry>Simplified Chinese (China, GB2312
	encoding)</entry>
	</row>

	<row>
	<entry><literal>zh_TW.Big5</literal></entry>

	<entry>Traditional Chinese (Taiwan, Big5 encoding)</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<note>
	<para>Some documents may not be available in all
	languages.</para>
	</note>
	</listitem>

	<listitem>
	<para>The document's format. We produce the documentation
	in a number of different output formats. Each format
	has its own advantages and disadvantages. Some formats
	are better suited for online reading, while others are
	meant to be aesthetically pleasing when printed on
	paper. Having the documentation available in any of
	these formats ensures that our readers will be able to
	read the parts they are interested in, either on their
	monitor, or on paper after printing the documents. The
	currently available formats are:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Format</entry>

	<entry>Meaning</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>html-split</literal></entry>

	<entry>A collection of small, linked, HTML
	files.</entry>
	</row>

	<row>
	<entry><literal>html</literal></entry>

	<entry>One large HTML file containing the entire
	document</entry>
	</row>

	<row>
	<entry><literal>pdf</literal></entry>

	<entry>Adobe's Portable Document Format</entry>
	</row>

	<row>
	<entry><literal>ps</literal></entry>

	<entry>&postscript;</entry>
	</row>

	<row>
	<entry><literal>rtf</literal></entry>

	<entry>Microsoft's Rich Text Format</entry>
	</row>

	<row>
	<entry><literal>txt</literal></entry>

	<entry>Plain text</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<note>
	<para>Page numbers are not automatically updated when
	loading Rich Text Format into Word. Press <keycombo
	action="simul"><keycap>Ctrl</keycap><keycap>A</keycap></keycombo>,
	<keycombo
	action="simul"><keycap>Ctrl</keycap><keycap>End</keycap></keycombo>,
	<keycap>F9</keycap> after loading the document, to
	update the page numbers.</para>
	</note>
	</listitem>

	<listitem>
	<para>The compression and packaging scheme.</para>

	<orderedlist>
	<listitem>
	<para>Where the format is
	<literal>html-split</literal>, the files are bundled
	up using &man.tar.1;. The resulting
	<filename>.tar</filename> file is then compressed
	using the compression schemes detailed in the next
	point.</para>
	</listitem>

	<listitem>
	<para>All the other formats generate one file, called
	<filename><replaceable>type</replaceable>.<replaceable>format</replaceable></filename>
	(i.e., <filename>article.pdf</filename>,
	<filename>book.html</filename>, and so on).</para>

	<para>These files are then compressed using either
	the <literal>zip</literal> or
	<literal>bz2</literal> compression schemes.
	&man.tar.1; can be used to uncompress these
	files.</para>

	<para>So the &postscript; version of the Handbook,
	compressed using <literal>bzip2</literal> will be stored in a file
	called <filename>book.ps.bz2</filename> in the
	<filename class="directory">handbook/</filename> directory.</para>
	</listitem>
	</orderedlist>
	</listitem>
	</itemizedlist>

	<para>After choosing the format and compression mechanism that
	you want to download, you will have to download the compressed
	files yourself, uncompress them, and then copy the
	appropriate documents into place.</para>

	<para>For example, the split HTML version of the FAQ,
	compressed using &man.bzip2.1;, can be found in
	<filename>doc/en_US.ISO8859-1/books/faq/book.html-split.tar.bz2</filename>
	To download and uncompress that file you would have
	to do this:</para>

	<screen>&prompt.root; <userinput>fetch ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/faq/book.html-split.tar.bz2</userinput>
	&prompt.root; <userinput>tar xvf book.html-split.tar.bz2</userinput></screen>

	<para>If the file is compressed,
	<application>tar</application> will automatically
	detect the appropriate format and decompress it correctly.
	You will be left with a collection of
	<filename>.html</filename> files. The main one is called
	<filename>index.html</filename>, which will contain the
	table of contents, introductory material, and links to the
	other parts of the document. You can then copy or move
	these to their final location as necessary.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="mailing">
	<para>Where do I find info on the &os; mailing lists?
	What &os; news groups are available?</para>
	</question>

	<answer>
	<para>You can find full information in the <ulink
	url="&url.books.handbook;/eresources.html#eresources-mail">Handbook entry on mailing-lists</ulink>
	and the <ulink
	url="&url.books.handbook;/eresources-news.html">Handbook entry on newsgroups</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="irc">
	<para>Are there &os; IRC (Internet Relay Chat)
	channels?</para>
	</question>

	<answer>
	<para>Yes, most major IRC networks host a &os; chat
	channel:</para>

	<itemizedlist>
	<listitem>
	- <para>Channel <literal>#FreeBSD</literal> on <ulink
	- url="http://www.efnet.org/index.php">EFNet</ulink> is
	- a &os; forum, but do not go there for tech support or
	- try to get folks there to help you avoid the pain of
	- reading manual pages or doing your own research. It is
	- a chat channel, first and foremost, and topics there are
	- just as likely to involve sex, sports or nuclear weapons
	- as they are &os;. You Have Been Warned! Available at
	- server <hostid>irc.efnet.org</hostid>.</para>
	- </listitem>
	-
	- <listitem>
	<para>Channel <literal>#FreeBSDhelp</literal> on <ulink
	url="http://www.efnet.org/index.php">EFNet</ulink> is
	a channel dedicated to helping &os; users. They are
	much more sympathetic to questions than
	<literal>#FreeBSD</literal> is.</para>
	</listitem>

	<listitem>
	<para>Channel <literal>##FreeBSD</literal> on <ulink
	url="http://freenode.net/">Freenode</ulink> is a
	general help channel with many users at any time.
	The conversations have been known to run off-topic for a
	while, but priority is given to users with &os;
	questions. We are good about helping you understand the
	basics, referring to the Handbook whenever possible, and
	directing you where to learn more about the topic you
	need help with. We are a primarily English speaking
	channel, though we have users from all over the world.
	If you would like to speak in your native language, try
	to ask the question in English and then relocate to
	another channel
	<literal>##freebsd-<replaceable>lang</replaceable></literal>
	as appropriate.</para>
	</listitem>

	<listitem>
	<para>Channel <literal>#FreeBSD</literal> on <ulink
	url="http://www.dal.net/">DALNET</ulink> is available at
	<hostid>irc.dal.net</hostid> in the US and
	<hostid>irc.eu.dal.net</hostid> in Europe.</para>
	</listitem>

	<listitem>
	<para>Channel <literal>#FreeBSD</literal> on <ulink
	url="http://www.undernet.org/">UNDERNET</ulink> is
	available at <hostid>us.undernet.org</hostid> in the US
	and <hostid>eu.undernet.org</hostid> in Europe. Since
	it is a help channel, be prepared to read the documents
	you are referred to.</para>
	</listitem>

	<listitem>
	<para>Channel <literal>#FreeBSD</literal> on
	<ulink url="http://www.rusnet.org.ru/">RUSNET</ulink>
	is a russian-language oriented channel dedicated
	to helping &os; users. This is also good place
	for non-technical discussions.</para>
	</listitem>

	<listitem>
	<para>Channel <literal>#bsdchat</literal> on <ulink
	url="http://freenode.net/">Freenode</ulink> is a
	Traditional-Chinese (UTF-8 encoding) language oriented
	channel dedicated to helping &os; users. This is also
	good place for non-technical discussions.</para>
	</listitem>
	</itemizedlist>

	<para>The &os; wiki has a <ulink
	url="http://wiki.freebsd.org/IrcChannels">good list</ulink>
	of IRC channels.</para>

	<para>Each of these channels are distinct and are not
	connected to each other. Their chat styles also differ, so
	you may need to try each to find one suited to your chat
	style. As with <emphasis>all</emphasis> types of IRC
	traffic, if you are easily offended or cannot deal with lots
	of young people (and more than a few older ones) doing the
	verbal equivalent of jello wrestling, do not even bother
	with it.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="forums">
	<para>Are there any web based forums to discuss &os;?</para>
	</question>
	<answer>
	<para>The official &os; forums are located at <ulink
	url="http://forums.FreeBSD.org/">http://forums.FreeBSD.org/</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="training">
	<para>Where can I get commercial &os; training and
	support?</para>
	</question>

	<answer>
	<para><ulink
	url="http://www.ixsystems.com">iXsystems, Inc.</ulink>,
	parent company of the <ulink
	url="http://www.freebsdmall.com/">&os; Mall</ulink>,
	provides commercial &os; and PC-BSD software <ulink
	url="http://www.ixsystems.com/bsdsupport">support</ulink>,
	in addition to &os; development and tuning solutions.</para>

	<para>BSD Certification Group, Inc. provides system
	administration certifications for DragonFly BSD, &os;, NetBSD,
	OpenBSD. If you are interested in them, visit <ulink
	url="http://www.BSDCertification.org">their site</ulink>.</para>

	<para>Any other organizations providing training and support
	should contact the Project to be listed here.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="install">
	<chapterinfo>
	<author>
	<firstname>Nik</firstname>
	<surname>Clayton</surname>
	<affiliation>
	<address><email>nik@FreeBSD.org</email></address>
	</affiliation>
	</author>
	</chapterinfo>

	<title>Installation</title>

	<qandaset>

	<qandaentry>
	<question id="which-architecture">
	<para>Which platform should I download? I have a 64
	bit capable &intel; CPU,
	but I only see <literal>amd64</literal>.</para>
	</question>

	<answer>
	<para>&arch.amd64; is the term &os; uses for 64-bit
	- compatible x86 architectures. Most modern computers
	+ compatible x86 architectures (also known as "x86-64"
	+ or "x64"). Most modern computers
	should use &arch.amd64;. Older hardware should use
	&arch.i386;. If you are installing on a
	non-x86-compatible architecture select the platform
	which best matches the architecture you are
	using.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="floppy-download">
	<para>Which file do I download to get &os;?</para>
	</question>

	<answer>
	<para>On the
	<ulink url="http://www.freebsd.org/where.html">Getting &os;</ulink>
	page select <literal>[iso]</literal> next to the
	architecture you want to use.</para>

	<para>Any of the following can be used:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>file</entry>
	<entry>description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><filename>disc1.iso</filename></entry>
	<entry>Contains enough to install &os; and
	a minimal set of packages.</entry>
	</row>

	<row>
	<entry><filename>dvd1.iso</filename></entry>
	<entry>Similar to <filename>disc1.iso</filename>
	but with additional packages.</entry>
	</row>

	<row>
	<entry><filename>memstick.img</filename></entry>
	- <entry>A bootable image sufficient for copying to a
	+ <entry>A bootable image sufficient for writing to a
	USB stick.</entry>
	</row>

	<row>
	<entry><filename>bootonly.iso</filename></entry>
	<entry>A minimal image that requires network
	access during installation to completely
	install &os;.</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>&arch.pc98; users require these floppy images:
	<filename>floppies/boot.flp</filename>,
	<filename>floppies/kern1.flp</filename>,
	<filename>floppies/kern2.flp</filename>, and
	<filename>floppies/mfsroot1.flp</filename>. These images
	need
	- to be copied onto floppies by tools like
	+ to be written onto floppies by tools like
	&man.dd.1;.</para>

	<para>Full instructions on this procedure and a little bit
	more about installation issues in general can be found in
	the <ulink
	url="&url.books.handbook;/install.html">Handbook entry on installing &os;</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="floppy-image-too-large">
	<para>What do I do if the images do not fit on a
	single disk?</para>
	</question>

	<answer>
	<para>Common mistakes when preparing the boot media
	are:</para>

	<itemizedlist>
	<listitem>
	<para>Not downloading the image in
	<emphasis>binary</emphasis> mode when using
	<acronym>FTP</acronym>.</para>

	<para>Some FTP clients default their transfer mode to
	<emphasis>ascii</emphasis> and attempt to change any
	end-of-line characters received to match the conventions
	used by the client's system. This will almost
	invariably corrupt the boot image. Check the SHA-256
	of
	the downloaded boot image: if it is not
	<emphasis>exactly</emphasis> that on the server, then
	the download process is suspect.</para>

	<para>To workaround: type <emphasis>binary</emphasis> at
	the FTP command prompt after getting connected to the
	server and before starting the download of the
	image.</para>
	</listitem>

	<listitem>
	<para>Using the DOS <command>copy</command> command (or
	equivalent GUI tool) to transfer the boot image to
	floppy.</para>

	<para>Programs like <command>copy</command> will not work
	as the boot image has been created to be booted into
	directly. The image has the complete content of the
	floppy, track for track, and is not meant to be placed
	on the floppy as a regular file. You have to transfer
	it to the floppy <quote>raw</quote>, using the low-level
	tools (e.g., <command>fdimage</command> or
	<command>rawrite</command>) described in the <ulink
	url="&url.books.handbook;/install.html">installation guide to &os;</ulink>.</para>
	</listitem>
	</itemizedlist>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="install-instructions-location">
	<para>Where are the instructions for installing &os;?</para>
	</question>

	<answer>
	<para>Installation instructions for versions since
	&os; 9.0 can be found at <ulink
	url="&url.books.handbook;/bsdinstall.html">Handbook entry on installing &os;</ulink>.
	Older instructions can be found in the <ulink
	url="&url.books.handbook;/install.html">legacy entry on installing &os;</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="need-to-run">
	<para>What do I need to run &os;?</para>
	</question>

	<answer>
	<para>For &os; you will need a 486 or better PC, with
	64 MB or more of RAM and at least 1 GB of hard
	disk space.</para>

	<para>See also <xref linkend="hardware"/>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="custom-boot-floppy">
	<para>How can I make my own custom release or install disk?</para>
	</question>

	<answer>
	<para>Customized &os; installation media can be created by
	building a custom release. Follow the instructions in the
	<ulink
	url="&url.articles.releng;/article.html">Release Engineering</ulink>
	article.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="windows-coexist">
	<para>Can &windows; co-exist with &os;?</para>
	</question>

	<answer>
	<para>If &windows; is installed first, then yes.
	&os;'s boot manager
	will then manage to boot &windows; and &os;. If you install
	&windows; second, it will boorishly overwrite your boot
	manager without even asking. If that happens, see the next
	section.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="bootmanager-restore">
	<para>Another operating system destroyed my Boot Manager. How
	do I get it back?</para>
	</question>

	<answer>
	<para>This depends on what boot manager you have installed.
	The &os; boot selection menu (likely what you are using
	if you end up in this situation) can be reinstalled using
	&man.boot0cfg.8;. For example, to restore the boot menu
	onto the disk <replaceable>ada0</replaceable>:</para>

	<screen>&prompt.root; <userinput>boot0cfg -B ada0</userinput></screen>

	<para>The non-interactive MBR bootloader can be installed using
	&man.gpart.8;:</para>

	<screen>&prompt.root; <userinput>gpart bootcode -b /boot/mbr ada0</userinput></screen>

	<para>For more complex situations, including GPT disks, see &man.gpart.8;.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="no-install-cdrom">
	<para>I booted from my ATAPI CD-ROM, but the install program
	says no CD-ROM is found. Where did it go?</para>
	</question>

	<answer>
	<para>The usual cause of this problem is a mis-configured
	CD-ROM drive. Many PCs now ship with the CD-ROM as the slave
	device on the secondary IDE controller, with no master
	device on that controller. This is illegal according to the
	ATAPI specification, but &windows; plays fast and loose with
	the specification, and the BIOS ignores it when booting.
	This is why the BIOS was able to see the CD-ROM to boot from
	it, but why &os; cannot see it to complete the
	install.</para>

	<para>Reconfigure your system so that the CD-ROM is either the
	master device on the IDE controller it is attached to, or
	make sure that it is the slave on an IDE controller that
	also has a master device.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="need-complete-sources">
	<para>Do I need to install the source?</para>
	</question>

	<answer>
	<para>In general, no. There is nothing in the base
	system which requires the presence of the source to
	operate. Some ports, like <filename
	role="package">sysutils/lsof</filename>, will not build
	unless the source is installed. In particular, if the
	port builds a kernel module or directly operates on kernel
	structures, the source must be installed.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="need-kernel">
	<para>Do I need to build a kernel?</para>
	</question>

	<answer>
	<para>Usually not. The supplied <literal>GENERIC</literal>
	kernel contains the drivers an ordinary computer will
	need. &man.freebsd-update.8;, the &os; binary upgrade
	tool, cannot upgrade custom kernels, another reason
	to stick with the <literal>GENERIC</literal> kernel when
	possible. For computers with very limited RAM, such as
	embedded systems, it may be worthwhile to build a
	smaller custom kernel containing just the required
	drivers.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="password-encryption">
	<para>Should I use DES, Blowfish, or MD5 passwords and how do
	I specify which form my users receive?</para>
	</question>

	<answer>
	<para>&os; 7 and 8 use MD5 password hashing by
	default. Recent versions
	of &os; use <emphasis>SHA512</emphasis> by default.
	These are
	believed to be more secure than the traditional &unix;
	password format, which used a scheme based on the
	<emphasis>DES</emphasis> algorithm. DES passwords are still
	available if you need to share your password file with
	legacy operating systems which still use the less secure
	password format. &os; also allows you to use the Blowfish
	and MD5 password formats. Which password
	format to use for new passwords is controlled by the
	<literal>passwd_format</literal> login capability in
	<filename>/etc/login.conf</filename>, which takes values of
	<literal>des</literal>, <literal>blf</literal> (if these are
	available) or <literal>md5</literal>. See the
	&man.login.conf.5; manual page for more information about
	login capabilities.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="memory-limits">
	<para>What are the limits for memory?</para>
	</question>

	<answer>
	<para>Memory limits depend on the platform used. On a
	standard &i386; install, the limit is 4 GB but more
	memory can be supported through &man.pae.4;. See <link
	linkend="memory-i386-over-4gb">instructions for using 4 GB or more memory on &i386;</link>.</para>

	<para>&os;/pc98 has a limit of 4 GB memory, and PAE can
	not be used with it. Other architectures supported by &os;
	have much higher theoretical limits on maximum memory (many
	terabytes).</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ffs-limits">
	<para>What are the limits for FFS file systems?</para>
	</question>

	<answer>
	<para>For FFS file systems, the maximum theoretical limit is
	8 TB (2 G blocks), or 16 TB for the default
	block size of 8 KB. In practice, there is a soft limit
	of 1 TB, but with modifications file systems with
	4 TB are possible (and exist).</para>

	<para>The maximum size of a single FFS file is approximately
	1 G blocks, or 4 TB with a block size of
	4 KB.</para>

	<table>
	<title>Maximum File Sizes</title>

	<tgroup cols="3">
	<thead>
	<row>
	<entry>FS Block Size</entry>

	<entry>Works</entry>

	<entry>Should Work</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>4 KB</entry>

	<entry>> 4 GB</entry>

	<entry>4 TB - 1</entry>
	</row>

	<row>
	<entry>8 KB</entry>

	<entry>> 32 GB</entry>

	<entry>32 TB - 1</entry>
	</row>

	<row>
	<entry>16 KB</entry>

	<entry>> 128 GB</entry>

	<entry>32 TB - 1</entry>
	</row>

	<row>
	<entry>32 KB</entry>

	<entry>> 512 GB</entry>

	<entry>64 TB - 1</entry>
	</row>

	<row>
	<entry>64 KB</entry>

	<entry>> 2048 GB</entry>

	<entry>128 TB - 1</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>When the FS block size is 4 KB, triple indirect
	blocks work and everything should be limited by the maximum FS
	block number that can be represented using triple indirect
	blocks (approx.
	1024<superscript>3</superscript> + 1024<superscript>2</superscript> + 1024),
	but everything is limited by a (wrong) limit of
	1 G - 1 on FS block numbers. The limit on FS
	block numbers should be 2 G - 1. There are
	some bugs for FS block numbers near 2 G - 1,
	but such block numbers are unreachable when the FS block
	size is 4 KB.</para>

	<para>For block sizes of 8 KB and larger, everything
	should be limited by the 2 G - 1 limit on FS
	block numbers, but is actually limited by the
	1 G - 1 limit on FS block numbers. Using the
	correct limit of 2 G - 1 blocks does cause
	problems.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="archsw-readin-failed-error">
	<para>Why do I get an error message,
	- <errorname>archsw.readin.failed</errorname> after compiling
	+ <errorname>readin failed</errorname> after compiling
	and booting a new kernel?</para>
	</question>

	<answer>
	<para>Because your world and kernel are out of sync. This is
	not supported. Be sure you use <command>make <maketarget>buildworld</maketarget></command>
	and <command>make <maketarget>buildkernel</maketarget></command>
	to update your kernel.</para>

	<para>You can boot by specifying the kernel directly at the
	second stage, pressing any key when the <literal>\|</literal>
	shows up before loader is started.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="general-configuration-tool">
	<para>Is there a tool to perform post-installation
	configuration tasks?</para>
	</question>

	<answer>
	<para>Yes, &rel.head.releng; users can set
	<varname>WITH_BSDCONFIG</varname> in
	<filename>/etc/src.conf</filename>. Users of &rel.relx;
	and higher may also install
	<filename role="package">sysutils/bsdconfig</filename>.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="hardware">
	<title>Hardware Compatibility</title>

	<sect1 id="compatibility-general">
	<title>General</title>

	<qandaset>
	<qandaentry>
	<question id="which-hardware-to-get">
	<para>I want to get a piece of hardware for my &os; system.
	Which model/brand/type is best?</para>
	</question>

	<answer>
	<para>This is discussed continually on the &os; mailing
	lists. Since hardware changes so quickly, however, we
	expect this. We <emphasis>still</emphasis> strongly
	recommend that you read through the Hardware Notes
	for &os; <ulink
	url="&rel.current.hardware;">&rel.current;</ulink> or
	<ulink
	url="&rel2.current.hardware;">&rel2.current;</ulink> and
	search the mailing list <ulink
	url="http://www.FreeBSD.org/search/#mailinglists">archives</ulink>
	before asking about the latest and greatest hardware.
	Chances are a discussion about the type of hardware you
	are looking for took place just last week.</para>

	<para>If you are looking for a laptop, check the &a.mobile;
	archives. Otherwise, you probably want the archives for
	the &a.questions;, or possibly a specific mailing list for
	a particular hardware type.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="memory-upper-limitation">
	<para>Does &os; support more than 4 GB of memory (RAM)?
	More than 16 GB? More than 48 GB?</para>
	</question>

	<answer>
	<para>Yes. &os; as an operating system generally supports
	as much physical memory (RAM) as the platform it is running
	on does. Keep in mind that different platforms have
	different limits for memory; for example &i386; without
	<acronym>PAE</acronym> supports at most 4 GB of
	memory (and usually less than that because of PCI address
	space) and &i386; with PAE supports at most 64 GB
	memory. AMD64 platforms currently deployed support up to
	1 TB of physical memory.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="memory-i386-over-4gb">
	<para>Why does &os; report less than 4 GB memory when
	installed on an &i386; machine?</para>
	</question>

	<answer>
	<para>The total address space on &i386; machines is 32-bit,
	meaning that at most 4 GB of memory is addressable (can
	be accessed). Furthermore, some addresses in this range
	are reserved by hardware for different purposes, for
	example for using and controlling PCI devices, for
	accessing video memory, and so on. Therefore, the total
	amount of memory usable by the operating system for its
	kernel and applications is limited to significantly less
	than 4 GB. Usually, 3.2 GB to 3.7 GB is
	the maximum usable physical memory in this
	configuration.</para>

	<para>To access more than 3.2 GB to 3.7 GB of
	installed memory (meaning up to 4 GB but also more than
	4 GB), a special tweak called <acronym>PAE</acronym>
	must be used. PAE stands for Physical Address Extension
	and is a way for 32-bit x86 CPUs to address more than
	4 GB of memory. It remaps the memory that would
	otherwise be overlaid by address reservations for
	hardware devices above the 4 GB range and uses it as
	additional physical memory (see &man.pae.4;). Using PAE
	has some drawbacks; this mode of memory access is a little
	bit slower than the normal (without PAE) mode and loadable
	modules (see &man.kld.4;) are not supported. This means
	all drivers must be compiled into the kernel.</para>

	<para>The most common way to enable PAE is to build a new
	kernel with the special ready-provided kernel configuration
	file called <filename>PAE</filename>, which is already
	configured to build a safe kernel. Note that some entries
	in this kernel configuration file are too conservative and
	some drivers marked as unready to be used with PAE are
	actually usable. A rule of thumb is that if the driver is
	usable on 64-bit architectures (like AMD64), it is also
	usable with PAE. If you wish to create your own kernel
	configuration file, you can enable PAE by adding the
	following line to your configuration:</para>

	<programlisting>options PAE</programlisting>

	<para>PAE is not much used nowadays because most new x86
	hardware also supports running in 64-bit mode, known as
	AMD64 or &intel; 64. It has a much larger address
	space and does not need such tweaks. &os; supports AMD64
	and it is recommended that this version of &os; be used
	instead of the &i386; version if 4 GB or more memory
	is required.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</sect1>

	<sect1 id="compatibility-processors">
	<title>Architectures and Processors</title>

	<qandaset>
	<qandaentry>
	<question id="architectures">
	<para>Does &os; support architectures other than the
	x86?</para>
	</question>

	<answer>
	<para>Yes. &os; divides support into multiple tiers.
	Tier 1 architectures, such as i386 or amd64; are
	- fully supported. Tiers 2 and 3 are supported on a
	+ fully supported. Tiers 2 and 3 are supported on an
	if-possible basis. A full explanation of the tier
	system is available in the
	<ulink
	url="&url.articles.committers-guide;/archs.html">Committer's Guide.</ulink></para>

	<para>A complete list of supported architectures can be
	found on the
	<ulink
	url="http://www.FreeBSD.org/platforms/">platforms page.</ulink></para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="smp-support">
	<para>Does &os; support Symmetric Multiprocessing
	(SMP)?</para>
	</question>

	<answer>
	<para>Symmetric multi-processor (SMP) systems are generally
	supported by &os;, although in some cases, BIOS or
	motherboard bugs may generate some problems.</para>

	<para>&os; will take advantage of HyperThreading (HTT)
	support on &intel; CPUs that support this feature. A kernel
	- with the <literal>options SMP</literal> feature enabled
	+ with the <literal>options SMP</literal> option, enabled
	+ by default,
	will automatically detect the additional logical
	processors.</para>

	<para>&man.smp.4; has more details.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="microcode">
	<para>What is microcode?
	How do I install &intel; CPU microcode updates?</para>
	</question>

	<answer>
	<para>Microcode is a method of programmatically
	implementating hardware level instructions. This allows
	for CPU bugs to be fixed without replacing the on board chip.</para>

	<para>Install <filename role="package">sysutils/devcpu-data</filename>,
	then add:</para>
	<programlisting>microcode_update_enable="YES"</programlisting>

	<para>to <filename>/etc/rc.conf</filename></para>
	</answer>
	</qandaentry>
	</qandaset>
	</sect1>

	<sect1 id="compatibility-drives">
	<title>Hard Drives, Tape Drives, and CD and DVD Drives</title>

	<qandaset>
	<qandaentry>
	<question id="supported-hard-drives">
	<para>What kind of hard drives does &os; support?</para>
	</question>

	<answer>
	<para>&os; supports EIDE, SATA, SCSI, and SAS drives (with a
	compatible controller; see the next section), and all
	drives using the original <quote>Western Digital</quote>
	interface (MFM, RLL, ESDI, and of course IDE). A few ESDI
	controllers that use proprietary interfaces may not work:
	stick to WD1002/3/6/7 interfaces and clones.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="supported-scsi-controllers">
	<para>Which SCSI or SAS controllers are supported?</para>
	</question>

	<answer>
	<para>See the complete list in the Hardware Notes for &os;
	<ulink url="&rel.current.hardware;">&rel.current;</ulink>
	or <ulink
	url="&rel2.current.hardware;">&rel2.current;</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="tape-support">
	<para>What types of tape drives are supported?</para>
	</question>

	<answer>
	<para>&os; supports SCSI and QIC-36 (with a QIC-02
	interface). This includes 8-mm (aka Exabyte) and DAT
	drives.</para>

	<para>Some of the early 8-mm drives are not quite compatible
	with SCSI-2, and may not work well with &os;.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="tape-changer-support">
	<para>Does &os; support tape changers?</para>
	</question>

	<answer>
	<para>&os; supports SCSI changers using the &man.ch.4; device
	and the &man.chio.1; command. The details of how you
	actually control the changer can be found in the
	&man.chio.1; manual page.</para>

	<para>If you are not using <application>AMANDA</application>
	or some other product that already understands changers,
	remember that they only know how to move a tape from one
	point to another, so you need to keep track of which slot a
	tape is in, and which slot the tape currently in the drive
	needs to go back to.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="supported-cdrom-drives">
	<para>Which CD-ROM drives are supported by &os;?</para>
	</question>

	<answer>
	<para>Any SCSI drive connected to a supported controller is
	supported. Most ATAPI compatible IDE CD-ROMs are
	supported.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="supported-cdrw-drives">
	<para>Which CD-RW drives are supported by &os;?</para>
	</question>

	<answer>
	<para>&os; supports any ATAPI-compatible IDE CD-R or CD-RW
	drive. See &man.burncd.8; for details.</para>

	<para>&os; also supports any SCSI CD-R or CD-RW drives.
	Install and use <command>cdrecord</command>
	from the ports or packages system, and make sure that you
	have the <devicename>pass</devicename> device compiled in
	your kernel.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</sect1>

	<sect1 id="compatibility-kbd-mice">
	<title>Keyboards and Mice</title>

	<qandaset>
	<qandaentry>
	<question id="moused">
	<para>Is it possible to use a mouse in any way outside the X
	Window system?</para>
	</question>

	<answer>
	<para>If you are using the default console driver,
	&man.syscons.4;, you can use a mouse pointer in text
	consoles to cut & paste text. Run the mouse daemon,
	&man.moused.8;, and turn on the mouse pointer in the
	virtual console:</para>

	<screen>&prompt.root; <userinput>moused -p /dev/<replaceable>xxxx</replaceable> -t <replaceable>yyyy</replaceable></userinput>
	&prompt.root; <userinput>vidcontrol -m on</userinput></screen>

	<para>Where <replaceable>xxxx</replaceable> is the mouse
	device name and <replaceable>yyyy</replaceable> is a
	protocol type for the mouse. The mouse daemon can
	automatically determine the protocol type of most mice,
	except old serial mice. Specify the
	<literal>auto</literal> protocol to invoke automatic
	detection. If automatic detection does not work, see the
	&man.moused.8; manual page for a list of supported
	protocol types.</para>

	<para>If you have a PS/2 mouse, just add
	<literal>moused_enable="YES"</literal> to
	<filename>/etc/rc.conf</filename> to start the mouse
	daemon at boot-time. Additionally, if you would like to
	use the mouse daemon on all virtual terminals instead of
	just the console, add
	<literal>allscreens_flags="-m on"</literal> to
	<filename>/etc/rc.conf</filename>.</para>

	<para>When the mouse daemon is running, access to the mouse
	must be coordinated between the mouse daemon and other
	programs such as X Windows. Refer to the FAQ <link
	linkend="x-and-moused">Why does my mouse not work with X?</link>
	for more details on this issue.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="text-mode-cut-paste">
	<para>How do I cut and paste text with a mouse in the text
	console?</para>
	</question>

	<answer>
	<para>It is not possible to remove data using the mouse.
	However, it is possible to <quote>copy and
	paste</quote>.
	Once you get the mouse daemon running (see the
	<link linkend="moused">previous question</link>)
	hold down
	button 1 (left button) and move the mouse to select a region
	of text. Then, press button 2 (middle button) to paste
	it at the text cursor. Pressing button 3 (right button)
	will <quote>extend</quote> the selected region of
	text.</para>

	<para>If your mouse does not have a middle button, you may
	wish to emulate one or remap buttons using mouse daemon
	options. See the &man.moused.8; manual page for
	details.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="mouse-wheel-buttons">
	<para>My mouse has a fancy wheel and buttons. Can I use
	them in &os;?</para>
	</question>

	<answer>
	<para>The answer is, unfortunately, <quote>It
	- depends</quote>. These mice with additional features
	+ depends</quote>. These mice with additional features
	require specialized driver in most cases. Unless the
	mouse device driver or the user program has specific
	support for the mouse, it will act just like a standard
	two, or three button mouse.</para>

	<para>For the possible usage of wheels in the X Window
	environment, refer to <link
	linkend="x-and-wheel">that section</link>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="keyboard-delete-key">
	<para>How do I use my delete key in <command>sh</command>
	and <command>csh</command>?</para>
	</question>

	<answer>
	<para>For the <application>Bourne Shell</application>, add
	the following lines to your <filename>.shrc</filename>. See
	&man.sh.1; and &man.editrc.5;.</para>

	<programlisting>bind ^? ed-delete-next-char # for console
	bind ^[[3~ ed-delete-next-char # for xterm</programlisting>

	<para>For the <application>C Shell</application>, add the
	following lines to your <filename>.cshrc</filename>. See
	&man.csh.1;.</para>

	<programlisting>bindkey ^? delete-char # for console
	bindkey ^[[3~ delete-char # for xterm</programlisting>

	<para>For more information, see <ulink
	url="http://www.ibb.net/~anne/keyboard.html">this page</ulink>.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</sect1>

	- <sect1 id="compatibility-networking">
	- <title>Networking</title>
	+ <sect1 id="compatibility-other">
	+ <title>Other Hardware</title>

	<qandaset>
	<qandaentry>
	- <question id="support-broadcom">
	- <para>Is there a native driver for the Broadcom 43xx
	- cards?</para>
	- </question>
	-
	- <answer>
	- <para>Yes, many Broadcom 43xx cards are supported by the
	- &man.bwn.4; and &man.bwi.4; drivers.</para>
	- </answer>
	- </qandaentry>
	- </qandaset>
	- </sect1>
	-
	- <sect1 id="compatibility-sound">
	- <title>Sound Devices</title>
	-
	- <qandaset>
	- <qandaentry>
	<question id="es1370-silent-pcm">
	<para>Workarounds for no sound from my &man.pcm.4; sound
	card?</para>
	</question>

	<answer>
	<para>Some sound cards set their output volume to 0 at every
	boot. Run the following command every time the machine
	boots:</para>

	<screen>&prompt.root; <userinput>mixer pcm 100 vol 100 cd 100</userinput></screen>
	</answer>
	</qandaentry>
	- </qandaset>
	- </sect1>

	- <sect1 id="compatibility-other">
	- <title>Other Hardware</title>
	-
	- <qandaset>
	<qandaentry>
	<question id="power-management-support">
	<para>Does &os; support power management on my
	laptop?</para>
	</question>

	<answer>
	<para>&os; supports the <acronym>ACPI</acronym>
	features found in modern hardware. Further
	information can be found in &man.acpi.4;.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</sect1>
	</chapter>

	<chapter id="troubleshoot">
	<title>Troubleshooting</title>

	<qandaset>
	<qandaentry>
	<question id="pae">
	<para>Why is &os; finding the wrong amount of memory on &i386;
	hardware?</para>
	</question>

	<answer>
	<para>The most likely reason is the difference between
	physical memory addresses and virtual addresses.</para>

	<para>The convention for most PC hardware is to use the memory
	area between 3.5 GB and 4 GB for a special purpose
	(usually for PCI). This address space is used to access PCI
	hardware. As a result real, physical memory can not be
	accessed by that address space.</para>

	<para>What happens to the memory that should appear in that
	location is dependent on your hardware. Unfortunately, some
	hardware does nothing and the ability to use that last
	500 MB of RAM is entirely lost.</para>

	<para>Luckily, most hardware remaps the memory to a higher
	location so that it can still be used. However, this can
	cause some confusion if you watch the boot messages.</para>

	<para>On a 32-bit version of &os;, the memory appears
	lost, since it will be remapped above 4 GB, which a
	32-bit kernel is unable to access. In this case, the
	solution is to build a PAE enabled kernel. See <link
	linkend="memory-limits">the entry on memory limits</link>
	and <link linkend="memory-upper-limitation">about different
	memory limits on different platforms</link> for more
	information.</para>

	<para>On a 64-bit version of &os;, or when running a
	PAE-enabled kernel, &os; will correctly detect and remap the
	memory so it is usable. During boot, however, it may seem
	as if &os; is detecting more memory than the system really
	has, due to the described remapping. This is normal and the
	available memory will be corrected as the boot process
	completes.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="signal11">
	<para>Why do my programs occasionally die with
	<errorname>Signal 11</errorname> errors?</para>
	</question>

	<answer>
	<para>Signal 11 errors are caused when your process has
	attempted to access memory which the operating system has not
	granted it access to. If something like this is happening
	at seemingly random intervals then you need to start
	investigating things very carefully.</para>

	<para>These problems can usually be attributed to
	either:</para>

	<orderedlist>
	<listitem>
	<para>If the problem is occurring only in a specific
	application that you are developing yourself it is
	probably a bug in your code.</para>
	</listitem>

	<listitem>
	<para>If it is a problem with part of the base &os;
	system, it may also be buggy code, but more often than not
	these problems are found and fixed long before us
	general FAQ readers get to use these bits of code (that
	is what -current is for).</para>
	</listitem>
	</orderedlist>

	<para>In particular, a dead giveaway that this is
	<emphasis>not</emphasis> a &os; bug is if you see the
	problem when you are compiling a program, but the activity
	that the compiler is carrying out changes each time.</para>

	<para>For example, suppose you are running
	<command>make <maketarget>buildworld</maketarget></command>,
	and the compile fails while trying to compile
	<filename>ls.c</filename> into <filename>ls.o</filename>.
	If you then run
	<command>make <maketarget>buildworld</maketarget></command>
	again, and the compile fails in the same place then this is
	a broken build — try updating your sources and try
	again. If the compile fails elsewhere then this is almost
	certainly hardware.</para>

	<para>What you should do:</para>

	<para>In the first case you can use a debugger e.g.,
	&man.gdb.1; to find the point in the program which is
	attempting to access a bogus address and then fix it.</para>

	<para>In the second case you need to verify that it is not
	your hardware at fault.</para>

	<para>Common causes of this include:</para>

	<orderedlist>
	<listitem>
	<para>Your hard disks might be overheating: Check the fans
	in your case are still working, as your disk (and perhaps
	other hardware might be overheating).</para>
	</listitem>

	<listitem>
	<para>The processor running is overheating: This might be
	because the processor has been overclocked, or the fan
	on the processor might have died. In either case you
	need to ensure that you have hardware running at what it
	is specified to run at, at least while trying to solve
	this problem (in other words, clock it back to the default
	settings.)</para>

	<para>If you are overclocking then note that it is far
	cheaper to have a slow system than a fried system that
	needs replacing! Also the wider community is not often
	sympathetic to problems on overclocked systems, whether
	you believe it is safe or not.</para>
	</listitem>

	<listitem>
	<para>Dodgy memory: If you have multiple memory
	SIMMS/DIMMS installed then pull them all out and try
	running the machine with each SIMM or DIMM individually
	and narrow the problem down to either the problematic
	DIMM/SIMM or perhaps even a combination.</para>
	</listitem>

	<listitem>
	<para>Over-optimistic Motherboard settings: In your BIOS
	settings, and some motherboard jumpers you have options
	to set various timings, mostly the defaults will be
	sufficient, but sometimes, setting the wait states on
	RAM too low, or setting the <quote>RAM Speed:
	Turbo</quote> option, or similar in the BIOS will cause
	strange behavior. A possible idea is to set to BIOS
	defaults, but it might be worth noting down your
	settings first!</para>
	</listitem>

	<listitem>
	<para>Unclean or insufficient power to the motherboard.
	If you have any unused I/O boards, hard disks, or CD-ROMs
	in your system, try temporarily removing them or
	disconnecting the power cable from them, to see if your
	power supply can manage a smaller load. Or try another
	power supply, preferably one with a little more power
	(for instance, if your current power supply is rated at
	250 Watts try one rated at 300 Watts).</para>
	</listitem>
	</orderedlist>

	<para>You should also read the SIG11 FAQ (listed below) which
	has excellent explanations of all these problems, albeit from
	a &linux; viewpoint. It also discusses how memory testing
	software or hardware can still pass faulty memory.</para>

	<para>Finally, if none of this has helped it is possible that
	you have just found a bug in &os;, and you should follow the
	instructions to send a problem report.</para>

	<para>There is an extensive FAQ on this at <ulink
	url="http://www.bitwizard.nl/sig11/">the SIG11 problem FAQ</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="trap-12-panic">
	<para>My system crashes with either <errorname>Fatal trap 12:
	- page fault in kernel mode</errorname>, or
	+ page fault in kernel mode</errorname>, or
	<errorname>panic:</errorname>, and spits out a bunch of
	information. What should I do?</para>
	</question>

	<answer>
	<para>The &os; developers are very interested in these
	errors, but need some more information than just the error
	you see. Copy your full crash message. Then consult the
	FAQ section on <link
	linkend="kernel-panic-troubleshooting">kernel panics</link>,
	build a debugging kernel, and get a backtrace. This might
	sound difficult, but you do not need any programming skills;
	you just have to follow the instructions.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="proc-table-full">
	<para>Why do I get the error <errorname>maxproc limit
	exceeded by uid %i, please see tuning(7) and
	login.conf(5)</errorname>?</para>
	</question>

	<answer>
	<para>The &os; kernel will only allow a certain number of
	processes to exist at one time. The number is based on the
	<varname>kern.maxusers</varname> &man.sysctl.8; variable.
	<varname>kern.maxusers</varname> also affects various other
	in-kernel limits, such as network buffers.
	If your machine is heavily loaded, you probably
	want to increase <varname>kern.maxusers</varname>. This
	will increase these other system limits in addition to the
	maximum number of processes.</para>

	<para>To adjust your <varname>kern.maxusers</varname> value,
	see the <ulink
	url="&url.books.handbook;/configtuning-kernel-limits.html#kern-maxfiles">File/Process Limits</ulink>
	section of the Handbook. (While that section refers to open
	files, the same limits apply to processes.)</para>

	<para>If your machine is lightly loaded, and you are simply
	running a very large number of processes, you can adjust
	this with the <varname>kern.maxproc</varname> tunable. If
	this tunable needs adjustment it needs to be defined in
	<filename>/boot/loader.conf</filename>. The tunable will
	not get adjusted until the system is rebooted. For more
	information about tuning tunables, see
	&man.loader.conf.5;.
	If these processes are being run by a single user, you will
	also need to adjust <varname>kern.maxprocperuid</varname> to
	be one less than your new <varname>kern.maxproc</varname>
	value. (It must be at least one less because one system
	program, &man.init.8;, must always be running.)</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="mail-loopback">
	<para>Why does <application>sendmail</application> give me an
	error reading <errorname>mail loops back to
	- myself</errorname>?</para>
	+ myself</errorname>?</para>
	</question>

	<answer>
	<para>You can find a detailed answer for this question in the
	<ulink
	url="&url.books.handbook;/mail-trouble.html#q26.5.2.">Handbook</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="remote-fullscreen">
	<para>Why do full screen applications on remote machines
	misbehave?</para>
	</question>

	<answer>
	<para>The remote machine may be setting your terminal type to
	something other than the <literal>cons25</literal> terminal
	type required by the &os; console.</para>

	<para>There are a number of possible work-arounds for this
	problem:</para>

	<itemizedlist>
	<listitem>
	<para>After logging on to the remote machine, set your
	<envar>TERM</envar> shell variable to
	<literal>ansi</literal> or <literal>sco</literal> if
	the remote machine knows about these terminal
	types.</para>
	</listitem>

	<listitem>
	<para>Use a VT100 emulator like
	<application>screen</application> at the &os; console.
	<application>screen</application> offers you the
	ability to run multiple concurrent sessions from one
	terminal, and is a neat program in its own right.
	Each <application>screen</application> window behaves
	like a VT100 terminal, so the <envar>TERM</envar>
	variable at the remote end should be set to
	<literal>vt100</literal>.</para>
	</listitem>

	<listitem>
	<para>Install the <literal>cons25</literal> terminal
	database entry on the remote machine. The way to do
	this depends on the operating system on the remote
	machine. The system administration manuals for the
	remote system should be able to help you here.</para>
	</listitem>

	<listitem>
	<para>Fire up an X server at the &os; end and login to the
	remote machine using an X based terminal emulator such
	as <command>xterm</command> or <command>rxvt</command>.
	The <envar>TERM</envar> variable at the remote host
	should be set to <literal>xterm</literal> or
	<literal>vt100</literal>.</para>
	</listitem>
	</itemizedlist>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="connection-delay">
	<para>Why does it take so long to connect to my computer via
	<command>ssh</command> or <command>telnet</command>?</para>
	</question>

	<answer>
	<para>The symptom: there is a long delay between the time the
	TCP connection is established and the time when the client
	software asks for a password (or, in &man.telnet.1;'s case,
	when a login prompt appears).</para>

	<para>The problem: more likely than not, the delay is caused
	by the server software trying to resolve the client's IP
	address into a hostname. Many servers, including the
	<application>Telnet</application> and
	<application>SSH</application> servers that come with &os;,
	do this to store the hostname
	in a log file for future reference by the
	administrator.</para>

	<para>The remedy: if the problem occurs whenever you connect
	from your computer (the client) to any server, the problem is
	with the client; likewise, if the problem only occurs when
	someone connects to your computer (the server) the problem
	is with the server.</para>

	<para>If the problem is with the client, the only remedy is to
	fix the DNS so the server can resolve it. If this is on a
	local network, consider it a server problem and keep
	reading; conversely, if this is on the global Internet, you
	will most likely need to contact your ISP and ask them to
	fix it for you.</para>

	<para>If the problem is with the server, and this is on a
	local network, you need to configure the server to be able to
	resolve address-to-hostname queries for your local address
	range. See the &man.hosts.5; and &man.named.8; manual pages
	for more information. If this is on the global Internet,
	the problem may be that your server's resolver is not
	functioning correctly. To check, try to look up another
	host — say, <hostid>www.yahoo.com</hostid>. If it
	does not work, that is your problem.</para>

	<para>Following a fresh install of &os;, it is also possible
	that domain and name server information is missing from
	<filename>/etc/resolv.conf</filename>. This will often
	cause a delay in <application>SSH</application>, as the
	option <literal>UseDNS</literal> is set to
	<literal>yes</literal> by default in
	<filename>/etc/ssh/sshd_config</filename>.
	If this is causing the
	problem, you will either need to fill in the missing
	information in <filename>/etc/resolv.conf</filename> or set
	<literal>UseDNS</literal> to <literal>no</literal> in
	<filename>sshd_config</filename> as a temporary
	workaround.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="file-table-full">
	<para>Why does <errorname>file: table is full</errorname> show
	up repeatedly in &man.dmesg.8;?</para>
	</question>

	<answer>
	<para>This error message indicates you have exhausted the
	number of available file descriptors on your system. Please
	see the <ulink
	url="&url.books.handbook;/configtuning-kernel-limits.html#kern-maxfiles">kern.maxfiles</ulink>
	section of the <ulink
	url="&url.books.handbook;/configtuning-kernel-limits.html">Tuning Kernel Limits</ulink>
	section of the Handbook for a discussion and
	solution.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="computer-clock-skew">
	<para>Why does the clock on my computer keep incorrect time?</para>
	</question>

	<answer>
	<para>Your computer has two or more clocks, and &os; has
	chosen to use the wrong one.</para>

	<para>Run &man.dmesg.8;, and check for lines that contain
	<literal>Timecounter</literal>. The one with the highest
	quality value that &os; chose.</para>

	<screen>&prompt.root; <userinput>dmesg \| grep Timecounter</userinput>
	Timecounter "i8254" frequency 1193182 Hz quality 0
	Timecounter "ACPI-fast" frequency 3579545 Hz quality 1000
	Timecounter "TSC" frequency 2998570050 Hz quality 800
	Timecounters tick every 1.000 msec</screen>

	<para>You can confirm this by checking the
	<varname>kern.timecounter.hardware</varname>
	&man.sysctl.3;.</para>

	<screen>&prompt.root; <userinput>sysctl kern.timecounter.hardware</userinput>
	kern.timecounter.hardware: ACPI-fast</screen>

	<para>It may be a broken ACPI timer. The simplest solution is
	to disable the ACPI timer in
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>debug.acpi.disabled="timer"</programlisting>

	<para>Or the BIOS may modify the TSC clock—perhaps to
	change the speed of the processor when running from batteries,
	or going into a power saving mode, but &os; is unaware of
	these adjustments, and appears to gain or lose time.</para>

	<para>In this example, the <literal>i8254</literal> clock is
	also available, and can be selected by writing its name to the
	<varname>kern.timecounter.hardware</varname>
	&man.sysctl.3;.</para>

	<screen>&prompt.root; <userinput>sysctl kern.timecounter.hardware=i8254</userinput>
	kern.timecounter.hardware: TSC -> i8254</screen>

	<para>Your computer should now start keeping more accurate
	time.</para>

	<para>To have this change automatically run at boot time, add
	the following line to
	<filename>/etc/sysctl.conf</filename>:</para>

	<programlisting>kern.timecounter.hardware=i8254</programlisting>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="indefinite-wait-buffer">
	<para>What does the error <errorname>swap_pager: indefinite
	- wait buffer:</errorname> mean?</para>
	+ wait buffer:</errorname> mean?</para>
	</question>

	<answer>
	<para>This means that a process is trying to page memory to
	disk, and the page attempt has hung trying to access the
	disk for more than 20 seconds. It might be caused by bad
	blocks on the disk drive, disk wiring, cables, or any other
	disk I/O-related hardware. If the drive itself is actually
	bad, you will also see disk errors in
	<filename>/var/log/messages</filename> and in the output of
	<command>dmesg</command>. Otherwise, check your cables and
	connections.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="lock-order-reversal">
	<para>What is a <errorname>lock order
	- reversal</errorname>?</para>
	+ reversal</errorname>?</para>
	</question>

	<answer>
	- <para>An answer for this question can be found in the &os;
	- Glossary, see <ulink
	- url="&url.books.handbook;/freebsd-glossary.html#lor-glossary">LOR</ulink>.</para>
	+ <para>The &os; kernel uses a number of resource locks to
	+ arbitrate contention for certain resources. When multiple
	+ kernel threads try to obtain multiple resource locks,
	+ there's always the potential for a deadlock,
	+ where two threads have each obtained one of the locks and
	+ blocks forever waiting for the other thread to release one
	+ of the other locks. This sort of locking problem can be
	+ avoided if all threads obtain the locks in the same
	+ order.</para>
	+
	+ <para>A run-time lock diagnostic system called &man.witness.4;,
	+ enabled in &os.current; and disabled by default for stable
	+ branches and releases, detects the potential for deadlocks due to
	+ locking errors, including errors caused by obtaining multiple
	+ resource locks with a different order from different parts of the
	+ kernel. The &man.witness.4; framework tries to detect this
	+ problem as it happens, and reports it by printing a message to the
	+ system console about a <errorname>lock order reversal</errorname>
	+ (often referred to also as <acronym>LOR</acronym>).</para>
	+
	+ <para>It is possible to get false positives, as &man.witness.4;
	+ is conservative. A true positive report <emphasis>does
	+ not</emphasis> mean that a system is dead-locked; instead
	+ it should be understood as a warning of the form <quote>if
	+ you were unlucky, a deadlock would have happened
	+ here</quote>.</para>
	+
	+ <note>
	+ <para>Problematic <acronym>LOR</acronym>s tend to get fixed
	+ quickly, so check &a.current.url; before posting to the
	+ mailing lists.</para>
	+ </note>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="called-with-non-sleepable-locks-held">
	<para>What does <errorname>Called ... with the following
	- non-sleepable locks held</errorname> mean?</para>
	+ non-sleepable locks held</errorname> mean?</para>
	</question>

	<answer>
	<para>This means that a function that may sleep was called
	while a mutex (or other unsleepable) lock was held.</para>

	<para>The reason this is an error is because mutexes are not
	intended to be held for long periods of time; they are
	supposed to only be held to maintain short periods of
	synchronization. This programming contract allows device
	drivers to use mutexes to synchronize with the rest of the
	kernel during interrupts. Interrupts (under &os;) may not
	sleep. Hence it is imperative that no subsystem in the
	kernel block for an extended period while holding a
	mutex.</para>

	<para>To catch such errors, assertions may be added to the
	kernel that interact with the &man.witness.4; subsystem to
	emit a warning or fatal error (depending on the system
	configuration) when a potentially blocking call is made
	while holding a mutex.</para>

	<para>In summary, such warnings are non-fatal, however with
	unfortunate timing they could cause undesirable effects
	ranging from a minor blip in the system's responsiveness to
	a complete system lockup.</para>

	<para>For additional information about locking in &os; see
	&man.locking.9;.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="touch-not-found">
	<para>Why does
	<maketarget>buildworld</maketarget>/<maketarget>installworld</maketarget>
	die with the message <errorname>touch: not
	- found</errorname>?</para>
	+ found</errorname>?</para>
	</question>

	<answer>
	<para>This error does not mean that the &man.touch.1; utility
	is missing. The error is instead probably due to the dates
	of the files being set sometime in the future. If your
	CMOS-clock is set to local time you need to run the command
	<command>adjkerntz -i</command> to adjust the kernel
	clock when booting into single user mode.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="applications">
	<title>User Applications</title>

	<qandaset>
	<qandaentry>
	<question id="user-apps">
	<para>So, where are all the user applications?</para>
	</question>

	<answer>
	<para>Please take a look at <ulink
	url="&url.base;/ports/index.html">the ports page</ulink>
	for info on software packages ported to &os;. The list
	currently tops &os.numports; and is growing daily, so come
	back to check often or subscribe to the &a.announce; for
	periodic updates on new entries.</para>

	<para>Most ports should work on the
	- &rel3.relx;, &rel2.relx;, and &rel.relx; branches.
	+ &rel2.relx;, and &rel.relx; branches.
	Each time a &os;
	release is made, a snapshot of the ports tree at the time of
	release in also included in the <filename class="directory">ports/</filename>
	directory.</para>

	<para>We also support the concept of a <quote>package</quote>,
	essentially no more than a compressed binary distribution
	with a little extra intelligence embedded in it for doing
	whatever custom installation work is required. A package
	can be installed and uninstalled again easily without having
	to know the gory details of which files it includes.</para>

	<para>Use
	&man.pkg.add.1; on the specific package files
	you are interested in installing. Package files can usually
	be identified by their <filename>.tbz</filename> suffix and
	CD-ROM distribution people will have a
	<filename class="directory">packages/All</filename> directory on their CD
	which contains such files. They can also be downloaded over
	the net for various versions of &os; at the following
	locations:</para>

	<variablelist>
	<varlistentry>
	- <term>for &rel3.relx; -RELEASE/&rel3.stable;</term>
	-
	- <listitem>
	- <para><ulink
	- url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel3.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel3.packages;</ulink></para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	<term>for &rel2.relx; -RELEASE/&rel2.stable;</term>

	<listitem>
	<para><ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel2.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel2.packages;</ulink></para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>for &rel.relx; -RELEASE/&rel.stable;</term>

	<listitem>
	<para><ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel.packages;</ulink></para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>or your nearest local mirror site.</para>

	<para>Note that all ports may not be available as packages
	since new ones are constantly being added. It is always a
	good idea to check back periodically to see which packages
	are available at the <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/">ftp.FreeBSD.org</ulink>
	master site.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="how-do-download-ports-tree">
	<para>How do I download the Ports tree? Should I be using
	SVN?</para>
	</question>

	<answer>
	<para>Any of the methods listed here work:</para>

	<itemizedlist>
	<listitem>
	<para>Use portsnap for most use cases.</para>
	</listitem>
	<listitem>
	<para>Use SVN directly if you need custom patches
	to the ports tree.</para>
	</listitem>
	<listitem>
	<para>Use CTM if you prefer getting patches
	by email (this is a rarer use case).</para>
	</listitem>
	</itemizedlist>

	<para>Any other method should be considered a
	legacy method. If you do not already use them,
	do not start.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="java">
	<para>Does &os; support &java;?</para>
	</question>

	<answer>
	<para>Yes. Please see <ulink
	url="&url.base;/java/index.html">http://www.FreeBSD.org/java/</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ports-4x">
	<para>Why can I not build this port on my
	- &rel3.relx; -, &rel2.relx; -, or
	+ &rel2.relx; -, or
	&rel.relx; -STABLE machine?</para>
	</question>

	<answer>
	<para>If you are running a &os; version that lags
	significantly behind <emphasis>-CURRENT</emphasis> or
	<emphasis>-STABLE</emphasis>, you may need to update your
	Ports Collection; see the <ulink
	url="&url.books.porters-handbook;/keeping-up.html">Keeping Up</ulink>
	section of the Porter's Handbook for further information on
	how to do this. If you are up to date, then someone might
	have committed a change to the port which works for
	<emphasis>-CURRENT</emphasis> but which broke the port for
	<emphasis>-STABLE</emphasis>. Please submit a bug report on
	this with the &man.send-pr.1; command, since the Ports
	Collection is supposed to work for both the
	<emphasis>-CURRENT</emphasis> and
	<emphasis>-STABLE</emphasis> branches.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="make-index">
	<para>I just tried to build <filename>INDEX</filename> using
	<command>make <maketarget>index</maketarget></command>, and
	it failed. Why?</para>
	</question>

	<answer>
	<para>First, always make sure that you have a complete
	up-to-date Ports Collection. Errors that affect building
	<filename>INDEX</filename> from an up-to-date copy of the
	Ports Collection are high-visibility and are thus almost
	always fixed immediately.</para>

	<para>There are rare cases where <filename>INDEX</filename>
	will not build due to odd cases involving
	<makevar>WITH_<replaceable>*</replaceable></makevar> or
	<makevar>WITHOUT_<replaceable>*</replaceable></makevar>
	variables being set in <filename>make.conf</filename>. If
	you suspect that this is the case, please try to make
	<filename>INDEX</filename> with those make variables turned
	off before reporting it to &a.ports;.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ports-update">
	<para>I updated the sources, now how do I update my installed
	ports?</para>
	</question>

	<answer>
	<para>&os; does not include a port upgrading tool, but it does
	have some tools to make the upgrade process somewhat easier.
	You can also install additional tools to simplify port
	handling, see the <ulink
	url="&url.books.handbook;/ports-using.html">Upgrading Ports</ulink>
	section in the &os; Handbook.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ports-major-upgrade">
	<para>Do I need to recompile every port each time I perform a
	major version update?</para>
	</question>

	<answer>
	<para>By all means! While a recent system will run with
	software compiled under an older release, you will end up with
	things randomly crashing and failing to work once you start
	installing other ports or updating a portion of what you
	already have.</para>

	<para>When the system is upgraded, various shared libraries,
	loadable modules, and other parts of the system will be
	replaced with newer versions. Applications linked against
	the older versions may fail to start or, in other cases,
	fail to function properly.</para>

	<para>For more information, see <ulink
	url="&url.books.handbook;/updating-upgrading-freebsdupdate.html#freebsdupdate-upgrade">the section on upgrades</ulink>
	in the &os; Handbook.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ports-minor-upgrade">
	<para>Do I need to recompile every port each time I perform a
	minor version update?</para>
	</question>

	<answer>
	<para>In general, no. &os; developers do their utmost to
	guarantee binary compatibility across all releases with the
	same major version number. Any exceptions will be
	documented in the Release Notes, and advice given there
	should be followed.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="minimal-sh">
	<para>Why is <command>/bin/sh</command> so minimal? Why
	does &os; not use <command>bash</command> or another
	shell?</para>
	</question>

	<answer>
	<para>Many people need to write shell scripts which will be
	portable across many systems. That is why &posix;
	specifies the shell and utility commands in great detail.
	Most scripts are written in Bourne shell (&man.sh.1;), and
	because several important programming interfaces
	(&man.make.1;, &man.system.3;, &man.popen.3;, and
	analogues in higher-level scripting languages like Perl
	and Tcl) are specified to use the Bourne shell to
	interpret commands. Because the Bourne shell is so often
	and widely used, it is important for it to be quick to
	start, be deterministic in its behavior, and have a small
	memory footprint.</para>

	<para>The existing implementation is our best effort at
	meeting as many of these requirements simultaneously as we
	can. To keep <command>/bin/sh</command> small,
	we have not provided many of the convenience features that
	other shells have. That is why other more
	featureful shells like
	<command>bash</command>, <command>scsh</command>,
	&man.tcsh.1;, and <command>zsh</command> are available.
	(You can
	compare for yourself the memory utilization of all these
	shells by looking at the <quote>VSZ</quote> and
	<quote>RSS</quote> columns in a <command>ps
	- <option>-u</option></command> listing.)</para>
	+ <option>-u</option></command> listing.)</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="midi-sound-files">
	<para>How do I create audio CDs from my MIDI files?</para>
	</question>

	<answer>
	<para>To create audio CDs from MIDI files, first install
	<filename role="package">audio/timidity++</filename> from
	ports then install manually the GUS patches set by Eric A.
	Welsh, available at <ulink
	url="http://alleg.sourceforge.net/digmid.html"></ulink>.
	After <application>TiMidity++</application> has been installed
	properly, MIDI files may be converted to WAV files with the
	following command line:</para>

	<screen>&prompt.user; <userinput>timidity -Ow -s 44100 -o <replaceable>/tmp/juke/01.wav</replaceable> <replaceable>01.mid</replaceable></userinput></screen>

	<para>The WAV files can then be converted to other formats or
	burned onto audio CDs, as described in the <ulink
	url="&url.books.handbook;/creating-cds.html">&os; Handbook</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="officesuite">
	<para>Where can I get an Office Suite for &os;?</para>
	</question>

	<answer>
	<para>The open-source <application><ulink
	- url="http://www.openoffice.org">Apache OpenOffice</ulink></application>
	+ url="http://www.openoffice.org">Apache OpenOffice</ulink></application>
	and <application><ulink
	url="http://www.libreoffice.org">LibreOffice</ulink></application>
	office suites work natively on &os;.</para>

	<para>&os; also includes a variety of text editors,
	spreadsheets, and drawing programs in the Ports
	Collection.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="database-systems">
	<para>Are there any Database systems for &os;?</para>
	</question>

	<answer>
	<para>Yes! See the <ulink
	url="&url.base;/commercial/software_bycat.html#category_database">Commercial Vendors</ulink>
	section of &os;'s Web site.</para>

	<para>Also see the <ulink
	url="&url.base;/ports/databases.html">Databases</ulink>
	section of the Ports Collection.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="convert-back-from-pkgng">
	<para>How can I convert from pkgng to the old package
	tools?</para>
	</question>

	<answer>
	<para>Short answer: it is not possible.</para>

	<para>Longer answer: if you have made any changes using
	<command>pkg</command> converting back is non-trivial and
	requires lots of manual editing of internal package
	database files. However, if you have just run
	<command>pkg2ng</command> then you may remove
	<filename>/var/db/pkg/local.sqlite</filename>
	and extract
	<filename>/var/backups/pkgdb.bak.tbz</filename>.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="kernelconfig">
	<title>Kernel Configuration</title>

	<qandaset>
	<qandaentry>
	<question id="make-kernel">
	<para>I would like to customize my kernel. Is it
	difficult?</para>
	</question>

	<answer>
	<para>Not at all! Check out the <ulink
	url="&url.books.handbook;/kernelconfig.html">kernel config section of the Handbook</ulink>.</para>

	<note>
	<para>The new <filename>kernel</filename> will be installed
	to the <filename class="directory">/boot/kernel</filename> directory along
	with its modules, while the old kernel and its modules
	will be moved to the <filename class="directory">/boot/kernel.old</filename>
	directory, so if you make a mistake the next time you play
	with your configuration you can boot the previous version
	of your kernel.</para>
	</note>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="why-kernel-big">
	<para>Why is my kernel so big?</para>
	</question>

	<answer>
	<para><literal>GENERIC</literal> kernels shipped with &os;
	and later are compiled in <emphasis>debug mode</emphasis>.
	Kernels built in debug mode
	contain many symbols in separate files that are used for
	debugging, thus greatly increasing the size of
	<filename class="directory">/boot/kernel/</filename>.
	Note that there will be little or no performance loss
	from running a debug kernel, and it is useful to keep one
	around in case of a system panic.</para>

	<para>However, if you are running low on disk space, there
	are different options to reduce the size of <filename
	class="directory">/boot/kernel/</filename>.</para>

	<para>If you do not want the symbol files to be installed,
	make sure you have the following line present in
	<filename>/etc/src.conf</filename>:</para>

	<programlisting>WITHOUT_KERNEL_SYMBOLS=yes</programlisting>

	<para>For more information see &man.src.conf.5;.</para>

	<para>If you do not want to build a debug kernel, make
	sure that both of the following are true:</para>

	<itemizedlist>
	<listitem>
	<para>You do not have a line in your kernel configuration
	file that reads:</para>

	<programlisting>makeoptions DEBUG=-g</programlisting>
	</listitem>

	<listitem>
	<para>You are not running &man.config.8; with
	<option>-g</option>.</para>
	</listitem>
	</itemizedlist>

	<para>Either of the above settings will cause your kernel to
	be built in debug mode. As long as you make sure you follow
	the steps above, you can build your kernel normally.</para>

	<para>If you want only the modules you use to be built
	and installed, make sure you have a line like below in
	<filename>/etc/make.conf</filename>:</para>

	<programlisting>MODULES_OVERRIDE= <replaceable>accf_http ipfw</replaceable></programlisting>

	<para>Replace <emphasis>accf_httpd ipfw</emphasis> with
	a list of modules you need. Only these modules will be
	built. This does not only reduce the size of the kernel
	directory but also decreases the amount of time needed to
	build your kernel. For more information see
	<filename>/usr/share/examples/etc/make.conf</filename>.</para>

	<para>You can also remove unneeded devices from your kernel
	to further reduce the size. See
	<xref linkend="make-kernel"/> for more information.</para>

	<para>To put any of these options into effect you will have
	to <ulink url="&url.books.handbook;/kernelconfig-building.html">build and install</ulink>
	your new kernel.</para>

	<para>Most kernels (<filename>/boot/kernel/kernel</filename>)
	tend to be around 12 MB to 16 MB.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="generic-kernel-build-failure">
	<para>Why does every kernel I try to build fail to compile,
	even <filename>GENERIC</filename>?</para>
	</question>

	<answer>
	<para>There are a number of possible causes for this problem.
	They are, in no particular order:</para>

	<itemizedlist>
	<listitem>
	<para>You are not using the
	<command>make <maketarget>buildkernel</maketarget></command> and
	<command>make <maketarget>installkernel</maketarget></command>
	targets, and your source tree is different from the one
	used to build the currently running system (e.g., you
	are compiling &rel.current;-RELEASE on a
	&rel2.current;-RELEASE system). If you are attempting
	an upgrade, please read
	<filename>/usr/src/UPDATING</filename>, paying
	particular attention to the <quote>COMMON ITEMS</quote>
	section at the end.</para>
	</listitem>

	<listitem>
	<para>You are using the
	<command>make <maketarget>buildkernel</maketarget></command>
	and
	<command>make <maketarget>installkernel</maketarget></command>
	targets, but you failed to assert the completion of the
	<command>make <maketarget>buildworld</maketarget></command>
	target. The
	<command>make <maketarget>buildkernel</maketarget></command>
	target relies on files generated by the
	<command>make <maketarget>buildworld</maketarget></command>
	target to complete its job correctly.</para>
	</listitem>

	<listitem>
	<para>Even if you are trying to build <link
	linkend="stable">&os;-STABLE</link>, it is possible that
	you fetched the source tree at a time when it was either
	being modified, or broken for other reasons; only
	releases are absolutely guaranteed to be buildable,
	although <link linkend="stable">&os;-STABLE</link>
	builds fine the majority of the time. If you have not
	already done so, try re-fetching the source tree and see
	if the problem goes away. Try using a different server
	in case the one you are using is having problems.</para>
	</listitem>
	</itemizedlist>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="scheduler-in-use">
	<para>How can I verify which scheduler is in use on a running
	system?</para>
	</question>

	<answer>
	<para>The name of the scheduler currently being used is
	directly available as the value of the
	<varname>kern.sched.name</varname> sysctl:</para>

	<screen>&prompt.user; sysctl <replaceable>kern.sched.name</replaceable>
	kern.sched.name: ULE</screen>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="scheduler-kern-quantum">
	<para>What is <varname>kern.sched.quantum</varname>?</para>
	</question>

	<answer>
	<para><varname>kern.sched.quantum</varname> is the maximum
	number of ticks a process can run without being preempted
	in the 4BSD scheduler.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="disks">
	<title>Disks, File Systems, and Boot Loaders</title>

	<qandaset>
	<qandaentry>
	<question id="adding-disks">
	<para>How can I add my new hard disk to my &os; system?</para>
	</question>

	<answer>
	<para>See the <ulink
	url="&url.books.handbook;/disks-adding.html">Adding Disks</ulink>
	section in the &os; Handbook.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="new-huge-disk">
	<para>How do I move my system over to my huge new disk?</para>
	</question>

	<answer>
	<para>The best way is to reinstall the OS on the new disk,
	then move the user data over. This is highly recommended if
	you have been tracking <emphasis>-STABLE</emphasis> for more
	than one release, or have updated a release instead of
	installing a new one. You can install booteasy on both
	disks with &man.boot0cfg.8;, and dual boot them until you
	are happy with the new configuration. Skip the next
	paragraph to find out how to move the data after doing
	this.</para>

	<para>Alternatively, partition and label the new disk with either
	&man.sade.8; or &man.gpart.8;. If the disks are MBR-formatted,
	you can also install booteasy on both disks with
	&man.boot0cfg.8;, so that you can dual boot to the old or
	new system after the copying is done.</para>

	<para>Now you have the new disk set up, and are ready to move
	the data. Unfortunately, you cannot just blindly copy the
	data. Things like device files (in
	<filename class="directory">/dev</filename>), flags, and links tend to screw
	that up. You need to use tools that understand these
	things, which means &man.dump.8;. Although it is suggested
	that you move the data in single user mode, it is not
	required.</para>

	<para>You should never use anything but &man.dump.8; and
	&man.restore.8; to move the root file system. The
	&man.tar.1; command may work — then again, it may not.
	You should also use &man.dump.8; and &man.restore.8; if you
	are moving a single partition to another empty partition.
	The sequence of steps to use <command>dump</command> to move
	a partitions data to a new partition is:</para>

	<procedure>
	<step>
	<para><command>newfs</command> the new partition.</para>
	</step>

	<step>
	<para><command>mount</command> it on a temporary mount
	point.</para>
	</step>

	<step>
	<para><command>cd</command> to that directory.</para>
	</step>

	<step>
	<para><command>dump</command> the old partition, piping
	output to the new one.</para>
	</step>
	</procedure>

	<para>For example, if you are going to move root to
	<devicename>/dev/<replaceable>ada1s1a</replaceable></devicename>,
	with <filename class="directory"><replaceable>/mnt</replaceable></filename> as
	the temporary mount point, it is:</para>

	<screen>&prompt.root; <userinput>newfs /dev/<replaceable>ada1s1a</replaceable></userinput>
	&prompt.root; <userinput>mount /dev/<replaceable>ada1s1a</replaceable> <replaceable>/mnt</replaceable></userinput>
	&prompt.root; <userinput>cd <replaceable>/mnt</replaceable></userinput>
	&prompt.root; <userinput>dump 0af - / \| restore rf -</userinput></screen>

	<para>Rearranging your partitions with <command>dump</command>
	takes a bit more work. To merge a partition like
	<filename class="directory">/var</filename> into its parent, create the new
	partition large enough for both, move the parent partition
	as described above, then move the child partition into the
	empty directory that the first move created:</para>

	<screen>&prompt.root; <userinput>newfs /dev/<replaceable>ada1s1a</replaceable></userinput>
	&prompt.root; <userinput>mount /dev/<replaceable>ada1s1a</replaceable> <replaceable>/mnt</replaceable></userinput>
	&prompt.root; <userinput>cd <replaceable>/mnt</replaceable></userinput>
	&prompt.root; <userinput>dump 0af - / \| restore rf -</userinput>
	&prompt.root; <userinput>cd var</userinput>
	&prompt.root; <userinput>dump 0af - /var \| restore rf -</userinput></screen>

	<para>To split a directory from its parent, say putting
	<filename class="directory">/var</filename> on its own partition when it was
	not before, create both partitions, then mount the child
	partition on the appropriate directory in the temporary
	mount point, then move the old single partition:</para>

	<screen>&prompt.root; <userinput>newfs /dev/<replaceable>ada1s1a</replaceable></userinput>
	&prompt.root; <userinput>newfs /dev/<replaceable>ada1s1d</replaceable></userinput>
	&prompt.root; <userinput>mount /dev/<replaceable>ada1s1a</replaceable> <replaceable>/mnt</replaceable></userinput>
	&prompt.root; <userinput>mkdir <replaceable>/mnt</replaceable>/var</userinput>
	&prompt.root; <userinput>mount /dev/<replaceable>ada1s1d</replaceable> <replaceable>/mnt</replaceable>/var</userinput>
	&prompt.root; <userinput>cd <replaceable>/mnt</replaceable></userinput>
	&prompt.root; <userinput>dump 0af - / \| restore rf -</userinput></screen>

	<para>You might prefer &man.cpio.1;, &man.pax.1;, &man.tar.1;
	to &man.dump.8; for user data. At the time of this writing,
	these are known to lose file flag information, so use them
	with caution.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="safe-softupdates">
	<para>Which partitions can safely use Soft Updates? I have
	heard that Soft Updates on <filename class="directory">/</filename> can cause
	problems. What about Journaled Soft Updates?</para>
	</question>

	<answer>
	<para>Short answer: you can usually use Soft Updates safely on
	all partitions.</para>

	<para>Long answer: Soft Updates has two
	characteristics that may be undesirable on certain
	paritions. First, a Soft Updates
	partition has a small chance of losing data during a system
	crash. (The partition will not be corrupted; the data will
	simply be lost.) Second, Soft Updates can cause temporary
	space shortages.</para>

	<para>When using Soft Updates, the kernel can take up to
	thirty seconds to write changes to the physical
	disk. When a large file is deleted the file still
	resides on
	disk until the kernel actually performs the deletion. This
	can cause a very simple race condition. Suppose you delete
	one large file and immediately create another large file.
	The first large file is not yet actually removed from the
	physical disk, so the disk might not have enough room for
	the second large file. You get an error that the partition
	does not have enough space, although you know perfectly well
	that you just released a large chunk of space! When you try
	again mere seconds later, the file creation works as you
	expect. This has left more than one user scratching his
	head and doubting his sanity, the &os; file system, or
	both.</para>

	<para>If a system should crash after the kernel accepts a
	chunk of data for writing to disk, but before that data is
	actually written out, data could be lost. This
	risk is extremely small, but generally manageable.</para>

	<para>These issues affect all partitions using Soft Updates.
	So, what does this mean for the root partition?</para>

	<para>Vital information on the root partition changes very
	rarely. If the
	system crashed during the thirty-second window after such a
	change is made, it is possible that data could be lost.
	This risk is negligible for most applications, but you
	should be aware that it exists. If your system cannot
	tolerate this much risk, do not use Soft Updates on the root
	file system!</para>

	<para><filename class="directory">/</filename> is traditionally one of the
	smallest partitions. If you put the
	<filename class="directory">/tmp</filename> directory on
	<filename class="directory">/</filename> and you have a busy
	<filename class="directory">/tmp</filename>, you might see intermittent space
	problems. Symlinking <filename class="directory">/tmp</filename> to
	<filename class="directory">/var/tmp</filename> will solve this
	problem.</para>

	<para>Finally, &man.dump.8; does not work in live mode (-L)
	on a filesystem, with Journaled Soft Updates
	(<acronym>SU+J</acronym>).</para>
	</answer>
	</qandaentry>

	<qandaentry>
	- <question id="inappropriate-ccd">
	- <para>What is inappropriate about my &man.ccd.4;?</para>
	- </question>
	-
	- <answer>
	- <para>The symptom of this is:</para>
	-
	- <screen>&prompt.root; <userinput>ccdconfig -C</userinput>
	-ccdconfig: ioctl (CCDIOCSET): /dev/<replaceable>ccd0c</replaceable>: Inappropriate file type or format</screen>
	-
	- <para>This usually happens when you are trying to concatenate
	- the <literal>c</literal> partitions, which default to type
	- <literal>unused</literal>. The &man.ccd.4; driver requires
	- the underlying partition type to be
	- <literal>FS_BSDFFS</literal>. Edit the disk label of the
	- disks you are trying to concatenate and change the types of
	- partitions to <literal>4.2BSD</literal>.</para>
	- </answer>
	- </qandaentry>
	-
	- <qandaentry>
	- <question id="ccd-disk-label">
	- <para>Why can I not edit the disk label on my
	- &man.ccd.4;?</para>
	- </question>
	-
	- <answer>
	- <para>The symptom of this is:</para>
	-
	- <screen>&prompt.root; <userinput>disklabel <replaceable>ccd0</replaceable></userinput>
	-(it prints something sensible here, so let us try to edit it)
	-&prompt.root; <userinput>disklabel -e <replaceable>ccd0</replaceable></userinput>
	-(edit, save, quit)
	-disklabel: ioctl DIOCWDINFO: No disk label on disk;
	-use "disklabel -r" to install initial label</screen>
	-
	- <para>This is because the disk label returned by &man.ccd.4;
	- is actually a <quote>fake</quote> one that is not really on
	- the disk. You can solve this problem by writing it back
	- explicitly, as in:</para>
	-
	- <screen>&prompt.root; <userinput>disklabel <replaceable>ccd0</replaceable> > <replaceable>/tmp/disklabel.tmp</replaceable></userinput>
	-&prompt.root; <userinput>disklabel -Rr <replaceable>ccd0</replaceable> <replaceable>/tmp/disklabel.tmp</replaceable></userinput>
	-&prompt.root; <userinput>disklabel -e <replaceable>ccd0</replaceable></userinput>
	-(this will work now)</screen>
	- </answer>
	- </qandaentry>
	-
	- <qandaentry>
	<question id="mount-foreign-fs">
	<para>Can I mount other foreign file systems under
	&os;?</para>
	</question>

	<answer>
	<para>&os; supports a variety of other file systems.</para>

	<variablelist>
	<varlistentry>
	<term>UFS</term>

	<listitem>
	<para>UFS CD-ROMs can be mounted directly on &os;.
	Mounting disk partitions from Digital UNIX and other
	systems that support UFS may be more complex,
	depending on the details of the disk partitioning for
	the operating system in question.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>ext2/ext3</term>

	<listitem>
	<para>&os; supports <literal>ext2fs</literal> and
	<literal>ext3fs</literal> partitions. See
	&man.mount.ext2fs.8; for more information.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>NTFS</term>

	<listitem>
	<para>FUSE based NTFS support is available as a port
	(<filename role="package">sysutils/fusefs-ntfs</filename>).
	For more information see <ulink
	url="http://www.tuxera.com/community/ntfs-3g-manual/"><application>ntfs-3g</application></ulink>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>FAT</term>

	<listitem>
	<para>&os; includes a read-write FAT driver. For more
	information, see &man.mount.msdosfs.8;.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>ZFS</term>

	<listitem>
	<para>&os; includes a port of
	&sun;'s ZFS driver. The current recommendation is to
	use it only on &arch.amd64; platforms with sufficient
	memory. For more information, see &man.zfs.8;.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>&os; also supports network file systems such as NFS (see
	&man.mount.nfs.8;), NetWare (see &man.mount.nwfs.8;), and
	Microsoft-style SMB file systems (see &man.mount.smbfs.8;).
	You can find ports based on FUSE (<filename
	role="package">sysutils/fusefs-kmod</filename>) for many
	other file systems.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="mount-dos">
	<para>How do I mount a secondary DOS partition?</para>
	</question>

	<answer>
	<para>The secondary DOS partitions are found after
	<emphasis>all</emphasis> the primary partitions. For
	example, if you have an <quote>E</quote> partition as the
	second DOS partition on the second SCSI drive, there will be
	a device file for <quote>slice 5</quote> in
	<filename class="directory">/dev</filename>, so simply mount it:</para>

	<screen>&prompt.root; <userinput>mount -t msdosfs /dev/da1s5 /dos/e</userinput></screen>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="crypto-file-system">
	<para>Is there a cryptographic file system for &os;?</para>
	</question>

	<answer>
	<para>Yes. You can use either &man.gbde.8; or &man.geli.8;,
	see the <ulink
	url="&url.books.handbook;/disks-encrypting.html">Encrypting Disk Partitions</ulink>
	section of the &os; Handbook.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="nt-bootloader">
	<para>How can I use the &windowsnt; loader to boot
	&os;?</para>
	</question>

	<answer>
	<para>The general idea is that you copy the first sector of
	your native root &os; partition into a file in the
	DOS/&windowsnt; partition. Assuming you name that file
	something like <filename>c:\bootsect.bsd</filename>
	(inspired by <filename>c:\bootsect.dos</filename>), you can
	then edit <filename>c:\boot.ini</filename> to come
	up with something like this:</para>

	<programlisting>[boot loader]
	timeout=30
	default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
	[operating systems]
	multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT"
	C:\BOOTSECT.BSD="&os;"
	C:\="DOS"</programlisting>

	<para>If &os; is installed on the same disk as the &windowsnt;
	boot partition simply copy <filename>/boot/boot1</filename> to
	<filename>C:\BOOTSECT.BSD</filename>. However, if &os; is
	installed on a different disk
	<filename>/boot/boot1</filename> will not work,
	<filename>/boot/boot0</filename> is needed.</para>

	<para><filename>/boot/boot0</filename> needs to be installed
	using &man.sysinstall.8; by selecting the &os; boot manager
	on the screen which asks if you wish to use a boot manager.
	This is because <filename>/boot/boot0</filename> has the
	partition table area filled with NULL characters but
	&man.sysinstall.8; copies the partition table before copying
	<filename>/boot/boot0</filename> to the MBR.</para>

	- <warning>
	- <para><emphasis>Do not simply copy
	+ <warning>
	+ <para><emphasis>Do not simply copy
	<filename>/boot/boot0</filename> instead of
	<filename>/boot/boot1</filename>; you will overwrite
	your partition table and render your computer
	un-bootable!</emphasis></para>
	- </warning>
	+ </warning>

	<para>When the &os; boot manager runs it records the last OS
	booted by setting the active flag on the partition table
	entry for that OS and then writes the whole 512-bytes of
	itself back to the MBR so if you just copy
	<filename>/boot/boot0</filename> to
	<filename>C:\BOOTSECT.BSD</filename> then it writes an empty
	partition table, with the active flag set on one entry, to
	the MBR.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="lilo-bootloader">
	<para>How do I boot &os; and &linux; from LILO?</para>
	</question>

	<answer>
	<para>If you have &os; and &linux; on the same disk, just
	follow LILO's installation instructions for booting a
	non-&linux; operating system. Very briefly, these
	are:</para>

	<para>Boot &linux;, and add the following lines to
	<filename>/etc/lilo.conf</filename>:</para>

	<programlisting>other=/dev/hda2
	table=/dev/hda
	label=&os;</programlisting>

	<para>(the above assumes that your &os; slice is known to
	&linux; as <devicename>/dev/hda2</devicename>; tailor to
	suit your setup). Then, run <command>lilo</command> as
	<username>root</username> and you should be done.</para>

	<para>If &os; resides on another disk, you need to add
	<literal>loader=/boot/chain.b</literal> to the LILO entry.
	For example:</para>

	<programlisting>other=/dev/dab4
	table=/dev/dab
	loader=/boot/chain.b
	label=&os;</programlisting>

	<para>In some cases you may need to specify the BIOS drive
	number to the &os; boot loader to successfully boot off the
	second disk. For example, if your &os; SCSI disk is probed
	by BIOS as BIOS disk 1, at the &os; boot loader prompt you
	need to specify:</para>

	<screen>Boot: <userinput>1:da(0,a)/boot/kernel/kernel</userinput></screen>

	<para>You can configure &man.boot.8; to automatically do this
	for you at boot time.</para>

	<para>The <ulink
	url="http://tldp.org/HOWTO/Linux+FreeBSD.html">&linux;+&os; mini-HOWTO</ulink>
	is a good reference for &os; and &linux; interoperability
	issues.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="grub-loader">
	<para>How do I boot &os; and &linux; using GRUB?</para>
	</question>

	<answer>
	<para>Booting &os; using GRUB is very simple. Just add the
	following to your configuration file
	<filename>/boot/grub/menu.lst</filename> (or
	<filename>/boot/grub/grub.conf</filename> in some systems,
	e.g., Red Hat Linux and its derivatives).</para>

	<programlisting>title &os; 6.1
	root <replaceable>(hd0,a)</replaceable>
	kernel /boot/loader</programlisting>

	<para>Where <replaceable>hd0,a</replaceable> points to your
	root partition on the first disk. If you need to specify
	which slice number should be used, use something like this
	<replaceable>(hd0,2,a)</replaceable>. By default, if the
	slice number is omitted, GRUB searches the first slice which
	has <literal>a</literal> partition.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="booteasy-loader">
	<para>How do I boot &os; and &linux; using
	<application>BootEasy?</application></para>
	</question>

	<answer>
	<para>Install LILO at the start of your &linux; boot partition
	instead of in the Master Boot Record. You can then boot
	LILO from <application>BootEasy</application>.</para>

	<para>If you are running &windows; and &linux; this is
	recommended anyway, to make it simpler to get &linux; booting
	again if you should need to reinstall &windows; (which is a
	Jealous Operating System, and will bear no other Operating
	Systems in the Master Boot Record).</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="changing-bootprompt">
	<para>How do I change the boot prompt from
	<literal>???</literal> to something more meaningful?</para>
	</question>

	<answer>
	<para>You can not do that with the standard boot manager
	without rewriting it. There are a number of other boot
	managers in the <filename class="directory">sysutils</filename> ports category
	that provide this functionality.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="removable-drives">
	<para>I have a new removable drive, how do I use it?</para>
	</question>

	<answer>
	<para>If the drive already has a
	file system on it, you can use a command like this:</para>

	<screen>&prompt.root; <userinput>mount -t msdosfs /dev/da0s1 /mnt</userinput></screen>

	<para>If the drive will only be used with &os;
	systems it is better idea to
	stick a BSD file system on it, like UFS or ZFS.
	You will get long filename
	support, at least a 2X improvement in performance,
	and a lot more stability. If the drive will be
	used by other operating systems a more portable
	choice, such as msdosfs, is better.</para>

	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da0 count=2</userinput>
	&prompt.root; <userinput>gpart create -s GPT /dev/da0</userinput>
	&prompt.root; <userinput>gpart add -t freebsd-ufs /dev/da0</userinput></screen>

	<para>Finally, create a new file system:</para>

	<screen>&prompt.root; <userinput>newfs /dev/da0p1</userinput></screen>

	<para>and mount it:</para>

	<screen>&prompt.root; <userinput>mount /dev/da0s1 /mnt</userinput></screen>

	<para>It is a good idea to add a line
	to <filename>/etc/fstab</filename> (see &man.fstab.5;) so
	you can just type <command>mount /mnt</command> in the
	future:</para>

	<programlisting>/dev/da0p1 /mnt ufs rw,noauto 0 0</programlisting>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="mount-cd-superblock">
	<para>Why do I get <errorname>Incorrect super
	- block</errorname> when mounting a CD-ROM?</para>
	+ block</errorname> when mounting a CD-ROM?</para>
	</question>

	<answer>
	<para>You have to tell &man.mount.8; the type of the device
	that you want to mount. This is described in the <ulink
	url="&url.books.handbook;/creating-cds.html"> Handbook section on optical media</ulink>,
	specifically the section <ulink
	url="&url.books.handbook;/creating-cds.html#mounting-cd">Using Data CDs</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="cdrom-not-configured">
	<para>Why do I get <errorname>Device not
	- configured</errorname> when mounting a CD-ROM?</para>
	+ configured</errorname> when mounting a CD-ROM?</para>
	</question>

	<answer>
	<para>This generally means that there is no CD-ROM in the
	CD-ROM drive, or the drive is not visible on the bus.
	Please see the <ulink
	url="&url.books.handbook;/creating-cds.html#mounting-cd">Using Data CDs</ulink>
	section of the Handbook for a detailed discussion of this
	issue.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="cdrom-unicode-filenames">
	<para>Why do all non-English characters in filenames show up
	as <quote>?</quote> on my CDs when mounted in &os;?</para>
	</question>

	<answer>
	<para>Your CD-ROM probably uses the <quote>Joliet</quote>
	extension for storing information about files and
	directories. This is discussed in the Handbook chapter on
	<ulink
	url="&url.books.handbook;/creating-cds.html">creating and using CD-ROMs</ulink>,
	specifically the section on <ulink
	url="&url.books.handbook;/creating-cds.html#mounting-cd">Using Data CD-ROMs</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="burncd-isofs">
	<para>I burned a CD under &os; and now I can not read it under
	any other operating system. Why?</para>
	</question>

	<answer>
	<para>You most likely burned a raw file to your CD, rather
	than creating an ISO 9660 file system. Take a look at
	the <ulink
	url="&url.books.handbook;/creating-cds.html">Handbook chapter on creating CD-ROMs</ulink>,
	particularly the section on <ulink
	url="&url.books.handbook;/creating-cds.html#rawdata-cd">burning raw data CDs</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="copy-cd">
	<para>How can I create an image of a data CD?</para>
	</question>

	<answer>
	<para>This is discussed in the Handbook section on <ulink
	url="&url.books.handbook;/creating-cds.html#imaging-cd">duplicating data CDs</ulink>.
	For more on working with CD-ROMs, see the <ulink
	url="&url.books.handbook;/creating-cds.html">Creating CDs Section</ulink>
	in the Storage chapter in the Handbook.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="mount-audio-CD">
	<para>Why can I not <command>mount</command> an audio
	- CD?</para>
	+ CD?</para>
	</question>

	<answer>
	<para>If you try to mount an audio CD, you will get an error
	like <errorname>cd9660: /dev/acd0c: Invalid
	argument</errorname>. This is because
	<command>mount</command> only works on file systems. Audio
	CDs do not have file systems; they just have data. You need
	a program that reads audio CDs, such as the <filename
	role="package">audio/xmcd</filename> port.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="multi-session-CD">
	<para>How do I <command>mount</command> a multi-session
	CD?</para>
	</question>

	<answer>
	<para>By default, &man.mount.8; will attempt to mount the last
	data track (session) of a CD. If you would like to load an
	earlier session, you must use the <option>-s</option>
	command line argument. Please see &man.mount.cd9660.8; for
	specific examples.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="user-floppymount">
	<para>How do I let ordinary users mount CD-ROMs, DVDs,
	USB drives, and other removable media?</para>
	</question>

	<answer>
	<para>As <username>root</username> set the sysctl variable
	<varname>vfs.usermount</varname> to
	<literal>1</literal>.</para>

	<screen>&prompt.root; <userinput>sysctl vfs.usermount=1</userinput></screen>

	<para>To make this persist across reboots, add the line
	<literal><varname>vfs.usermount</varname>=1</literal> to
	<filename>/etc/sysctl.conf</filename> so that
	it is reset at system boot time.</para>

	<para>Users can only mount devices they have read
	permissions to. To allow users to mount a device
	permissions must be set in
	<filename>/etc/devfs.conf</filename>.</para>

	<para>For example, to allow users to mount the first USB
	drive add:</para>

	<programlisting># Allow all users to mount a USB drive.
	own /dev/da0 root:operator
	perm /dev/da00 0666</programlisting>

	<para>All users can now mount devices they could read
	onto a directory that they own:</para>

	<screen>&prompt.user; <userinput>mkdir <replaceable>~/my-mount-point</replaceable></userinput>
	&prompt.user; <userinput>mount -t msdosfs /dev/da0<replaceable>~/my-mount-point</replaceable></userinput></screen>

	<para>Unmounting the device is simple:</para>

	<screen>&prompt.user; <userinput>umount <replaceable>~/my-mount-point</replaceable></userinput></screen>

	<para>Enabling <varname>vfs.usermount</varname>, however, has
	negative security implications. A better way to access
	&ms-dos; formatted media is to use the <filename
	role="package">emulators/mtools</filename> package in the
	Ports Collection.</para>

	<note>
	<para>The device name used in the previous examples must be
	changed according to your configuration.</para>
	</note>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="du-vs-df">
	<para>The <command>du</command> and <command>df</command>
	commands show different amounts of disk space available.
	What is going on?</para>
	</question>

	<answer>
	<para>You need to understand what <command>du</command> and
	<command>df</command> really do. <command>du</command> goes
	through the directory tree, measures how large each file is,
	and presents the totals. <command>df</command> just asks
	the file system how much space it has left. They seem to be
	the same thing, but a file without a directory entry will
	affect <command>df</command> but not
	<command>du</command>.</para>

	<para>When a program is using a file, and you delete the file,
	the file is not really removed from the file system until
	the program stops using it. The file is immediately deleted
	from the directory listing, however. You can see this
	easily enough with a program such as
	<command>more</command>. Assume you have a file large
	enough that its presence affects the output of
	<command>du</command> and <command>df</command>. (Since
	disks can be so large today, this might be a
	<emphasis>very</emphasis> large file!) If you delete this
	file while using <command>more</command> on it,
	<command>more</command> does not immediately choke and
	complain that it cannot view the file. The entry is simply
	removed from the directory so no other program or user can
	access it. <command>du</command> shows that it is gone
	— it has walked the directory tree and the file is not
	listed. <command>df</command> shows that it is still there,
	as the file system knows that <command>more</command> is
	still using that space. Once you end the
	<command>more</command> session, <command>du</command> and
	<command>df</command> will agree.</para>

	- <para>Note that Soft Updates can delay the freeing of disk
	- space; you might need to wait up to 30 seconds for the
	- change to be visible!</para>
	-
	<para>This situation is common on web servers. Many people
	set up a &os; web server and forget to rotate the log files.
	The access log fills up <filename class="directory">/var</filename>. The new
	administrator deletes the file, but the system still
	complains that the partition is full. Stopping and
	restarting the web server program would free the file,
	allowing the system to release the disk space. To prevent
	this from happening, set up &man.newsyslog.8;.</para>
	+
	+ <para>Note that Soft Updates can delay the freeing of disk
	+ space; you might need to wait up to 30 seconds for the
	+ change to be visible!</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="add-swap-space">
	<para>How can I add more swap space?</para>
	</question>

	<answer>
	<para>In the <ulink
	url="&url.books.handbook;/config-tuning.html">Configuration and Tuning</ulink>
	section of the Handbook, you will find a <ulink
	url="&url.books.handbook;/adding-swap-space.html">section</ulink>
	describing how to do this.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="manufacturer-disk-size">
	<para>Why does &os; see my disk as smaller than the
	manufacturer says it is?</para>
	</question>

	<answer>
	<para>Disk manufacturers calculate gigabytes as a billion
	bytes each, whereas &os; calculates them as
	1,073,741,824 bytes each. This explains why, for
	example, &os;'s boot messages will report a disk that
	supposedly has 80 GB as holding 76,319 MB.</para>

	<para>Also note that &os; will (by default) <link
	linkend="disk-more-than-full">reserve</link> 8% of the disk
	space.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="disk-more-than-full">
	<para>How is it possible for a partition to be more than 100%
	full?</para>
	</question>

	<answer>
	<para>A portion of each UFS partition (8%, by default) is
	reserved for use by the operating system and the
	<username>root</username> user. &man.df.1; does not count
	that space when calculating the <literal>Capacity</literal>
	column, so it can exceed 100%. Also, you will notice that
	the <literal>Blocks</literal> column is always greater than
	the sum of the <literal>Used</literal> and
	<literal>Avail</literal> columns, usually by a factor of
	8%.</para>

	<para>For more details, look up <option>-m</option>
	in &man.tunefs.8;.</para>
	</answer>
	</qandaentry>
	</qandaset>

	<sect1 id="all-about-zfs">
	<title>ZFS</title>

	<qandaset>
	<qandaentry>
	<question id="how-much-ram-for-zfs">
	<para>What is the minimum amount of RAM one should have to
	run ZFS?</para>
	</question>

	<answer>
	<para>A minimum of 4GB of RAM is required for comfortable
	usage, but individual workloads can vary widely.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="what-is-zil">
	<para>What is the ZIL and when does it get used?</para>
	</question>

	<answer>
	<para>The <acronym>ZIL</acronym> ((<acronym>ZFS</acronym>
	intent log) is a write log used to implement posix write
	commitment semantics across crashes. Normally writes
	are bundled up into transaction groups
	and written to disk when filled (<quote>Transaction Group
	Commit</quote>). However syscalls like &man.fsync.2;
	require a commitment that the data is written to stable
	storage before returning.
	The ZIL is needed for writes that have been acknowledged
	as written but which are not yet on disk as part of a
	transaction. The transaction groups are timestamped.
	In the event of a crash the last valid timestamp is
	found and missing data is merged in from the ZIL.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="need-ssd-for-zil">
	<para>Do I need a SSD for ZIL?</para>
	</question>

	<answer>
	<para>By default, ZFS stores the ZIL in the pool with all
	the data. If your application has a heavy write load,
	storing the ZIL in a separate device that has very fast
	synchronous, sequential write performance can improve
	overall system. For other workloads, a SSD is unlikely
	to make much of an improvement.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="what-is-l2arc">
	<para>What is the L2ARC?</para>
	</question>

	<answer>
	<para>The <acronym>L2ARC</acronym> is a read cache stored
	on a fast device such as an <acronym>SSD</acronym>.
	This cache is not persisent across
	reboots. Note that RAM is used as the first layer
	of cache and the L2ARC is only needed if there is
	insufficient RAM.</para>

	<para>L2ARC needs space in the ARC to index it. So,
	perversely, a working set that fits perfectly in the
	ARC will not fit perfectly any more if a L2ARC is used
	because part of the ARC is holding the L2ARC index,
	pushing part of the working set into the
	L2ARC which is slower than RAM.</para>
	- </answer>
	+ </answer>
	</qandaentry>

	<qandaentry>
	<question id="should-enable-dedup">
	<para>Is enabling deduplication advisable?</para>
	</question>

	<answer>
	<para>Generally speaking, no.</para>

	<para>Deduplication takes up a significant amount
	of RAM and may slow down read and write
	disk access times. Unless one is storing data that is
	very heavily duplicated (such as virtual machine images,
	or user backups) it is possible that deduplication will
	do more harm than good. Another consideration is the
	inability to revert deduplication status. If data is
	written when deduplication is enabled, disabling dedup
	will not cause those blocks which were deduplicated to
	be replicated until they are next modified.</para>

	<para>Deduplication can also lead to some unexpected
	situations. In particular deleting files may become much
	slower.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="zpool-fully-full">
	<para>I can not delete or create files on my ZFS pool.
	How can I fix this?</para>
	</question>

	<answer>
	<para>This could happen because the pool is 100% full.
	ZFS requires space on the disk to write
	transaction metadata. To restore the pool
	to a usable state, truncate a file you want to
	delete.</para>

	<screen>&prompt.user; <userinput>truncate -s 0 <replaceable>unimportant-file</replaceable></userinput></screen>

	<para>File truncation works because a new transaction is
	not started, new spare blocks are created instead.</para>

	<note>
	<para>On systems with additional ZFS dataset tuning,
	such as deduplication, the space may not be immediately
	available</para>
	</note>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="zfs-ssd-trim">
	<para>Does ZFS support TRIM for Solid State Drives?</para>
	</question>

	<answer>
	<para>ZFS TRIM support was added to &os; 10-CURRENT
	with revision r<svnref>240868</svnref>. ZFS TRIM
	support is not yet available on the -STABLE
	branches.</para>

	<para>ZFS TRIM is enabled by default, and can be turned
	off by adding this line to
	<filename>/etc/sysctl.conf</filename>:</para>

	<programlisting>vfs.zfs.trim_disable=1</programlisting>

	<note>
	<para>ZFS TRIM may not work with all configurations,
	such as a ZFS filesystem on a GELI-backed
	device.</para>
	</note>
	</answer>
	</qandaentry>
	</qandaset>
	</sect1>
	</chapter>

	<chapter id="admin">
	<title>System Administration</title>

	<qandaset>
	<qandaentry>
	<question id="startup-config-files">
	<para>Where are the system start-up configuration
	files?</para>
	</question>

	<answer>
	<para>The primary configuration file is
	<filename>/etc/defaults/rc.conf</filename> (see
	&man.rc.conf.5;). System startup scripts such as
	<filename class="directory">/etc/rc</filename> and
	<filename class="directory">/etc/rc.d</filename> (see &man.rc.8;) just include
	this file. <emphasis>Do not edit this file!</emphasis>
	Instead, if there is any entry in
	<filename>/etc/defaults/rc.conf</filename> that you want to
	change, you should copy the line into
	<filename>/etc/rc.conf</filename> and change it
	there.</para>

	<para>For example, if you wish to start &man.named.8;, the
	included DNS server, all you need to do is:</para>

	<screen>&prompt.root; <userinput>echo 'named_enable="YES"' >> /etc/rc.conf</userinput></screen>

	<para>To start up local services, place shell scripts in the
	<filename class="directory">/usr/local/etc/rc.d</filename> directory. These
	shell scripts should be set executable, the default file
	mode is <literal>555</literal>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="adding-users">
	<para>How do I add a user easily?</para>
	</question>

	<answer>
	<para>Use the &man.adduser.8; command, or the &man.pw.8;
	command for more complicated situations.</para>

	<para>To remove the user, use the &man.rmuser.8; command or,
	if necessary, &man.pw.8;.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="root-not-found-cron-errors">
	<para>Why do I keep getting messages like <errorname>root: not
	- found</errorname> after editing
	- <filename>/etc/crontab</filename></para>
	+ found</errorname> after editing
	+ <filename>/etc/crontab</filename></para>
	</question>

	<answer>
	<para>This is normally caused by editing the system crontab
	(<filename>/etc/crontab</filename>) and then using
	&man.crontab.1; to install it:</para>

	<screen>&prompt.root; <userinput>crontab /etc/crontab</userinput></screen>

	<para>This is not the correct way to do things. The system
	crontab has a different format to the per-user crontabs
	which &man.crontab.1; updates (the &man.crontab.5; manual
	page explains the differences in more detail).</para>

	<para>If this is what you did, the extra crontab is simply a
	copy of <filename>/etc/crontab</filename> in the wrong
	format it. Delete it with the command:</para>

	<screen>&prompt.root; <userinput>crontab -r</userinput></screen>

	<para>Next time, when you edit
	<filename>/etc/crontab</filename>, you should not do
	anything to inform &man.cron.8; of the changes, since it
	will notice them automatically.</para>

	<para>If you want something to be run once per day, week, or
	month, it is probably better to add shell scripts
	<filename class="directory">/usr/local/etc/periodic</filename>, and let the
	&man.periodic.8; command run from the system
	<command>cron</command> schedule it with the other periodic
	system tasks.</para>

	<para>The actual reason for the error is that the system
	crontab has an extra field, specifying which user to run the
	command as. In the default system crontab provided with
	&os;, this is <username>root</username> for all entries.
	When this crontab is used as the <username>root</username>
	user's crontab (which is <emphasis>not</emphasis> the same
	as the system crontab), &man.cron.8; assumes the string
	<literal>root</literal> is the first word of the command to
	execute, but no such command exists.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="su-wheel-group">
	<para>Why do I get the error, <errorname>you are not in the
	- correct group to su root</errorname> when I try to
	+ correct group to su root</errorname> when I try to
	<command>su</command> to <username>root</username>?</para>
	</question>

	<answer>
	<para>This is a security feature. To
	<command>su</command> to <username>root</username> (or any
	other account with superuser privileges), you must be in the
	<groupname>wheel</groupname> group. If this feature were
	not there, anybody with an account on a system who also
	found out <username>root</username>'s password would be able
	to gain superuser level access to the system. With this
	feature, this is not strictly true; &man.su.1; will prevent
	them from even trying to enter the password if they are not
	in <groupname>wheel</groupname>.</para>

	<para>To allow someone to <command>su</command> to
	<username>root</username>, simply put them in the
	<groupname>wheel</groupname> group. Use &man.pw.8;
	for this purpose.</para>

	<screen>&prompt.root; <userinput>pw groupmod wheel -m <replaceable>lisa</replaceable></userinput></screen>

	<para>The above example will add user
	<username>lisa</username> to the group
	<groupname>wheel</groupname>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="rcconf-readonly">
	<para>I made a mistake in <filename>rc.conf</filename>, or
	another startup file, and now I cannot edit it because the
	file system is read-only. What should I do?</para>
	</question>

	<answer>
	<para>Restart the system using <userinput>boot -s</userinput>
	at the loader prompt to enter Single User mode. When
	prompted for a shell pathname, simply press
	<keycap>Enter</keycap>, and run
	<command>mount -urw /</command> to re-mount the root file
	system in read/write mode. You may also need to run
	<command>mount -a -t ufs</command> to mount the file system
	where your favorite editor is defined. If your favorite
	editor is on a network file system, you will need to either
	configure the network manually before you can mount network
	file systems, or use an editor which resides on a local file
	system, such as &man.ed.1;.</para>

	<para>If you intend to use a full screen editor such as
	&man.vi.1; or &man.emacs.1;, you may also need to run
	- <command>export TERM=cons25</command> so that these editors
	+ <command>export TERM=xterm</command> on &os; 9.0+, or
	+ <command>export TERM=cons25</command> on &os; 8.X
	+ so that these editors
	can load the correct data from the &man.termcap.5;
	database.</para>

	<para>Once you have performed these steps, you can edit
	<filename>/etc/rc.conf</filename> as you usually would to
	fix the syntax error. The error message displayed
	immediately after the kernel boot messages should tell you
	the number of the line in the file which is at fault.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="printer-setup">
	<para>Why am I having trouble setting up my printer?</para>
	</question>

	<answer>
	<para>See the <ulink
	url="&url.books.handbook;/printing.html">Handbook entry on printing</ulink>.
	It should cover most of your problem.</para>

	<para>Some printers require a host-based driver to do any kind
	of printing. These so-called <quote>WinPrinters</quote> are
	not natively supported by &os;. If your printer does not
	work in DOS or &windows;, it is probably a WinPrinter. Your
	only hope of getting one of these to work is to check if the
	<filename role="package">print/pnm2ppa</filename> port
	supports it.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="keyboard-mappings">
	<para>How can I correct the keyboard mappings for my
	system?</para>
	</question>

	<answer>
	<para>Please see the Handbook section on <ulink
	url="&url.books.handbook;/using-localization.html">using localization</ulink>,
	specifically the section on <ulink
	url="&url.books.handbook;/using-localization.html#setting-console">console setup</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="user-quotas">
	<para>Why can I not get user quotas to work properly?</para>
	</question>

	<answer>
	<orderedlist>
	<listitem>
	<para>It is possible that your kernel is not configured
	to use quotas. If this is the case, you will need to
	add the following line to your kernel configuration
	file and recompile:</para>

	<programlisting>options QUOTA</programlisting>

	<para>Please read the <ulink
	url="&url.books.handbook;/quotas.html">Handbook entry on quotas</ulink>
	for full details.</para>
	</listitem>

	<listitem>
	<para>Do not turn on quotas on
	<filename class="directory">/</filename>.</para>
	</listitem>

	<listitem>
	<para>Put the quota file on the file system that the
	quotas are to be enforced on, i.e.:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>File System</entry>

	<entry>Quota file</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><filename class="directory">/usr</filename></entry>

	<entry><filename>/usr/admin/quotas</filename></entry>
	</row>

	<row>
	<entry><filename class="directory">/home</filename></entry>

	<entry><filename>/home/admin/quotas</filename></entry>
	</row>

	<row>
	<entry>…</entry>

	<entry>…</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</listitem>
	</orderedlist>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="sysv-ipc">
	<para>Does &os; support System V IPC primitives?</para>
	</question>

	<answer>
	<para>Yes, &os; supports System V-style IPC, including shared
	memory, messages and semaphores, in the
	- <filename>GENERIC</filename> kernel. In a custom kernel,
	- enable this support by adding the following lines to your
	- kernel config.</para>
	+ <filename>GENERIC</filename> kernel. With a custom kernel,
	+ support may be loaded with the <filename>sysvshm.ko</filename>,
	+ <filename>sysvsem.ko</filename> and <filename>
	+ sysvmsg.ko</filename> kernel modules, or
	+ enabled in the custom kernel by adding the following lines to your
	+ kernel config:</para>

	<programlisting>options SYSVSHM # enable shared memory
	options SYSVSEM # enable for semaphores
	options SYSVMSG # enable for messaging</programlisting>

	<para>Recompile and install your kernel.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="sendmail-alternative">
	<para>What other mail-server software can I use instead of
	<application>sendmail</application>?</para>
	</question>

	<answer>
	<para>The <ulink
	url="http://www.sendmail.org/"><application>sendmail</application></ulink>
	server is the default mail-server software for &os;, but you
	can easily replace it with one of the other MTA (for
	instance, an MTA installed from the ports).</para>

	<para>There are various alternative MTAs in the ports tree
	already, with <filename role="package">mail/exim</filename>,
	<filename role="package">mail/postfix</filename>, <filename
	role="package">mail/qmail</filename>, and <filename
	role="package">mail/zmailer</filename> being some of the
	most popular choices.</para>

	<para>Diversity is nice, and the fact that you have many
	different mail-servers to chose from is considered a good
	thing; therefore try to avoid asking questions like
	<quote>Is <application>sendmail</application> better than
	- <application>qmail</application>?</quote> in the mailing
	+ <application>qmail</application>?</quote> in the mailing
	lists. If you do feel like asking, first check the mailing
	list archives. The advantages and disadvantages of each and
	every one of the available MTAs have already been discussed
	a few times.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="forgot-root-pw">
	<para>I have forgotten the <username>root</username> password!
	What do I do?</para>
	</question>

	<answer>
	<para>Do not panic! Restart the system, type
	<userinput>boot -s</userinput> at the
	<literal>Boot:</literal> prompt to enter Single User mode.
	At the question about the shell to use, hit
	<keycap>Enter</keycap>. You will be dropped to a
	&prompt.root; prompt. Enter <command>mount -urw /</command>
	to remount your root file system read/write, then run
	<command>mount -a</command> to remount all the file systems.
	Run <command>passwd root</command> to change the
	<username>root</username> password then run &man.exit.1; to
	continue booting.</para>

	<note>
	<para>If you are still prompted to give the
	<username>root</username> password when entering the
	Single User mode, it means that the console has been
	marked as <literal>insecure</literal> in
	<filename>/etc/ttys</filename>. In this case it will be
	required to boot from a &os; installation disk, choose
	the <guimenuitem>Live CD</guimenuitem> or
	<guimenuitem>Shell</guimenuitem> at the beginning of the install
	process and issue the commands mentioned above. You will need to
	mount the specific partition in this case and then chroot to it,
	i.e., replace <command>mount -urw /</command> by
	<command>mount /dev/ada0p1 /mnt; chroot /mnt</command> for
	a system on <replaceable>ada0p1</replaceable>.</para>
	</note>

	<note>
	<para>If you cannot mount your root partition from Single
	User mode, it is possible that the partitions are
	encrypted and it is impossible to mount them without the
	access keys. Your chances depend on the chosen
	implementation. For more information see the section
	about encrypted disks in the &os; <ulink
	url="&url.books.handbook;/disks-encrypting.html">Handbook</ulink>.</para>
	</note>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="CAD-reboot">
	<para>How do I keep <keycombo
	action="simul"><keycap>Control</keycap><keycap>Alt</keycap><keycap>Delete</keycap></keycombo>
	from rebooting the system?</para>
	</question>

	<answer>
	<para>If you are using &man.syscons.4; (the default console
	driver) build and install a new kernel with the line in the
	configuration file:</para>

	<programlisting>options SC_DISABLE_REBOOT</programlisting>

	<para>This can also be done by setting the following
	&man.sysctl.8; which does not require a reboot or kernel
	recompile:</para>

	<screen>&prompt.root; <userinput>sysctl hw.syscons.kbd_reboot=0</userinput></screen>

	<note>
	<para>The above two methods are exclusive: The &man.sysctl.8;
	does not exist if you compile your kernel with the
	<literal>SC_DISABLE_REBOOT</literal> option.</para>
	</note>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="dos-to-unix-txt">
	<para>How do I reformat DOS text files to &unix; ones?</para>
	</question>

	<answer>
	<para>Use this &man.perl.1; command:</para>

	<screen>&prompt.user; <userinput>perl -i.bak -npe 's/\r\n/\n/g' <replaceable>file(s)</replaceable></userinput></screen>

	<para>where <replaceable>file(s)</replaceable> is one or more
	files to process. The modification is done in-place, with the
	original file stored with a <filename>.bak</filename>
	extension.</para>

	<para>Alternatively you can use the &man.tr.1; command:</para>

	<screen>&prompt.user; <userinput>tr -d '\r' < <replaceable>dos-text-file</replaceable> > <replaceable>unix-file</replaceable></userinput></screen>

	<para><replaceable>dos-text-file</replaceable> is the file
	containing DOS text while
	<replaceable>unix-file</replaceable> will contain the
	converted output. This can be quite a bit faster than using
	<command>perl</command>.</para>

	<para>Yet another way to reformat DOS text files is to use the
	<filename role="package">converters/dosunix</filename> port
	from the Ports Collection. Consult its documentation about
	the details.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="kill-by-name">
	<para>How do I kill processes by name?</para>
	</question>

	<answer>
	<para>Use &man.pkill.1;.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	- <question id="uninstall-kerberos">
	- <para>How do I uninstall
	- <application>Kerberos</application>?</para>
	- </question>
	-
	- <answer>
	- <para>To remove <application>Kerberos</application> from the
	- system, reinstall the <literal>base</literal> distribution
	- for the release you are running. If you have the CD-ROM,
	- you can mount it (we will assume on <filename
	- class="directory">/cdrom</filename>) and run the commands
	- below:</para>
	-
	- <screen>&prompt.root; <userinput>cd /cdrom/base</userinput>
	-&prompt.root; <userinput>./install.sh</userinput></screen>
	-
	- <para>Alternately, you can include the
	- <makevar>NO_KERBEROS</makevar> option in your
	- <filename>/etc/make.conf</filename> and rebuild
	- world.</para>
	- </answer>
	- </qandaentry>
	- <qandaentry>
	- <question id="add-pty">
	- <para>How do I add pseudoterminals to the system?</para>
	- </question>
	-
	- <answer>
	- <para>If you have a lot of <command>telnet</command>,
	- <command>ssh</command>, X, or <command>screen</command>
	- users, you might run out of pseudoterminals. By default,
	- &os; supports 512 pseudoterminals.</para>
	- </answer>
	- </qandaentry>
	-
	- <qandaentry>
	<question id="reread-rc">
	<para>How do I re-read <filename>/etc/rc.conf</filename> and
	re-start <filename>/etc/rc</filename> without a
	reboot?</para>
	</question>

	<answer>
	<para>Go into single user mode and then back to multi user
	mode.</para>

	<para>On the console do:</para>

	<screen>&prompt.root; <userinput>shutdown now</userinput>
	(Note: without -r or -h)

	&prompt.root; <userinput>return</userinput>
	&prompt.root; <userinput>exit</userinput></screen>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="release-candidate">
	<para>I tried to update my system to the latest
	<emphasis>-STABLE</emphasis>, but got
	<emphasis>-BETA<replaceable>x</replaceable></emphasis>,
	<emphasis>-RC</emphasis> or
	<emphasis>-PRERELEASE</emphasis>! What is going on?</para>
	</question>

	<answer>
	<para>Short answer: it is just a name.
	<emphasis>RC</emphasis> stands for <quote>Release
	- Candidate</quote>. It signifies that a release is imminent.
	+ Candidate</quote>. It signifies that a release is imminent.
	In &os;, <emphasis>-PRERELEASE</emphasis> is typically
	synonymous with the code freeze before a release. (For some
	releases, the <emphasis>-BETA</emphasis> label was used in
	the same way as <emphasis>-PRERELEASE</emphasis>.)</para>

	<para>Long answer: &os; derives its releases from one of two
	- places. Major, dot-zero, releases, such as 7.0-RELEASE and
	- 8.0-RELEASE, are branched from the head of the development
	+ places. Major, dot-zero, releases, such as 9.0-RELEASE
	+ are branched from the head of the development
	stream, commonly referred to as <link
	- linkend="current">-CURRENT</link>. Minor releases, such as
	+ linkend="current">-CURRENT</link>. Minor releases, such as
	6.3-RELEASE or 5.2-RELEASE, have been snapshots of the
	active <link linkend="stable">-STABLE</link> branch.
	Starting with 4.3-RELEASE, each release also now has its own
	branch which can be tracked by people requiring an extremely
	conservative rate of development (typically only security
	advisories).</para>

	<para>When a release is about to be made, the branch from
	which it will be derived from has to undergo a certain
	process. Part of this process is a code freeze. When a
	code freeze is initiated, the name of the branch is changed
	to reflect that it is about to become a release. For
	example, if the branch used to be called 6.2-STABLE, its
	name will be changed to 6.3-PRERELEASE to signify the code
	freeze and signify that extra pre-release testing should be
	happening. Bug fixes can still be committed to be part of
	the release. When the source code is in shape for the
	release the name will be changed to 6.3-RC to signify that a
	release is about to be made from it. Once in the RC stage,
	only the most critical bugs found can be fixed. Once the
	release (6.3-RELEASE in this example) and release branch
	have been made, the branch will be renamed to
	6.3-STABLE.</para>

	<para>For more information on version numbers and the various
	Subversion branches, refer to the <ulink
	url="&url.articles.releng;/article.html">Release Engineering</ulink>
	article.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="kernel-chflag-failure">
	<para>I tried to install a new kernel, and the &man.chflags.1;
	failed. How do I get around this?</para>
	</question>

	<answer>
	<para>Short answer: You are probably at security level greater
	than 0. Reboot directly to Single User mode to install the
	kernel.</para>

	<para>Long answer: &os; disallows changing system flags at
	security levels greater than 0. You can check your security
	level with the command:</para>

	<screen>&prompt.root; <userinput>sysctl kern.securelevel</userinput></screen>

	<para>You cannot lower the security level; you have to boot to
	Single Mode to install the kernel, or change the security
	level in <filename>/etc/rc.conf</filename> then reboot. See
	the &man.init.8; manual page for details on
	<literal>securelevel</literal>, and see
	<filename>/etc/defaults/rc.conf</filename> and the
	&man.rc.conf.5; manual page for more information on
	<filename>rc.conf</filename>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="kernel-securelevel-time">
	<para>I cannot change the time on my system by more than one
	second! How do I get around this?</para>
	</question>

	<answer>
	<para>Short answer: You are probably at security level greater
	than 1. Reboot directly to Single User mode to change the
	date.</para>

	<para>Long answer: &os; disallows changing the time by more
	that one second at security levels greater than 1. You can
	check your security level with the command:</para>

	<screen>&prompt.root; <userinput>sysctl kern.securelevel</userinput></screen>

	<para>You cannot lower the security level; you have to boot to
	Single User mode to change the date, or change the security
	level in <filename>/etc/rc.conf</filename> then reboot. See
	the &man.init.8; manual page for details on
	<literal>securelevel</literal>, and see
	<filename>/etc/defaults/rc.conf</filename> and the
	&man.rc.conf.5; manual page for more information on
	<filename>rc.conf</filename>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="statd-mem-leak">
	<para>Why is <command>rpc.statd</command> using 256 MB of
	memory?</para>
	</question>

	<answer>
	<para>No, there is no memory leak, and it is not using
	256 MB of memory. For convenience,
	<command>rpc.statd</command> maps an obscene amount of
	memory into its address space. There is nothing terribly
	wrong with this from a technical standpoint; it just throws
	off things like &man.top.1; and &man.ps.1;.</para>

	<para>&man.rpc.statd.8; maps its status file (resident on
	<filename class="directory">/var</filename>) into its address space; to save
	worrying about remapping it later when it needs to grow, it
	maps it with a generous size. This is very evident from the
	source code, where one can see that the length argument to
	&man.mmap.2; is <literal>0x10000000</literal>, or one
	sixteenth of the address space on an IA32, or exactly
	256 MB.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="unsetting-schg">
	<para>Why can I not unset the <literal>schg</literal> file
	flag?</para>
	</question>

	<answer>
	<para>You are running at an elevated (i.e., greater than 0)
	securelevel. Lower the securelevel and try again. For more
	information, see <link linkend="securelevel">the FAQ entry
	- on securelevel</link> and the &man.init.8; manual
	+ on securelevel</link> and the &man.init.8; manual
	page.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ssh-shosts">
	<para>Why does <application>SSH</application> authentication
	through <filename>.shosts</filename> not work by default in
	recent versions of &os;?</para>
	</question>

	<answer>
	<para>The reason why <filename>.shosts</filename>
	authentication does not work by default in more recent
	versions of &os; is because &man.ssh.1; is not installed
	suid <username>root</username> by default. To
	<quote>fix</quote> this, you can do one of the
	following:</para>

	<itemizedlist>
	<listitem>
	<para>As a permanent fix, set
	<makevar>ENABLE_SUID_SSH</makevar> to
	<literal>true</literal> in
	<filename>/etc/make.conf</filename> then rebuild and
	reinstall &man.ssh.1;.</para>
	</listitem>

	<listitem>
	<para>As a temporary fix, change the mode on
	<filename>/usr/bin/ssh</filename> to
	<literal>4555</literal> by running
	<command>chmod 4555 /usr/bin/ssh</command> as
	<username>root</username>.</para>
	</listitem>
	</itemizedlist>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="vnlru">
	<para>What is <literal>vnlru</literal>?</para>
	</question>

	<answer>
	<para><literal>vnlru</literal> flushes and frees vnodes when
	the system hits the <varname>kern.maxvnodes</varname> limit.
	This kernel thread sits mostly idle, and only activates if
	you have a huge amount of RAM and are accessing tens of
	thousands of tiny files.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="top-memory-states">
	<para>What do the various memory states displayed by
	<command>top</command> mean?</para>
	</question>

	-<!-- Provided by John Dyson via Usenet -->
	+ <!-- Provided by John Dyson via Usenet -->
	<answer>
	<itemizedlist>
	<listitem>
	<para><literal>Active</literal>: pages recently
	statistically used.</para>
	</listitem>

	<listitem>
	<para><literal>Inactive</literal>: pages recently
	statistically unused.</para>
	</listitem>

	<listitem>
	<para><literal>Cache</literal>: (most often) pages that
	have percolated from inactive to a status where they
	maintain their data, but can often be immediately reused
	(either with their old association, or reused with a new
	association). There can be certain immediate transitions
	from <literal>active</literal> to
	<literal>cache</literal> state if the page is known to
	be clean (unmodified), but that transition is a matter
	of policy, depending upon the algorithm choice of the VM
	system maintainer.</para>
	</listitem>

	<listitem>
	<para><literal>Free</literal>: pages without data content,
	and can be immediately used in certain circumstances
	where cache pages might be ineligible. Free pages can
	be reused at interrupt or process
	state.</para>
	</listitem>

	<listitem>
	<para><literal>Wired</literal>: pages that are fixed into
	memory, usually for kernel purposes, but also sometimes
	for special use in processes.</para>
	</listitem>
	</itemizedlist>

	<para>Pages are most often written to disk (sort of a VM sync)
	when they are in the inactive state, but active pages can
	also be synced. This depends upon the CPU tracking of the
	modified bit being available, and in certain situations
	there can be an advantage for a block of VM pages to be
	synced, whether they are active or inactive. In most common
	cases, it is best to think of the inactive queue to be a
	queue of relatively unused pages that might or might not be
	in the process of being written to disk. Cached pages are
	already synced, not mapped, but available for immediate
	process use with their old association or with a new
	association. Free pages are available at interrupt level,
	but cached or free pages can be used at process state for
	reuse. Cache pages are not adequately locked to be
	available at interrupt level.</para>

	<para>There are some other flags (e.g., busy flag or busy
	count) that might modify some of the described rules.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="free-memory-amount">
	<para>How much free memory is available?</para>
	</question>

	-<!-- Provided by John Dyson via Usenet -->
	+ <!-- Provided by John Dyson via Usenet -->
	<answer>
	<para>There are a couple of kinds of <quote>free
	- memory</quote>. One kind is the amount of memory
	+ memory</quote>. One kind is the amount of memory
	immediately available without paging anything else out.
	That is approximately the size of cache queue + size of free
	queue (with a derating factor, depending upon system
	tuning). Another kind of <quote>free memory</quote> is the
	total amount of <acronym>VM</acronym> space. That can be
	complex, but is dependent upon the amount of swap space and
	memory. Other kinds of <quote>free memory</quote>
	descriptions are also possible, but it is relatively useless
	to define these, but rather it is important to make sure
	that the paging rate is kept low, and to avoid running out
	of swap space.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="var-empty">
	<para>What is <filename class="directory">/var/empty</filename>? I can not
	delete it!</para>
	</question>

	<answer>
	<para><filename class="directory">/var/empty</filename> is a directory that the
	&man.sshd.8; program uses when performing privilege separation.
	The <filename class="directory">/var/empty</filename> directory is empty, owned by
	<username>root</username> and has the <literal>schg</literal>
	flag set.</para>

	<para>Although it is not recommended to delete this directory, to
	do so you will need to unset the <literal>schg</literal> flag
	first. See the &man.chflags.1; manual page for more information
	(and bear in mind the answer to
	<link linkend="unsetting-schg">the question on unsetting the schg flag</link>).</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="newsyslog-expectations">
	<para>I just changed
	<filename>/etc/newsyslog.conf</filename>. How can I check
	- if it does what I expect?</para>
	+ if it does what I expect?</para>
	</question>

	<answer>
	<para>To see what &man.newsyslog.8; will do use the
	following:</para>

	<screen>&prompt.user; <userinput>newsyslog -nrvv</userinput></screen>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="timezone">
	<para>My time is wrong, how can I change the
	timezone?</para>
	</question>

	<answer>
	<para>Use &man.tzsetup.8;.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="x">
	<title>The X Window System and Virtual Consoles</title>

	<qandaset>
	<qandaentry>
	<question id="whatis-X">
	<para>What is the X Window System?</para>
	</question>

	<answer>
	<para>The X Window System (commonly <literal>X11</literal>) is
	the most widely available windowing system capable of running
	on &unix; or &unix; like systems, including &os;.
	<ulink url= "http://www.x.org/wiki/">The X.Org Foundation</ulink>
	administers the <ulink
	url="http://en.wikipedia.org/wiki/X_Window_System_core_protocol">X protocol standards</ulink>,
	with the current reference implementation, version 11
	release &xorg.version;, so you will often see references
	shortened to <literal>X11</literal>.</para>

	<para>Many implementations are available for different
	architectures and operating systems. An implementation of
	the server-side code is properly known as an <literal>X
	- server</literal>.</para>
	+ server</literal>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="running-X">
	<para>I want to run &xorg;, how do I go about it?</para>
	</question>

	<answer>
	<para>To install &xorg; do one of the following:</para>

	<para>Use the <filename role="package">x11/xorg</filename>
	meta-port, which builds and installs every &xorg;
	component.</para>

	<para>Use <filename
	role="package">x11/xorg-minimal</filename>, which builds
	and installs only the necessary &xorg; components.</para>

	<para>Install &xorg; from &os; packages:</para>

	<screen><userinput>&prompt.root; pkg_add -r xorg</userinput></screen>

	<para>or on systems using <application>pkg</application>:</para>

	<screen><userinput>&prompt.root; pkg install xorg</userinput></screen>

	<para>After the installation of &xorg;, follow
	the instructions from the <ulink
	url="&url.books.handbook;/x-config.html">X11 Configuration</ulink> section of
	the &os; Handbook.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="running-X-securelevels">
	<para>I <emphasis>tried</emphasis> to run X, but I get a
	<errorname>No devices detected.</errorname> error when I
	type
	<command>startx</command>. What do I do now?</para>
	</question>

	<answer>
	<para>Your system is probably running at a raised
	<literal>securelevel</literal>. It is not possible to start X
	at a raised <literal>securelevel</literal> because X
	requires write access to &man.io.4;. For more information,
	see at the &man.init.8; manual page.</para>

	<para>There are two solutions to the problem:
	Set your
	<literal>securelevel</literal> back down to zero (usually
	in <filename>/etc/rc.conf</filename>), or run &man.xdm.1;
	(or an alternative display manager)
	at boot time (before the <literal>securelevel</literal> is
	raised).</para>

	<para>See <xref linkend="xdm-boot"/> for more information about
	running &man.xdm.1; at boot time.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="x-and-moused">
	<para>Why does my mouse not work with X?</para>
	</question>

	<answer>
	<para>If you are using &man.syscons.4; (the default console
	driver), you can configure &os; to support a mouse pointer on
	each virtual screen. To avoid conflicting with X,
	&man.syscons.4; supports a virtual device called
	<devicename>/dev/sysmouse</devicename>. All mouse events
	received from the real mouse device are written to the
	&man.sysmouse.4; device via &man.moused.8;. To use your
	mouse on one or more virtual consoles,
	<emphasis>and</emphasis> use X, see <xref
	linkend="moused" remap="another section"/> and set up
	&man.moused.8;.</para>

	<para>Then edit <filename>/etc/X11/xorg.conf</filename> and
	make sure you have the following lines:</para>

	<programlisting>Section "InputDevice"
	Option "Protocol" "SysMouse"
	Option "Device" "/dev/sysmouse"
	.....</programlisting>

	<para>Starting with &xorg; version 7.4, the
	<literal>InputDevice</literal> sections in
	<filename>xorg.conf</filename> are ignored in favor of
	autodetected devices. To restore the old behavior, add the
	following line to the <literal>ServerLayout</literal> or
	<literal>ServerFlags</literal> section:</para>

	<programlisting>Option "AutoAddDevices" "false"</programlisting>

	<para>Some people prefer to use
	<devicename>/dev/mouse</devicename> under X. To make this
	work, <devicename>/dev/mouse</devicename> should be linked
	to <devicename>/dev/sysmouse</devicename> (see
	&man.sysmouse.4;) by adding the following line to
	<filename>/etc/devfs.conf</filename> (see
	&man.devfs.conf.5;):</para>

	<programlisting>link sysmouse mouse</programlisting>

	<para>This link can be created by restarting &man.devfs.5;
	with the following command (as
	<username>root</username>):</para>

	<screen>&prompt.root; <userinput>service devfs restart</userinput></screen>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="x-and-wheel">
	<para>My mouse has a fancy wheel. Can I use it in X?</para>
	</question>

	<answer>
	<para>Yes.</para>

	<para>You need to tell X that you have a 5 button mouse. To
	do this, simply add the lines <literal>Buttons 5</literal>
	and <literal>ZAxisMapping 4 5</literal> to the
	<quote>InputDevice</quote> section of
	<filename>/etc/X11/xorg.conf</filename>. For example, you
	might have the following <quote>InputDevice</quote> section
	in <filename>/etc/X11/xorg.conf</filename>.</para>

	<example>
	<title><quote>InputDevice</quote> Section for Wheeled Mouse
	in &xorg; Configuration File</title>

	<programlisting>Section "InputDevice"
	Identifier "Mouse1"
	Driver "mouse"
	Option "Protocol" "auto"
	Option "Device" "/dev/sysmouse"
	Option "Buttons" "5"
	Option "ZAxisMapping" "4 5"
	EndSection</programlisting>
	</example>

	<example>
	<title><quote>.emacs</quote> Example for Naive Page
	Scrolling with Wheeled Mouse (optional)</title>

	<programlisting>;; wheel mouse
	(global-set-key [mouse-4] 'scroll-down)
	(global-set-key [mouse-5] 'scroll-up)</programlisting>
	</example>
	</answer>
	</qandaentry>

	- <qandaentry>
	+ <qandaentry>
	<question id="x-and-synaptic">
	<para>My laptop has a Synaptics touchpad. Can I use
	it in X?</para>
	</question>

	<answer>
	<para>Yes, you will have to configure a few things to
	make it work.</para>

	<para>If you plan to use the Xorg synaptics driver you
	<emphasis>must</emphasis> remove moused_enable from
	<filename>rc.conf</filename>. Xorg can not use
	the synaptics mouse if the moused already sits on
	<filename>/dev/psm0</filename>.</para>

	<para>To enable synaptics in the &man.psm.4; driver you need
	to add the following into
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>hw.psm.synaptics_support="1"</programlisting>

	<para>You also need the following into
	<filename>xorg.conf</filename>:</para>

	<programlisting>Section "InputDevice"
	Identifier "Touchpad0"
	Driver "synaptics"
	Option "Protocol" "psm"
	Option "Device" "/dev/psm0"
	EndSection</programlisting>

	<para>And be sure to add the following into the
	<quote>ServerLayout</quote> section:</para>

	<programlisting>InputDevice "Touchpad0" "SendCoreEvents"</programlisting>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="no-remote-x11">
	<para>How do I use remote X displays?</para>
	</question>

	<answer>
	<para>For security reasons, the default setting is to not
	allow a machine to remotely open a window.</para>

	<para>To enable this feature, simply start
	<application>X</application> with the optional
	<option>-listen_tcp</option> argument:</para>

	<screen>&prompt.user; <userinput>startx -listen_tcp</userinput></screen>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="virtual-console">
	<para>What is a virtual console and how do I make more?</para>
	</question>

	<answer>
	<para>Virtual consoles, put simply, enable you to have several
	simultaneous sessions on the same machine without doing
	anything complicated like setting up a network or running
	X.</para>

	<para>When the system starts, it will display a login prompt
	on the monitor after displaying all the boot messages. You
	can then type in your login name and password and start
	working (or playing!) on the first virtual console.</para>

	<para>At some point, you will probably wish to start another
	session, perhaps to look at documentation for a program you
	are running or to read your mail while waiting for an FTP
	transfer to finish. Just do <keycombo
	action="simul"><keycap>Alt</keycap><keycap>F2</keycap></keycombo>
	(hold down <keycap>Alt</keycap> and press
	<keycap>F2</keycap>), and you will find a login prompt
	waiting for you on the second <quote>virtual
	- console</quote>! When you want to go back to the original
	+ console</quote>! When you want to go back to the original
	session, do <keycombo
	action="simul"><keycap>Alt</keycap><keycap>F1</keycap></keycombo>.</para>

	<para>The default &os; installation has eight virtual consoles
	enabled. <keycombo
	action="simul"><keycap>Alt</keycap><keycap>F1</keycap></keycombo>,
	<keycombo
	action="simul"><keycap>Alt</keycap><keycap>F2</keycap></keycombo>,
	<keycombo
	action="simul"><keycap>Alt</keycap><keycap>F3</keycap></keycombo>,
	and so on will switch between these virtual consoles.</para>

	<para>To enable more of them, edit
	<filename>/etc/ttys</filename> (see &man.ttys.5;) and add
	entries for <devicename>ttyv8</devicename> to
	<devicename>ttyvc</devicename> after the comment on
	<quote>Virtual terminals</quote>:</para>

	<programlisting># Edit the existing entry for ttyv8 in /etc/ttys and change
	# "off" to "on".
	-ttyv8 "/usr/libexec/getty Pc" cons25 on secure
	-ttyv9 "/usr/libexec/getty Pc" cons25 on secure
	-ttyva "/usr/libexec/getty Pc" cons25 on secure
	-ttyvb "/usr/libexec/getty Pc" cons25 on secure</programlisting>
	+ttyv8 "/usr/libexec/getty Pc" xterm on secure
	+ttyv9 "/usr/libexec/getty Pc" xterm on secure
	+ttyva "/usr/libexec/getty Pc" xterm on secure
	+ttyvb "/usr/libexec/getty Pc" xterm on secure</programlisting>

	<para>Use as many or as few as you want. The more virtual
	terminals you have, the more resources that are used; this
	can be important if you have 8 MB RAM or less. You may
	also want to change the <literal>secure</literal> to
	<literal>insecure</literal>.</para>

	+ <note>
	+ <para>Versions of &os; prior to 9.0 used the <quote>
	+ cons25</quote> terminal type, and not <quote>
	+ xterm</quote>. Existing entries in
	+ <filename>/etc/ttys</filename> can be used on which to
	+ base new additions.</para>
	+ </note>
	+
	<important>
	<para>If you want to run an X server you
	<emphasis>must</emphasis> leave at least one virtual
	terminal unused (or turned off) for it to use. That is to
	say that if you want to have a login prompt pop up for all
	twelve of your Alt-function keys, you are out of luck
	— you can only do this for eleven of them if you
	also want to run an X server on the same machine.</para>
	</important>

	<para>The easiest way to disable a console is by turning it
	off. For example, if you had the full 12 terminal
	allocation mentioned above and you wanted to run X, you
	would change settings for virtual terminal 12 from:</para>

	- <programlisting>ttyvb "/usr/libexec/getty Pc" cons25 on secure</programlisting>
	+ <programlisting>ttyvb "/usr/libexec/getty Pc" xterm on secure</programlisting>

	<para>to:</para>

	- <programlisting>ttyvb "/usr/libexec/getty Pc" cons25 off secure</programlisting>
	+ <programlisting>ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting>

	<para>If your keyboard has only ten function keys, you would
	end up with:</para>

	- <programlisting>ttyv9 "/usr/libexec/getty Pc" cons25 off secure
	-ttyva "/usr/libexec/getty Pc" cons25 off secure
	-ttyvb "/usr/libexec/getty Pc" cons25 off secure</programlisting>
	+ <programlisting>ttyv9 "/usr/libexec/getty Pc" xterm off secure
	+ttyva "/usr/libexec/getty Pc" xterm off secure
	+ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting>

	<para>(You could also just delete these lines.)</para>

	<para>Next, the easiest (and cleanest) way to activate the
	virtual consoles is to reboot. However, if you really do
	not want to reboot, you can just shut down the X Window
	system and execute (as <username>root</username>):</para>

	<screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen>

	<para>It is imperative that you completely shut down X Window
	if it is running, before running this command. If you do not,
	your system will probably appear to hang or lock up after
	executing <command>kill</command>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="vty-from-x">
	<para>How do I access the virtual consoles from X?</para>
	</question>

	<answer>
	<para>Use <keycombo
	action="simul"><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F<replaceable>n</replaceable></keycap></keycombo>
	to switch back to a virtual console. <keycombo
	action="simul"><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F1</keycap></keycombo>
	would return you to the first virtual console.</para>

	<para>Once you are back to a text console, you can then use
	<keycombo
	action="simul"><keycap>Alt</keycap><keycap>F<replaceable>n</replaceable></keycap></keycombo>
	as normal to move between them.</para>

	<para>To return to the X session, you must switch to the
	virtual console running X. If you invoked X from the
	command line, (e.g., using <command>startx</command>) then
	the X session will attach to the next unused virtual
	console, not the text console from which it was invoked. If
	you have eight active virtual terminals then X will be
	running on the ninth, and you would use <keycombo
	action="simul"><keycap>Alt</keycap><keycap>F9</keycap></keycombo>
	to return.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="xdm-boot">
	<para>How do I start <application>XDM</application> on
	boot?</para>
	</question>

	<answer>
	<para>There are two schools of thought on how to start
	&man.xdm.1;. One school starts <command>xdm</command> from
	<filename>/etc/ttys</filename> (see &man.ttys.5;) using the
	supplied example, while the other simply runs
	<command>xdm</command> from
	<filename>rc.local</filename> (see &man.rc.8;) or from an
	<filename>X</filename> script in
	<filename class="directory">/usr/local/etc/rc.d</filename>. Both are equally
	valid, and one may work in situations where the other does
	not. In both cases the result is the same: X will pop up a
	graphical login prompt.</para>

	<para>The &man.ttys.5; method has the advantage of documenting
	which vty X will start on and passing the responsibility of
	restarting the X server on logout to &man.init.8;. The
	&man.rc.8; method makes it easy to <command>kill</command>
	<command>xdm</command> if there is a problem starting the X
	server.</para>

	<para>If loaded from &man.rc.8;, <command>xdm</command> should
	be started without any arguments (i.e., as a daemon).
	<command>xdm</command> must start
	<emphasis>after</emphasis> &man.getty.8; runs, or else
	<command>getty</command> and <command>xdm</command> will
	conflict, locking out the console. The best way around this
	is to have the script sleep 10 seconds or so then launch
	<command>xdm</command>.</para>

	<para>If you are to start <command>xdm</command> from
	<filename>/etc/ttys</filename>, there still is a chance of
	conflict between <command>xdm</command> and &man.getty.8;.
	One way to avoid this is to add the <literal>vt</literal>
	number in
	<filename>/usr/local/lib/X11/xdm/Xservers</filename></para>

	<programlisting>:0 local /usr/local/bin/X vt4</programlisting>

	<para>The above example will direct the X server to run in
	<devicename>/dev/ttyv3</devicename>. Note the number is
	offset by one. The X server counts the vty from one,
	whereas the &os; kernel numbers the vty from zero.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="xconsole-failure">
	<para>Why do I get <errorname>Couldn't open
	- console</errorname> when I run
	+ console</errorname> when I run
	<command>xconsole</command>?</para>
	</question>

	<answer>
	<para>If you start <application>X</application> with
	<command>startx</command>, the permissions on
	<devicename>/dev/console</devicename> will
	<emphasis>not</emphasis> get changed, resulting in things
	like <command>xterm -C</command> and
	<command>xconsole</command> not working.</para>

	<para>This is because of the way console permissions are set
	by default. On a multi-user system, one does not
	necessarily want just any user to be able to write on the
	system console. For users who are logging directly onto a
	machine with a VTY, the &man.fbtab.5; file exists to solve
	such problems.</para>

	<para>In a nutshell, make sure an uncommented line of the form
	is in <filename>/etc/fbtab</filename> (see
	&man.fbtab.5;):</para>

	<programlisting>/dev/ttyv0 0600 /dev/console</programlisting>

	<para>It will ensure that whomever logs in on
	<devicename>/dev/ttyv0</devicename> will own the
	console.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ps2-x">
	<para>Why does my PS/2 mouse misbehave under X?</para>
	</question>

	<answer>
	<para>Your mouse and the mouse driver may have somewhat become
	out of synchronization.</para>

	<para> In rare cases the driver may erroneously report
	synchronization problem and you may see the kernel
	message:</para>

	<programlisting>psmintr: out of sync (xxxx != yyyy)</programlisting>

	<para>and notice that your mouse does not work
	properly.</para>

	<para>If this happens, disable the synchronization check code
	by setting the driver flags for the PS/2 mouse driver to
	- <literal>0x100</literal>. Enter
	- <emphasis>UserConfig</emphasis> by giving the
	- <option>-c</option> option at the boot prompt:</para>
	+ <literal>0x100</literal>. This can be easiest achieved
	+ by adding

	- <screen>boot: <userinput>-c</userinput></screen>
	+ <screen>hint.psm.0.flags="0x100"</screen>

	- <para>Then, in the <emphasis>UserConfig</emphasis> command
	- line, type:</para>
	-
	- <screen>UserConfig> <userinput>flags psm0 0x100</userinput>
	-UserConfig> <userinput>quit</userinput></screen>
	+ to
	+ <filename>/boot/loader.conf</filename> and rebooting.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="mouse-button-reverse">
	<para>How do I reverse the mouse buttons?</para>
	</question>

	<answer>
	<para>Run the command <command>xmodmap -e "pointer = 3 2 1"</command>
	from <filename>.xinitrc</filename> or
	<filename>.xsession</filename>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="install-splash">
	<para>How do I install a splash screen and where do I find
	them?</para>
	</question>

	<answer>
	<para>The detailed answer for this question can be found in
	the <ulink
	url="&url.books.handbook;/boot-blocks.html#boot-splash">Boot Time Splash Screens</ulink>
	section of the &os; Handbook.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="windows-keys">
	<para>Can I use the <keycap>Windows</keycap> keys on my
	keyboard in X?</para>
	</question>

	<answer>
	<para>Yes. All you need to do is use &man.xmodmap.1; to
	define what function you wish them to perform.</para>

	<para>Assuming all <quote>Windows</quote> keyboards are
	standard then the keycodes for these three keys are the
	following:</para>

	<itemizedlist>
	<listitem>
	<para><keycode>115</keycode> —
	<keycap>Windows</keycap> key, between the left-hand
	<keycap>Ctrl</keycap> and <keycap>Alt</keycap>
	keys</para>
	</listitem>

	<listitem>
	<para><keycode>116</keycode> —
	<keycap>Windows</keycap> key, to the right of
	<keycap>AltGr</keycap></para>
	</listitem>

	<listitem>
	<para><keycode>117</keycode> — <keycap>Menu</keycap>,
	to the left of the right-hand <keycap>Ctrl</keycap></para>
	</listitem>
	</itemizedlist>

	<para>To have the left <keycap>Windows</keycap> key print a
	comma, try this.</para>

	<screen>&prompt.root; <userinput>xmodmap -e "keycode 115 = comma"</userinput></screen>

	<para>To have the <keycap>Windows</keycap> key-mappings
	enabled automatically every time you start X either put the
	<command>xmodmap</command> commands in
	<filename>~/.xinitrc</filename> or, preferably, create
	a <filename>~/.xmodmaprc</filename> and include the
	<command>xmodmap</command> options, one per line, then add
	the following line to
	<filename>~/.xinitrc</filename>:</para>

	<programlisting>xmodmap $HOME/.xmodmaprc</programlisting>

	<para>For example, you could map the 3 keys to be
	<keycap>F13</keycap>, <keycap>F14</keycap>, and
	<keycap>F15</keycap>, respectively. This would make it easy
	to map them to useful functions within applications or your
	window manager, as demonstrated further down.</para>

	<para>To do this put the following in
	<filename>~/.xmodmaprc</filename>.</para>

	<programlisting>keycode 115 = F13
	keycode 116 = F14
	keycode 117 = F15</programlisting>

	<para>If you use the <filename
	role="package">x11-wm/fvwm2</filename> port, for example,
	you could map the keys so that <keycap>F13</keycap>
	iconifies (or de-iconifies) the window the cursor is in,
	<keycap>F14</keycap> brings the window the cursor is in to
	the front or, if it is already at the front, pushes it to
	the back, and <keycap>F15</keycap> pops up the main
	Workplace (application) menu even if the cursor is not on
	the desktop, which is useful if you do not have any part of
	the desktop visible (and the logo on the key matches its
	functionality).</para>

	<para>The following entries in <filename>~/.fvwmrc</filename>
	implement the aforementioned setup:</para>

	<programlisting>Key F13 FTIWS A Iconify
	Key F14 FTIWS A RaiseLower
	Key F15 A A Menu Workplace Nop</programlisting>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="x-3d-acceleration">
	<para>How can I get 3D hardware acceleration for
	&opengl;?</para>
	</question>

	<answer>
	<para>The availability of 3D acceleration depends on the
	version of &xorg; that you are using and the type of video
	chip you have. If you have an nVidia chip, you can use the
	binary drivers provided for &os; by installing one of the
	following ports:</para>

	<itemizedlist>
	<listitem>
	<para>The latest versions of nVidia cards are supported by
	the <filename role="package">x11/nvidia-driver</filename>
	port.</para>
	</listitem>

	<listitem>
	<para>nVidia cards like the GeForce2 MX/3/4 series
	are supported by the 96XX series of drivers, available
	in the <filename
	role="package">x11/nvidia-driver-96xx</filename>
	port.</para>
	</listitem>

	<listitem>
	<para>Even older cards, like GeForce and RIVA TNT are
	supported by the 71XX series of drivers, available in
	the <filename
	role="package">x11/nvidia-driver-71xx</filename>
	port.</para>
	</listitem>
	</itemizedlist>

	<para>nVidia provides detailed information on which
	card is supported by which driver
	on their web site: <ulink
	url="http://www.nvidia.com/object/IO_32667.html"></ulink>.</para>

	<para>For Matrox G200/G400, check the
	<filename role="package">x11-servers/mga_hal</filename>
	port.</para>

	<para>For ATI Rage 128 and Radeon see
	&man.ati.4x;, &man.r128.4x; and &man.radeon.4x;.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="networking">
	<title>Networking</title>

	<qandaset>
	<qandaentry>
	<question id="diskless-booting">
	<para>Where can I get information on <quote>diskless
	booting</quote>?</para>
	</question>

	<answer>
	<para><quote>Diskless booting</quote> means that the &os;
	box is booted over a network, and reads the necessary
	files from a server instead of its hard disk. For full
	- details, please read <ulink
	- url="&url.books.handbook;/network-diskless.html">the Handbook entry on diskless booting</ulink>.</para>
	- </answer>
	- </qandaentry>
	+ details, please read <ulink
	+ url="&url.books.handbook;/network-diskless.html">the Handbook entry on diskless booting</ulink>.</para>
	+ </answer>
	+ </qandaentry>

	- <qandaentry>
	- <question id="router">
	+ <qandaentry>
	+ <question id="router">
	<para>Can a &os; box be used as a dedicated network
	router?</para>
	</question>

	<answer>
	<para>Yes. Please see the Handbook entry on <ulink
	url="&url.books.handbook;/advanced-networking.html">advanced networking</ulink>,
	specifically the section on <ulink
	url="&url.books.handbook;/network-routing.html">routing and gateways</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="win95-connection">
	<para>Can I connect my &windows; box to the Internet via
	&os;?</para>
	</question>

	<answer>
	<para>Typically, people who ask this question have two PCs at
	home, one with &os; and one with some version of &windows;
	the idea is to use the &os; box to connect to the Internet
	and then be able to access the Internet from the &windows;
	box through the &os; box. This is really just a special
	case of the previous question and works perfectly
	well.</para>

	<para>Dialup users must use <option>-nat</option>
	and set
	<literal>gateway_enable</literal> to
	<emphasis>YES</emphasis> in
	<filename>/etc/rc.conf</filename>.
	For
	more information, please see the &man.ppp.8; manual page or
	the <ulink
	url="&url.books.handbook;/userppp.html">Handbook entry on user PPP</ulink>.</para>

	<para>If you are using kernel-mode PPP or have an Ethernet
	connection to the Internet, you need to use &man.natd.8;.
	Please look at the <ulink
	url="&url.books.handbook;/network-natd.html">natd</ulink>
	section of the Handbook for a tutorial.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="slip-ppp-support">
	<para>Does &os; support PPP?</para>
	</question>

	<answer>
	<para>Yes. &man.ppp.8; provides support for both
	incoming and outgoing connections.</para>

	<para>For more information on how to use this, please see the
	<ulink
	url="&url.books.handbook;/ppp-and-slip.html">Handbook chapter on PPP</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="natd">
	<para>Does &os; support NAT or Masquerading?</para>
	</question>

	<answer>
	<para>Yes. If you want to use NAT over a user PPP connection,
	please see the <ulink
	url="&url.books.handbook;/userppp.html">Handbook entry on user PPP</ulink>.
	If you want to use NAT over some other sort of network
	connection, please look at the <ulink
	url="&url.books.handbook;/network-natd.html">natd</ulink>
	section of the Handbook.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ethernet-aliases">
	<para>How can I set up Ethernet aliases?</para>
	</question>

	<answer>
	<para>If the alias is on the same subnet as an address already
	configured on the interface, then add <literal>netmask
	- 0xffffffff</literal> to your &man.ifconfig.8; command-line,
	+ 0xffffffff</literal> to your &man.ifconfig.8; command-line,
	as in the following:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>ed0</replaceable> alias <replaceable>192.0.2.2</replaceable> netmask 0xffffffff</userinput></screen>

	<para>Otherwise, just specify the network address and netmask
	as usual:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>ed0</replaceable> alias <replaceable>172.16.141.5</replaceable> netmask 0xffffff00</userinput></screen>

	<para>You can read more about this in the &os; <ulink
	url="&url.books.handbook;/configtuning-virtual-hosts.html">Handbook</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	- <question id="port-3c503">
	- <para>How do I get my 3C503 to use the other network
	- port?</para>
	- </question>
	-
	- <answer>
	- <para>If you want to use the other ports, you will have to
	- specify an additional parameter on the &man.ifconfig.8;
	- command line. The default port is <literal>link0</literal>.
	- To use the AUI port instead of the BNC one, use
	- <literal>link2</literal>. These flags should be specified
	- using the ifconfig_* variables in
	- <filename>/etc/rc.conf</filename> (see
	- &man.rc.conf.5;).</para>
	- </answer>
	- </qandaentry>
	-
	- <qandaentry>
	<question id="nfs-linux">
	<para>Why can I not NFS-mount from a &linux; box?</para>
	</question>

	<answer>
	<para>Some versions of the &linux; NFS code only accept mount
	requests from a privileged port; try to issue the following
	command:</para>

	<screen>&prompt.root; <userinput>mount -o -P <replaceable>linuxbox:/blah</replaceable> <replaceable>/mnt</replaceable></userinput></screen>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="exports-errors">
	<para>Why does <command>mountd</command> keep telling me it
	<errorname>can't change attributes</errorname> and that I
	have a <errorname>bad exports list</errorname> on my &os;
	NFS server?</para>
	</question>

	<answer>
	<para>The most frequent problem is not understanding the
	correct format of <filename>/etc/exports</filename>. Please
	review &man.exports.5; and the <ulink
	url="&url.books.handbook;/network-nfs.html">NFS</ulink>
	entry in the Handbook, especially the section on <ulink
	url="&url.books.handbook;/network-nfs.html#configuring-nfs">configuring NFS</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ip-multicast">
	<para>How do I enable IP multicast support?</para>
	</question>

	<answer>
	<para>&os; supports multicast host operations by default. If
	you want your box to run as a multicast router, you need to
	recompile your kernel with the <literal>MROUTING</literal>
	option and run &man.mrouted.8;. &os; will start
	&man.mrouted.8; at boot time if the flag
	<literal>mrouted_enable</literal> is set to
	<literal>YES</literal> in
	<filename>/etc/rc.conf</filename>.</para>

	<note>
	<para>In recent &os; releases, the &man.mrouted.8; multicast
	routing daemon, the &man.map-mbone.8; and &man.mrinfo.8;
	utilities have been removed from the base system. These
	programs are now available in the &os; Ports Collection as
	<filename role="package">net/mrouted</filename>.</para>
	</note>
	-
	- <para>MBONE tools are available in their own ports category,
	- <ulink
	- url="http://www.FreeBSD.org/ports/mbone.html">mbone</ulink>.
	- If you are looking for the conference tools
	- <command>vic</command> and <command>vat</command>, look
	- there!</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="fqdn-hosts">
	<para>Why do I have to use the FQDN for hosts on my
	site?</para>
	</question>

	<answer>
	<para>See the answer in the &os; <ulink
	url="&url.books.handbook;/mail-trouble.html">Handbook</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="network-permission-denied">
	<para>Why do I get an error, <errorname>Permission
	- denied</errorname>, for all networking operations?</para>
	+ denied</errorname>, for all networking operations?</para>
	</question>

	<answer>
	<para>If you have compiled your kernel with the
	<literal>IPFIREWALL</literal> option, you need to be aware
	that the default policy is to deny all packets that are not
	explicitly allowed.</para>

	<para>If you had unintentionally misconfigured your system for
	firewalling, you can restore network operability by typing
	the following while logged in as
	<username>root</username>:</para>

	<screen>&prompt.root; <userinput>ipfw add 65534 allow all from any to any</userinput></screen>

	<para>You can also set <literal>firewall_type="open"</literal>
	in <filename>/etc/rc.conf</filename>.</para>

	<para>For further information on configuring a &os; firewall,
	see the <ulink
	url="&url.books.handbook;/firewalls.html">Handbook chapter</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ipfw-fwd">
	<para>Why is my <command>ipfw</command> <quote>fwd</quote>
	rule to redirect a service to another machine not
	working?</para>
	</question>

	<answer>
	<para>Possibly because you want to do network address
	translation (NAT) and not just forward packets. A
	<quote>fwd</quote> rule does exactly what it says; it
	forwards packets. It does not actually change the data
	inside the packet. Say we have a rule like:</para>

	<screen>01000 fwd <replaceable>10.0.0.1</replaceable> from any to <replaceable>foo 21</replaceable></screen>

	<para>When a packet with a destination address of
	<replaceable>foo</replaceable> arrives at the machine with
	this rule, the packet is forwarded to
	<replaceable>10.0.0.1</replaceable>, but it still has the
	destination address of <replaceable>foo</replaceable>! The
	destination address of the packet is
	<emphasis>not</emphasis> changed to
	<replaceable>10.0.0.1</replaceable>. Most machines would
	probably drop a packet that they receive with a destination
	address that is not their own. Therefore, using a
	<quote>fwd</quote> rule does not often work the way the user
	expects. This behavior is a feature and not a bug.</para>

	<para>See the <link
	linkend="service-redirect">FAQ about redirecting services</link>,
	the &man.natd.8; manual, or one of the several port
	redirecting utilities in the <ulink
	url="&url.base;/ports/index.html">Ports Collection</ulink>
	for a correct way to do this.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="service-redirect">
	<para>How can I redirect service requests from one machine to
	another?</para>
	</question>

	<answer>
	<para>You can redirect FTP (and other service) request with
	the <filename role="package">sysutils/socket</filename>
	port. Simply replace the service's command line to call
	<command>socket</command> instead, like so:</para>

	<programlisting>ftp stream tcp nowait nobody /usr/local/bin/socket socket <replaceable>ftp.example.com</replaceable> <replaceable>ftp</replaceable></programlisting>

	<para>where <replaceable>ftp.example.com</replaceable> and
	<replaceable>ftp</replaceable> are the host and port to
	redirect to, respectively.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="bandwidth-mgr-tool">
	<para>Where can I get a bandwidth management tool?</para>
	</question>

	<answer>
	<para>There are three bandwidth management tools available for
	&os;. &man.dummynet.4; is integrated into &os; as part of
	&man.ipfw.4;. <ulink
	url="http://www.sonycsl.co.jp/person/kjc/programs.html">ALTQ</ulink>
	has been integrated into &os; as part of &man.pf.4;.
	Bandwidth Manager from <ulink
	url="http://www.etinc.com/">Emerging Technologies</ulink>
	is a commercial product.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="bpf-not-configured">
	<para>Why do I get <errorname>/dev/bpf0: device not
	- configured</errorname>?</para>
	+ configured</errorname>?</para>
	</question>

	<answer>
	<para>You are running a program that requires the Berkeley
	Packet Filter (&man.bpf.4;), but it is not in your kernel.
	Add this to your kernel config file and build a new
	kernel:</para>

	<programlisting>device bpf # Berkeley Packet Filter</programlisting>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="mount-smb-share">
	<para>How do I mount a disk from a &windows; machine that is
	on my network, like smbmount in &linux;?</para>
	</question>

	<answer>
	<para>Use the <application>SMBFS</application> toolset. It
	includes a set of kernel modifications and a set of userland
	programs. The programs and information are available as
	&man.mount.smbfs.8; in the base system.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="icmp-response-bw-limit">
	<para>What are these messages about: <errorname>Limiting
	- icmp/open port/closed port response</errorname> in my log
	+ icmp/open port/closed port response</errorname> in my log
	files?</para>
	</question>

	<answer>
	<para>This is the kernel telling you that some activity is
	provoking it to send more ICMP or TCP reset (RST) responses
	than it thinks it should. ICMP responses are often
	generated as a result of attempted connections to unused UDP
	ports. TCP resets are generated as a result of attempted
	connections to unopened TCP ports. Among others, these are
	the kinds of activities which may cause these
	messages:</para>

	<itemizedlist>
	<listitem>
	<para>Brute-force denial of service (DoS) attacks (as
	opposed to single-packet attacks which exploit a
	specific vulnerability).</para>
	</listitem>

	<listitem>
	<para>Port scans which attempt to connect to a large
	number of ports (as opposed to only trying a few
	well-known ports).</para>
	</listitem>
	</itemizedlist>

	<para>The first number in the message tells you how many
	packets the kernel would have sent if the limit was not in
	place, and the second number tells you the limit. You can
	control the limit using the
	<varname>net.inet.icmp.icmplim</varname> sysctl variable
	like this, where <literal>300</literal> is the limit in
	packets per second:</para>

	<screen>&prompt.root; <userinput>sysctl net.inet.icmp.icmplim=300</userinput></screen>

	<para>If you do not want to see messages about this in your
	log files, but you still want the kernel to do response
	limiting, you can use the
	<varname>net.inet.icmp.icmplim_output</varname> sysctl
	variable to disable the output like this:</para>

	<screen>&prompt.root; <userinput>sysctl net.inet.icmp.icmplim_output=0</userinput></screen>

	<para>Finally, if you want to disable response limiting, you
	can set the <varname>net.inet.icmp.icmplim</varname> sysctl
	variable (see above for an example) to <literal>0</literal>.
	Disabling response limiting is discouraged for the reasons
	listed above.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="unknown-hw-addr-format">
	<para>What are these <errorname>arp: unknown hardware address
	- format</errorname> error messages?</para>
	+ format</errorname> error messages?</para>
	</question>

	<answer>
	<para>This means that some device on your local Ethernet is
	using a MAC address in a format that &os; does not
	recognize. This is probably caused by someone experimenting
	with an Ethernet card somewhere else on the network. You
	will see this most commonly on cable modem networks. It is
	harmless, and should not affect the performance of your &os;
	machine.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="arp-wrong-iface">
	<para>Why do I keep seeing messages like: <errorname>192.168.0.10 is on
	- fxp1 but got reply from 00:15:17:67:cf:82 on rl0</errorname>, and how do I
	+ fxp1 but got reply from 00:15:17:67:cf:82 on rl0</errorname>, and how do I
	disable it?</para>
	</question>

	<answer>
	<para>Because a packet is coming from outside the network
	unexpectedly. To disable them, set
	<varname>net.link.ether.inet.log_arp_wrong_iface</varname>
	to <literal>0</literal>.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="security">
	<title>Security</title>

	<qandaset>
	<qandaentry>
	<question id="sandbox">
	<para>What is a sandbox?</para>
	</question>
	<answer>
	<para><quote>Sandbox</quote> is a security term. It can mean
	two things:</para>

	<itemizedlist>
	<listitem>
	<para>A process which is placed inside a set of virtual
	walls that are designed to prevent someone who breaks
	into the process from being able to break into the wider
	system.</para>

	<para>The process is said to be able to
	<quote>play</quote> inside the walls. That is, nothing
	the process does in regards to executing code is
	supposed to be able to breech the walls so you do not
	have to do a detailed audit of its code to be able to
	say certain things about its security.</para>

	<para>The walls might be a user ID, for example.
	This is the definition used in the &man.security.7; and
	&man.named.8; man pages.</para>

	<para>Take the <literal>ntalk</literal> service, for
	example (see &man.inetd.8;). This service used to run
	as user ID <username>root</username>. Now it runs
	as user ID <username>tty</username>. The
	<username>tty</username> user is a sandbox designed to
	make it more difficult for someone who has successfully
	hacked into the system via <literal>ntalk</literal> from
	being able to hack beyond that user ID.</para>
	</listitem>

	<listitem>
	<para>A process which is placed inside a simulation of the
	machine. It means
	that someone who is able to break into the process may
	believe that he can break into the wider machine but is,
	in fact, only breaking into a simulation of that machine
	and not modifying any real data.</para>

	<para>The most common way to accomplish this is to build a
	simulated environment in a subdirectory and then run the
	processes in that directory chrooted (i.e., <filename
	class="directory">/</filename> for that process is this
	directory, not the real <filename
	class="directory">/</filename> of the system).</para>

	<para>Another common use is to mount an underlying file
	system read-only and then create a file system layer on
	top of it that gives a process a seemingly writeable
	view into that file system. The process may believe it
	is able to write to those files, but only the process
	sees the effects — other processes in the system
	do not, necessarily.</para>

	<para>An attempt is made to make this sort of sandbox so
	transparent that the user (or hacker) does not realize
	that he is sitting in it.</para>
	</listitem>
	</itemizedlist>

	<para>&unix; implements two core sandboxes. One is at the
	process level, and one is at the userid level.</para>

	<para>Every &unix; process is completely firewalled off from
	every other &unix; process. One process cannot modify the
	- address space of another. This is unlike &windows; where a
	- process can easily overwrite the address space of any other,
	- leading to a crash.</para>
	+ address space of another.</para>

	<para>A &unix; process is owned by a particular userid. If
	the user ID is not the <username>root</username> user,
	it serves to firewall the process off from processes owned
	by other users. The user ID is also used to firewall
	off on-disk data.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="securelevel">
	<para>What is securelevel?</para>
	</question>

	<answer>
	<para><literal>securelevel</literal> is a security
	mechanism implemented in the kernel. When the securelevel
	is positive, the
	kernel restricts certain tasks; not even the superuser
	(i.e., <username>root</username>) is allowed to do them.
	The securelevel mechanism limits the ability to:</para>

	<itemizedlist>
	<listitem>
	<para>Unset certain file flags, such as
	<literal>schg</literal> (the system immutable
	flag).</para>
	</listitem>

	<listitem>
	<para>Write to kernel memory via
	<devicename>/dev/mem</devicename> and
	<devicename>/dev/kmem</devicename>.</para>
	</listitem>

	<listitem>
	<para>Load kernel modules.</para>
	</listitem>

	<listitem>
	<para>Alter firewall rules.</para>
	</listitem>
	</itemizedlist>

	<para>To check the status of the securelevel on a running
	system, simply execute the following command:</para>

	<screen>&prompt.root; <userinput>sysctl -n kern.securelevel</userinput></screen>

	<para>The output contains the current value of the
	securelevel. If it is positive (i.e., greater than 0), at
	least some of the securelevel's protections are
	enabled.</para>

	<para>The securelevel of a running system can not be
	lowered as this would defeat its purpose. If you need
	to do a task that requires that the securelevel be
	non-positive (e.g., an <maketarget>installworld</maketarget>
	or changing the date), you will have to change the
	securelevel setting in <filename>/etc/rc.conf</filename>
	(you want to look for the
	<varname>kern_securelevel</varname> and
	<varname>kern_securelevel_enable</varname> variables) and
	reboot.</para>

	<para>For more information on securelevel and the specific
	things all the levels do, please consult the &man.init.8;
	manual page.</para>

	<warning>
	<para>Securelevel is not a silver bullet; it has many known
	deficiencies. More often than not, it provides a false
	sense of security.</para>

	<para>One of its biggest problems is that in order for it to
	be at all effective, all files used in the boot process up
	until the securelevel is set must be protected. If an
	attacker can get the system to execute their code prior to
	the securelevel being set (which happens quite late in the
	boot process since some things the system must do at
	start-up cannot be done at an elevated securelevel), its
	protections are invalidated. While this task of
	protecting all files used in the boot process is not
	technically impossible, if it is achieved, system
	maintenance will become a nightmare since one would have
	to take the system down, at least to single-user mode, to
	modify a configuration file.</para>

	<para>This point and others are often discussed on the
	mailing lists, particularly the &a.security;. Please
	search the archives <ulink
	url="&url.base;/search/index.html">here</ulink> for an
	extensive discussion. A more fine-grained mechanism
	- is preffered.</para>
	+ is preferred.</para>
	</warning>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="extra-named-port">
	<para>BIND (<command>named</command>) is listening on
	some high-numbered ports. What is going on?</para>
	</question>

	<answer>
	<para>BIND uses a random high-numbered port for outgoing
	queries. Recent versions of it choose a new, random UDP
	port for each query. This may cause problems for some
	network configurations, especially if a firewall blocks
	incoming UDP packets on particular ports. If you want to
	get past that firewall, you can try the
	<literal>avoid-v4-udp-ports</literal> and
	<literal>avoid-v6-udp-ports</literal> options to avoid
	selecting random port numbers within a blocked range.</para>

	<warning>
	<para>If a port number (like 53) is specified via the
	<literal>query-source</literal> or
	<literal>query-source-v6</literal> options in
	<filename>/etc/namedb/named.conf</filename>, randomized
	port selection will not be used. It is strongly
	recommended that these options not be used to specify
	fixed port numbers.</para>
	</warning>

	<para>Congratulations, by the way. It is good practice to
	read your &man.sockstat.1; output and notice odd
	things!</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="sendmail-port-587">
	<para>The <application>sendmail</application> daemon is
	listening on port 587 as well as the standard port 25! What
	is going on?</para>
	</question>

	<answer>
	<para>Recent versions of <application>sendmail</application>
	support a mail submission feature that runs over port 587.
	This is not yet widely supported, but is growing in
	popularity.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="toor-account">
	<para>What is this UID 0 <username>toor</username> account?
	Have I been compromised?</para>
	</question>

	<answer>
	<para>Do not worry. <username>toor</username> is an
	<quote>alternative</quote> superuser account (toor is root
	spelt backwards). Previously it was created when the
	&man.bash.1; shell was installed but now it is created by
	default. It is intended to be used with a non-standard
	shell so you do not have to change
	<username>root</username>'s default shell. This is
	important as shells which are not part of the base
	distribution (for example a shell installed from ports or
	packages) are likely to be installed in
	<filename class="directory">/usr/local/bin</filename> which, by default,
	resides on a different file system. If
	<username>root</username>'s shell is located in
	<filename class="directory">/usr/local/bin</filename> and
	<filename class="directory">/usr</filename> (or whatever file system contains
	<filename class="directory">/usr/local/bin</filename>) is not mounted for some
	reason, <username>root</username> will not be able to log in
	to fix a problem (although if you reboot into single user
	mode you will be prompted for the path to a shell).</para>

	<para>Some people use <username>toor</username> for day-to-day
	<username>root</username> tasks with a non-standard shell,
	leaving <username>root</username>, with a standard shell,
	for single user mode or emergencies. By default you cannot
	log in using <username>toor</username> as it does not have a
	password, so log in as <username>root</username> and set a
	password for <username>toor</username> if you want to use
	it.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="ppp">
	<title>PPP</title>

	<qandaset>
	<qandaentry>
	<question id="userppp">
	<para>I cannot make &man.ppp.8; work. What am I doing
	wrong?</para>
	</question>

	<answer>
	<para>You should first read the &man.ppp.8; manual page and
	the <ulink
	url="&url.books.handbook;/ppp-and-slip.html#userppp">PPP section of the handbook</ulink>.
	Enable logging with the following command:</para>

	<programlisting>set log Phase Chat Connect Carrier lcp ipcp ccp command</programlisting>

	<para>This command may be typed at the &man.ppp.8; command
	prompt or it may be entered in the
	<filename>/etc/ppp/ppp.conf</filename> configuration file
	(the start of the <literal>default</literal> section is the
	best place to put it). Make sure that
	<filename>/etc/syslog.conf</filename> (see
	&man.syslog.conf.5;) contains the lines below and the file
	<filename>/var/log/ppp.log</filename> exists:</para>

	<programlisting>!ppp
	. /var/log/ppp.log</programlisting>

	<para>You can now find out a lot about what is going on from
	the log file. Do not worry if it does not all make sense.
	If you need to get help from someone, it may make sense to
	them.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-hangs">
	<para>Why does &man.ppp.8; hang when I run it?</para>
	</question>

	<answer>
	<para>This is usually because your hostname will not resolve.
	The best way to fix this is to make sure that
	<filename>/etc/hosts</filename> is consulted by your
	resolver first by editing
	<filename>/etc/host.conf</filename> and putting the
	<literal>hosts</literal> line first. Then, simply put an
	entry in <filename>/etc/hosts</filename> for your local
	machine. If you have no local network, change your
	<hostid>localhost</hostid> line:</para>

	<programlisting>127.0.0.1 foo.example.com foo localhost</programlisting>

	<para>Otherwise, simply add another entry for your host.
	Consult the relevant manual pages for more details.</para>

	<para>You should be able to successfully
	<command>ping -c1 `hostname`</command> when you are
	done.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-nodial-auto">
	<para>Why will &man.ppp.8; not dial in
	<literal>-auto</literal> mode?</para>
	</question>

	<answer>
	<para>First, check that you have got a default route. By
	running <command>netstat -rn</command> (see
	&man.netstat.1;), you should see two entries like
	this:</para>

	<programlisting>Destination Gateway Flags Refs Use Netif Expire
	default 10.0.0.2 UGSc 0 0 tun0
	10.0.0.2 10.0.0.1 UH 0 0 tun0</programlisting>

	<para>This is assuming that you have used the addresses from
	the handbook, the manual page, or from
	<filename>ppp.conf.sample</filename>. If you do not
	have a default route, it may be because you forgot to add
	the <literal>HISADDR</literal> line to
	<filename>ppp.conf</filename>.</para>

	<para>Another reason for the default route line being missing
	is that you have mistakenly set up a default router in your
	<filename>/etc/rc.conf</filename> (see &man.rc.conf.5;) file
	and you have omitted the line below from
	<filename>ppp.conf</filename>:</para>

	<programlisting>delete ALL</programlisting>

	<para>If this is the case, go back to the <ulink
	url="&url.books.handbook;/userppp.html#userppp-final">Final System Configuration</ulink>
	section of the handbook.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="no-route-to-host">
	<para>What does <errorname>No route to host</errorname>
	mean?</para>
	</question>

	<answer>
	<para>This error is usually due that the following section is
	missing in your <filename>/etc/ppp/ppp.linkup</filename>:</para>

	<programlisting>MYADDR:
	delete ALL
	add 0 0 HISADDR</programlisting>

	<para>This is only necessary if you have a dynamic IP address
	or do not know the address of your gateway. If you are
	using interactive mode, you can type the following after
	entering <literal>packet mode</literal> (packet mode is
	indicated by the capitalized <acronym>PPP</acronym> in the
	prompt):</para>

	<programlisting>delete ALL
	add 0 0 HISADDR</programlisting>

	<para>Refer to the <ulink
	url="&url.books.handbook;/userppp.html#userppp-dynamicip">PPP and Dynamic IP addresses</ulink>
	section of the handbook for further details.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="connection-threeminutedrop">
	<para>Why does my connection drop after about 3
	minutes?</para>
	</question>

	<answer>
	<para>The default PPP timeout is 3 minutes. This can be
	adjusted with the following line:</para>

	<programlisting>set timeout <replaceable>NNN</replaceable></programlisting>

	<para>where <replaceable>NNN</replaceable> is the number of
	seconds of inactivity before the connection is closed. If
	<replaceable>NNN</replaceable> is zero, the connection is
	never closed due to a timeout. It is possible to put this
	command in <filename>ppp.conf</filename>, or to
	type it at the prompt in interactive mode. It is also
	possible to adjust it on the fly while the line is active by
	connecting to <application>ppp</application>'s server socket
	using &man.telnet.1; or &man.pppctl.8;. Refer to the
	&man.ppp.8; man page for further details.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-drop-heavy-load">
	<para>Why does my connection drop under heavy load?</para>
	</question>

	<answer>
	<para>If you have Link Quality Reporting (LQR) configured, it
	is possible that too many LQR packets are lost between your
	machine and the peer. &man.ppp.8; deduces that
	the line must therefore be bad, and disconnects.
	LQR is disabled by default and can be enabled with the
	following line:</para>

	<programlisting>enable lqr</programlisting>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-drop-random">
	<para>Why does my connection drop after a random amount of
	time?</para>
	</question>

	<answer>
	<para>Sometimes, on a noisy phone line or even on a line with
	call waiting enabled, your modem may hang up because it
	thinks (incorrectly) that it lost carrier.</para>

	<para>There is a setting on most modems for determining how
	tolerant it should be to temporary losses of carrier.
	Refer to the modem manual for details.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-hangs-random">
	<para>Why does my connection hang after a random amount of
	time?</para>
	</question>

	<answer>
	<para>Many people experience hung connections with no apparent
	explanation. The first thing to establish is which side of
	the link is hung.</para>

	<para>If you are using an external modem, you can simply try
	using &man.ping.8; to see if the <acronym>TD</acronym> light
	is flashing when you transmit data. If it flashes (and the
	<acronym>RD</acronym> light does not), the problem is with
	the remote end. If <acronym>TD</acronym> does not flash,
	the problem is local. With an internal modem, you will need
	to use the <literal>set server</literal> command in
	<filename>ppp.conf</filename>. When the hang occurs,
	connect to &man.ppp.8; using &man.pppctl.8;. If your
	network connection suddenly revives (PPP was revived due to
	the activity on the diagnostic socket) or if you cannot
	connect (assuming the <literal>set socket</literal> command
	succeeded at startup time), the problem is local. If you
	can connect and things are still hung, enable local async
	logging with <literal>set log local async</literal> and use
	&man.ping.8; from another window or terminal to make use of
	the link. The async logging will show you the data being
	transmitted and received on the link. If data is going out
	and not coming back, the problem is remote.</para>

	<para>Having established whether the problem is local or
	remote, you now have two possibilities:</para>

	<itemizedlist>
	<listitem>
	<para>If the problem is remote, read on entry <xref
	linkend="ppp-remote-not-responding"/>.</para>
	</listitem>

	<listitem>
	<para>If the problem is local, read on entry <xref
	linkend="ppp-hung"/>.</para>
	</listitem>
	</itemizedlist>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-remote-not-responding">
	<para>The remote end is not responding. What can I do?</para>
	</question>

	<answer>
	<para>There is very little you can do about this. Most ISPs
	will refuse to help if you are not running a &microsoft; OS.
	You can <literal>enable lqr</literal> in your
	<filename>ppp.conf</filename>, allowing &man.ppp.8; to
	detect the remote failure and hang up, but this detection is
	relatively slow and therefore not that useful. You may want
	to avoid telling your ISP that you are running
	user-PPP.</para>

	<para>First, try disabling all local compression by adding the
	following to your configuration:</para>

	<programlisting>disable pred1 deflate deflate24 protocomp acfcomp shortseq vj
	deny pred1 deflate deflate24 protocomp acfcomp shortseq vj</programlisting>

	<para>Then reconnect to ensure that this makes no difference.
	If things improve or if the problem is solved completely,
	determine which setting makes the difference through trial
	and error. This will provide good ammunition when you
	contact your ISP (although it may make it apparent that you
	are not running a &microsoft; product).</para>

	<para>Before contacting your ISP, enable async logging locally
	and wait until the connection hangs again. This may use up
	quite a bit of disk space. The last data read from the port
	may be of interest. It is usually ASCII data, and may even
	describe the problem (<errorname>Memory fault</errorname>,
	<errorname>Core dumped</errorname>).</para>

	<para>If your ISP is helpful, they should be able to enable
	logging on their end, then when the next link drop occurs,
	they may be able to tell you why their side is having a
	problem.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-hung">
	<para>&man.ppp.8; has hung. What can I do?</para>
	</question>

	<answer>
	<para>Your best bet here is to rebuild &man.ppp.8; with
	debugging information, and then use &man.gdb.1; to grab a
	stack trace from the <application>ppp</application> process
	that is stuck. To rebuild the
	<application>ppp</application> utility with debugging
	information, you can type:</para>

	<screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/ppp</userinput>
	&prompt.root; <userinput>env DEBUG_FLAGS='-g' make clean</userinput>
	&prompt.root; <userinput>env DEBUG_FLAGS='-g' make install</userinput></screen>

	<para>Then you should restart <application>ppp</application>
	and wait until it hangs again. When the debug build of
	<application>ppp</application> hangs, start
	<application>gdb</application> on the stuck process by
	typing:</para>

	<screen>&prompt.root; <userinput>gdb ppp `pgrep ppp`</userinput></screen>

	<para>At the <application>gdb</application> prompt, you can
	use the <command>bt</command> or <command>where</command>
	commands to get a stack trace. Save the output of your
	<application>gdb</application> session, and
	<quote>detach</quote> from the running process by typing
	<command>quit</command>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-same-magic">
	<para>I keep seeing errors about magic being the same. What
	does it mean?</para>
	</question>

	<answer>
	<para>Occasionally, just after connecting, you may see
	messages in the log that say <errorname>Magic is
	- same</errorname>. Sometimes, these messages are harmless,
	+ same</errorname>. Sometimes, these messages are harmless,
	and sometimes one side or the other exits. Most PPP
	implementations cannot survive this problem, and even if the
	link seems to come up, you will see repeated configure
	requests and configure acknowledgments in the log file until
	&man.ppp.8; eventually gives up and closes the
	connection.</para>

	<para>This normally happens on server machines with slow disks
	that are spawning a &man.getty.8; on the port, and executing
	&man.ppp.8; from a login script or program after login.
	There were reports of it happening consistently when using
	slirp. The reason is that in the time taken between
	&man.getty.8; exiting and &man.ppp.8; starting, the
	client-side &man.ppp.8; starts sending Line Control Protocol
	(LCP) packets. Because ECHO is still switched on for the
	port on the server, the client &man.ppp.8; sees these
	packets <quote>reflect</quote> back.</para>

	<para>One part of the LCP negotiation is to establish a magic
	number for each side of the link so that
	<quote>reflections</quote> can be detected. The protocol
	says that when the peer tries to negotiate the same magic
	number, a NAK should be sent and a new magic number should
	be chosen. During the period that the server port has ECHO
	turned on, the client &man.ppp.8; sends LCP packets, sees
	the same magic in the reflected packet and NAKs it. It also
	sees the NAK reflect (which also means &man.ppp.8; must
	change its magic). This produces a potentially enormous
	number of magic number changes, all of which are happily
	piling into the server's tty buffer. As soon as &man.ppp.8;
	starts on the server, it is flooded with magic number
	changes and almost immediately decides it has tried enough
	to negotiate LCP and gives up. Meanwhile, the client, who
	no longer sees the reflections, becomes happy just in time
	to see a hangup from the server.</para>

	<para>This can be avoided by allowing the peer to start
	negotiating with the following line in
	<filename>ppp.conf</filename>:</para>

	<programlisting>set openmode passive</programlisting>

	<para>This tells &man.ppp.8; to wait for the server to
	initiate LCP negotiations. Some servers however may never
	initiate negotiations. If this is the case, you can do
	something like:</para>

	<programlisting>set openmode active 3</programlisting>

	<para>This tells &man.ppp.8; to be passive for 3 seconds, and
	then to start sending LCP requests. If the peer starts
	sending requests during this period, &man.ppp.8; will
	immediately respond rather than waiting for the full 3
	second period.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-lcp-constant">
	<para>LCP negotiations continue until the connection is
	closed. What is wrong?</para>
	</question>

	<answer>
	<para>There is currently an implementation mis-feature in
	&man.ppp.8; where it does not associate LCP, CCP & IPCP
	responses with their original requests. As a result, if one
	PPP implementation is more than 6 seconds slower than the
	other side, the other side will send two additional LCP
	configuration requests. This is fatal.</para>

	<para>Consider two implementations, <hostid>A</hostid> and
	<hostid>B</hostid>. <hostid>A</hostid> starts sending LCP
	requests immediately after connecting and <hostid>B</hostid>
	takes 7 seconds to start. When <hostid>B</hostid> starts,
	<hostid>A</hostid> has sent 3 LCP REQs. We are assuming the
	line has ECHO switched off, otherwise we would see magic
	number problems as described in the previous section.
	<hostid>B</hostid> sends a REQ, then an ACK to the first of
	<hostid>A</hostid>'s REQs. This results in
	<hostid>A</hostid> entering the <acronym>OPENED</acronym>
	state and sending and ACK (the first) back to
	<hostid>B</hostid>. In the meantime, <hostid>B</hostid>
	sends back two more ACKs in response to the two additional
	REQs sent by <hostid>A</hostid> before <hostid>B</hostid>
	started up. <hostid>B</hostid> then receives the first ACK
	from <hostid>A</hostid> and enters the
	<acronym>OPENED</acronym> state. <hostid>A</hostid>
	receives the second ACK from <hostid>B</hostid> and goes
	back to the <acronym>REQ-SENT</acronym> state, sending
	another (forth) REQ as per the RFC. It then receives the
	third ACK and enters the <acronym>OPENED</acronym> state.
	In the meantime, <hostid>B</hostid> receives the forth REQ
	from <hostid>A</hostid>, resulting in it reverting to the
	<acronym>ACK-SENT</acronym> state and sending another
	(second) REQ and (forth) ACK as per the RFC.
	<hostid>A</hostid> gets the REQ, goes into
	<acronym>REQ-SENT</acronym> and sends another REQ. It
	immediately receives the following ACK and enters
	<acronym>OPENED</acronym>.</para>

	<para>This goes on until one side figures out that they are
	getting nowhere and gives up.</para>

	<para>The best way to avoid this is to configure one side to
	be <literal>passive</literal> — that is, make one side
	wait for the other to start negotiating. This can be done
	with the following command:</para>

	<programlisting>set openmode passive</programlisting>

	<para>Care should be taken with this option. You should also
	use this command to limit the amount of time that
	&man.ppp.8; waits for the peer to begin negotiations:</para>

	<programlisting>set stopped <replaceable>N</replaceable></programlisting>

	<para>Alternatively, the following command (where
	<replaceable>N</replaceable> is the number of seconds to
	wait before starting negotiations) can be used:</para>

	<programlisting>set openmode active <replaceable>N</replaceable></programlisting>

	<para>Check the manual page for details.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-shell-test-lockup">
	<para>Why does &man.ppp.8; lock up when I shell out to test
	it?</para>
	</question>

	<answer>
	<para>When you execute the <command>shell</command> or
	<command>!</command> command, &man.ppp.8; executes a shell
	(or if you have passed any arguments, &man.ppp.8; will
	execute those arguments). The
	<application>ppp</application> program will wait for the
	command to complete before continuing. If you attempt to
	use the PPP link while running the command, the link will
	appear to have frozen. This is because &man.ppp.8; is
	waiting for the command to complete.</para>

	<para>To execute commands like this, use
	<command>!bg</command> instead. This will execute
	the given command in the background, and &man.ppp.8; can
	continue to service the link.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-null-modem">
	<para>Why does &man.ppp.8; over a null-modem cable never
	exit?</para>
	</question>

	<answer>
	<para>There is no way for &man.ppp.8; to automatically
	determine that a direct connection has been dropped. This
	is due to the lines that are used in a null-modem serial
	cable. When using this sort of connection, LQR should
	always be enabled with the following line:</para>

	<programlisting>enable lqr</programlisting>

	<para>LQR is accepted by default if negotiated by the
	peer.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-auto-noreasondial">
	<para>Why does &man.ppp.8; dial for no reason in
	<option>-auto</option> mode?</para>
	</question>

	<answer>
	<para>If &man.ppp.8; is dialing unexpectedly, you must
	determine the cause, and set up Dial filters (dfilters) to
	prevent such dialing.</para>

	<para>To determine the cause, use the following line:</para>

	<programlisting>set log +tcp/ip</programlisting>

	<para>This will log all traffic through the connection. The
	next time the line comes up unexpectedly, you will see the
	reason logged with a convenient timestamp next to it.</para>

	<para>You can now disable dialing under these circumstances.
	Usually, this sort of problem arises due to DNS lookups. To
	prevent DNS lookups from establishing a connection (this
	will <emphasis>not</emphasis> prevent &man.ppp.8; from
	passing the packets through an established connection), use
	the following:</para>

	<programlisting>set dfilter 1 deny udp src eq 53
	set dfilter 2 deny udp dst eq 53
	set dfilter 3 permit 0/0 0/0</programlisting>

	<para>This is not always suitable, as it will effectively
	break your demand-dial capabilities — most programs
	will need a DNS lookup before doing any other network
	related things.</para>

	<para>In the DNS case, you should try to determine what is
	actually trying to resolve a host name. A lot of the time,
	&man.sendmail.8; is the culprit. You should make sure that
	you tell <application>sendmail</application> not to do any
	DNS lookups in its configuration file. See the section on
	<ulink
	url="&url.books.handbook;/smtp-dialup.html">using email with a dialup connection</ulink>
	in the &os; Handbook for details on how to create your own
	configuration file and what should go into it. You may also
	want to add the following line to
	<filename>.mc</filename>:</para>

	<programlisting>define(`confDELIVERY_MODE', `d')dnl</programlisting>

	<para>This will make <application>sendmail</application> queue
	everything until the queue is run (usually, sendmail is
	run with <option>-bd -q30m</option>, telling it to run
	the queue every 30 minutes) or until a <command>sendmail
	- <option>-q</option></command> is done (perhaps from your
	+ <option>-q</option></command> is done (perhaps from your
	<filename>ppp.linkup</filename>).</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ccp-errors">
	<para>What do these CCP errors mean?</para>
	</question>

	<answer>
	<para>I keep seeing the following errors in my log
	file:</para>

	<programlisting>CCP: CcpSendConfigReq
	CCP: Received Terminate Ack (1) state = Req-Sent (6)</programlisting>

	<para>This is because &man.ppp.8; is trying to negotiate
	Predictor1 compression, and the peer does not want to
	negotiate any compression at all. The messages are
	harmless, but if you wish to remove them, you can disable
	Predictor1 compression locally too:</para>

	<programlisting>disable pred1</programlisting>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-connectionspeed">
	<para>Why does &man.ppp.8; not log my connection speed?</para>
	</question>

	<answer>
	<para>To log all lines of your modem
	<quote>conversation</quote>, you must enable the
	following:</para>

	<programlisting>set log +connect</programlisting>

	<para>This will make &man.ppp.8; log everything up until the
	last requested <quote>expect</quote> string.</para>

	<para>If you wish to see your connect speed and are using PAP
	or CHAP (and therefore do not have anything to
	<quote>chat</quote> after the CONNECT in the dial script
	— no <literal>set login</literal> script), you must
	make sure that you instruct &man.ppp.8; to
	<quote>expect</quote> the whole CONNECT line, something like
	this:</para>

	<programlisting>set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 4 \
	\"\" ATZ OK-ATZ-OK ATDT\\T TIMEOUT 60 CONNECT \\c \\n"</programlisting>

	<para>Here, we get our CONNECT, send nothing, then expect a
	line-feed, forcing &man.ppp.8; to read the whole CONNECT
	response.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-ignores-backslash">
	<para>Why does &man.ppp.8; ignore the <literal>\</literal>
	character in my chat script?</para>
	</question>

	<answer>
	<para>The <application>ppp</application> utility parses each
	line in your config files so that it can interpret strings
	such as <literal>set phone "123 456 789"</literal> correctly
	and realize that the number is actually only
	<emphasis>one</emphasis> argument. To specify a
	<literal>"</literal> character, you must escape it
	using a backslash (<literal>\</literal>).</para>

	<para>When the chat interpreter parses each argument, it
	re-interprets the argument to find any special
	escape sequences such as <literal>\P</literal> or
	<literal>\T</literal> (see the manual page). As a result of
	this double-parsing, you must remember to use the correct
	number of escapes.</para>

	<para>If you wish to actually send a <literal>\</literal>
	character to (say) your modem, you would need something
	like:</para>

	<programlisting>set dial "\"\" ATZ OK-ATZ-OK AT\\\\X OK"</programlisting>

	<para>It will result in the following sequence:</para>

	<programlisting>ATZ
	OK
	AT\X
	OK</programlisting>

	<para>Or:</para>

	<programlisting>set phone 1234567
	set dial "\"\" ATZ OK ATDT\\T"</programlisting>

	<para>It will result in the following sequence:</para>

	<programlisting>ATZ
	OK
	ATDT1234567</programlisting>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-segfault-nocore">
	<para>Why does &man.ppp.8; get a <errorname>Segmentation
	fault</errorname>, but I see no
	<filename>ppp.core</filename></para>
	</question>

	<answer>
	<para>The <application>ppp</application> utility (or any other
	program for that matter) should never dump core. Because
	&man.ppp.8; runs setuid (with an effective user ID of
	<literal>0</literal>), the operating system will not write
	core image of &man.ppp.8; to disk before terminating it.
	If, however &man.ppp.8; is actually terminating due to a
	segmentation violation or some other signal that normally
	causes core to be dumped, <emphasis>and</emphasis> you are
	sure you are using the latest version (see the start of this
	section), then you should install the system sources and do
	the following:</para>

	<screen>&prompt.root; <userinput><command>cd</command> <filename class="directory">/usr/src/usr.sbin/ppp</filename></userinput>
	&prompt.root; <userinput><command>echo</command> <makevar>STRIP</makevar>= >> <filename>/etc/make.conf</filename></userinput>
	&prompt.root; <userinput><command>echo</command> <makevar>CFLAGS</makevar>+=<option>-g</option> >> <filename>/etc/make.conf</filename></userinput>
	&prompt.root; <userinput><command>make</command> <maketarget>install</maketarget> <maketarget>clean</maketarget></userinput></screen>

	<para>You will now have a debuggable version of &man.ppp.8;
	installed. You will have to be <username>root</username> to
	run &man.ppp.8; as all of its privileges have been revoked.
	When you start &man.ppp.8;, take a careful note of what your
	current directory was at the time.</para>

	<para>Now, if and when &man.ppp.8; receives the segmentation
	violation, it will dump a core file called
	<filename>ppp.core</filename>. You should then do the
	following:</para>

	<screen>&prompt.user; <userinput>su</userinput>
	&prompt.root; <userinput>gdb /usr/sbin/ppp ppp.core</userinput>
	<prompt>(gdb)</prompt> <userinput>bt</userinput>
	.....
	<prompt>(gdb)</prompt> <userinput>f 0</userinput>
	....
	<prompt>(gdb)</prompt> <userinput>i args</userinput>
	....
	<prompt>(gdb)</prompt> <userinput>l</userinput>
	.....</screen>

	<para>All of this information should be given alongside your
	question, making it possible to diagnose the problem.</para>

	<para>If you are familiar with &man.gdb.1;, you may wish to
	find out some other bits and pieces such as what actually
	caused the dump or the addresses and values of the relevant
	variables.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-autodialprocess-noconnect">
	<para>Why does the process that forces a dial in
	<option>-auto</option> mode never connect?</para>
	</question>

	<answer>
	<para>This was a known problem with &man.ppp.8; set up to
	negotiate a dynamic local IP number with the peer in
	<option>-auto</option> mode. It has been fixed a long time
	ago — search the manual page for
	<literal>iface</literal>.</para>

	<para>The problem was that when that initial program calls
	&man.connect.2;, the IP number of the &man.tun.4; interface
	is assigned to the socket endpoint. The kernel creates the
	first outgoing packet and writes it to the &man.tun.4;
	device. &man.ppp.8; then reads the packet and establishes a
	connection. If, as a result of &man.ppp.8;'s dynamic IP
	assignment, the interface address is changed, the original
	socket endpoint will be invalid. Any subsequent packets
	sent to the peer will usually be dropped. Even if they are
	not, any responses will not route back to the originating
	machine as the IP number is no longer owned by that
	machine.</para>

	<para>There are several theoretical ways to approach this
	problem. It would be nicest if the peer would re-assign the
	same IP number if possible. The current version of
	&man.ppp.8; does this, but most other implementations do
	not.</para>

	<para>The easiest method from our side would be to never
	change the &man.tun.4; interface IP number, but instead to
	change all outgoing packets so that the source IP number is
	changed from the interface IP to the negotiated IP on the
	fly. This is essentially what the
	<literal>iface-alias</literal> option in the latest version
	of &man.ppp.8; is doing (with the help of &man.libalias.3;
	and &man.ppp.8;'s <option>-nat</option> switch) — it
	is maintaining all previous interface addresses and NATing
	them to the last negotiated address.</para>

	<para>Another alternative (and probably the most reliable)
	would be to implement a system call that changes all bound
	sockets from one IP to another. &man.ppp.8; would use this
	call to modify the sockets of all existing programs when a
	new IP number is negotiated. The same system call could be
	used by <acronym>DHCP</acronym> clients when they are forced
	to call the <function>bind()</function> function for their
	sockets.</para>

	<para>Yet another possibility is to allow an interface to be
	brought up without an IP number. Outgoing packets would be
	given an IP number of <hostid
	role="ipaddr">255.255.255.255</hostid> up until the first
	<literal>SIOCAIFADDR</literal> &man.ioctl.2; is done. This
	would result in fully binding the socket. It would be up to
	&man.ppp.8; to change the source IP number, but only if it
	is set to <hostid role="ipaddr">255.255.255.255</hostid>,
	and only the IP number and IP checksum would need to change.
	This, however is a bit of a hack as the kernel would be
	sending bad packets to an improperly configured interface,
	on the assumption that some other mechanism is capable of
	fixing things retrospectively.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ppp-nat-games">
	<para>Why do most games not work with the
	<option>-nat</option> switch?</para>
	</question>

	<answer>
	<para>The reason games and the like do not work when
	&man.libalias.3; is in use is that the machine on the outside
	will try to open a connection or send (unsolicited) UDP
	packets to the machine on the inside. The NAT software does
	not know that it should send these packets to the interior
	machine.</para>

	<para>To make things work, make sure that the only thing
	running is the software that you are having problems with,
	then either run &man.tcpdump.1; on the &man.tun.4; interface
	of the gateway or enable &man.ppp.8; TCP/IP logging
	(<literal>set log +tcp/ip</literal>) on the gateway.</para>

	<para>When you start the offending software, you should see
	packets passing through the gateway machine. When something
	comes back from the outside, it will be dropped (that is the
	problem). Note the port number of these packets then shut
	down the offending software. Do this a few times to see if
	the port numbers are consistent. If they are, then the
	following line in the relevant section of
	<filename>/etc/ppp/ppp.conf</filename> will make the
	software functional:</para>

	<programlisting>nat port <replaceable>proto</replaceable> <replaceable>internalmachine</replaceable>:<replaceable>port</replaceable> <replaceable>port</replaceable></programlisting>

	<para>where <replaceable>proto</replaceable> is either
	<literal>tcp</literal> or <literal>udp</literal>,
	<replaceable>internalmachine</replaceable> is the machine
	that you want the packets to be sent to and
	<replaceable>port</replaceable> is the destination port
	number of the packets.</para>

	<para>You will not be able to use the software on other
	machines without changing the above command, and running the
	software on two internal machines at the same time is out of
	the question — after all, the outside world is seeing
	your entire internal network as being just a single
	machine.</para>

	<para>If the port numbers are not consistent, there are three
	more options:</para>

	<orderedlist>
	<listitem>
	<para>Submit support in &man.libalias.3;. Examples of
	<quote>special cases</quote> can be found in
	<filename>/usr/src/sys/netinet/libalias/alias_*.c</filename>
	(<filename>alias_ftp.c</filename> is a good prototype).
	This usually involves reading certain recognized
	outgoing packets, identifying the instruction that tells
	the outside machine to initiate a connection back to the
	internal machine on a specific (random) port and setting
	up a <quote>route</quote> in the alias table so that the
	subsequent packets know where to go.</para>

	<para>This is the most difficult solution, but it is the
	best and will make the software work with multiple
	machines.</para>
	</listitem>

	<listitem>
	<para>Use a proxy. The application may support
	<literal>socks5</literal> for example, or
	may have a
	<quote>passive</quote> option that avoids ever
	requesting that the peer open connections back to the
	local machine.</para>
	</listitem>

	<listitem>
	<para>Redirect everything to the internal machine using
	<literal>nat addr</literal>. This is the sledge-hammer
	approach.</para>
	</listitem>
	</orderedlist>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="fcs-errors">
	<para>What are FCS errors?</para>
	</question>

	<answer>
	<para>FCS stands for Frame Check Sequence. Each
	PPP packet has a checksum attached to ensure that the data
	being received is the data being sent. If the FCS of an
	incoming packet is incorrect, the packet is dropped and the
	HDLC FCS count is increased. The HDLC error values can be
	displayed using the <literal>show hdlc</literal>
	command.</para>

	<para>If your link is bad (or if your serial driver is
	dropping packets), you will see the occasional FCS error.
	This is not usually worth worrying about although it does
	slow down the compression protocols substantially. If you
	have an external modem, make sure your cable is properly
	shielded from interference — this may eradicate the
	problem.</para>

	<para>If your link freezes as soon as you have connected and
	you see a large number of FCS errors, this may be because your
	link is not 8-bit clean. Make sure your modem is not using
	software flow control (XON/XOFF). If your datalink
	<emphasis>must</emphasis> use software flow control, use the
	command <literal>set accmap 0x000a0000</literal> to tell
	&man.ppp.8; to escape the <literal>^Q</literal> and
	<literal>^S</literal> characters.</para>

	<para>Another reason for seeing too many FCS errors may be
	that the remote end has stopped talking
	<acronym>PPP</acronym>. You may want to enable
	<literal>async</literal> logging at this point to determine
	if the incoming data is actually a login or shell prompt.
	If you have a shell prompt at the remote end, it is possible
	to terminate &man.ppp.8; without dropping the line by using
	<command>close lcp</command> (a following
	<command>term</command>) will reconnect you to the
	shell on the remote machine.</para>

	<para>If nothing in your log file indicates why the link might
	have been terminated, you should ask the remote
	administrator (your ISP?) why the session was
	terminated.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="desperation">
	<para>None of this helps — I am desperate! What can I
	do?</para>
	</question>

	<answer>
	<para>If all else fails, send as much information as you can,
	including your config files, how you are starting
	&man.ppp.8;, the relevant parts of your log file and the
	output of <command>netstat -rn</command> (before
	and after connecting) to the &a.questions;
	and someone should point you in the right
	direction.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="serial">
	<title>Serial Communications</title>

	<para>This section answers common questions about serial
	communications with &os;. PPP is covered in the <link
	- linkend="networking">Networking</link> section.</para>
	+ linkend="networking">Networking</link> section.</para>

	<qandaset>
	<qandaentry>
	<question id="multiport-serial-support">
	<para>Which multi-port serial cards are supported by
	&os;?</para>
	</question>

	<answer>
	<para>There is a list of these in the <ulink
	url="&url.books.handbook;/serial.html">Serial Communications</ulink>
	chapter of the handbook.</para>

	<para>Most multi-port PCI cards that are based on 16550 or
	clones are supported with no extra effort.</para>

	<para>Some unnamed clone cards have also been known to work,
	especially those that claim to be AST compatible.</para>

	<para>Check &man.uart.4; and &man.sio.4; to get more
	information on configuring such cards.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="serial-console-prompt">
	<para>How do I get the boot: prompt to show on the serial
	console?</para>
	</question>

	<answer>
	<para>See <ulink
	url="&url.books.handbook;/serialconsole-setup.html">this section of the handbook</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="found-serial">
	<para>How do I tell if &os; found my serial ports or modem
	cards?</para>
	</question>

	<answer>
	<para>As the &os; kernel boots, it will probe for the serial
	ports in your system for which the kernel was configured.
	You can either watch your system closely for the messages it
	prints or run this command after your system is up and
	running:</para>

	<screen>&prompt.user; <userinput>dmesg \| grep -E "^sio[0-9]"</userinput></screen>

	<para>Here is some example output from the above
	command:</para>

	<programlisting>sio0: <16550A-compatible COM port> port 0x3f8-0x3ff irq 4 flags 0x10 on acpi0
	sio0: type 16550A
	sio1: <16550A-compatible COM port> port 0x2f8-0x2ff irq 3 on acpi0
	sio1: type 16550A</programlisting>

	<para>This shows two serial ports. The first is on
	IRQ 4, is using port address <literal>0x3f8</literal>,
	and has a 16550A-type UART chip. The second uses the same
	kind of chip but is on IRQ 3 and is at port address
	<literal>0x2f8</literal>. Internal modem cards are treated
	just like serial ports — except that they always have
	a modem <quote>attached</quote> to the port.</para>

	<para>The <filename>GENERIC</filename> kernel includes support
	for two serial ports using the same IRQ and port address
	settings in the above example. If these settings are not
	right for your system, or if you have added modem cards or
	have more serial ports than your kernel is configured for,
	just reconfigure your kernel. See section <link
	linkend="make-kernel">about building a kernel</link> for
	more details.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="access-serial-ports">
	<para>How do I access the serial ports on &os;?</para>
	</question>

	<answer>
	<para>The third serial port, <devicename>sio2</devicename>
	(see &man.sio.4;, known as <devicename>COM3</devicename> in
	DOS), is on <devicename>/dev/cuad2</devicename> for dial-out
	devices, and on <devicename>/dev/ttyd2</devicename> for
	dial-in devices. What is the difference between these two
	classes of devices?</para>

	<para>You use
	<devicename>ttyd<replaceable>X</replaceable></devicename>
	for dial-ins. When opening
	<devicename>/dev/ttyd<replaceable>X</replaceable></devicename>
	in blocking mode, a process will wait for the corresponding
	<devicename>cuad<replaceable>X</replaceable></devicename>
	device to become inactive, and then wait for the carrier
	detect line to go active. When you open the
	<devicename>cuad<replaceable>X</replaceable></devicename>
	device, it makes sure the serial port is not already in use
	by the
	<devicename>ttyd<replaceable>X</replaceable></devicename>
	device. If the port is available, it <quote>steals</quote>
	it from the
	<devicename>ttyd<replaceable>X</replaceable></devicename>
	device. Also, the
	<devicename>cuad<replaceable>X</replaceable></devicename>
	device does not care about carrier detect. With this scheme
	and an auto-answer modem, you can have remote users log in
	and you can still dial out with the same modem and the
	system will take care of all the conflicts.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="enable-multiport-serial">
	<para>How do I enable support for a multiport serial
	card?</para>
	</question>

	<answer>
	<para>Again, the section on kernel configuration provides
	information about configuring your kernel. For a multiport
	serial card, place an &man.sio.4; line for each serial port
	on the card in the &man.device.hints.5; file. But place the
	IRQ specifiers on only one of the entries. All of the ports
	on the card should share one IRQ. For consistency, use the
	last serial port to specify the IRQ. Also, specify the
	following option in the kernel configuration file:</para>

	<programlisting>options COM_MULTIPORT</programlisting>

	<para>The following <filename>/boot/device.hints</filename>
	example is for an AST 4-port serial card on
	IRQ 12:</para>

	<programlisting>hint.sio.4.at="isa"
	hint.sio.4.port="0x2a0"
	hint.sio.4.flags="0x701"
	hint.sio.5.at="isa"
	hint.sio.5.port="0x2a8"
	hint.sio.5.flags="0x701"
	hint.sio.6.at="isa"
	hint.sio.6.port="0x2b0"
	hint.sio.6.flags="0x701"
	hint.sio.7.at="isa"
	hint.sio.7.port="0x2b8"
	hint.sio.7.flags="0x701"
	hint.sio.7.irq="12"</programlisting>

	<para>The flags indicate that the master port has minor number
	<literal>7</literal> (<literal>0x700</literal>), and all the
	ports share an IRQ (<literal>0x001</literal>).</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="default-serial-params">
	<para>Can I set the default serial parameters for a
	port?</para>
	</question>

	<answer>
	<para>See the <ulink
	url="&url.books.handbook;/serial.html#serial-hw-config">Serial Communications</ulink>
	section in the &os; Handbook.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="enable-dialup">
	<para>How can I enable dialup logins on my modem?</para>
	</question>

	<answer>
	<para>Please read the section about <ulink
	url="&url.books.handbook;/dialup.html">Dial-in Services</ulink>
	in the &os; Handbook.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="dumb-terminal">
	<para>How can I connect a dumb terminal to my &os; box?</para>
	</question>

	<answer>
	<para>You can find this information in the <ulink
	url="&url.books.handbook;/term.html">Terminals</ulink>
	section of the &os; Handbook.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="cannot-tip">
	<para>Why can I not run <command>tip</command> or
	<command>cu</command>?</para>
	</question>

	<answer>
	<para>On your system, the programs &man.tip.1; and &man.cu.1;
	can only access the <filename class="directory">/var/spool/lock</filename>
	directory via user <username>uucp</username> and group
	<groupname>dialer</groupname>. You can use the group
	<groupname>dialer</groupname> to control who has access to
	your modem or remote systems. Just add yourself to group
	<groupname>dialer</groupname>.</para>

	<para>Alternatively, you can let everyone on your system run
	&man.tip.1; and &man.cu.1; by typing:</para>

	<screen>&prompt.root; <userinput>chmod 4511 /usr/bin/cu</userinput>
	&prompt.root; <userinput>chmod 4511 /usr/bin/tip</userinput></screen>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="misc">
	<title>Miscellaneous Questions</title>

	<qandaset>
	<qandaentry>
	<question id="more-swap">
	<para>&os; a lot of swap space even when the computer has
	free memory left. Why?</para>
	</question>

	<answer>
	<para>&os; will proactively
	move entirely idle, unused pages of main memory into swap in
	order to make more main memory available for active use.
	This heavy use of swap is balanced by using the extra free
	memory for cacheing.</para>

	<para>Note that while &os; is proactive in this regard, it
	does not arbitrarily decide to swap pages when the system is
	truly idle. Thus you will not find your system all paged
	out when you get up in the morning after leaving it idle
	overnight.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="top-freemem">
	<para>Why does <command>top</command> show very little free
	memory even when I have very few programs running?</para>
	</question>

	<answer>
	<para>The simple answer is that free memory is wasted memory.
	Any memory that your programs do not actively allocate is
	used within the &os; kernel as disk cache. The values shown
	by &man.top.1; labeled as <literal>Inact</literal>,
	<literal>Cache</literal>, and <literal>Buf</literal> are all
	cached data at different aging levels. This cached data
	means the system does not have to access a slow disk again
	for data it has accessed recently, thus increasing overall
	performance. In general, a low value shown for
	<literal>Free</literal> memory in &man.top.1; is good,
	provided it is not <emphasis>very</emphasis> low.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="chmod-symlinks">
	<para>Why will <command>chmod</command> not change the
	permissions on symlinks?</para>
	</question>

	<answer>
	<para>Symlinks do not have permissions, and by default,
	&man.chmod.1; will follow symlinks to change the
	permissions on the source file, if possible. So if you have a file,
	<filename>foo</filename>, and a symlink to that file,
	<filename>bar</filename>, then this command will always
	succeed.</para>

	<screen>&prompt.user; <userinput>chmod g-w bar</userinput></screen>

	<para>However, the permissions on <filename>bar</filename>
	will not have changed.</para>

	<para>When changing modes of the file hierarchies rooted in the
	files instead of the files themselves,
	you have to use either <option>-H</option> or
	<option>-L</option> together with <option>-R</option>
	to make this work. See &man.chmod.1; and
	&man.symlink.7; for more information.</para>

	<warning>
	<para><option>-R</option> does a
	<emphasis>recursive</emphasis> &man.chmod.1;. Be careful
	about specifying directories or symlinks to directories to
	&man.chmod.1;. If you want to change the permissions of a
	directory referenced by a symlink, use &man.chmod.1;
	without any options and follow the symlink with a trailing
	slash (<filename class="directory">/</filename>). For example, if
	<filename>foo</filename> is a symlink to directory
	<filename class="directory">bar</filename>, and you want to change the
	permissions of <filename>foo</filename> (actually
	<filename class="directory">bar</filename>), you would do something
	like:</para>

	<screen>&prompt.user; <userinput>chmod 555 foo/</userinput></screen>

	<para>With the trailing slash, &man.chmod.1; will follow the
	symlink, <filename>foo</filename>, to change the
	permissions of the directory,
	<filename class="directory">bar</filename>.</para>
	</warning>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="dos-binaries">
	<para>Can I run DOS binaries under &os;?</para>
	</question>

	<answer>
	<para>Yes, you can use <filename
	role="package">emulators/doscmd</filename>, a DOS
	emulation program, available in the &os; Ports
	Collection.</para>

	<para>If <application>doscmd</application> will not suffice,
	the add-on utility <filename
	role="package">emulators/pcemu</filename> emulates an 8088
	and enough BIOS services to run many DOS text mode
	applications. It requires the X Window System.</para>

	<para>You may also try <filename
	role="package">emulators/dosbox</filename> from the &os;
	Ports Collection. The main focus of this application is
	emulating old DOS games using the local file system for
	files.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="translation">
	<para>What do I need to do to translate a &os; document into
	my native language?</para>
	</question>

	<answer>
	<para>See the <ulink
	url="&url.books.fdp-primer;/translations.html">Translation FAQ</ulink>
	in the &os; Documentation Project Primer.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="freebsd-mail-bounces">
	<para>Why does my email to any address at <hostid
	role="domainname">FreeBSD.org</hostid> bounce?</para>
	</question>

	<answer>
	<para>The <hostid role="domainname">FreeBSD.org</hostid> mail
	system implements some
	<application>Postfix</application> checks on incoming mail
	and rejects mail that is either from misconfigured relays or
	otherwise appears likely to be spam. Some of the
	specific requirements are: </para>

	<itemizedlist>
	<listitem>
	<para>The IP address of the SMTP client must
	"reverse-resolve" to a forward
	confirmed hostname.</para>
	</listitem>

	<listitem>
	<para>The fully-qualified hostname given in the
	SMTP conversation (either HELO or EHLO) must resolve
	to the IP address of the client.</para>
	</listitem>
	</itemizedlist>

	<para>Other advice to help your mail reach its destination
	include:</para>

	<itemizedlist>
	<listitem>
	<para>Mail should be sent in plain text, and messages
	sent to mailing lists should generally be no more than
	200KB in length.</para>
	</listitem>

	<listitem>
	<para>Avoid excessive cross posting. Choose
	<emphasis>one</emphasis> mailing list which seems most
	relevant and send it there.</para>
	</listitem>
	</itemizedlist>

	<para>If you still have trouble with email infrastructure at
	<hostid role="domainname">FreeBSD.org</hostid> send a note
	with the details to
	<email>postmaster@freebsd.org</email>; Include a
	date/time interval so that logs may be reviewed —
	and note that we only keep one week's worth of mail logs.
	(Be sure to specify the time zone or offset from
	UTC.)</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="free-account">
	<para>Where can I find a free &os; account?</para>
	</question>

	<answer>
	<para>While &os; does not provide open access to any of their
	servers, others do provide open access &unix; systems. The
	charge varies and limited services may be available.</para>

	<para><ulink
	url="http://www.arbornet.org/">Arbornet, Inc</ulink>,
	also known as <emphasis>M-Net</emphasis>, has been providing
	open access to &unix; systems since 1983. Starting on an
	Altos running System III, the site switched to BSD/OS in
	1991. In June of 2000, the site switched again to &os;.
	<emphasis>M-Net</emphasis> can be accessed via
	<application>telnet</application> and
	<application>SSH</application> and provides basic access to
	the entire &os; software suite. However, network access is
	limited to members and patrons who donate to the system,
	which is run as a non-profit organization.
	<emphasis>M-Net</emphasis> also provides an bulletin board
	system and interactive chat.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="daemon-name">
	<para>What is the cute little red guy's name?</para>
	</question>

	<answer>
	<para>He does not have one, and is just called <quote>the BSD
	- daemon</quote>. If you insist upon using a name, call him
	+ daemon</quote>. If you insist upon using a name, call him
	<quote>beastie</quote>. Note that <quote>beastie</quote> is
	pronounced <quote>BSD</quote>.</para>

	<para>You can learn more about the BSD daemon on his <ulink
	url="http://www.mckusick.com/beastie/index.html">home page</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="use-beastie">
	<para>Can I use the BSD daemon image?</para>
	</question>

	<answer>
	<para>Perhaps. The BSD daemon is copyrighted by Marshall Kirk
	McKusick. You will want to check his <ulink
	url="http://www.mckusick.com/beastie/mainpage/copyright.html">Statement on the Use of the BSD Daemon Figure</ulink>
	for detailed usage terms.</para>

	<para>In summary, you are free to use the image in a tasteful
	manner, for personal use, so long as appropriate credit is
	given. If you want to use him commercially, you must
	contact &a.mckusick.email;. More details are available on the
	<ulink
	url="http://www.mckusick.com/beastie/index.html">BSD Daemon's home page</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="daemon-images">
	<para>Do you have any BSD daemon images I could use?</para>
	</question>

	<answer>
	<para>You will find eps and Xfig drawings under
	<filename class="directory">/usr/share/examples/BSD_daemon/</filename>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="glossary">
	<para>I have seen an acronym or other term on the mailing
	lists and I do not understand what it means. Where should I
	look?</para>
	</question>

	<answer>
	<para>Please see the <ulink
	url="&url.books.handbook;/freebsd-glossary.html">&os; Glossary</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="bikeshed-painting">
	<para>Why should I care what color the bikeshed is?</para>
	</question>

	<answer>
	<para>The really, really short answer is that you should not.
	The somewhat longer answer is that just because you are
	capable of building a bikeshed does not mean you should stop
	others from building one just because you do not like the
	color they plan to paint it. This is a metaphor indicating
	that you need not argue about every little feature just
	because you know enough to do so. Some people have
	commented that the amount of noise generated by a change is
	inversely proportional to the complexity of the
	change.</para>

	<para>The longer and more complete answer is that after a very
	long argument about whether &man.sleep.1; should take
	fractional second arguments, &a.phk.email; posted a long message
	entitled <quote><ulink
	- url="http://www.FreeBSD.org/cgi/getmsg.cgi?fetch=506636+517178+/usr/local/www/db/text/1999/freebsd-hackers/19991003.freebsd-hackers">A bike shed (any color will do) on greener grass...</ulink></quote>.
	+ url="http://www.FreeBSD.org/cgi/getmsg.cgi?fetch=506636+517178+/usr/local/www/db/text/1999/freebsd-hackers/19991003.freebsd-hackers">A bike shed (any color will do) on greener grass...</ulink></quote>.
	The appropriate portions of that message are quoted
	below.</para>

	<blockquote>
	<attribution>&a.phk.email; on &a.hackers.name;, October 2,
	1999</attribution>

	<para><quote>What is it about this bike shed?</quote> Some
	of you have asked me.</para>

	<para>It is a long story, or rather it is an old story, but
	it is quite short actually. C. Northcote Parkinson wrote
	a book in the early 1960s, called <quote>Parkinson's
	- Law</quote>, which contains a lot of insight into the
	+ Law</quote>, which contains a lot of insight into the
	dynamics of management.</para>

	<para><emphasis>[snip a bit of commentary on the
	- book]</emphasis></para>
	+ book]</emphasis></para>

	<para>In the specific example involving the bike shed, the
	other vital component is an atomic power-plant, I guess
	that illustrates the age of the book.</para>

	<para>Parkinson shows how you can go into the board of
	directors and get approval for building a multi-million or
	even billion dollar atomic power plant, but if you want to
	build a bike shed you will be tangled up in endless
	discussions.</para>

	<para>Parkinson explains that this is because an atomic
	plant is so vast, so expensive and so complicated that
	people cannot grasp it, and rather than try, they fall
	back on the assumption that somebody else checked all the
	details before it got this far. Richard P. Feynmann
	gives a couple of interesting, and very much to the point,
	examples relating to Los Alamos in his books.</para>

	<para>A bike shed on the other hand. Anyone can build one
	of those over a weekend, and still have time to watch the
	game on TV. So no matter how well prepared, no matter how
	reasonable you are with your proposal, somebody will seize
	the chance to show that he is doing his job, that he is
	paying attention, that he is
	<emphasis>here</emphasis>.</para>

	<para>In Denmark we call it <quote>setting your
	- fingerprint</quote>. It is about personal pride and
	+ fingerprint</quote>. It is about personal pride and
	prestige, it is about being able to point somewhere and
	say <quote>There! <emphasis>I</emphasis> did
	- that.</quote> It is a strong trait in politicians, but
	+ that.</quote> It is a strong trait in politicians, but
	present in most people given the chance. Just think about
	footsteps in wet cement.</para>
	</blockquote>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="funnies">
	<title>The &os; Funnies</title>

	<qandaset>
	<qandaentry>
	<question id="very-very-cool">
	<para>How cool is &os;?</para>
	</question>

	<answer>
	<para>Q. Has anyone done any temperature testing while
	running &os;? I know &linux; runs cooler than DOS, but have
	never seen a mention of &os;. It seems to run really
	hot.</para>

	<para>A. No, but we have done numerous taste tests on
	blindfolded volunteers who have also had 250 micrograms of
	LSD-25 administered beforehand. 35% of the volunteers said
	that &os; tasted sort of orange, whereas &linux; tasted like
	purple haze. Neither group mentioned any significant
	variances in temperature. We eventually had to throw the
	results of this survey out entirely anyway when we found
	that too many volunteers were wandering out of the room
	during the tests, thus skewing the results. We think most
	of the volunteers are at Apple now, working on their new
	<quote>scratch and sniff</quote> GUI. It is a funny old
	business we are in!</para>

	<para>Seriously, &os; uses the
	<acronym>HLT</acronym> (halt) instruction when the system is
	idle thus lowering its energy consumption and therefore the
	heat it generates. Also if you have
	<acronym>ACPI</acronym> (Advanced
	Configuration and Power Interface)
	configured, then &os; can also put the CPU into
	a low power mode.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="letmeoutofhere">
	<para>Who is scratching in my memory banks??</para>
	</question>

	<answer>
	<para>Q. Is there anything <quote>odd</quote> that &os; does
	when compiling the kernel which would cause the memory to
	make a scratchy sound? When compiling (and for a brief
	moment after recognizing the floppy drive upon startup, as
	well), a strange scratchy sound emanates from what appears
	to be the memory banks.</para>

	<para>A. Yes! You will see frequent references to
	<quote>daemons</quote> in the BSD documentation, and what
	most people do not know is that this refers to genuine,
	non-corporeal entities that now possess your computer. The
	scratchy sound coming from your memory is actually
	high-pitched whispering exchanged among the daemons as they
	best decide how to deal with various system administration
	tasks.</para>

	<para>If the noise gets to you, a good
	<command>fdisk /mbr</command> from DOS will get rid of them,
	but do not be surprised if they react adversely and try to
	stop you. In fact, if at any point during the exercise you
	hear the satanic voice of Bill Gates coming from the
	built-in speaker, take off running and do not ever look
	back! Freed from the counterbalancing influence of the BSD
	daemons, the twin demons of DOS and &windows; are often able
	to re-assert total control over your machine to the eternal
	damnation of your soul. Now that you know, given a choice
	you would probably prefer to get used to the scratchy
	noises, no?</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="changing-lightbulbs">
	<para>How many &os; hackers does it take to change a
	lightbulb?</para>
	</question>

	<answer>
	<para>One thousand, one hundred and sixty-nine:</para>

	<para>Twenty-three to complain to -CURRENT about the lights
	being out;</para>

	<para>Four to claim that it is a configuration problem, and
	that such matters really belong on -questions;</para>

	<para>Three to submit PRs about it, one of which is misfiled
	under doc and consists only of <quote>it's
	- dark</quote>;</para>
	+ dark</quote>;</para>

	<para>One to commit an untested lightbulb which breaks
	buildworld, then back it out five minutes later;</para>

	<para>Eight to flame the PR originators for not including
	patches in their PRs;</para>

	<para>Five to complain about buildworld being broken;</para>

	<para>Thirty-one to answer that it works for them, and they
	must have updated at a bad time;</para>

	<para>One to post a patch for a new lightbulb to
	-hackers;</para>

	<para>One to complain that he had patches for this three years
	ago, but when he sent them to -CURRENT they were just
	ignored, and he has had bad experiences with the PR system;
	besides, the proposed new lightbulb is non-reflexive;</para>

	<para>Thirty-seven to scream that lightbulbs do not belong in
	the base system, that committers have no right to do things
	like this without consulting the Community, and WHAT IS
	-CORE DOING ABOUT IT!?</para>

	<para>Two hundred to complain about the color of the bicycle
	shed;</para>

	<para>Three to point out that the patch breaks
	&man.style.9;;</para>

	<para>Seventeen to complain that the proposed new lightbulb is
	under GPL;</para>

	<para>Five hundred and eighty-six to engage in a flame war
	about the comparative advantages of the GPL, the BSD
	license, the MIT license, the NPL, and the personal hygiene
	of unnamed FSF founders;</para>

	<para>Seven to move various portions of the thread to -chat
	and -advocacy;</para>

	<para>One to commit the suggested lightbulb, even though it
	shines dimmer than the old one;</para>

	<para>Two to back it out with a furious flame of a commit
	message, arguing that &os; is better off in the dark than
	with a dim lightbulb;</para>

	<para>Forty-six to argue vociferously about the backing out of
	the dim lightbulb and demanding a statement from
	-core;</para>

	<para>Eleven to request a smaller lightbulb so it will fit
	their Tamagotchi if we ever decide to port &os; to that
	platform;</para>

	<para>Seventy-three to complain about the SNR on -hackers and
	-chat and unsubscribe in protest;</para>

	<para>Thirteen to post <quote>unsubscribe</quote>, <quote>How
	- do I unsubscribe?</quote>, or <quote>Please remove me from
	- the list</quote>, followed by the usual footer;</para>
	+ do I unsubscribe?</quote>, or <quote>Please remove me from
	+ the list</quote>, followed by the usual footer;</para>

	<para>One to commit a working lightbulb while everybody is too
	busy flaming everybody else to notice;</para>

	<para>Thirty-one to point out that the new lightbulb would
	shine 0.364% brighter if compiled with TenDRA (although it
	will have to be reshaped into a cube), and that &os; should
	therefore switch to TenDRA instead of GCC;</para>

	<para>One to complain that the new lightbulb lacks
	fairings;</para>

	<para>Nine (including the PR originators) to ask <quote>what
	- is MFC?</quote>;</para>
	+ is MFC?</quote>;</para>

	<para>Fifty-seven to complain about the lights being out two
	weeks after the bulb has been changed.</para>

	<para><emphasis>&a.nik.email; adds:</emphasis></para>

	<para><emphasis>I was laughing quite hard at
	- this.</emphasis></para>
	+ this.</emphasis></para>

	<para><emphasis>And then I thought, <quote>Hang on, shouldn't
	- there be '1 to document it.' in that list
	- somewhere?</quote></emphasis></para>
	+ there be '1 to document it.' in that list
	+ somewhere?</quote></emphasis></para>

	<para><emphasis>And then I was enlightened
	- :-)</emphasis></para>
	+ :-)</emphasis></para>

	<para><emphasis>&a.tabthorpe.email;</emphasis> says: <quote>None,
	- <emphasis>real</emphasis> &os; hackers are not afraid of the
	- dark!</quote></para>
	+ <emphasis>real</emphasis> &os; hackers are not afraid of the
	+ dark!</quote></para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="dev-null">
	<para>Where does data written to
	<filename>/dev/null</filename> go?</para>
	</question>

	<answer>
	<para>It goes into a special data sink in the CPU where it is
	converted to heat which is vented through the heatsink / fan
	assembly. This is why CPU cooling is increasingly
	important; as people get used to faster processors, they
	become careless with their data and more and more of it ends
	up in <filename>/dev/null</filename>, overheating their
	CPUs. If you delete <filename>/dev/null</filename> (which
	effectively disables the CPU data sink) your CPU may run
	cooler but your system will quickly become constipated with
	all that excess data and start to behave erratically. If
	you have a fast network connection you can cool down your
	CPU by reading data out of <filename>/dev/random</filename>
	and sending it off somewhere; however you run the risk of
	overheating your network connection and
	<filename class="directory">/</filename> or angering your ISP, as most of the
	data will end up getting converted to heat by their
	equipment, but they generally have good cooling, so if you
	do not overdo it you should be OK.</para>

	<para><emphasis>Paul Robinson adds:</emphasis></para>

	<para>There are other methods. As every good sysadmin knows,
	it is part of standard practice to send data to the screen
	of interesting variety to keep all the pixies that make up
	your picture happy. Screen pixies (commonly mis-typed or
	re-named as <quote>pixels</quote>) are categorized by the
	type of hat they wear (red, green or blue) and will hide or
	appear (thereby showing the color of their hat) whenever
	they receive a little piece of food. Video cards turn data
	into pixie-food, and then send them to the pixies —
	the more expensive the card, the better the food, so the
	better behaved the pixies are. They also need constant
	stimulation — this is why screen savers exist.</para>

	<para>To take your suggestions further, you could just throw
	the random data to console, thereby letting the pixies
	consume it. This causes no heat to be produced at all,
	keeps the pixies happy and gets rid of your data quite
	quickly, even if it does make things look a bit messy on
	your screen.</para>

	<para>Incidentally, as an ex-admin of a large ISP who
	experienced many problems attempting to maintain a stable
	temperature in a server room, I would strongly discourage
	people sending the data they do not want out to the network.
	The fairies who do the packet switching and routing get
	annoyed by it as well.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="punk-my-friend">
	<para>My colleague sits at the computer too much, how
	can I prank her?</para>
	</question>

	<answer>
	<para>Install <filename role="port">games/sl</filename> and wait
	for her to mistype <userinput>sl</userinput> for
	<command>ls</command>.</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="advanced">
	<title>Advanced Topics</title>

	<qandaset>
	<qandaentry>
	<question id="learn-advanced">
	<para>How can I learn more about &os;'s internals?</para>
	</question>

	<answer>
	<para>See the
	<ulink
	url="&url.books.arch-handbook;">&os; Architecture Handbook</ulink>.</para>

	<para>Additionally, much general &unix; knowledge is directly
	applicable to &os;.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="how-to-contribute">
	<para>How can I contribute to &os;?</para>
	</question>

	<answer>
	<para>Please see the article on <ulink
	url="&url.articles.contributing;/article.html">Contributing to &os;</ulink>
	for specific advice on how to do this. Assistance is more
	than welcome!</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="define-snap-release">
	<para>What are snapshots and releases?</para>
	</question>

	<answer>
	<para>There are currently four active/semi-active branches in
	the &os; <ulink
	url="http://svnweb.FreeBSD.org/base/">Subversion Repository</ulink>.
	(Earlier branches are only changed very rarely, which is why
	there are only four active branches of development):</para>

	<itemizedlist>
	<listitem>
	- <para>&rel3.releng; AKA
	- &rel3.stable;</para>
	- </listitem>
	-
	- <listitem>
	<para>&rel2.releng; AKA
	&rel2.stable;</para>
	</listitem>

	<listitem>
	<para>&rel.releng; AKA
	&rel.stable;</para>
	</listitem>

	<listitem>
	<para>&rel.head.releng; AKA
	<emphasis>-CURRENT</emphasis> AKA
	&rel.head;</para>
	</listitem>
	</itemizedlist>

	<para><literal>HEAD</literal> is not an actual branch tag,
	like the others; it is simply a symbolic constant for
	<quote><emphasis>the current, non-branched development
	- stream</emphasis></quote> which we simply refer to as
	+ stream</emphasis></quote> which we simply refer to as
	<emphasis>-CURRENT</emphasis>.</para>

	<para>Right now, <emphasis>-CURRENT</emphasis> is the
	&rel.head.relx; development stream; the
	&rel.stable; branch,
	&rel.releng;, forked off from
	<emphasis>-CURRENT</emphasis> in &rel.relengdate; and the
	&rel2.stable; branch,
	&rel2.releng;, forked off from
	<emphasis>-CURRENT</emphasis> in &rel2.relengdate;.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="ctm">
	<para>Can I follow <emphasis>-CURRENT</emphasis> with limited
	Internet access?</para>
	</question>

	<answer>
	<para>Yes, you can do this <emphasis>without</emphasis>
	downloading the whole source tree by using the <ulink
	url="&url.books.handbook;/synching.html#ctm">CTM facility</ulink>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="submitting-kernel-extensions">
	<para>I have written a kernel extension, who do I send it
	to?</para>
	</question>

	<answer>
	<para>Please take a look at the article on <ulink
	url="&url.articles.contributing;/article.html">Contributing to &os;</ulink>
	to learn how to submit code.</para>

	<para>And thanks for the thought!</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="kernel-panic-troubleshooting">
	<para>How can I make the most of the data I see when my kernel
	panics?</para>
	</question>

	<answer>
	<para>Here is typical kernel panic:</para>

	<programlisting>Fatal trap 12: page fault while in kernel mode
	fault virtual address = 0x40
	fault code = supervisor read, page not present
	instruction pointer = 0x8:0xf014a7e5
	stack pointer = 0x10:0xf4ed6f24
	frame pointer = 0x10:0xf4ed6f28
	code segment = base 0x0, limit 0xfffff, type 0x1b
	= DPL 0, pres 1, def32 1, gran 1
	processor eflags = interrupt enabled, resume, IOPL = 0
	current process = 80 (mount)
	interrupt mask =
	trap number = 12
	panic: page fault</programlisting>

	<para>When you see a message like this, it is not enough to
	just reproduce it and send it in. The instruction pointer
	value is important;
	unfortunately, it is also configuration dependent. In other
	words, the value varies depending on the exact kernel image
	that you are using. If you are using a
	<filename>GENERIC</filename> kernel image from one of the
	snapshots, then it is possible for somebody else to track
	down the offending function, but if you are running a custom
	kernel then only <emphasis>you</emphasis> can tell us where
	the fault occurred.</para>

	<para>What you should do is this:</para>

	<procedure>
	<step>
	<para>Write down the instruction pointer value. Note
	that the <literal>0x8:</literal> part at the beginning
	is not significant in this case: it is the
	<literal>0xf0xxxxxx</literal> part that we
	want.</para>
	</step>

	<step>
	<para>When the system reboots, do the following:</para>

	<screen>&prompt.user; <userinput><command>nm</command> <option>-n</option> <replaceable>kernel.that.caused.the.panic</replaceable> \| <command>grep</command> f0xxxxxx</userinput></screen>

	<para>where <literal>f0xxxxxx</literal> is the
	instruction pointer value. The odds are you will not
	get an exact match since the symbols in the kernel
	symbol table are for the entry points of functions and
	the instruction pointer address will be somewhere
	inside a function, not at the start. If you do not
	get an exact match, omit the last digit from the
	instruction pointer value and try again, i.e.:</para>

	<screen>&prompt.user; <userinput><command>nm</command> <option>-n</option> <replaceable>kernel.that.caused.the.panic</replaceable> \| <command>grep</command> f0xxxxx</userinput></screen>

	<para>If that does not yield any results, chop off another
	digit. Repeat until you get some sort of output. The
	result will be a possible list of functions which caused
	the panic. This is a less than exact mechanism for
	tracking down the point of failure, but it is better
	than nothing.</para>
	</step>
	</procedure>

	<para>However, the best way to track down the cause of a panic
	is by capturing a crash dump, then using &man.kgdb.1; to
	generate a stack trace on the crash dump.</para>

	<para>In any case, the method is this:</para>

	<procedure>
	<step>
	<para>Make sure that the following line is included in
	your kernel configuration file
	(<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/<replaceable>MYKERNEL</replaceable></filename>):</para>

	<programlisting>makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols</programlisting>
	</step>

	<step>
	<para>Change to the <filename
	class="directory">/usr/src</filename>
	directory:</para>

	<screen>&prompt.root; <userinput><command>cd</command> <filename class="directory">/usr/src</filename></userinput></screen>
	</step>

	<step>
	<para>Compile the kernel:</para>

	<screen>&prompt.root; <userinput><command>make</command> <maketarget>buildkernel</maketarget> <makevar>KERNCONF</makevar>=<replaceable>MYKERNEL</replaceable></userinput></screen>
	</step>

	<step>
	<para>Wait for &man.make.1; to finish compiling.</para>
	</step>

	<step>
	<screen>&prompt.root; <userinput><command>make</command> <maketarget>installkernel</maketarget> <makevar>KERNCONF</makevar>=<replaceable>MYKERNEL</replaceable></userinput></screen>
	</step>

	<step>
	<para>Reboot.</para>
	</step>
	</procedure>

	<note>
	<para>If you do not use the <makevar>KERNCONF</makevar>
	make variable a <filename>GENERIC</filename> kernel will
	be built and installed.</para>
	</note>

	<para>The &man.make.1; process will have built two kernels.
	<filename>/usr/obj/usr/src/sys/<replaceable>MYKERNEL</replaceable>/kernel</filename>
	and
	<filename>/usr/obj/usr/src/sys/<replaceable>MYKERNEL</replaceable>/kernel.debug</filename>.
	<filename>kernel</filename> was installed as
	<filename>/boot/kernel/kernel</filename>, while
	<filename>kernel.debug</filename> can be used as the source
	of debugging symbols for &man.kgdb.1;.</para>

	<para>To make sure you capture a crash dump, you need edit
	<filename>/etc/rc.conf</filename> and set
	<literal>dumpdev</literal> to point to your swap partition
	(or <literal>AUTO</literal>). This will cause the
	&man.rc.8; scripts to use the &man.dumpon.8; command to
	enable crash dumps. You can also run &man.dumpon.8;
	manually. After a panic, the crash dump can be recovered
	using &man.savecore.8;; if <literal>dumpdev</literal> is set
	in <filename>/etc/rc.conf</filename>, the &man.rc.8; scripts
	will run &man.savecore.8; automatically and put the crash
	dump in <filename class="directory">/var/crash</filename>.</para>

	<note>
	<para>&os; crash dumps are usually the same size as the
	physical RAM size of your machine. That is, if you have
	512 MB of RAM, you will get a 512 MB crash dump.
	Therefore you must make sure there is enough space in
	<filename class="directory">/var/crash</filename> to hold the dump.
	Alternatively, you run &man.savecore.8; manually and have
	it recover the crash dump to another directory where you
	have more room. It is possible to limit the size of the
	crash dump by using <literal>options
	- MAXMEM=<replaceable>N</replaceable></literal> where
	+ MAXMEM=<replaceable>N</replaceable></literal> where
	<replaceable>N</replaceable> is the size of kernel's
	memory usage in KBs. For example, if you have 1 GB
	of RAM, you can limit the kernel's memory usage to
	128 MB by this way, so that your crash dump size will
	be 128 MB instead of 1 GB.</para>
	</note>

	<para>Once you have recovered the crash dump, you can get a
	stack trace with &man.kgdb.1; as follows:</para>

	<screen>&prompt.user; <userinput><command>kgdb</command> <filename>/usr/obj/usr/src/sys/<replaceable>MYKERNEL</replaceable>/kernel.debug</filename> <filename class="directory">/var/crash/<replaceable>vmcore.0</replaceable></filename></userinput>
	<prompt>(kgdb)</prompt> <userinput>backtrace</userinput></screen>

	<para>Note that there may be several screens worth of
	information; ideally you should use &man.script.1; to
	capture all of them. Using the unstripped kernel image with
	all the debug symbols should show the exact line of kernel
	source code where the panic occurred. Usually you have to
	read the stack trace from the bottom up to trace
	the exact sequence of events that lead to the crash. You
	can also use &man.kgdb.1; to print out the contents of
	various variables or structures to examine the
	system state at the time of the crash.</para>

	<tip>
	<para>Now, if you are really insane and have a second
	computer, you can also configure &man.kgdb.1; to do remote
	debugging such that you can use &man.kgdb.1; on one system
	to debug the kernel on another system, including setting
	breakpoints, single-stepping through the kernel code, just
	like you can do with a normal user-mode program.</para>
	</tip>

	<note>
	<para>If you have <literal>DDB</literal> enabled and the
	kernel drops into the debugger, you can force a panic (and
	a crash dump) just by typing <literal>panic</literal> at
	the <literal>ddb</literal> prompt. It may stop in the
	debugger again during the panic phase. If it does, type
	<literal>continue</literal> and it will finish the crash
	dump.</para>
	</note>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="dlsym-failure">
	<para>Why has <function>dlsym()</function> stopped working for
	ELF executables?</para>
	</question>

	<answer>
	<para>The ELF toolchain does not, by default, make the symbols
	defined in an executable visible to the dynamic linker.
	Consequently <function>dlsym()</function> searches on
	handles obtained from calls to <function>dlopen(NULL,
	flags)</function> will fail to find such symbols.</para>

	<para>If you want to search, using
	<function>dlsym()</function>, for symbols present in the
	main executable of a process, you need to link the
	executable using the <option>--export-dynamic</option>
	option to the ELF linker (&man.ld.1;).</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question id="change-kernel-address-space">
	<para>How can I increase or reduce the kernel address space on
	i386?</para>
	</question>

	<answer>
	<para>By default, the kernel address space is 1 GB
	(2 GB for PAE) for i386. If you run a
	network-intensive server (e.g., a FTP or HTTP server),
	or you want to use ZFS, you might find that is not
	enough.</para>

	<para>Add the following line to your kernel configuration file
	to increase available space and rebuild your kernel:</para>

	<programlisting>options KVA_PAGES=<replaceable>N</replaceable></programlisting>

	<para>To find the correct value of
	<replaceable>N</replaceable>, divide the desired address
	space size (in megabytes) by four. (For example, it is
	<literal>512</literal> for 2 GB.)</para>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>

	<chapter id="acknowledgments">
	<title>Acknowledgments</title>

	<para>This innocent little Frequently Asked Questions document has
	been written, rewritten, edited, folded, spindled, mutilated,
	eviscerated, contemplated, discombobulated, cogitated,
	regurgitated, rebuilt, castigated, and reinvigorated over the last
	decade, by a cast of hundreds if not thousands.
	Repeatedly.</para>

	<para>We wish to thank every one of the people responsible, and we
	encourage you to <ulink
	url="&url.articles.contributing;/article.html">join them</ulink>
	in making this FAQ even better.</para>
	</chapter>

	&bibliography;
	</book>
	Index: projects/entities/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml (revision 41355)
	@@ -1,302 +1,312 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!-- Copyright (c) 1998, 1999 Nik Clayton, 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 NIK CLAYTON "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$
	-->

	<chapter id="overview">
	<title>Overview</title>

	<para>Welcome to the FreeBSD Documentation Project. Good quality
	documentation is very important to the success of FreeBSD, and the
	FreeBSD Documentation Project (FDP) is how a lot of that
	documentation is produced. Your contributions are very
	valuable.</para>

	<para>This document's main purpose is to clearly explain
	<emphasis>how the FDP is organized</emphasis>, <emphasis>how to
	write and submit documentation to the FDP</emphasis>, and
	<emphasis>how to effectively use the tools available to you when
	writing documentation</emphasis>.</para>

	<indexterm>
	<primary>Membership</primary>
	</indexterm>
	<para>Everyone is welcome to join the FDP. There is no minimum
	membership requirement, no quota of documentation you need to
	produce per month. All you need to do is subscribe to the
	&a.doc;.</para>

	<para>After you have finished reading this document you
	should:</para>

	<itemizedlist>
	<listitem>
	<para>Know which documentation is maintained by the FDP.</para>
	</listitem>

	<listitem>
	<para>Be able to read and understand the XML source code for
	the documentation maintained by the FDP.</para>
	</listitem>

	<listitem>
	<para>Be able to make changes to the documentation.</para>
	</listitem>

	<listitem>
	<para>Be able to submit your changes back for review and
	eventual inclusion in the FreeBSD documentation.</para>
	</listitem>
	</itemizedlist>

	<sect1 id="overview-doc">
	<title>The FreeBSD Documentation Set</title>

	<para>The FDP is responsible for four categories of FreeBSD
	documentation.</para>

	<variablelist>
	<varlistentry>
	<term>Manual pages</term>

	<listitem>
	<para>The English language system manual pages are not
	written by the FDP, as they are part of the base system.
	However, the FDP can (and has) re-worded parts of existing
	manual pages to make them clearer, or to correct
	inaccuracies.</para>

	<para>The translation teams are responsible for translating
	the system manual pages into different languages. These
	translations are kept within the FDP.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>FAQ</term>

	<listitem>
	<para>The FAQ aims to address (in short question and answer
	format) questions that are asked, or should be asked, on
	the various mailing lists and newsgroups devoted to
	FreeBSD. The format does not permit long and
	comprehensive answers.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Handbook</term>

	<listitem>
	<para>The Handbook aims to be the comprehensive on-line
	resource and reference for FreeBSD users.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Web site</term>

	<listitem>
	<para>This is the main FreeBSD presence on the World Wide
	Web, visible at <ulink
	url="&url.base;/index.html">http://www.FreeBSD.org/</ulink>
	and many mirrors around the world. The web site is many
	people's first exposure to FreeBSD.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>The documentation for the web site, &os; Handbook, and FAQ
	are available in the <literal>doc/</literal> Subversion
	repository, which is located at
	- <literal>svn://svn.FreeBSD.org/doc/</literal>.</para>
	+ <literal>https://svn.FreeBSD.org/doc/</literal>.</para>

	<para>Manual pages are available in the <literal>src/</literal>
	Subversion repository, which is available at
	- <literal>svn://svn.FreeBSD.org/base/</literal>.</para>
	+ <literal>https://svn.FreeBSD.org/base/</literal>.</para>

	<para>This means that the logs of changes to these
	files are visible to anyone, and anyone can use
	<application>svn</application> to view the changes.</para>

	<para>In addition, many people have written tutorials or other web
	sites relating to FreeBSD. Some of these are stored in the
	Subversion repository as well (where the author has agreed to
	this). In other cases the author has decided to keep his
	documentation separate from the main FreeBSD repository. The
	FDP endeavors to provide links to as much of this documentation
	as possible.</para>
	</sect1>

	<sect1 id="overview-before">
	<title>Before You Start</title>

	<para>This document assumes that you already know:</para>

	<itemizedlist>
	<listitem>
	<para>How to maintain an up-to-date local copy of the FreeBSD
	documentation by maintaining a local copy of the FreeBSD
	Subversion repository using
	<application>svn</application>.</para>
	</listitem>

	<listitem>
	<para>How to download and install new software using either
	the FreeBSD Ports system or &man.pkg.add.1;.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="overview-quick-start">
	<title>Quick Start</title>

	<para>If you just want to get going, and feel confident you can
	pick things up as you go along, follow these
	instructions.</para>

	<procedure>
	<step>
	<para>Install the
	<filename role="package">textproc/docproj</filename>
	meta-port.</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
	&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
	</step>

	<step>
	<para>Get a local copy of the FreeBSD <filename>doc</filename>
	tree using <application>svn</application>.</para>

	<para>If network bandwidth or local drive space is a concern,
	then at minimum, the <filename>head/share</filename> and
	<filename>head/<replaceable>language</replaceable>/share</filename>
	directories will need to be checked out. For
	example:</para>

	<screen>&prompt.user; <userinput>mkdir -p head/share</userinput>
	&prompt.user; <userinput>mkdir -p head/en_US.ISO8859-1/share</userinput>
	-&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/share head/share</userinput>
	-&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share</userinput></screen>
	+&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/share head/share</userinput>
	+&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share</userinput></screen>

	<para>If you have plenty of disk space then you could check
	out everything.</para>

	- <screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head head</userinput></screen>
	+ <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head head</userinput></screen>
	+
	+ <note>
	+ <para><ulink
	+ url="https://svn0.us-east.FreeBSD.org/">svn0.us-east.FreeBSD.org</ulink>
	+ is a public <literal>SVN</literal> server.
	+ Select the closest mirror and verify the mirror server
	+ certificate from the list of <ulink
	+ url="&url.books.handbook;/svn-mirrors.html">Subversion
	+ mirror sites</ulink>.</para>
	+ </note>
	</step>

	<step>
	<para>If you are preparing a change to an existing book or
	article, check it out of the repository as necessary. If
	you are planning on contributing a new book or article then
	use an existing one as a guide.</para>

	<para>For example, if you want to contribute a new article
	about setting up a VPN between FreeBSD and Windows 2000 you
	might do the following.</para>

	<procedure>
	<step>
	<para>Check out the <filename>articles</filename>
	directory.</para>

	- <screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/articles</userinput></screen>
	+ <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/en_US.ISO8859-1/articles</userinput></screen>
	</step>

	<step>
	<para>Copy an existing article to use as a template. In
	this case, you have decided that your new article
	belongs in a directory called
	<filename>vpn-w2k</filename>.</para>

	<screen>&prompt.user; <userinput>cd head/en_US.ISO8859-1/articles</userinput>
	&prompt.user; <userinput>svn export committers-guide vpn-w2k</userinput></screen>
	</step>
	</procedure>

	<para>If you wanted to edit an existing document, such as the
	FAQ, which is in
	<filename>head/en_US.ISO8859-1/books/faq</filename> you
	would check it out of the repository like this.</para>

	- <screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/books/faq</userinput></screen>
	+ <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/en_US.ISO8859-1/books/faq</userinput></screen>
	</step>

	<step>
	<para>Edit the <filename>.xml</filename> files using your
	editor of choice.</para>
	</step>

	<step>
	<para>Test the markup using the <maketarget>lint</maketarget>
	target. This will quickly find any errors in the document
	without actually performing the time-consuming
	transformation.</para>

	<screen>&prompt.user; <userinput>make lint</userinput></screen>

	<para>When you are ready to actually build the document, you
	may specify a single format or a list of formats in the
	<varname>FORMATS</varname> variable. Currently,
	<literal>html</literal>, <literal>html-split</literal>,
	<literal>txt</literal>, <literal>ps</literal>,
	<literal>pdf</literal>, and <literal>rtf</literal> are
	supported. The most up to date list of supported formats is
	listed at the top of the
	<filename>head/share/mk/doc.docbook.mk</filename> file.
	Make sure to use quotes around the list of formats when you
	build more than one format with a single command.</para>

	<para>For example, to convert the document to
	<literal>html</literal> only, you would use:</para>

	<screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen>

	<para>But when you want to convert the document to both
	<literal>html</literal> and <literal>txt</literal> format,
	you could use either two separate &man.make.1; runs,
	with:</para>

	<screen>&prompt.user; <userinput>make FORMATS=html</userinput>
	&prompt.user; <userinput>make FORMATS=txt</userinput></screen>

	<para>or, you can do it in one command:</para>

	<screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>
	</step>

	<step>
	<para>Submit your changes using &man.send-pr.1;.</para>
	</step>
	</procedure>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml (revision 41355)
	@@ -1,243 +1,251 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!-- Copyright (c) 1998, 1999 Nik Clayton, 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 NIK CLAYTON "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$
	-->

	<chapter id="the-website">
	<title>The Website</title>

	<sect1 id="the-website-prep">
	<title>Preparation</title>

	<para>Use a disk with sufficient free space. You may need
	anything from 200 MB to over 500 MB, depending on the
	method you choose. This space will hold the XML tools, a
	subset of the <application>svn</application> tree, temporary
	build space and the installed web pages.</para>

	<note>
	<para>Make sure your documentation ports are up to date! When
	in doubt, remove the old ports using &man.pkg.delete.1;
	command before installing the port. For example, we currently
	depend on jade-1.2 and if you have installed jade-1.1, please
	do:</para>

	<screen>&prompt.root; <userinput><command>pkg_delete</command> jade-1.1</userinput></screen>
	</note>

	<sect2 id="the-website-svn">
	<title>Using <command>svn</command></title>

	<para><command>svn</command> is necessary to <quote>check
	out</quote> the necessary files from the
	<literal>doc/</literal> Subversion repository.
	<command>svn</command> can be installed with &man.pkg.add.1;
	or from the &os; Ports Collection by running:</para>

	<screen>&prompt.root; <userinput><command>cd /usr/ports/devel/subversion</command></userinput>
	&prompt.root; <userinput><command>make</command> <maketarget>install clean</maketarget></userinput></screen>

	<para>To check out the full source files for the &os; website,
	run:</para>

	- <screen>&prompt.root; <userinput><command>svn checkout svn://svn.FreeBSD.org/doc/head/ <replaceable>/usr/build</replaceable></command></userinput></screen>
	+ <screen>&prompt.root; <userinput><command>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/ <replaceable>/usr/build</replaceable></command></userinput></screen>
	+
	+ <para><ulink
	+ url="https://svn0.us-east.FreeBSD.org/">svn0.us-east.FreeBSD.org</ulink>
	+ is a public <literal>SVN</literal> server.
	+ Select the closest mirror and verify the mirror server
	+ certificate from the list of <ulink
	+ url="&url.books.handbook;/svn-mirrors.html">Subversion
	+ mirror sites</ulink>.</para>

	<tip>
	<para>If <command>svn</command> is not run as
	<username>root</username>, be sure <filename
	class="directory">/usr/build</filename> has the proper
	permissions for the current user. If changing the
	permissions is not possible, use a different target
	directory for the website files.</para>
	</tip>

	<para>When <command>svn</command> finishes, the current version
	of the &os; website will exist within <filename
	class="directory">/usr/build</filename>. If a different
	target directory was used, replace <filename
	class="directory">/usr/build</filename> appropriately
	throughout the remainder of this document.</para>

	<para>That's it! You can now proceed with the
	<link linkend="the-website-build">website build</link>.</para>
	</sect2>
	</sect1>

	<sect1 id="the-website-build">
	<title>Build the Web Pages from Scratch</title>

	<para>Having completed the necessary steps to obtain the website
	source files, the website can be built. In our example, the
	build directory is <filename
	class="directory"><replaceable>/usr/build</replaceable></filename>
	and all the required files are already in place.</para>

	<procedure>
	<step>
	<para>Change into the build directory:</para>

	<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build</replaceable></userinput></screen>
	</step>

	<step>
	<para>The website build starts from the <filename
	class="directory">en_US.ISO8859-1/htdocs</filename>
	directory by executing the &man.make.1;
	<maketarget>all</maketarget> target, to create the web
	pages.</para>

	<screen>&prompt.root; <userinput><command>cd</command> en_US.ISO8859-1/htdocs</userinput>
	&prompt.root; <userinput><command>make</command> <maketarget>all</maketarget></userinput></screen>

	<tip>
	<para>The build requires a few files from the Ports Collection
	and may fail without a properly configured Ports CVS
	mirror. Set the <makevar>NOPORTSCVS</makevar> environment
	variable as described in <xref linkend="the-website-env"/>
	to use your local Ports Collection (typically <filename
	class="directory">/usr/ports</filename>) instead.</para>
	</tip>
	</step>
	</procedure>
	</sect1>

	<sect1 id="the-website-install">
	<title>Install the Web Pages into Your Web Server</title>

	<procedure>
	<step>
	<para>If you have moved out of the <filename
	class="directory">en_US.ISO8859-1/htdocs</filename>
	directory, change back to it.</para>

	<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build/en_US.ISO8859-1/htdocs</replaceable></userinput></screen>
	</step>

	<step>
	<para>Run the &man.make.1; <maketarget>install</maketarget>
	target, setting the <makevar>DESTDIR</makevar> variable to
	the name of the directory you want to install the files to.
	The actual files are installed under <filename
	class="directory">$DESTDIR/data</filename>
	which should be configured as your web server's document
	root.</para>

	<screen>&prompt.root; <userinput><command>env</command> <makevar>DESTDIR</makevar>=<replaceable>/usr/local/www</replaceable> <command>make</command> <maketarget>install</maketarget></userinput></screen>
	</step>

	<step>
	<para>If you have previously installed the web pages into the
	same directory the install process will not have deleted any
	old or outdated pages. For example, if you build and
	install a new copy of the site every day, this command will
	find and delete all files that have not been updated in
	three days.</para>

	<screen>&prompt.root; <userinput><command>find</command> <replaceable>/usr/local/www</replaceable> <option>-ctime</option> 3 <option>-print0</option> \| <command>xargs</command> <option>-0</option> <command>rm</command></userinput></screen>
	</step>
	</procedure>
	</sect1>

	<sect1 id="the-website-env">
	<title>Environment Variables</title>

	<variablelist>
	<varlistentry>
	<term><makevar>ENGLISH_ONLY</makevar></term>

	<listitem>
	<para>If set and not empty, the makefiles will build and
	install only the English documents. All translations will
	be ignored. E.g.:</para>

	<screen>&prompt.root; <userinput><command>make</command> <makevar>ENGLISH_ONLY=YES</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget></userinput></screen>

	<para>If you want to unset the variable
	<makevar>ENGLISH_ONLY</makevar> and build all pages,
	including translations, set the variable
	<makevar>ENGLISH_ONLY</makevar> to an empty value:</para>

	<screen>&prompt.root; <userinput><command>make</command> <makevar>ENGLISH_ONLY=""</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget> <maketarget>clean</maketarget></userinput></screen>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><makevar>WEB_ONLY</makevar></term>

	<listitem>
	<para>If set and not empty, the Makefiles will build and
	install only the HTML pages from the <filename
	class="directory">en_US.ISO8859-1/htdocs</filename>
	directory. All other directories within <filename
	class="directory">en_US.ISO8859-1</filename>
	(Handbook, FAQ, Tutorials) will be ignored.
	E.g.:</para>

	<screen>&prompt.root; <userinput><command>make</command> <makevar>WEB_ONLY=YES</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget></userinput></screen>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><makevar>WEB_LANG</makevar></term>

	<listitem>
	<para>If set, the Makefiles will build and install only for
	the languages specified by this variable inside the
	<filename
	class="directory"><replaceable>/usr/build</replaceable></filename>
	directory. All other languages except English will be
	ignored. E.g.:</para>

	<screen>&prompt.root; <userinput>make WEB_LANG="el_GR.ISO8859-7 es_ES.ISO8859-1 hu_HU.ISO8859-2 nl_NL.ISO8859-1" all install</userinput></screen>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><makevar>NOPORTSCVS</makevar></term>

	<listitem>
	<para>If set, the Makefiles will not checkout files from the
	ports CVS repository. Instead, it will copy the files
	from <filename class="directory">/usr/ports</filename> (or
	where the variable <envar>PORTSBASE</envar> points
	to).</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para><makevar>WEB_ONLY</makevar>, <makevar>WEB_LANG</makevar>,
	<makevar>ENGLISH_ONLY</makevar> and
	<makevar>NOPORTSCVS</makevar> are make variables. You can set
	the variables in <filename>/etc/make.conf</filename>,
	<filename>Makefile.inc</filename>, as environment variables on
	the command line, or in your dot files.</para>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml (revision 41355)
	@@ -1,484 +1,492 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!-- Copyright (c) 1999 Nik Clayton, 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 NIK CLAYTON "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$
	-->

	<chapter id="translations">
	<title>Translations</title>

	<para>This is the FAQ for people translating the FreeBSD
	documentation (FAQ, Handbook, tutorials, manual pages, and others)
	to different languages.</para>

	<para>It is <emphasis>very</emphasis> heavily based on the
	translation FAQ from the FreeBSD German Documentation Project,
	originally written by Frank Gründer
	<email>elwood@mc5sys.in-berlin.de</email> and translated back to
	English by Bernd Warken <email>bwarken@mayn.de</email>.</para>

	<para>The FAQ is maintained by the &a.doceng;.</para>

	<qandaset>
	<qandaentry>
	<question>
	<para>Why a FAQ?</para>
	</question>

	<answer>
	<para>More and more people are approaching the freebsd-doc
	mailing list and volunteering to translate FreeBSD
	documentation to other languages. This FAQ aims to answer
	their questions so they can start translating documentation
	as quickly as possible.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase>
	mean?</para>
	</question>

	<answer>
	<para><phrase>i18n</phrase> means
	<phrase>internationalization</phrase> and
	<phrase>l10n</phrase> means <phrase>localization</phrase>.
	They are just a convenient shorthand.</para>

	<para><phrase>i18n</phrase> can be read as <quote>i</quote>
	followed by 18 letters, followed by <quote>n</quote>.
	Similarly, <phrase>l10n</phrase> is <quote>l</quote>
	followed by 10 letters, followed by <quote>n</quote>.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>Is there a mailing list for translators?</para>
	</question>

	<answer>
	<para>Yes. Different translation groups have their own
	mailing lists. The <ulink
	url="http://www.freebsd.org/docproj/translations.html">list
	of translation projects</ulink> has more information about
	the mailing lists and web sites run by each translation
	project.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>Are more translators needed?</para>
	</question>

	<answer>
	<para>Yes. The more people work on translation the faster it
	gets done, and the faster changes to the English
	documentation are mirrored in the translated
	documents.</para>

	<para>You do not have to be a professional translator to be
	able to help.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>What languages do I need to know?</para>
	</question>

	<answer>
	<para>Ideally, you will have a good knowledge of written
	English, and obviously you will need to be fluent in the
	language you are translating to.</para>

	<para>English is not strictly necessary. For example, you
	could do a Hungarian translation of the FAQ from the Spanish
	translation.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>What software do I need to know?</para>
	</question>

	<answer>
	<para>It is strongly recommended that you maintain a local
	copy of the FreeBSD Subversion repository (at least the
	documentation part). This can be done by running:</para>

	- <screen>&prompt.user; <userinput><command>svn</command> checkout svn://svn.FreeBSD.org/doc/head/ head</userinput></screen>
	+ <screen>&prompt.user; <userinput><command>svn</command> checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/ head</userinput></screen>
	+
	+ <para><ulink
	+ url="https://svn0.us-east.FreeBSD.org/">svn0.us-east.FreeBSD.org</ulink>
	+ is a public <literal>SVN</literal> server.
	+ Select the closest mirror and verify the mirror server
	+ certificate from the list of <ulink
	+ url="&url.books.handbook;/svn-mirrors.html">Subversion
	+ mirror sites</ulink>.</para>

	<note>
	<para>This will require the <filename
	role="package">devel/subversion</filename> package to
	be installed.</para>
	</note>

	<para>You should be comfortable using
	<application>svn</application>. This will allow you to see
	what has changed between different versions of the files
	that make up the documentation.</para>

	<para>For example, to view the differences between revisions
	<literal>r33733</literal> and <literal>r33734</literal> of
	<filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename>,
	run:</para>

	<screen>&prompt.user; <userinput><command>svn</command> diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> <filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename></userinput></screen>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>How do I find out who else might be translating to the
	same language?</para>
	</question>

	<answer>
	<para>The <ulink
	url="http://www.FreeBSD.org/docproj/translations.html">Documentation
	Project translations page</ulink> lists the translation
	efforts that are currently known about. If others are
	already working on translating documentation to your
	language, please do not duplicate their efforts. Instead,
	contact them to see how you can help.</para>

	<para>If no one is listed on that page as translating for your
	language, then send a message to the &a.doc; in case someone
	else is thinking of doing a translation, but has not
	announced it yet.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>No one else is translating to my language. What do I
	do?</para>
	</question>

	<answer>
	<para>Congratulations, you have just started the
	<quote>FreeBSD <replaceable>your-language-here</replaceable>
	Documentation Translation Project</quote>. Welcome
	aboard.</para>

	<para>First, decide whether or not you have got the time to
	spare. Since you are the only person working on your
	language at the moment it is going to be your responsibility
	to publicize your work and coordinate any volunteers that
	might want to help you.</para>

	<para>Write an email to the Documentation Project mailing
	list, announcing that you are going to translate the
	documentation, so the Documentation Project translations
	page can be maintained.</para>

	<para>If there is already someone in your country providing
	FreeBSD mirroring services you should contact them and ask
	if you can have some webspace for your project, and possibly
	an email address or mailing list services.</para>

	<para>Then pick a document and start translating. It is best
	to start with something fairly small—either the FAQ,
	or one of the tutorials.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>I have translated some documentation, where do I send
	it?</para>
	</question>

	<answer>
	<para>That depends. If you are already working with a
	translation team (such as the Japanese team, or the German
	team) then they will have their own procedures for handling
	submitted documentation, and these will be outlined on their
	web pages.</para>

	<para>If you are the only person working on a particular
	language (or you are responsible for a translation project
	and want to submit your changes back to the FreeBSD project)
	then you should send your translation to the FreeBSD project
	(see the next question).</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>I am the only person working on translating to this
	language, how do I submit my translation?</para>

	<para>or</para>

	<para>We are a translation team, and want to submit
	documentation that our members have translated for
	us.</para>
	</question>

	<answer>
	<para>First, make sure your translation is organized properly.
	This means that it should drop into the existing
	documentation tree and build straight away.</para>

	<para>Currently, the FreeBSD documentation is stored in a top
	level directory called <filename>head/</filename>.
	Directories below this are named according to the language
	code they are written in, as defined in ISO639
	(<filename>/usr/share/misc/iso639</filename> on a version of
	FreeBSD newer than 20th January 1999).</para>

	<para>If your language can be encoded in different ways (for
	example, Chinese) then there should be directories below
	this, one for each encoding format you have provided.</para>

	<para>Finally, you should have directories for each
	document.</para>

	<para>For example, a hypothetical Swedish translation might
	look like:</para>

	<programlisting>head/
	sv_SE.ISO8859-1/
	Makefile
	htdocs/
	docproj/
	books/
	faq/
	Makefile
	book.xml</programlisting>

	<para><literal>sv_SE.ISO8859-1</literal> is the name of the
	translation, in
	<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
	form. Note the two Makefiles, which will be used to build
	the documentation.</para>

	<para>Use &man.tar.1; and &man.gzip.1; to compress up your
	documentation, and send it to the project.</para>

	<screen>&prompt.user; <userinput>cd doc</userinput>
	&prompt.user; <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput>
	&prompt.user; <userinput>gzip -9 swedish-docs.tar</userinput></screen>

	<para>Put <filename>swedish-docs.tar.gz</filename> somewhere.
	If you do not have access to your own webspace (perhaps your
	ISP does not let you have any) then you can email
	&a.doceng;, and arrange to email the files when it is
	convenient.</para>

	<para>Either way, you should use &man.send-pr.1; to submit a
	report indicating that you have submitted the documentation.
	It would be very helpful if you could get other people to
	look over your translation and double check it first, since
	it is unlikely that the person committing it will be fluent
	in the language.</para>

	<para>Someone (probably the Documentation Project Manager,
	currently &a.doceng;) will then take your translation and
	confirm that it builds. In particular, the following things
	will be looked at:</para>

	<orderedlist>
	<listitem>
	<para>Do all your files use RCS strings (such as
	"ID")?</para>
	</listitem>

	<listitem>
	<para>Does <command>make all</command> in the
	<filename>sv_SE.ISO8859-1</filename> directory work
	correctly?</para>
	</listitem>

	<listitem>
	<para>Does <command>make install</command> work
	correctly?</para>
	</listitem>
	</orderedlist>

	<para>If there are any problems then whoever is looking at the
	submission will get back to you to work them out.</para>

	<para>If there are no problems your translation will be
	committed as soon as possible.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>Can I include language or country specific text in my
	translation?</para>
	</question>

	<answer>
	<para>We would prefer that you did not.</para>

	<para>For example, suppose that you are translating the
	Handbook to Korean, and want to include a section about
	retailers in Korea in your Handbook.</para>

	<para>There is no real reason why that information should not
	be in the English (or German, or Spanish, or Japanese, or
	…) versions as well. It is feasible that an English
	speaker in Korea might try to pick up a copy of FreeBSD
	whilst over there. It also helps increase FreeBSD's
	perceived presence around the globe, which is not a bad
	thing.</para>

	<para>If you have country specific information, please submit
	it as a change to the English Handbook (using
	&man.send-pr.1;) and then translate the change back to your
	language in the translated Handbook.</para>

	<para>Thanks.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>How should language specific characters be
	included?</para>
	</question>

	<answer>
	<para>Non-ASCII characters in the documentation should be
	included using SGML entities.</para>

	<para>Briefly, these look like an ampersand (&), the name
	of the entity, and a semi-colon (;).</para>

	<para>The entity names are defined in ISO8879, which is in the
	ports tree as <filename
	role="package">textproc/iso8879</filename>.</para>

	<para>A few examples include:</para>

	<segmentedlist>
	<segtitle>Entity</segtitle>

	<segtitle>Appearance</segtitle>

	<segtitle>Description</segtitle>

	<seglistitem>
	<seg>&eacute;</seg>
	<seg>é</seg>
	<seg>Small <quote>e</quote> with an acute accent</seg>
	</seglistitem>

	<seglistitem>
	<seg>&Eacute;</seg>
	<seg>É</seg>
	<seg>Large <quote>E</quote> with an acute accent</seg>
	</seglistitem>

	<seglistitem>
	<seg>&uuml;</seg>
	<seg>ü</seg>
	<seg>Small <quote>u</quote> with an umlaut</seg>
	</seglistitem>
	</segmentedlist>

	<para>After you have installed the iso8879 port, the files in
	<filename>/usr/local/share/xml/iso8879</filename> contain
	the complete list.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>Addressing the reader</para>
	</question>

	<answer>
	<para>In the English documents, the reader is addressed as
	<quote>you</quote>, there is no formal/informal distinction
	as there is in some languages.</para>

	<para>If you are translating to a language which does
	distinguish, use whichever form is typically used in other
	technical documentation in your language. If in doubt, use
	a mildly polite form.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>Do I need to include any additional information in my
	translations?</para>
	</question>

	<answer>
	<para>Yes.</para>

	<para>The header of the English version of each document will
	look something like this:</para>

	<programlisting><!--
	The FreeBSD Documentation Project

	&dollar;FreeBSD: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z &dollar;
	--></programlisting>

	<para>The exact boilerplate may change, but it will always
	include a &dollar;FreeBSD&dollar; line and the phrase
	<literal>The FreeBSD Documentation Project</literal>.
	Note that the &dollar;FreeBSD part is expanded automatically
	by Subversion, so it should be empty (just
	<literal>&dollar;FreeBSD&dollar;</literal>) for new
	files.</para>

	<para>Your translated documents should include their own
	&dollar;FreeBSD&dollar; line, and change the
	<literal>FreeBSD Documentation Project</literal> line to
	<literal>The FreeBSD <replaceable>language</replaceable>
	Documentation Project</literal>.</para>

	<para>In addition, you should add a third line which indicates
	which revision of the English text this is based on.</para>

	<para>So, the Spanish version of this file might start:</para>

	<programlisting><!--
	The FreeBSD Spanish Documentation Project

	&dollar;FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs &dollar;
	Original revision: r38674
	--></programlisting>
	</answer>
	</qandaentry>
	</qandaset>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml (revision 41355)
	@@ -1,6288 +1,6252 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="advanced-networking">
	<title>Advanced Networking</title>

	<sect1 id="advanced-networking-synopsis">
	<title>Synopsis</title>

	<para>This chapter will cover a number of advanced networking
	topics.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>The basics of gateways and routes.</para>
	</listitem>

	<listitem>
	<para>How to set up &ieee; 802.11 and &bluetooth;
	devices.</para>
	</listitem>

	<listitem>
	<para>How to make FreeBSD act as a bridge.</para>
	</listitem>

	<listitem>
	<para>How to set up network booting on a diskless
	machine.</para>
	</listitem>

	<listitem>
	<para>How to set up network PXE booting with an NFS root file
	system.</para>
	</listitem>

	<listitem>
	<para>How to set up network address translation.</para>
	</listitem>

	<listitem>
	<para>How to set up IPv6 on a FreeBSD machine.</para>
	</listitem>

	<listitem>
	<para>How to configure ATM.</para>
	</listitem>

	<listitem>
	<para>How to enable and utilize the features of CARP, the
	Common Address Redundancy Protocol in &os;</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	<para>Understand the basics of the
	<filename>/etc/rc</filename> scripts.</para>
	</listitem>

	<listitem>
	<para>Be familiar with basic network terminology.</para>
	</listitem>

	<listitem>
	<para>Know how to configure and install a new FreeBSD kernel
	(<xref linkend="kernelconfig"/>).</para>
	</listitem>

	<listitem>
	<para>Know how to install additional third-party
	software (<xref linkend="ports"/>).</para>
	</listitem>

	</itemizedlist>
	</sect1>

	<sect1 id="network-routing">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Coranth</firstname>
	<surname>Gryphon</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>Gateways and Routes</title>

	<indexterm><primary>routing</primary></indexterm>
	<indexterm><primary>gateway</primary></indexterm>
	<indexterm><primary>subnet</primary></indexterm>

	<para>For one machine to be able to find another over a network,
	there must be a mechanism in place to describe how to get from
	one to the other. This is called
	<firstterm>routing</firstterm>. A <quote>route</quote> is a
	defined pair of addresses: a <quote>destination</quote> and a
	<quote>gateway</quote>. The pair indicates that if you are
	trying to get to this <emphasis>destination</emphasis>,
	communicate through this <emphasis>gateway</emphasis>. There
	are three types of destinations: individual hosts, subnets, and
	<quote>default</quote>. The <quote>default route</quote> is
	used if none of the other routes apply. We will talk a little
	bit more about default routes later on. There are also three
	types of gateways: individual hosts, interfaces (also called
	<quote>links</quote>), and Ethernet hardware addresses (MAC
	addresses).</para>

	<sect2>
	<title>An Example</title>

	<para>To illustrate different aspects of routing, we will use
	the following example from <command>netstat</command>:</para>

	<screen>&prompt.user; <userinput>netstat -r</userinput>
	Routing tables

	Destination Gateway Flags Refs Use Netif Expire

	default outside-gw UGSc 37 418 ppp0
	localhost localhost UH 0 181 lo0
	test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77
	10.20.30.255 link#1 UHLW 1 2421
	example.com link#1 UC 0 0
	host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0
	host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 =>
	host2.example.com link#1 UC 0 0
	224 link#1 UC 0 0</screen>

	<indexterm><primary>default route</primary></indexterm>
	<para>The first two lines specify the default route (which we
	will cover in the
	<link linkend="network-routing-default">next section</link>)
	and the <hostid>localhost</hostid> route.</para>

	<indexterm><primary>loopback device</primary></indexterm>
	<para>The interface (<literal>Netif</literal> column) that this
	routing table specifies to use for
	<literal>localhost</literal> is <devicename>lo0</devicename>,
	also known as the loopback device. This says to keep all
	traffic for this destination internal, rather than sending it
	out over the LAN, since it will only end up back where it
	started.</para>

	<indexterm>
	<primary>Ethernet</primary>
	<secondary>MAC address</secondary>
	</indexterm>
	<para>The next thing that stands out are the addresses beginning
	with <hostid role="mac">0:e0:</hostid>. These are Ethernet
	hardware addresses, which are also known as MAC addresses.
	FreeBSD will automatically identify any hosts
	(<hostid>test0</hostid> in the example) on the local Ethernet
	and add a route for that host, directly to it over the
	Ethernet interface, <devicename>ed0</devicename>. There is
	also a timeout (<literal>Expire</literal> column) associated
	with this type of route, which is used if we fail to hear from
	the host in a specific amount of time. When this happens, the
	route to this host will be automatically deleted. These hosts
	are identified using a mechanism known as RIP (Routing
	Information Protocol), which figures out routes to local hosts
	based upon a shortest path determination.</para>

	<indexterm><primary>subnet</primary></indexterm>

	<para>FreeBSD will also add subnet routes for the local subnet
	(<hostid role="ipaddr">10.20.30.255</hostid> is the broadcast
	address for the subnet
	<hostid role="ipaddr">10.20.30</hostid>, and
	<hostid role="domainname">example.com</hostid> is the domain
	name associated with that subnet). The designation
	<literal>link#1</literal> refers to the first Ethernet card in
	the machine. You will notice no additional interface is
	specified for those.</para>

	<para>Both of these groups (local network hosts and local
	subnets) have their routes automatically configured by a
	daemon called <application>routed</application>. If this is
	not run, then only routes which are statically defined (i.e.,
	entered explicitly) will exist.</para>

	<para>The <literal>host1</literal> line refers to our host,
	which it knows by Ethernet address. Since we are the sending
	host, FreeBSD knows to use the loopback interface
	(<devicename>lo0</devicename>) rather than sending it out over
	the Ethernet interface.</para>

	<para>The two <literal>host2</literal> lines are an example of
	what happens when we use an &man.ifconfig.8; alias (see the
	section on Ethernet for reasons why we would do this). The
	<literal>=></literal> symbol after the
	<devicename>lo0</devicename> interface says that not only are
	we using the loopback (since this address also refers to the
	local host), but specifically it is an alias. Such routes
	only show up on the host that supports the alias; all other
	hosts on the local network will simply have a
	<literal>link#1</literal> line for such routes.</para>

	<para>The final line (destination subnet
	<hostid role="ipaddr">224</hostid>) deals with multicasting,
	which will be covered in another section.</para>

	<para>Finally, various attributes of each route can be seen in
	the <literal>Flags</literal> column. Below is a short table
	of some of these flags and their meanings:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<colspec colwidth="1*"/>
	<colspec colwidth="4*"/>

	<tbody>
	<row>
	<entry>U</entry>
	<entry>Up: The route is active.</entry>
	</row>

	<row>
	<entry>H</entry>
	<entry>Host: The route destination is a single
	host.</entry>
	</row>

	<row>
	<entry>G</entry>
	<entry>Gateway: Send anything for this destination on to
	this remote system, which will figure out from there
	where to send it.</entry>
	</row>

	<row>
	<entry>S</entry>
	<entry>Static: This route was configured manually, not
	automatically generated by the system.</entry>
	</row>

	<row>
	<entry>C</entry>
	<entry>Clone: Generates a new route based upon this
	route for machines we connect to. This type of route
	is normally used for local networks.</entry>
	</row>

	<row>
	<entry>W</entry>
	<entry>WasCloned: Indicated a route that was
	auto-configured based upon a local area network
	(Clone) route.</entry>
	</row>

	<row>
	<entry>L</entry>
	<entry>Link: Route involves references to Ethernet
	hardware.</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</sect2>

	<sect2 id="network-routing-default">
	<title>Default Routes</title>

	<indexterm><primary>default route</primary></indexterm>

	<para>When the local system needs to make a connection to a
	remote host, it checks the routing table to determine if a
	known path exists. If the remote host falls into a subnet
	that we know how to reach (Cloned routes), then the system
	checks to see if it can connect along that interface.</para>

	<para>If all known paths fail, the system has one last option:
	the <quote>default</quote> route. This route is a special
	type of gateway route (usually the only one present in the
	system), and is always marked with a <literal>c</literal> in
	the flags field. For hosts on a local area network, this
	gateway is set to whatever machine has a direct connection to
	the outside world (whether via PPP link, DSL, cable modem, T1,
	or another network interface).</para>

	<para>If you are configuring the default route for a machine
	which itself is functioning as the gateway to the outside
	world, then the default route will be the gateway machine at
	your Internet Service Provider's (ISP) site.</para>

	<para>Let us look at an example of default routes. This is a
	common configuration:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="advanced-networking/net-routing"/>
	</imageobject>

	<textobject>
	<literallayout class="monospaced">
	[Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW]</literallayout>
	</textobject>
	</mediaobject>

	<para>The hosts <hostid>Local1</hostid> and
	<hostid>Local2</hostid> are at your site.
	<hostid>Local1</hostid> is connected to an ISP via a dial up
	PPP connection. This PPP server computer is connected through
	a local area network to another gateway computer through an
	external interface to the ISPs Internet feed.</para>

	<para>The default routes for each of your machines will
	be:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="3">
	<thead>
	<row>
	<entry>Host</entry>
	<entry>Default Gateway</entry>
	<entry>Interface</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>Local2</entry>
	<entry>Local1</entry>
	<entry>Ethernet</entry>
	</row>

	<row>
	<entry>Local1</entry>
	<entry>T1-GW</entry>
	<entry>PPP</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>A common question is <quote>Why (or how) would we set
	the <hostid>T1-GW</hostid> to be the default gateway for
	<hostid>Local1</hostid>, rather than the ISP server it is
	connected to?</quote>.</para>

	<para>Remember, since the PPP interface is using an address on
	the ISP's local network for your side of the connection,
	routes for any other machines on the ISP's local network will
	be automatically generated. Hence, you will already know how
	to reach the <hostid>T1-GW</hostid> machine, so there is no
	need for the intermediate step of sending traffic to the ISP
	server.</para>

	<para>It is common to use the address
	<hostid role="ipaddr">X.X.X.1</hostid> as the gateway address
	for your local network. So (using the same example), if your
	local class-C address space was
	<hostid role="ipaddr">10.20.30</hostid> and your ISP was using
	<hostid role="ipaddr">10.9.9</hostid> then the default routes
	would be:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Host</entry>
	<entry>Default Route</entry>
	</row>
	</thead>
	<tbody>
	<row>
	<entry>Local2 (10.20.30.2)</entry>
	<entry>Local1 (10.20.30.1)</entry>
	</row>

	<row>
	<entry>Local1 (10.20.30.1, 10.9.9.30)</entry>
	<entry>T1-GW (10.9.9.1)</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>The default route can be easily defined in
	<filename>/etc/rc.conf</filename>. In our example, on
	the <hostid>Local2</hostid> machine, we added the following
	line in <filename>/etc/rc.conf</filename>:</para>

	<programlisting>defaultrouter="10.20.30.1"</programlisting>

	<para>It is also possible to do it directly from the command
	line with the &man.route.8; command:</para>

	<screen>&prompt.root; <userinput>route add default 10.20.30.1</userinput></screen>

	<para>For more information on manual manipulation of network
	routing tables, consult the &man.route.8; manual page.</para>
	</sect2>

	<sect2 id="network-dual-homed-hosts">
	<title>Dual Homed Hosts</title>

	<indexterm><primary>dual homed hosts</primary></indexterm>

	<para>There is one other type of configuration that we should
	cover, and that is a host that sits on two different networks.
	Technically, any machine functioning as a gateway (in the
	example above, using a PPP connection) counts as a dual-homed
	host. But the term is really only used to refer to a machine
	that sits on two local-area networks.</para>

	<para>In one case, the machine has two Ethernet cards, each
	having an address on the separate subnets. Alternately, the
	machine may only have one Ethernet card, and be using
	&man.ifconfig.8; aliasing. The former is used if two
	physically separate Ethernet networks are in use, the latter
	if there is one physical network segment, but two logically
	separate subnets.</para>

	<para>Either way, routing tables are set up so that each subnet
	knows that this machine is the defined gateway (inbound route)
	to the other subnet. This configuration, with the machine
	acting as a router between the two subnets, is often used when
	we need to implement packet filtering or firewall security in
	either or both directions.</para>

	<para>If you want this machine to actually forward packets
	between the two interfaces, you need to tell FreeBSD to enable
	this ability. See the next section for more details on how
	to do this.</para>
	</sect2>

	<sect2 id="network-dedicated-router">
	<title>Building a Router</title>

	<indexterm><primary>router</primary></indexterm>

	<para>A network router is simply a system that forwards packets
	from one interface to another. Internet standards and good
	engineering practice prevent the FreeBSD Project from enabling
	this by default in FreeBSD. You can enable this feature by
	changing the following variable to <literal>YES</literal> in
	&man.rc.conf.5;:</para>

	<programlisting>gateway_enable="YES" # Set to YES if this host will be a gateway</programlisting>

	<para>This option will set the &man.sysctl.8; variable
	<varname>net.inet.ip.forwarding</varname> to
	<literal>1</literal>. If you should need to stop routing
	temporarily, you can reset this to <literal>0</literal>
	temporarily.</para>

	<indexterm><primary>BGP</primary></indexterm>
	<indexterm><primary>RIP</primary></indexterm>
	<indexterm><primary>OSPF</primary></indexterm>
	<para>Your new router will need routes to know where to send the
	traffic. If your network is simple enough you can use static
	routes. FreeBSD also comes with the standard BSD routing
	daemon &man.routed.8;, which speaks RIP (both version 1 and
	version 2) and IRDP. Support for BGP v4, OSPF v2, and other
	sophisticated routing protocols is available with the
	<filename role="package">net/zebra</filename> package.
	Commercial products such as <application>&gated;</application>
	are also available for more complex network routing
	solutions.</para>
	</sect2>

	<sect2 id="network-static-routes">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Al</firstname>
	<surname>Hoang</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>
	<!-- Feb 2004 -->
	<title>Setting Up Static Routes</title>

	<sect3>
	<title>Manual Configuration</title>

	<para>Let us assume we have a network as follows:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="advanced-networking/static-routes"/>
	</imageobject>

	<textobject>
	<literallayout class="monospaced">
	INTERNET
	\| (10.0.0.1/24) Default Router to Internet
	\|
	\|Interface xl0
	\|10.0.0.10/24
	+------+
	\| \| RouterA
	\| \| (FreeBSD gateway)
	+------+
	\| Interface xl1
	\| 192.168.1.1/24
	\|
	+--------------------------------+
	Internal Net 1 \| 192.168.1.2/24
	\|
	+------+
	\| \| RouterB
	\| \|
	+------+
	\| 192.168.2.1/24
	\|
	Internal Net 2</literallayout>
	</textobject>
	</mediaobject>

	<para>In this scenario, <hostid>RouterA</hostid> is our &os;
	machine that is acting as a router to the rest of the
	Internet. It has a default route set to
	<hostid role="ipaddr">10.0.0.1</hostid> which allows it to
	connect with the outside world. We will assume that
	<hostid>RouterB</hostid> is already configured properly and
	knows how to get wherever it needs to go. (This is simple
	in this picture. Just add a default route on
	<hostid>RouterB</hostid> using
	<hostid role="ipaddr">192.168.1.1</hostid> as the
	gateway.)</para>

	<para>If we look at the routing table for
	<hostid>RouterA</hostid> we would see something like the
	following:</para>

	<screen>&prompt.user; <userinput>netstat -nr</userinput>
	Routing tables

	Internet:
	Destination Gateway Flags Refs Use Netif Expire
	default 10.0.0.1 UGS 0 49378 xl0
	127.0.0.1 127.0.0.1 UH 0 6 lo0
	10.0.0.0/24 link#1 UC 0 0 xl0
	192.168.1.0/24 link#2 UC 0 0 xl1</screen>

	<para>With the current routing table <hostid>RouterA</hostid>
	will not be able to reach our Internal Net 2. It does not
	have a route for
	<hostid role="ipaddr">192.168.2.0/24</hostid>. One way to
	alleviate this is to manually add the route. The following
	command would add the Internal Net 2 network to
	<hostid>RouterA</hostid>'s routing table using
	<hostid role="ipaddr">192.168.1.2</hostid> as the next
	hop:</para>

	<screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen>

	<para>Now <hostid>RouterA</hostid> can reach any hosts on the
	<hostid role="ipaddr">192.168.2.0/24</hostid>
	network.</para>
	</sect3>

	<sect3>
	<title>Persistent Configuration</title>

	<para>The above example is perfect for configuring a static
	route on a running system. However, one problem is that the
	routing information will not persist if you reboot your &os;
	machine. Additional static routes can be
	entered in <filename>/etc/rc.conf</filename>:</para>

	<programlisting># Add Internal Net 2 as a static route
	static_routes="internalnet2"
	route_internalnet2="-net 192.168.2.0/24 192.168.1.2"</programlisting>

	<para>The <literal>static_routes</literal> configuration
	variable is a list of strings separated by a space. Each
	string references to a route name. In our above example we
	only have one string in <literal>static_routes</literal>.
	This string is <replaceable>internalnet2</replaceable>. We
	then add a configuration variable called
	<literal>route_<replaceable>internalnet2</replaceable></literal>
	where we put all of the configuration parameters we would
	give to the &man.route.8; command. For our example above we
	would have used the command:</para>

	<screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen>

	<para>so we need <literal>"-net 192.168.2.0/24
	192.168.1.2"</literal>.</para>

	<para>As said above, we can have more than one string in
	<literal>static_routes</literal>. This allows us to create
	multiple static routes. The following lines shows an
	example of adding static routes for the
	<hostid role="ipaddr">192.168.0.0/24</hostid> and
	<hostid role="ipaddr">192.168.1.0/24</hostid> networks on an
	imaginary router:</para>

	<programlisting>static_routes="net1 net2"
	route_net1="-net 192.168.0.0/24 192.168.0.1"
	route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting>
	</sect3>
	</sect2>

	<sect2 id="network-routing-propagation">
	<title>Routing Propagation</title>

	<indexterm><primary>routing propagation</primary></indexterm>
	<para>We have already talked about how we define our routes to
	the outside world, but not about how the outside world finds
	us.</para>

	<para>We already know that routing tables can be set up so that
	all traffic for a particular address space (in our examples, a
	class-C subnet) can be sent to a particular host on that
	network, which will forward the packets inbound.</para>

	<para>When you get an address space assigned to your site, your
	service provider will set up their routing tables so that all
	traffic for your subnet will be sent down your PPP link to
	your site. But how do sites across the country know to send
	to your ISP?</para>

	<para>There is a system (much like the distributed DNS
	information) that keeps track of all assigned address-spaces,
	and defines their point of connection to the Internet
	Backbone. The <quote>Backbone</quote> are the main trunk
	lines that carry Internet traffic across the country, and
	around the world. Each backbone machine has a copy of a
	master set of tables, which direct traffic for a particular
	network to a specific backbone carrier, and from there down
	the chain of service providers until it reaches your
	network.</para>

	<para>It is the task of your service provider to advertise to
	the backbone sites that they are the point of connection (and
	thus the path inward) for your site. This is known as route
	propagation.</para>
	</sect2>

	<sect2 id="network-routing-troubleshooting">
	<title>Troubleshooting</title>

	<indexterm>
	<primary><command>traceroute</command></primary>
	</indexterm>

	<para>Sometimes, there is a problem with routing propagation,
	and some sites are unable to connect to you. Perhaps the most
	useful command for trying to figure out where routing is
	breaking down is the &man.traceroute.8; command. It is
	equally useful if you cannot seem to make a connection to a
	remote machine (i.e., &man.ping.8; fails).</para>

	<para>The &man.traceroute.8; command is run with the name of the
	remote host you are trying to connect to. It will show the
	gateway hosts along the path of the attempt, eventually either
	reaching the target host, or terminating because of a lack of
	connection.</para>

	<para>For more information, see the manual page for
	&man.traceroute.8;.</para>
	</sect2>

	<sect2 id="network-routing-multicast">
	<title>Multicast Routing</title>

	<indexterm>
	<primary>multicast routing</primary>
	</indexterm>
	<indexterm>
	<primary>kernel options</primary>
	<secondary>MROUTING</secondary>
	</indexterm>
	<para>FreeBSD supports both multicast applications and multicast
	routing natively. Multicast applications do not require any
	special configuration of FreeBSD; applications will generally
	run out of the box. Multicast routing
	requires that support be compiled into the kernel:</para>

	<programlisting>options MROUTING</programlisting>

	<para>In addition, the multicast routing daemon, &man.mrouted.8;
	must be configured to set up tunnels and
	<acronym>DVMRP</acronym> via
	<filename>/etc/mrouted.conf</filename>. More details on
	multicast configuration may be found in the manual page for
	&man.mrouted.8;.</para>

	<note>
	<para>The &man.mrouted.8; multicast routing daemon implements
	the <acronym>DVMRP</acronym> multicast routing protocol,
	which has largely been replaced by &man.pim.4; in many
	multicast installations. &man.mrouted.8; and the related
	&man.map-mbone.8; and &man.mrinfo.8; utilities are available
	in the &os; Ports Collection as
	<filename role="package">net/mrouted</filename>.</para>
	</note>
	</sect2>
	</sect1>

	<sect1 id="network-wireless">
	<sect1info>
	<authorgroup>
	<author>
	<othername>Loader</othername>
	</author>

	<author>
	<firstname>Marc</firstname>
	<surname>Fonvieille</surname>
	</author>

	<author>
	<firstname>Murray</firstname>
	<surname>Stokely</surname>
	</author>
	</authorgroup>
	</sect1info>
	<title>Wireless Networking</title>

	<indexterm><primary>wireless networking</primary></indexterm>
	<indexterm>
	<primary>802.11</primary>
	<see>wireless networking</see>
	</indexterm>

	<sect2>
	<title>Wireless Networking Basics</title>

	<para>Most wireless networks are based on the &ieee; 802.11
	standards. A basic wireless network consists of multiple
	stations communicating with radios that broadcast in either
	the 2.4GHz or 5GHz band (though this varies according to the
	locale and is also changing to enable communication in the
	2.3GHz and 4.9GHz ranges).</para>

	<para>802.11 networks are organized in two ways: in
	<emphasis>infrastructure mode</emphasis> one station acts as a
	master with all the other stations associating to it; the
	network is known as a BSS and the master station is termed an
	access point (AP). In a BSS all communication passes through
	the AP; even when one station wants to communicate with
	another wireless station messages must go through the AP. In
	the second form of network there is no master and stations
	communicate directly. This form of network is termed an IBSS
	and is commonly known as an
	<emphasis>ad-hoc network</emphasis>.</para>

	<para>802.11 networks were first deployed in the 2.4GHz band
	using protocols defined by the &ieee; 802.11 and 802.11b
	standard. These specifications include the operating
	frequencies, MAC layer characteristics including framing and
	transmission rates (communication can be done at various
	rates). Later the 802.11a standard defined operation in the
	5GHz band, including different signalling mechanisms and
	higher transmission rates. Still later the 802.11g standard
	was defined to enable use of 802.11a signalling and
	transmission mechanisms in the 2.4GHz band in such a way as to
	be backwards compatible with 802.11b networks.</para>

	<para>Separate from the underlying transmission techniques
	802.11 networks have a variety of security mechanisms. The
	original 802.11 specifications defined a simple security
	protocol called WEP. This protocol uses a fixed pre-shared key
	and the RC4 cryptographic cipher to encode data transmitted on
	a network. Stations must all agree on the fixed key in order
	to communicate. This scheme was shown to be easily broken and
	is now rarely used except to discourage transient users from
	joining networks. Current security practice is given by the
	&ieee; 802.11i specification that defines new cryptographic
	ciphers and an additional protocol to authenticate stations to
	an access point and exchange keys for doing data
	communication. Further, cryptographic keys are periodically
	refreshed and there are mechanisms for detecting intrusion
	attempts (and for countering intrusion attempts). Another
	security protocol specification commonly used in wireless
	networks is termed WPA. This was a precursor to 802.11i
	defined by an industry group as an interim measure while
	waiting for 802.11i to be ratified. WPA specifies a subset of
	the requirements found in 802.11i and is designed for
	implementation on legacy hardware. Specifically WPA requires
	only the TKIP cipher that is derived from the original WEP
	cipher. 802.11i permits use of TKIP but also requires support
	for a stronger cipher, AES-CCM, for encrypting data. (The AES
	cipher was not required in WPA because it was deemed too
	computationally costly to be implemented on legacy
	hardware.)</para>

	<para>Other than the above protocol standards the other
	important standard to be aware of is 802.11e. This defines
	protocols for deploying multi-media applications such as
	streaming video and voice over IP (VoIP) in an 802.11 network.
	Like 802.11i, 802.11e also has a precursor specification
	termed WME (later renamed WMM) that has been defined by an
	industry group as a subset of 802.11e that can be deployed now
	to enable multi-media applications while waiting for the final
	ratification of 802.11e. The most important thing to know
	about 802.11e and WME/WMM is that it enables prioritized
	traffic use of a wireless network through Quality of Service
	(QoS) protocols and enhanced media access protocols. Proper
	implementation of these protocols enable high speed bursting
	of data and prioritized traffic flow.</para>

	<para>&os; supports networks that operate
	using 802.11a, 802.11b, and 802.11g. The WPA and 802.11i
	security protocols are likewise supported (in conjunction with
	any of 11a, 11b, and 11g) and QoS and traffic prioritization
	required by the WME/WMM protocols are supported for a limited
	set of wireless devices.</para>
	</sect2>

	<sect2 id="network-wireless-basic">
	<title>Basic Setup</title>

	<sect3>
	<title>Kernel Configuration</title>

	<para>To use wireless networking, you need a wireless
	networking card and to configure the kernel with the
	appropriate wireless networking support. The latter is
	separated into multiple modules so that you only need to
	configure the software you are actually going to use.</para>

	<para>The first thing you need is a wireless device. The most
	commonly used devices are those that use parts made by
	Atheros. These devices are supported by the &man.ath.4;
	driver and require the following line to be added to
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>if_ath_load="YES"</programlisting>

	<para>The Atheros driver is split up into three separate
	pieces: the proper driver (&man.ath.4;), the hardware
	support layer that handles chip-specific functions
	(&man.ath.hal.4;), and an algorithm for selecting which of
	several possible rates for transmitting frames
	(ath_rate_sample here). When this support is loaded as
	kernel modules, these dependencies are automatically handled
	for you. If, instead of an Atheros device, you had another
	device you would select the module for that device;
	e.g.:</para>

	<programlisting>if_wi_load="YES"</programlisting>

	<para>for devices based on the Intersil Prism parts
	(&man.wi.4; driver).</para>

	<note>
	<para>In the rest of this document, we will use an
	&man.ath.4; device, the device name in the examples must
	be changed according to your configuration. A list of
	available wireless drivers and supported adapters can be
	found in the &os; Hardware Notes. Copies of these notes
	for various releases and architectures are available on
	the <ulink
	url="http://www.FreeBSD.org/releases/index.html">Release
	Information</ulink> page of the &os; Web site. If a
	native &os; driver for your wireless device does not
	exist, it may be possible to directly use the &windows;
	driver with the help of the
	<link linkend="config-network-ndis">NDIS</link> driver
	wrapper.</para>
	</note>

	- <para>Under &os; 7.X, with a device driver you need to
	- also bring in the 802.11 networking support required by the
	- driver. For the &man.ath.4; driver these are at least the
	- &man.wlan.4;, <literal>wlan_scan_ap</literal> and
	- <literal>wlan_scan_sta</literal> modules; the &man.wlan.4;
	- module is automatically loaded with the wireless device
	- driver, the remaining modules must be loaded at boot time
	- in <filename>/boot/loader.conf</filename>:</para>
	-
	- <programlisting>wlan_scan_ap_load="YES"
	-wlan_scan_sta_load="YES"</programlisting>
	-
	- <para>Since &os; 8.0, these modules are part of the
	- base &man.wlan.4; driver which is dynamically loaded with
	- the adapter driver.</para>
	-
	<para>With that, you will need the modules that implement
	cryptographic support for the security protocols you intend
	to use. These are intended to be dynamically loaded on
	demand by the &man.wlan.4; module but for now they must be
	manually configured. The following modules are available:
	&man.wlan.wep.4;, &man.wlan.ccmp.4; and &man.wlan.tkip.4;.
	Both &man.wlan.ccmp.4; and &man.wlan.tkip.4; drivers are
	only needed if you intend to use the WPA and/or 802.11i
	security protocols. If your network does not use
	encryption, you will not need &man.wlan.wep.4; support. To
	load these modules at boot time, add the following lines to
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>wlan_wep_load="YES"
	wlan_ccmp_load="YES"
	wlan_tkip_load="YES"</programlisting>

	<para>With this information in the system bootstrap
	configuration file (i.e.,
	<filename>/boot/loader.conf</filename>), you have to reboot
	your &os; box. If you do not want to reboot your machine
	for the moment, you can load the modules by hand using
	&man.kldload.8;.</para>

	<note>
	<para>If you do not want to use modules, it is possible to
	compile these drivers into the kernel by adding the
	following lines to your kernel configuration file:</para>

	<programlisting>device wlan # 802.11 support
	device wlan_wep # 802.11 WEP support
	device wlan_ccmp # 802.11 CCMP support
	device wlan_tkip # 802.11 TKIP support
	device wlan_amrr # AMRR transmit rate control algorithm
	device ath # Atheros pci/cardbus NIC's
	device ath_hal # pci/cardbus chip support
	options AH_SUPPORT_AR5416 # enable AR5416 tx/rx descriptors
	device ath_rate_sample # SampleRate tx rate control for ath</programlisting>

	- <para>Both following lines are also required by
	- &os; 7.X, other &os; versions do not need
	- them:</para>
	-
	- <programlisting>device wlan_scan_ap # 802.11 AP mode scanning
	-device wlan_scan_sta # 802.11 STA mode scanning</programlisting>
	-
	<para>With this information in the kernel configuration
	file, recompile the kernel and reboot your &os;
	machine.</para>
	</note>

	<para>When the system is up, we could find some information
	about the wireless device in the boot messages, like
	this:</para>

	<screen>ath0: <Atheros 5212> mem 0x88000000-0x8800ffff irq 11 at device 0.0 on cardbus1
	ath0: [ITHREAD]
	ath0: AR2413 mac 7.9 RF2413 phy 4.5</screen>
	</sect3>
	</sect2>

	<sect2>
	<title>Infrastructure Mode</title>

	<para>The infrastructure mode or BSS mode is the mode that is
	typically used. In this mode, a number of wireless access
	points are connected to a wired network. Each wireless
	network has its own name, this name is called the SSID of the
	network. Wireless clients connect to the wireless access
	points.</para>

	<sect3>
	<title>&os; Clients</title>

	<sect4>
	<title>How to Find Access Points</title>

	<para>To scan for networks, use the
	<command>ifconfig</command> command. This request may
	take a few moments to complete as it requires that the
	system switches to each available wireless frequency and
	probes for available access points. Only the super-user
	can initiate such a scan:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
	SSID/MESH ID BSSID CHAN RATE S:N INT CAPS
	dlinkap 00:13:46:49:41:76 11 54M -90:96 100 EPS WPA WME
	freebsdap 00:11:95:c3:0d:ac 1 54M -83:96 100 EPS WPA</screen>

	<note>
	<para>You must mark the interface <option>up</option>
	before you can scan. Subsequent scan requests do not
	require you to mark the interface up again.</para>
	</note>

	- <note>
	- <para>Under &os; 7.X, the adapter device, for example
	- <devicename><replaceable>ath0</replaceable></devicename>,
	- is used directly instead of the
	- <devicename>wlan<replaceable>0</replaceable></devicename>
	- device. This requires you to replace the both previous
	- lines with:</para>
	-
	- <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> up scan</userinput></screen>
	-
	- <para>In the rest of this document, &os; 7.X users
	- will need to change the command and configuration lines
	- according to that scheme.</para>
	- </note>
	-
	<para>The output of a scan request lists each BSS/IBSS
	network found. Beside the name of the network,
	<literal>SSID</literal>, we find the
	<literal>BSSID</literal> which is the MAC address of the
	access point. The <literal>CAPS</literal> field
	identifies the type of each network and the capabilities
	of the stations operating there:</para>

	<table frame="none" pgwide="0">
	<title>Station Capability Codes</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Capability Code</entry>
	<entry>Meaning</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>E</literal></entry>
	<entry>Extended Service Set (ESS). Indicates that
	the station is part of an infrastructure network
	(in contrast to an IBSS/ad-hoc network).</entry>
	</row>

	<row>
	<entry><literal>I</literal></entry>
	<entry>IBSS/ad-hoc network. Indicates that the
	station is part of an ad-hoc network (in contrast
	to an ESS network).</entry>
	</row>

	<row>
	<entry><literal>P</literal></entry>
	<entry>Privacy. Data confidentiality is required
	for all data frames exchanged within the BSS.
	This means that this BSS requires the station to
	use cryptographic means such as WEP, TKIP or
	AES-CCMP to encrypt/decrypt data frames being
	exchanged with others.</entry>
	</row>

	<row>
	<entry><literal>S</literal></entry>
	<entry>Short Preamble. Indicates that the network
	is using short preambles (defined in 802.11b High
	Rate/DSSS PHY, short preamble utilizes a 56 bit
	sync field in contrast to a 128 bit field used in
	long preamble mode).</entry>
	</row>

	<row>
	<entry><literal>s</literal></entry>
	<entry>Short slot time. Indicates that the 802.11g
	network is using a short slot time because there
	are no legacy (802.11b) stations present.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>One can also display the current list of known
	networks with:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> list scan</userinput></screen>

	<para>This information may be updated automatically by the
	adapter or manually with a <option>scan</option> request.
	Old data is automatically removed from the cache, so over
	time this list may shrink unless more scans are
	done.</para>
	</sect4>

	<sect4>
	<title>Basic Settings</title>

	<para>This section provides a simple example of how to make
	the wireless network adapter work in &os; without
	encryption. After you are familiar with these concepts,
	we strongly recommend using
	<link linkend="network-wireless-wpa">WPA</link> to set up
	your wireless network.</para>

	<para>There are three basic steps to configure a wireless
	network: selecting an access point, authenticating your
	station, and configuring an IP address. The following
	sections discuss each step.</para>

	<sect5>
	<title>Selecting an Access Point</title>

	<para>Most of time it is sufficient to let the system
	choose an access point using the builtin heuristics.
	This is the default behaviour when you mark an interface
	up or otherwise configure an interface by listing it in
	<filename>/etc/rc.conf</filename>, e.g.:</para>

	<programlisting>wlans_ath0="wlan0"
	ifconfig_wlan0="DHCP"</programlisting>

	- <note>
	- <para>As previously mentioned, &os; 7.X will only
	- require a line related to the adapter device:</para>
	-
	- <programlisting>ifconfig_ath0="DHCP"</programlisting>
	- </note>
	-
	<para>If there are multiple access points and you want to
	select a specific one, you can select it by its
	SSID:</para>

	<programlisting>wlans_ath0="wlan0"
	ifconfig_wlan0="ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting>

	<para>In an environment where there are multiple access
	points with the same SSID (often done to simplify
	roaming) it may be necessary to associate to one
	specific device. In this case you can also specify the
	BSSID of the access point (you can also leave off the
	SSID):</para>

	<programlisting>wlans_ath0="wlan0"
	ifconfig_wlan0="ssid <replaceable>your_ssid_here</replaceable> bssid <replaceable>xx:xx:xx:xx:xx:xx</replaceable> DHCP"</programlisting>

	<para>There are other ways to constrain the choice of an
	access point such as limiting the set of frequencies the
	system will scan on. This may be useful if you have a
	multi-band wireless card as scanning all the possible
	channels can be time-consuming. To limit operation to a
	specific band you can use the <option>mode</option>
	parameter; e.g.:</para>

	<programlisting>wlans_ath0="wlan0"
	ifconfig_wlan0="mode <replaceable>11g</replaceable> ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting>

	<para>will force the card to operate in 802.11g which is
	defined only for 2.4GHz frequencies so any 5GHz channels
	will not be considered. Other ways to do this are the
	<option>channel</option> parameter, to lock operation to
	one specific frequency, and the
	<option>chanlist</option> parameter, to specify a list
	of channels for scanning. More information about these
	parameters can be found in the &man.ifconfig.8; manual
	page.</para>
	</sect5>

	<sect5>
	<title>Authentication</title>

	<para>Once you have selected an access point your station
	needs to authenticate before it can pass data.
	Authentication can happen in several ways. The most
	common scheme used is termed open authentication and
	allows any station to join the network and communicate.
	This is the authentication you should use for test
	purpose the first time you set up a wireless network.
	Other schemes require cryptographic handshakes be
	completed before data traffic can flow; either using
	pre-shared keys or secrets, or more complex schemes that
	involve backend services such as RADIUS. Most users
	will use open authentication which is the default
	setting. Next most common setup is WPA-PSK, also known
	as WPA Personal, which is described <link
	linkend="network-wireless-wpa-wpa-psk">below</link>.</para>

	<note>
	<para>If you have an &apple; &airport; Extreme base
	station for an access point you may need to configure
	shared-key authentication together with a WEP key.
	This can be done in the
	<filename>/etc/rc.conf</filename> file or using the
	&man.wpa.supplicant.8; program. If you have a single
	&airport; base station you can setup access with
	something like:</para>

	<programlisting>wlans_ath0="wlan0"
	ifconfig_wlan0="authmode shared wepmode on weptxkey <replaceable>1</replaceable> wepkey <replaceable>01234567</replaceable> DHCP"</programlisting>

	<para>In general shared key authentication is to be
	avoided because it uses the WEP key material in a
	highly-constrained manner making it even easier to
	crack the key. If WEP must be used (e.g., for
	compatibility with legacy devices) it is better to use
	WEP with <literal>open</literal> authentication. More
	information regarding WEP can be found in the
	<xref linkend="network-wireless-wep"/>.</para>
	</note>
	</sect5>

	<sect5>
	<title>Getting an IP Address with DHCP</title>

	<para>Once you have selected an access point and set the
	authentication parameters, you will have to get an IP
	address to communicate. Most of time you will obtain
	your wireless IP address via DHCP. To achieve that,
	edit <filename>/etc/rc.conf</filename> and add
	<literal>DHCP</literal> to the configuration for your
	device as shown in various examples above:</para>

	<programlisting>wlans_ath0="wlan0"
	ifconfig_wlan0="DHCP"</programlisting>

	<para>At this point, you are ready to bring up the
	wireless interface:</para>

	<screen>&prompt.root; <userinput>service netif start</userinput></screen>

	<para>Once the interface is running, use
	<command>ifconfig</command> to see the status of the
	interface <devicename>ath0</devicename>:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
	ether 00:11:95:d5:43:62
	inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255
	media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g
	status: associated
	ssid dlinkap channel 11 (2462 Mhz 11g) bssid 00:13:46:49:41:76
	country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7
	scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7
	roam:rate 5 protmode CTS wme burst</screen>

	<para>The <literal>status: associated</literal> means you
	are connected to the wireless network (to the
	<literal>dlinkap</literal> network in our case). The
	<literal>bssid 00:13:46:49:41:76</literal> part is the
	MAC address of your access point; the
	<literal>authmode OPEN</literal> part informs you that
	the communication is not encrypted.</para>
	</sect5>

	<sect5>
	<title>Static IP Address</title>

	<para>In the case you cannot obtain an IP address from a
	DHCP server, you can set a fixed IP address. Replace
	the <literal>DHCP</literal> keyword shown above with the
	address information. Be sure to retain any other
	parameters you have set up for selecting an access
	point:</para>

	<programlisting>wlans_ath0="wlan0"
	ifconfig_wlan0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>your_ssid_here</replaceable>"</programlisting>
	</sect5>
	</sect4>

	<sect4 id="network-wireless-wpa">
	<title>WPA</title>

	<para>WPA (Wi-Fi Protected Access) is a security protocol
	used together with 802.11 networks to address the lack of
	proper authentication and the weakness of
	<link linkend="network-wireless-wep">WEP</link>. WPA
	leverages the 802.1X authentication protocol and uses one
	of several ciphers instead of WEP for data integrity. The
	only cipher required by WPA is TKIP (Temporary Key
	Integrity Protocol). TKIP is a cipher that extends the
	basic RC4 cipher used by WEP by adding integrity checking,
	tamper detection, and measures for responding to any
	detected intrusions. TKIP is designed to work on legacy
	hardware with only software modification; it represents a
	compromise that improves security but is still not
	entirely immune to attack. WPA also specifies the
	AES-CCMP cipher as an alternative to TKIP and that is
	preferred when possible; for this specification the term
	WPA2 (or RSN) is commonly used.</para>

	<para>WPA defines authentication and encryption protocols.
	Authentication is most commonly done using one of two
	techniques: by 802.1X and a backend authentication service
	such as RADIUS, or by a minimal handshake between the
	station and the access point using a pre-shared secret.
	The former is commonly termed WPA Enterprise with the
	latter known as WPA Personal. Since most people will not
	set up a RADIUS backend server for their wireless network,
	WPA-PSK is by far the most commonly encountered
	configuration for WPA.</para>

	<para>The control of the wireless connection and the
	authentication (key negotiation or authentication with a
	server) is done with the &man.wpa.supplicant.8; utility.
	This program requires a configuration file,
	<filename>/etc/wpa_supplicant.conf</filename>, to run.
	More information regarding this file can be found in the
	&man.wpa.supplicant.conf.5; manual page.</para>

	<sect5 id="network-wireless-wpa-wpa-psk">
	<title>WPA-PSK</title>

	<para>WPA-PSK, also known as WPA-Personal, is based on a
	pre-shared key (PSK) generated from a given password and
	that will be used as the master key in the wireless
	network. This means every wireless user will share the
	same key. WPA-PSK is intended for small networks where
	the use of an authentication server is not possible or
	desired.</para>

	<warning>
	<para>Always use strong passwords that are
	sufficiently long and made from a rich alphabet so
	they will not be guessed and/or attacked.</para>
	</warning>

	<para>The first step is the configuration of the
	<filename>/etc/wpa_supplicant.conf</filename> file with
	the SSID and the pre-shared key of your network:</para>

	<programlisting>network={
	ssid="freebsdap"
	psk="freebsdmall"
	}</programlisting>

	<para>Then, in <filename>/etc/rc.conf</filename>, we
	indicate that the wireless device configuration will be
	done with WPA and the IP address will be obtained with
	DHCP:</para>

	<programlisting>wlans_ath0="wlan0"
	ifconfig_wlan0="WPA DHCP"</programlisting>

	<para>Then we can bring up the interface:</para>

	- <screen>&prompt.root; <userinput><filename>service netif</filename> start</userinput>
	+ <screen>&prompt.root; <userinput>service netif start</userinput>
	Starting wpa_supplicant.
	DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 5
	DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 6
	DHCPOFFER from 192.168.0.1
	DHCPREQUEST on wlan0 to 255.255.255.255 port 67
	DHCPACK from 192.168.0.1
	bound to 192.168.0.254 -- renewal in 300 seconds.
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
	ether 00:11:95:d5:43:62
	inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
	media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g
	status: associated
	ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
	country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
	AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
	bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
	wme burst roaming MANUAL</screen>

	<para>Or you can try to configure it manually using the
	same <filename>/etc/wpa_supplicant.conf</filename> <link
	linkend="network-wireless-wpa-wpa-psk">above</link>, and
	run:</para>

	<screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>wlan0</replaceable> -c /etc/wpa_supplicant.conf</userinput>
	Trying to associate with 00:11:95:c3:0d:ac (SSID='freebsdap' freq=2412 MHz)
	Associated with 00:11:95:c3:0d:ac
	WPA: Key negotiation completed with 00:11:95:c3:0d:ac [PTK=CCMP GTK=CCMP]
	CTRL-EVENT-CONNECTED - Connection to 00:11:95:c3:0d:ac completed (auth) [id=0 id_str=]</screen>

	<para>The next operation is the launch of the
	<command>dhclient</command> command to get the IP
	address from the DHCP server:</para>

	<screen>&prompt.root; <userinput>dhclient <replaceable>wlan0</replaceable></userinput>
	DHCPREQUEST on wlan0 to 255.255.255.255 port 67
	DHCPACK from 192.168.0.1
	bound to 192.168.0.254 -- renewal in 300 seconds.
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
	ether 00:11:95:d5:43:62
	inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
	media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g
	status: associated
	ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
	country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
	AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
	bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
	wme burst roaming MANUAL</screen>

	<note>
	<para>If <filename>/etc/rc.conf</filename> has an
	<literal>ifconfig_wlan0</literal> entry with the
	<literal>DHCP</literal> string (like
	<literal>ifconfig_wlan0="DHCP"</literal>),
	<command>dhclient</command> will be launched
	automatically after <command>wpa_supplicant</command>
	associates with the access point.</para>
	</note>

	<para>If DHCP is not possible or desired,
	you can set a static IP address after
	<command>wpa_supplicant</command> has authenticated the
	station:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.100</replaceable> netmask <replaceable>255.255.255.0</replaceable></userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
	ether 00:11:95:d5:43:62
	inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255
	media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g
	status: associated
	ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
	country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
	AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
	bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
	wme burst roaming MANUAL</screen>

	<para>When DHCP is not used, you also have to manually set
	the default gateway and the nameserver:</para>

	<screen>&prompt.root; <userinput>route add default <replaceable>your_default_router</replaceable></userinput>
	&prompt.root; <userinput>echo "nameserver <replaceable>your_DNS_server</replaceable>" >> /etc/resolv.conf</userinput></screen>
	</sect5>

	<sect5 id="network-wireless-wpa-eap-tls">
	<title>WPA with EAP-TLS</title>

	<para>The second way to use WPA is with an 802.1X backend
	authentication server. In this case WPA is called
	WPA-Enterprise to differentiate it from the less secure
	WPA-Personal with its pre-shared key.
	Authentication in WPA-Enterprise is based on the
	Extensible Authentication Protocol (EAP).</para>

	<para>EAP does not come with an encryption method.
	Instead, it was decided to embed EAP inside an encrypted
	tunnel. There are many EAP authentication methods, but
	EAP-TLS, EAP-TTLS, and EAP-PEAP are the most
	common.</para>

	<para>EAP-TLS (EAP with Transport Layer Security) is a
	very well-supported authentication protocol in the
	wireless world since it was the first EAP method to be
	certified by the <ulink
	url="http://www.wi-fi.org/">Wi-Fi alliance</ulink>.
	EAP-TLS will require three certificates to run: the CA
	certificate (installed on all machines), the server
	certificate for your authentication server, and one
	client certificate for each wireless client. In this
	EAP method, both authentication server and wireless
	client authenticate each other in presenting their
	respective certificates, and they verify that these
	certificates were signed by your organization's
	certificate authority (CA).</para>

	<para>As previously, the configuration is done via
	<filename>/etc/wpa_supplicant.conf</filename>:</para>

	<programlisting>network={
	ssid="freebsdap" <co id="co-tls-ssid"/>
	proto=RSN <co id="co-tls-proto"/>
	key_mgmt=WPA-EAP <co id="co-tls-kmgmt"/>
	eap=TLS <co id="co-tls-eap"/>
	identity="loader" <co id="co-tls-id"/>
	ca_cert="/etc/certs/cacert.pem" <co id="co-tls-cacert"/>
	client_cert="/etc/certs/clientcert.pem" <co id="co-tls-clientcert"/>
	private_key="/etc/certs/clientkey.pem" <co id="co-tls-pkey"/>
	private_key_passwd="freebsdmallclient" <co id="co-tls-pwd"/>
	}</programlisting>

	<calloutlist>
	<callout arearefs="co-tls-ssid">
	<para>This field indicates the network name
	(SSID).</para>
	</callout>

	<callout arearefs="co-tls-proto">
	<para>Here, we use RSN (&ieee; 802.11i) protocol,
	i.e., WPA2.</para>
	</callout>

	<callout arearefs="co-tls-kmgmt">
	<para>The <literal>key_mgmt</literal> line refers to
	the key management protocol we use. In our case it
	is WPA using EAP authentication:
	<literal>WPA-EAP</literal>.</para>
	</callout>

	<callout arearefs="co-tls-eap">
	<para>In this field, we mention the EAP method for our
	connection.</para>
	</callout>

	<callout arearefs="co-tls-id">
	<para>The <literal>identity</literal> field contains
	the identity string for EAP.</para>
	</callout>

	<callout arearefs="co-tls-cacert">
	<para>The <literal>ca_cert</literal> field indicates
	the pathname of the CA certificate file. This file
	is needed to verify the server certificate.</para>
	</callout>

	<callout arearefs="co-tls-clientcert">
	<para>The <literal>client_cert</literal> line gives
	the pathname to the client certificate file. This
	certificate is unique to each wireless client of the
	network.</para>
	</callout>

	<callout arearefs="co-tls-pkey">
	<para>The <literal>private_key</literal> field is the
	pathname to the client certificate private key
	file.</para>
	</callout>

	<callout arearefs="co-tls-pwd">
	<para>The <literal>private_key_passwd</literal> field
	contains the passphrase for the private key.</para>
	</callout>
	</calloutlist>

	<para>Then add the following lines to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>wlans_ath0="wlan0"
	ifconfig_wlan0="WPA DHCP"</programlisting>

	<para>The next step is to bring up the interface:</para>

	<screen>&prompt.root; <userinput>service netif start</userinput>
	Starting wpa_supplicant.
	DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7
	DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15
	DHCPACK from 192.168.0.20
	bound to 192.168.0.254 -- renewal in 300 seconds.
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
	ether 00:11:95:d5:43:62
	inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
	media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g
	status: associated
	ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
	country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
	AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
	bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
	wme burst roaming MANUAL</screen>

	<para>As previously shown, it is also possible to bring up
	the interface manually with both
	<command>wpa_supplicant</command> and
	<command>ifconfig</command> commands.</para>
	</sect5>

	<sect5 id="network-wireless-wpa-eap-ttls">
	<title>WPA with EAP-TTLS</title>

	<para>With EAP-TLS both the authentication server and the
	client need a certificate, with EAP-TTLS (EAP-Tunneled
	Transport Layer Security) a client certificate is
	optional. This method is close to what some secure web
	sites do , where the web server can create a secure SSL
	tunnel even if the visitors do not have client-side
	certificates. EAP-TTLS will use the encrypted TLS
	tunnel for safe transport of the authentication
	data.</para>

	<para>The configuration is done via the
	<filename>/etc/wpa_supplicant.conf</filename>
	file:</para>

	<programlisting>network={
	ssid="freebsdap"
	proto=RSN
	key_mgmt=WPA-EAP
	eap=TTLS <co id="co-ttls-eap"/>
	identity="test" <co id="co-ttls-id"/>
	password="test" <co id="co-ttls-passwd"/>
	ca_cert="/etc/certs/cacert.pem" <co id="co-ttls-cacert"/>
	phase2="auth=MD5" <co id="co-ttls-pha2"/>
	}</programlisting>

	<calloutlist>
	<callout arearefs="co-ttls-eap">
	<para>In this field, we mention the EAP method for our
	connection.</para>
	</callout>

	<callout arearefs="co-ttls-id">
	<para>The <literal>identity</literal> field contains
	the identity string for EAP authentication inside
	the encrypted TLS tunnel.</para>
	</callout>

	<callout arearefs="co-ttls-passwd">
	<para>The <literal>password</literal> field contains
	the passphrase for the EAP authentication.</para>
	</callout>

	<callout arearefs="co-ttls-cacert">
	<para>The <literal>ca_cert</literal> field indicates
	the pathname of the CA certificate file. This file
	is needed to verify the server certificate.</para>
	</callout>

	<callout arearefs="co-ttls-pha2">
	<para>In this field, we mention the authentication
	method used in the encrypted TLS tunnel. In our
	case, EAP with MD5-Challenge has been used. The
	<quote>inner authentication</quote> phase is often
	called <quote>phase2</quote>.</para>
	</callout>
	</calloutlist>

	<para>You also have to add the following lines to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>wlans_ath0="wlan0"
	ifconfig_wlan0="WPA DHCP"</programlisting>

	<para>The next step is to bring up the interface:</para>

	<screen>&prompt.root; <userinput>service netif start</userinput>
	Starting wpa_supplicant.
	DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7
	DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15
	DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21
	DHCPACK from 192.168.0.20
	bound to 192.168.0.254 -- renewal in 300 seconds.
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
	ether 00:11:95:d5:43:62
	inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
	media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g
	status: associated
	ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
	country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
	AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
	bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
	wme burst roaming MANUAL</screen>
	</sect5>

	<sect5 id="network-wireless-wpa-eap-peap">
	<title>WPA with EAP-PEAP</title>

	<note>
	<para>PEAPv0/EAP-MSCHAPv2 is the most common PEAP
	method. In the rest of this document, we will use the
	PEAP term to refer to that method.</para>
	</note>

	<para>PEAP (Protected EAP) has been designed as an
	alternative to EAP-TTLS, and is the most used EAP
	standard after EAP-TLS. In other words, if you have a
	network with mixed OSes, PEAP should be the most
	supported standard after EAP-TLS.</para>

	<para>PEAP is similar to EAP-TTLS: it uses a server-side
	certificate to authenticate clients by creating an
	encrypted TLS tunnel between the client and the
	authentication server, which protects the ensuing
	exchange of authentication information. In terms of
	security, the difference between EAP-TTLS and PEAP is
	that PEAP authentication broadcasts the username in the
	clear, with only the password sent in the encrypted TLS
	tunnel. EAP-TTLS will use the TLS tunnel for both
	username and password.</para>

	<para>We have to edit the
	<filename>/etc/wpa_supplicant.conf</filename> file and
	add the EAP-PEAP related settings:</para>

	<programlisting>network={
	ssid="freebsdap"
	proto=RSN
	key_mgmt=WPA-EAP
	eap=PEAP <co id="co-peap-eap"/>
	identity="test" <co id="co-peap-id"/>
	password="test" <co id="co-peap-passwd"/>
	ca_cert="/etc/certs/cacert.pem" <co id="co-peap-cacert"/>
	phase1="peaplabel=0" <co id="co-peap-pha1"/>
	phase2="auth=MSCHAPV2" <co id="co-peap-pha2"/>
	}</programlisting>

	<calloutlist>
	<callout arearefs="co-peap-eap">
	<para>In this field, we mention the EAP method for our
	connection.</para>
	</callout>

	<callout arearefs="co-peap-id">
	<para>The <literal>identity</literal> field contains
	the identity string for EAP authentication inside
	the encrypted TLS tunnel.</para>
	</callout>

	<callout arearefs="co-peap-passwd">
	<para>The <literal>password</literal> field contains
	the passphrase for the EAP authentication.</para>
	</callout>

	<callout arearefs="co-peap-cacert">
	<para>The <literal>ca_cert</literal> field indicates
	the pathname of the CA certificate file. This file
	is needed to verify the server certificate.</para>
	</callout>

	<callout arearefs="co-peap-pha1">
	<para>This field contains the parameters for the
	first phase of authentication (the TLS tunnel).
	According to the authentication server used, you
	will have to specify a specific label for
	authentication. Most of the time, the label will be
	<quote>client EAP encryption</quote> which is set by
	using <literal>peaplabel=0</literal>. More
	information can be found in the
	&man.wpa.supplicant.conf.5; manual page.</para>
	</callout>

	<callout arearefs="co-peap-pha2">
	<para>In this field, we mention the authentication
	protocol used in the encrypted TLS tunnel. In the
	case of PEAP, it is
	<literal>auth=MSCHAPV2</literal>.</para>
	</callout>
	</calloutlist>

	<para>The following must be added to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>wlans_ath0="wlan0"
	ifconfig_wlan0="WPA DHCP"</programlisting>

	<para>Then we can bring up the interface:</para>

	<screen>&prompt.root; <userinput>service netif start</userinput>
	Starting wpa_supplicant.
	DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7
	DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15
	DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21
	DHCPACK from 192.168.0.20
	bound to 192.168.0.254 -- renewal in 300 seconds.
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
	ether 00:11:95:d5:43:62
	inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
	media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g
	status: associated
	ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
	country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
	AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
	bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
	wme burst roaming MANUAL</screen>
	</sect5>
	</sect4>

	<sect4 id="network-wireless-wep">
	<title>WEP</title>

	<para>WEP (Wired Equivalent Privacy) is part of the original
	802.11 standard. There is no authentication mechanism,
	only a weak form of access control, and it is easily
	cracked.</para>

	<para>WEP can be set up with
	<command>ifconfig</command>:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> \
	ssid <replaceable>my_net</replaceable> wepmode on weptxkey <replaceable>3</replaceable> wepkey <replaceable>3:0x3456789012</replaceable></userinput></screen>

	<itemizedlist>
	<listitem>

	<para>The <literal>weptxkey</literal> means which WEP
	key will be used in the transmission. Here we used
	the third key. This must match the setting in the
	access point. If you do not have any idea of which
	key is used by the access point, try
	<literal>1</literal> (i.e., the first key) for this
	value.</para>
	</listitem>

	<listitem>
	<para>The <literal>wepkey</literal> selects one of the
	WEP keys. It should be in the format
	<replaceable>index:key</replaceable>. Key
	<literal>1</literal> is used by default; the index
	only needs to be set if we use a key other
	than the first key.</para>

	<note>
	<para>You must replace the
	<literal>0x3456789012</literal> with the key
	configured for use on the access point.</para>
	</note>
	</listitem>
	</itemizedlist>

	<para>You are encouraged to read the &man.ifconfig.8; manual
	page for further information.</para>

	<para>The <command>wpa_supplicant</command> facility also
	can be used to configure your wireless interface with WEP.
	The example above can be set up by adding the following
	lines to
	<filename>/etc/wpa_supplicant.conf</filename>:</para>

	<programlisting>network={
	ssid="my_net"
	key_mgmt=NONE
	wep_key3=3456789012
	wep_tx_keyidx=3
	}</programlisting>

	<para>Then:</para>

	<screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>wlan0</replaceable> -c /etc/wpa_supplicant.conf</userinput>
	Trying to associate with 00:13:46:49:41:76 (SSID='dlinkap' freq=2437 MHz)
	Associated with 00:13:46:49:41:76</screen>
	</sect4>
	</sect3>
	</sect2>

	<sect2>
	<title>Ad-hoc Mode</title>

	<para>IBSS mode, also called ad-hoc mode, is designed for point
	to point connections. For example, to establish an ad-hoc
	network between the machine <hostid>A</hostid> and the machine
	<hostid>B</hostid>, we will just need to choose two IP
	addresses and a SSID.</para>

	<para>On the box <hostid>A</hostid>:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	ether 00:11:95:c3:0d:ac
	inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
	media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <adhoc>
	status: running
	ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac
	country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
	protmode CTS wme burst</screen>

	<para>The <literal>adhoc</literal> parameter indicates the
	interface is running in the IBSS mode.</para>

	<para>On <hostid>B</hostid>, we should be able to detect
	<hostid>A</hostid>:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
	SSID/MESH ID BSSID CHAN RATE S:N INT CAPS
	freebsdap 02:11:95:c3:0d:ac 2 54M -64:-96 100 IS WME</screen>

	<para>The <literal>I</literal> in the output confirms the
	machine <hostid>A</hostid> is in ad-hoc mode. We just have to
	configure <hostid>B</hostid> with a different IP
	address:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	ether 00:11:95:d5:43:62
	inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255
	media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <adhoc>
	status: running
	ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac
	country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
	protmode CTS wme burst</screen>

	<para>Both <hostid>A</hostid> and <hostid>B</hostid> are now
	ready to exchange information.</para>
	</sect2>

	<sect2 id="network-wireless-ap">
	<title>&os; Host Access Points</title>

	<para>&os; can act as an Access Point (AP) which eliminates the
	need to buy a hardware AP or run an ad-hoc network. This can
	be particularly useful when your &os; machine is acting as a
	gateway to another network (e.g., the Internet).</para>

	<sect3 id="network-wireless-ap-basic">
	<title>Basic Settings</title>

	<para>Before configuring your &os; machine as an AP, the
	kernel must be configured with the appropriate wireless
	networking support for your wireless card. You also have to
	add support for the security protocols you intend to
	use. For more details, see
	<xref linkend="network-wireless-basic"/>.</para>

	<note>
	<para>The use of the NDIS driver wrapper and the &windows;
	drivers do not currently allow AP operation. Only native
	&os; wireless drivers support AP mode.</para>
	</note>

	<para>Once wireless networking support is loaded, you can
	check if your wireless device supports the host-based access
	point mode (also known as hostap mode):</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> list caps</userinput>
	drivercaps=6f85edc1<STA,FF,TURBOP,IBSS,HOSTAP,AHDEMO,TXPMGT,SHSLOT,SHPREAMBLE,MONITOR,MBSS,WPA1,WPA2,BURST,WME,WDS,BGSCAN,TXFRAG>
	cryptocaps=1f<WEP,TKIP,AES,AES_CCM,TKIPMIC></screen>

	<para>This output displays the card capabilities; the
	<literal>HOSTAP</literal> word confirms this wireless card
	can act as an Access Point. Various supported ciphers are
	also mentioned: WEP, TKIP, AES, etc. This information
	is important to know what security protocols can be used
	on the Access Point.</para>

	<para>The wireless device can only be put into hostap mode
	during the creation of the network pseudo-device, so a
	previously created device must be destroyed first:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> destroy</userinput></screen>

	<para>then regenerated with the correct option before setting
	the other parameters:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel 1</userinput></screen>

	<para>Use <command>ifconfig</command> again to see the status
	of the <devicename>wlan0</devicename> interface:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	ether 00:11:95:c3:0d:ac
	inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
	media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap>
	status: running
	ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
	country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
	protmode CTS wme burst dtimperiod 1 -dfs</screen>

	<para>The <literal>hostap</literal> parameter indicates the
	interface is running in the host-based access point
	mode.</para>

	<para>The interface configuration can be done automatically at
	boot time by adding the following lines to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>wlans_ath0="wlan0"
	create_args_wlan0="wlanmode hostap"
	ifconfig_wlan0="inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel <replaceable>1</replaceable>"</programlisting>
	</sect3>

	<sect3>
	<title>Host-based Access Point Without Authentication or
	Encryption</title>

	<para>Although it is not recommended to run an AP without any
	authentication or encryption, this is a simple way to check
	if your AP is working. This configuration is also important
	for debugging client issues.</para>

	<para>Once the AP configured as previously shown, it is
	possible from another wireless machine to initiate a scan to
	find the AP:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
	SSID/MESH ID BSSID CHAN RATE S:N INT CAPS
	freebsdap 00:11:95:c3:0d:ac 1 54M -66:-96 100 ES WME</screen>

	<para>The client machine found the Access Point and can be
	associated with it:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	ether 00:11:95:d5:43:62
	inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255
	media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g
	status: associated
	ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
	country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7
	scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7
	roam:rate 5 protmode CTS wme burst</screen>
	</sect3>

	<sect3>
	<title>WPA Host-based Access Point</title>

	<para>This section will focus on setting up &os; Access Point
	using the WPA security protocol. More details regarding WPA
	and the configuration of WPA-based wireless clients can be
	found in the <xref linkend="network-wireless-wpa"/>.</para>

	<para>The <application>hostapd</application> daemon is used to
	deal with client authentication and keys management on the
	WPA enabled Access Point.</para>

	<para>In the following, all the configuration operations will
	be performed on the &os; machine acting as AP. Once the
	AP is correctly working, <application>hostapd</application>
	should be automatically enabled at boot with the following
	line in <filename>/etc/rc.conf</filename>:</para>

	<programlisting>hostapd_enable="YES"</programlisting>

	<para>Before trying to configure
	<application>hostapd</application>, be sure you have done
	the basic settings introduced in the
	<xref linkend="network-wireless-ap-basic"/>.</para>

	<sect4>
	<title>WPA-PSK</title>

	<para>WPA-PSK is intended for small networks where the use
	of an backend authentication server is not possible or
	desired.</para>

	<para>The configuration is done in the
	<filename>/etc/hostapd.conf</filename> file:</para>

	<programlisting>interface=wlan0 <co id="co-ap-wpapsk-iface"/>
	debug=1 <co id="co-ap-wpapsk-dbug"/>
	ctrl_interface=/var/run/hostapd <co id="co-ap-wpapsk-ciface"/>
	ctrl_interface_group=wheel <co id="co-ap-wpapsk-cifacegrp"/>
	ssid=freebsdap <co id="co-ap-wpapsk-ssid"/>
	wpa=1 <co id="co-ap-wpapsk-wpa"/>
	wpa_passphrase=freebsdmall <co id="co-ap-wpapsk-pass"/>
	wpa_key_mgmt=WPA-PSK <co id="co-ap-wpapsk-kmgmt"/>
	wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting>

	<calloutlist>
	<callout arearefs="co-ap-wpapsk-iface">
	<para>This field indicates the wireless interface used
	for the Access Point.</para>
	</callout>

	<callout arearefs="co-ap-wpapsk-dbug">
	<para>This field sets the level of verbosity during the
	execution of <application>hostapd</application>. A
	value of <literal>1</literal> represents the minimal
	level.</para>
	</callout>

	<callout arearefs="co-ap-wpapsk-ciface">
	<para>The <literal>ctrl_interface</literal> field gives
	the pathname of the directory used by
	<application>hostapd</application> to stores its
	domain socket files for the communication with
	external programs such as &man.hostapd.cli.8;. The
	default value is used here.</para>
	</callout>

	<callout arearefs="co-ap-wpapsk-cifacegrp">
	<para>The <literal>ctrl_interface_group</literal> line
	sets the group (here, it is the
	<groupname>wheel</groupname> group) allowed to access
	to the control interface files.</para>
	</callout>

	<callout arearefs="co-ap-wpapsk-ssid">
	<para>This field sets the network name.</para>
	</callout>

	<callout arearefs="co-ap-wpapsk-wpa">
	<para>The <literal>wpa</literal> field enables WPA and
	specifies which WPA authentication protocol will be
	required. A value of <literal>1</literal> configures
	the AP for WPA-PSK.</para>
	</callout>

	<callout arearefs="co-ap-wpapsk-pass">
	<para>The <literal>wpa_passphrase</literal> field
	contains the ASCII passphrase for the WPA
	authentication.</para>

	<warning>
	<para>Always use strong passwords that are
	sufficiently long and made from a rich alphabet so
	they will not be guessed and/or attacked.</para>
	</warning>
	</callout>

	<callout arearefs="co-ap-wpapsk-kmgmt">
	<para>The <literal>wpa_key_mgmt</literal> line refers to
	the key management protocol we use. In our case it is
	WPA-PSK.</para>
	</callout>

	<callout arearefs="co-ap-wpapsk-pwise">
	<para>The <literal>wpa_pairwise</literal> field
	indicates the set of accepted encryption algorithms by
	the Access Point. Here both TKIP (WPA) and CCMP
	(WPA2) ciphers are accepted. CCMP cipher is an
	alternative to TKIP and that is strongly preferred
	when possible; TKIP should be used solely for stations
	incapable of doing CCMP.</para>
	</callout>
	</calloutlist>

	<para>The next step is to start
	<application>hostapd</application>:</para>

	<screen>&prompt.root; <userinput>service hostapd forcestart</userinput></screen>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 2290
	inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
	inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4
	ether 00:11:95:c3:0d:ac
	media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap>
	status: associated
	ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
	authmode WPA2/802.11i privacy MIXED deftxkey 2 TKIP 2:128-bit txpowmax 36 protmode CTS dtimperiod 1 bintval 100</screen>

	<para>The Access Point is running, the clients can now be
	associated with it, see
	<xref linkend="network-wireless-wpa"/> for more details.
	It is possible to see the stations associated with the AP
	using the <command>ifconfig
	<replaceable>wlan0</replaceable> list sta</command>
	command.</para>
	</sect4>
	</sect3>

	<sect3>
	<title>WEP Host-based Access Point</title>

	<para>It is not recommended to use WEP for setting up an
	Access Point since there is no authentication mechanism and
	it is easily to be cracked. Some legacy wireless cards only
	support WEP as security protocol, these cards will only
	allow to set up AP without authentication or encryption or
	using the WEP protocol.</para>

	<para>The wireless device can now be put into hostap mode and
	configured with the correct SSID and IP address:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> \
	ssid <replaceable>freebsdap</replaceable> wepmode on weptxkey <replaceable>3</replaceable> wepkey <replaceable>3:0x3456789012</replaceable> mode 11g</userinput></screen>

	<itemizedlist>
	<listitem>
	<para>The <literal>weptxkey</literal> means which WEP
	key will be used in the transmission. Here we used the
	third key (note that the key numbering starts with
	<literal>1</literal>). This parameter must be specified
	to really encrypt the data.</para>
	</listitem>

	<listitem>
	<para>The <literal>wepkey</literal> means setting the
	selected WEP key. It should in the format
	<replaceable>index:key</replaceable>, if the index is
	not given, key <literal>1</literal> is set. That is
	to say we need to set the index if we use keys other
	than the first key.</para>
	</listitem>
	</itemizedlist>

	<para>Use again <command>ifconfig</command> to see the status
	of the <devicename>wlan0</devicename> interface:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
	wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	ether 00:11:95:c3:0d:ac
	inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
	media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap>
	status: running
	ssid freebsdap channel 4 (2427 Mhz 11g) bssid 00:11:95:c3:0d:ac
	country US ecm authmode OPEN privacy ON deftxkey 3 wepkey 3:40-bit
	txpower 21.5 scanvalid 60 protmode CTS wme burst dtimperiod 1 -dfs</screen>

	<para>From another wireless machine, it is possible to
	initiate a scan to find the AP:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
	&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
	SSID BSSID CHAN RATE S:N INT CAPS
	freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS</screen>

	<para>The client machine found the Access Point and can be
	associated with it using the correct parameters (key, etc.),
	see <xref linkend="network-wireless-wep"/> for more
	details.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Using Both Wired and Wireless Connection</title>

	<para>Wired connection provides better performance and
	reliability, while wireless connection provides flexibility
	and mobility, users of laptop computers usually want to
	combine these together and roam seamlessly between the
	two.</para>

	<para>On &os;, it is possible to combine two or even more
	network interfaces together in a <quote>failover</quote>
	fashion, that is, to use the most preferred and available
	connection from a group of network interfaces, and have the
	operating system switch automatically when the link state
	changes.</para>

	<para>We will cover link aggregation and failover in
	<xref linkend="network-aggregation"/> where an example for
	using both wired and wireless connection is also provided at
	<xref linkend="networking-lagg-wired-and-wireless"/>.</para>
	</sect2>

	<sect2>
	<title>Troubleshooting</title>

	<para>If you are having trouble with wireless networking, there
	are a number of steps you can take to help troubleshoot the
	problem.</para>

	<itemizedlist>
	<listitem>
	<para>If you do not see the access point listed when
	scanning be sure you have not configured your wireless
	device to a limited set of channels.</para>
	</listitem>

	<listitem>
	<para>If you cannot associate to an access point verify the
	configuration of your station matches the one of the
	access point. This includes the authentication scheme and
	any security protocols. Simplify your configuration as
	much as possible. If you are using a security protocol
	such as WPA or WEP configure the access point for open
	authentication and no security to see if you can get
	traffic to pass.</para>
	</listitem>

	<listitem>
	<para>Once you can associate to the access point diagnose
	any security configuration using simple tools like
	&man.ping.8;.</para>

	<para>The <command>wpa_supplicant</command> has much
	debugging support; try running it manually with the
	<option>-dd</option> option and look at the system
	logs.</para>
	</listitem>

	<listitem>
	<para>There are also many lower-level debugging tools. You
	can enable debugging messages in the 802.11 protocol
	support layer using the <command>wlandebug</command>
	program found in
	- <filename>/usr/src/tools/tools/net80211</filename>. For
	- example:</para>
	+ <filename class="directory">/usr/src/tools/tools/net80211</filename>.
	+ For example:</para>

	<screen>&prompt.root; <userinput>wlandebug -i <replaceable>ath0</replaceable> +scan+auth+debug+assoc</userinput>
	net.wlan.0.debug: 0 => 0xc80000<assoc,auth,scan></screen>

	<para>can be used to enable console messages related to
	scanning for access points and doing the 802.11 protocol
	handshakes required to arrange communication.</para>

	<para>There are also many useful statistics maintained by
	the 802.11 layer; the <command>wlanstats</command> tool
	will dump this information. These statistics should
	identify all errors identified by the 802.11 layer.
	Beware however that some errors are identified in the
	device drivers that lie below the 802.11 layer so they may
	not show up. To diagnose device-specific problems you
	need to refer to the drivers' documentation.</para>
	</listitem>
	</itemizedlist>

	<para>If the above information does not help to clarify the
	problem, please submit a problem report and include output
	from the above tools.</para>
	</sect2>
	</sect1>

	<sect1 id="network-bluetooth">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Pav</firstname>
	<surname>Lucistnik</surname>
	<contrib>Written by </contrib>
	<affiliation>
	<address><email>pav@FreeBSD.org</email></address>
	</affiliation>
	</author>
	</authorgroup>
	</sect1info>

	<title>Bluetooth</title>

	<indexterm><primary>Bluetooth</primary></indexterm>
	<sect2>
	<title>Introduction</title>

	<para>Bluetooth is a wireless technology for creating personal
	networks operating in the 2.4 GHz unlicensed band, with a
	range of 10 meters. Networks are usually formed ad-hoc from
	portable devices such as cellular phones, handhelds and
	laptops. Unlike the other popular wireless technology, Wi-Fi,
	Bluetooth offers higher level service profiles, e.g., FTP-like
	file servers, file pushing, voice transport, serial line
	emulation, and more.</para>

	<para>The Bluetooth stack in &os; is implemented using the
	Netgraph framework (see &man.netgraph.4;). A broad variety of
	Bluetooth USB dongles is supported by the &man.ng.ubt.4;
	driver. The Broadcom BCM2033 chip based Bluetooth devices are
	supported via the &man.ubtbcmfw.4; and &man.ng.ubt.4; drivers.
	The 3Com Bluetooth PC Card 3CRWB60-A is supported by the
	&man.ng.bt3c.4; driver. Serial and UART based Bluetooth
	devices are supported via &man.sio.4;, &man.ng.h4.4; and
	&man.hcseriald.8;. This section describes the use of the USB
	Bluetooth dongle.</para>
	</sect2>

	<sect2>
	<title>Plugging in the Device</title>

	<para>By default Bluetooth device drivers are available as
	kernel modules. Before attaching a device, you will need to
	load the driver into the kernel:</para>

	<screen>&prompt.root; <userinput>kldload ng_ubt</userinput></screen>

	<para>If the Bluetooth device is present in the system during
	system startup, load the module from
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>ng_ubt_load="YES"</programlisting>

	<para>Plug in your USB dongle. The output similar to the
	following will appear on the console (or in syslog):</para>

	<screen>ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2
	ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2
	ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3,
	wMaxPacketSize=49, nframes=6, buffer size=294</screen>

	<para>&man.service.8;
	is used to start and stop the Bluetooth stack. It is a good
	idea to stop the stack before unplugging the device, but it is
	not (usually) fatal. When starting the stack, you will
	receive output similar to the following:</para>

	<screen>&prompt.root; <userinput>service bluetooth start ubt0</userinput>
	BD_ADDR: 00:02:72:00:d4:1a
	Features: 0xff 0xff 0xf 00 00 00 00 00
	<3-Slot> <5-Slot> <Encryption> <Slot offset>
	<Timing accuracy> <Switch> <Hold mode> <Sniff mode>
	<Park mode> <RSSI> <Channel quality> <SCO link>
	<HV2 packets> <HV3 packets> <u-law log> <A-law log> <CVSD>
	<Paging scheme> <Power control> <Transparent SCO data>
	Max. ACL packet size: 192 bytes
	Number of ACL packets: 8
	Max. SCO packet size: 64 bytes
	Number of SCO packets: 8</screen>
	</sect2>

	<sect2>
	<title>Host Controller Interface (HCI)</title>

	<indexterm><primary>HCI</primary></indexterm>

	<para>Host Controller Interface (HCI) provides a command
	interface to the baseband controller and link manager, and
	access to hardware status and control registers. This
	interface provides a uniform method of accessing the Bluetooth
	baseband capabilities. HCI layer on the Host exchanges data
	and commands with the HCI firmware on the Bluetooth hardware.
	The Host Controller Transport Layer (i.e., physical bus)
	driver provides both HCI layers with the ability to exchange
	information with each other.</para>

	<para>A single Netgraph node of type <emphasis>hci</emphasis> is
	created for a single Bluetooth device. The HCI node is
	normally connected to the Bluetooth device driver node
	(downstream) and the L2CAP node (upstream). All HCI
	operations must be performed on the HCI node and not on the
	device driver node. Default name for the HCI node is
	<quote>devicehci</quote>. For more details refer to the
	&man.ng.hci.4; manual page.</para>

	<para>One of the most common tasks is discovery of Bluetooth
	devices in RF proximity. This operation is called
	<emphasis>inquiry</emphasis>. Inquiry and other HCI related
	operations are done with the &man.hccontrol.8; utility. The
	example below shows how to find out which Bluetooth devices
	are in range. You should receive the list of devices in a few
	seconds. Note that a remote device will only answer the
	inquiry if it put into <emphasis>discoverable</emphasis>
	mode.</para>

	<screen>&prompt.user; <userinput>hccontrol -n ubt0hci inquiry</userinput>
	Inquiry result, num_responses=1
	Inquiry result #0
	BD_ADDR: 00:80:37:29:19:a4
	Page Scan Rep. Mode: 0x1
	Page Scan Period Mode: 00
	Page Scan Mode: 00
	Class: 52:02:04
	Clock offset: 0x78ef
	Inquiry complete. Status: No error [00]</screen>

	<para><literal>BD_ADDR</literal> is unique address of a
	Bluetooth device, similar to MAC addresses of a network card.
	This address is needed for further communication with a
	device. It is possible to assign human readable name to a
	BD_ADDR. The <filename>/etc/bluetooth/hosts</filename> file
	contains information regarding the known Bluetooth hosts. The
	following example shows how to obtain human readable name that
	was assigned to the remote device:</para>

	<screen>&prompt.user; <userinput>hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4</userinput>
	BD_ADDR: 00:80:37:29:19:a4
	Name: Pav's T39</screen>

	<para>If you perform an inquiry on a remote Bluetooth device, it
	will find your computer as
	<quote>your.host.name (ubt0)</quote>. The name assigned to the
	local device can be changed at any time.</para>

	<para>The Bluetooth system provides a point-to-point connection
	(only two Bluetooth units involved), or a point-to-multipoint
	connection. In the point-to-multipoint connection the
	connection is shared among several Bluetooth devices. The
	following example shows how to obtain the list of active
	baseband connections for the local device:</para>

	<screen>&prompt.user; <userinput>hccontrol -n ubt0hci read_connection_list</userinput>
	Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State
	00:80:37:29:19:a4 41 ACL 0 MAST NONE 0 0 OPEN</screen>

	<para>A <emphasis>connection handle</emphasis> is useful when
	termination of the baseband connection is required. Note,
	that it is normally not required to do it by hand. The stack
	will automatically terminate inactive baseband
	connections.</para>

	<screen>&prompt.root; <userinput>hccontrol -n ubt0hci disconnect 41</userinput>
	Connection handle: 41
	Reason: Connection terminated by local host [0x16]</screen>

	<para>Refer to <command>hccontrol help</command> for a complete
	listing of available HCI commands. Most of the HCI commands
	do not require superuser privileges.</para>
	</sect2>

	<sect2>
	<title>Logical Link Control and Adaptation Protocol
	(L2CAP)</title>

	<indexterm><primary>L2CAP</primary></indexterm>

	<para>Logical Link Control and Adaptation Protocol (L2CAP)
	provides connection-oriented and connectionless data services
	to upper layer protocols with protocol multiplexing capability
	and segmentation and reassembly operation. L2CAP permits
	higher level protocols and applications to transmit and
	receive L2CAP data packets up to 64 kilobytes in
	length.</para>

	<para>L2CAP is based around the concept of
	<emphasis>channels</emphasis>. Channel is a logical
	connection on top of baseband connection. Each channel is
	bound to a single protocol in a many-to-one fashion. Multiple
	channels can be bound to the same protocol, but a channel
	cannot be bound to multiple protocols. Each L2CAP packet
	received on a channel is directed to the appropriate higher
	level protocol. Multiple channels can share the same baseband
	connection.</para>

	<para>A single Netgraph node of type <emphasis>l2cap</emphasis>
	is created for a single Bluetooth device. The L2CAP node is
	normally connected to the Bluetooth HCI node (downstream) and
	Bluetooth sockets nodes (upstream). Default name for the
	L2CAP node is <quote>devicel2cap</quote>. For more details
	refer to the &man.ng.l2cap.4; manual page.</para>

	<para>A useful command is &man.l2ping.8;, which can be used to
	ping other devices. Some Bluetooth implementations might not
	return all of the data sent to them, so
	<literal>0 bytes</literal> in the following example is
	normal.</para>

	<screen>&prompt.root; <userinput>l2ping -a 00:80:37:29:19:a4</userinput>
	0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0
	0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0
	0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0
	0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0</screen>

	<para>The &man.l2control.8; utility is used to perform various
	operations on L2CAP nodes. This example shows how to obtain
	the list of logical connections (channels) and the list of
	baseband connections for the local device:</para>

	<screen>&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_channel_list</userinput>
	L2CAP channels:
	Remote BD_ADDR SCID/ DCID PSM IMTU/ OMTU State
	00:07:e0:00:0b:ca 66/ 64 3 132/ 672 OPEN
	&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_connection_list</userinput>
	L2CAP connections:
	Remote BD_ADDR Handle Flags Pending State
	00:07:e0:00:0b:ca 41 O 0 OPEN</screen>

	<para>Another diagnostic tool is &man.btsockstat.1;. It does a
	job similar to as &man.netstat.1; does, but for Bluetooth
	network-related data structures. The example below shows the
	same logical connection as &man.l2control.8; above.</para>

	<screen>&prompt.user; <userinput>btsockstat</userinput>
	Active L2CAP sockets
	PCB Recv-Q Send-Q Local address/PSM Foreign address CID State
	c2afe900 0 0 00:02:72:00:d4:1a/3 00:07:e0:00:0b:ca 66 OPEN
	Active RFCOMM sessions
	L2PCB PCB Flag MTU Out-Q DLCs State
	c2afe900 c2b53380 1 127 0 Yes OPEN
	Active RFCOMM sockets
	PCB Recv-Q Send-Q Local address Foreign address Chan DLCI State
	c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPEN</screen>
	</sect2>

	<sect2>
	<title>RFCOMM Protocol</title>

	<para>The RFCOMM protocol provides emulation of serial ports
	over the L2CAP protocol. The protocol is based on the ETSI
	standard TS 07.10. RFCOMM is a simple transport protocol,
	with additional provisions for emulating the 9 circuits of
	RS-232 (EIATIA-232-E) serial ports. The RFCOMM protocol
	supports up to 60 simultaneous connections (RFCOMM channels)
	between two Bluetooth devices.</para>

	<para>For the purposes of RFCOMM, a complete communication path
	involves two applications running on different devices (the
	communication endpoints) with a communication segment between
	them. RFCOMM is intended to cover applications that make use
	of the serial ports of the devices in which they reside. The
	communication segment is a Bluetooth link from one device to
	another (direct connect).</para>

	<para>RFCOMM is only concerned with the connection between the
	devices in the direct connect case, or between the device and
	a modem in the network case. RFCOMM can support other
	configurations, such as modules that communicate via Bluetooth
	wireless technology on one side and provide a wired interface
	on the other side.</para>

	<para>In &os; the RFCOMM protocol is implemented at the
	Bluetooth sockets layer.</para>
	</sect2>

	<sect2>
	<title>Pairing of Devices</title>

	<para>By default, Bluetooth communication is not authenticated,
	and any device can talk to any other device. A Bluetooth
	device (for example, cellular phone) may choose to require
	authentication to provide a particular service (for example,
	Dial-Up service). Bluetooth authentication is normally done
	with <emphasis>PIN codes</emphasis>. A PIN code is an ASCII
	string up to 16 characters in length. User is required to
	enter the same PIN code on both devices. Once user has
	entered the PIN code, both devices will generate a
	<emphasis>link key</emphasis>. After that the link key can be
	stored either in the devices themselves or in a persistent
	storage. Next time both devices will use previously generated
	link key. The described above procedure is called
	<emphasis>pairing</emphasis>. Note that if the link key is
	lost by any device then pairing must be repeated.</para>

	<para>The &man.hcsecd.8; daemon is responsible for handling of
	all Bluetooth authentication requests. The default
	configuration file is
	<filename>/etc/bluetooth/hcsecd.conf</filename>. An example
	section for a cellular phone with the PIN code arbitrarily set
	to <quote>1234</quote> is shown below:</para>

	<programlisting>device {
	bdaddr 00:80:37:29:19:a4;
	name "Pav's T39";
	key nokey;
	pin "1234";
	}</programlisting>

	<para>There is no limitation on PIN codes (except length). Some
	devices (for example Bluetooth headsets) may have a fixed PIN
	code built in. The <option>-d</option> switch forces the
	&man.hcsecd.8; daemon to stay in the foreground, so it is easy
	to see what is happening. Set the remote device to receive
	pairing and initiate the Bluetooth connection to the remote
	device. The remote device should say that pairing was
	accepted, and request the PIN code. Enter the same PIN code
	as you have in <filename>hcsecd.conf</filename>. Now your PC
	and the remote device are paired. Alternatively, you can
	initiate pairing on the remote device.</para>

	<para>The following line can be added to the
	<filename>/etc/rc.conf</filename> file to have
	<application>hcsecd</application> started automatically on
	system start:</para>

	<programlisting>hcsecd_enable="YES"</programlisting>

	<para>The following is a sample of the
	<application>hcsecd</application> daemon output:</para>

	<programlisting>hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
	hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist
	hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4
	hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
	hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists
	hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4</programlisting>
	</sect2>

	<sect2>
	<title>Service Discovery Protocol (SDP)</title>

	<indexterm><primary>SDP</primary></indexterm>

	<para>The Service Discovery Protocol (SDP) provides the means
	for client applications to discover the existence of services
	provided by server applications as well as the attributes of
	those services. The attributes of a service include the type
	or class of service offered and the mechanism or protocol
	information needed to utilize the service.</para>

	<para>SDP involves communication between a SDP server and a SDP
	client. The server maintains a list of service records that
	describe the characteristics of services associated with the
	server. Each service record contains information about a
	single service. A client may retrieve information from a
	service record maintained by the SDP server by issuing a SDP
	request. If the client, or an application associated with the
	client, decides to use a service, it must open a separate
	connection to the service provider in order to utilize the
	service. SDP provides a mechanism for discovering services
	and their attributes, but it does not provide a mechanism for
	utilizing those services.</para>

	<para>Normally, a SDP client searches for services based on some
	desired characteristics of the services. However, there are
	times when it is desirable to discover which types of services
	are described by an SDP server's service records without any a
	priori information about the services. This process of
	looking for any offered services is called
	<emphasis>browsing</emphasis>.</para>

	<para>The Bluetooth SDP server &man.sdpd.8; and command line
	client &man.sdpcontrol.8; are included in the standard &os;
	installation. The following example shows how to perform a
	SDP browse query.</para>

	<screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec browse</userinput>
	Record Handle: 00000000
	Service Class ID List:
	Service Discovery Server (0x1000)
	Protocol Descriptor List:
	L2CAP (0x0100)
	Protocol specific parameter #1: u/int/uuid16 1
	Protocol specific parameter #2: u/int/uuid16 1

	Record Handle: 0x00000001
	Service Class ID List:
	Browse Group Descriptor (0x1001)

	Record Handle: 0x00000002
	Service Class ID List:
	LAN Access Using PPP (0x1102)
	Protocol Descriptor List:
	L2CAP (0x0100)
	RFCOMM (0x0003)
	Protocol specific parameter #1: u/int8/bool 1
	Bluetooth Profile Descriptor List:
	LAN Access Using PPP (0x1102) ver. 1.0</screen>

	<para>... and so on. Note that each service has a list of
	attributes (RFCOMM channel for example). Depending on the
	service you might need to make a note of some of the
	attributes. Some Bluetooth implementations do not support
	service browsing and may return an empty list. In this case
	it is possible to search for the specific service. The
	example below shows how to search for the OBEX Object Push
	(OPUSH) service:</para>

	<screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH</userinput></screen>

	<para>Offering services on &os; to Bluetooth clients is done
	with the &man.sdpd.8; server. The following line can be added
	to the <filename>/etc/rc.conf</filename> file:</para>

	<programlisting>sdpd_enable="YES"</programlisting>

	<para>Then the <application>sdpd</application> daemon can be
	started with:</para>

	<screen>&prompt.root; <userinput>service sdpd start</userinput></screen>

	<para>The local server application that wants to provide
	Bluetooth service to the remote clients will register service
	with the local SDP daemon. The example of such application is
	&man.rfcomm.pppd.8;. Once started it will register Bluetooth
	LAN service with the local SDP daemon.</para>

	<para>The list of services registered with the local SDP server
	can be obtained by issuing SDP browse query via local control
	channel:</para>

	<screen>&prompt.root; <userinput>sdpcontrol -l browse</userinput></screen>
	</sect2>

	<sect2>
	<title>Dial-Up Networking (DUN) and Network Access with PPP
	(LAN) Profiles</title>

	<para>The Dial-Up Networking (DUN) profile is mostly used with
	modems and cellular phones. The scenarios covered by this
	profile are the following:</para>

	<itemizedlist>
	<listitem>
	<para>use of a cellular phone or modem by a computer as a
	wireless modem for connecting to a dial-up Internet access
	server, or using other dial-up services;</para>
	</listitem>

	<listitem>
	<para>use of a cellular phone or modem by a computer to
	receive data calls.</para>
	</listitem>
	</itemizedlist>

	<para>Network Access with PPP (LAN) profile can be used in the
	following situations:</para>

	<itemizedlist>
	<listitem>
	<para>LAN access for a single Bluetooth device;</para>
	</listitem>

	<listitem>
	<para>LAN access for multiple Bluetooth devices;</para>
	</listitem>

	<listitem>
	<para>PC to PC (using PPP networking over serial cable
	emulation).</para>
	</listitem>
	</itemizedlist>

	<para>In &os; both profiles are implemented with &man.ppp.8; and
	&man.rfcomm.pppd.8; - a wrapper that converts RFCOMM Bluetooth
	connection into something PPP can operate with. Before any
	profile can be used, a new PPP label in the
	<filename>/etc/ppp/ppp.conf</filename> must be created.
	Consult &man.rfcomm.pppd.8; manual page for examples.</para>

	<para>In the following example &man.rfcomm.pppd.8; will be used
	to open RFCOMM connection to remote device with BD_ADDR
	00:80:37:29:19:a4 on DUN RFCOMM channel. The actual RFCOMM
	channel number will be obtained from the remote device via
	SDP. It is possible to specify RFCOMM channel by hand, and in
	this case &man.rfcomm.pppd.8; will not perform SDP query. Use
	&man.sdpcontrol.8; to find out RFCOMM channel on the remote
	device.</para>

	<screen>&prompt.root; <userinput>rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup</userinput></screen>

	<para>In order to provide Network Access with PPP (LAN) service
	the &man.sdpd.8; server must be running. A new entry for LAN
	clients must be created in the
	<filename>/etc/ppp/ppp.conf</filename> file. Consult
	&man.rfcomm.pppd.8; manual page for examples. Finally, start
	RFCOMM PPP server on valid RFCOMM channel number. The RFCOMM
	PPP server will automatically register Bluetooth LAN service
	with the local SDP daemon. The example below shows how to
	start RFCOMM PPP server.</para>

	<screen>&prompt.root; <userinput>rfcomm_pppd -s -C 7 -l rfcomm-server</userinput></screen>
	</sect2>

	<sect2>
	<title>OBEX Object Push (OPUSH) Profile</title>

	<indexterm><primary>OBEX</primary></indexterm>
	<para>OBEX is a widely used protocol for simple file transfers
	between mobile devices. Its main use is in infrared
	communication, where it is used for generic file transfers
	between notebooks or PDAs, and for sending business cards or
	calendar entries between cellular phones and other devices
	with PIM applications.</para>

	<para>The OBEX server and client are implemented as a
	third-party package <application>obexapp</application>, which
	is available as <filename
	role="package">comms/obexapp</filename> port.</para>

	<para>OBEX client is used to push and/or pull objects from the
	OBEX server. An object can, for example, be a business card
	or an appointment. The OBEX client can obtain RFCOMM channel
	number from the remote device via SDP. This can be done by
	specifying service name instead of RFCOMM channel number.
	Supported service names are: IrMC, FTRN and OPUSH. It is
	possible to specify RFCOMM channel as a number. Below is an
	example of an OBEX session, where device information object is
	pulled from the cellular phone, and a new object (business
	card) is pushed into the phone's directory.</para>

	<screen>&prompt.user; <userinput>obexapp -a 00:80:37:29:19:a4 -C IrMC</userinput>
	obex> get telecom/devinfo.txt devinfo-t39.txt
	Success, response: OK, Success (0x20)
	obex> put new.vcf
	Success, response: OK, Success (0x20)
	obex> di
	Success, response: OK, Success (0x20)</screen>

	<para>In order to provide OBEX Object Push service, &man.sdpd.8;
	server must be running. A root folder, where all incoming
	objects will be stored, must be created. The default path to
	- the root folder is <filename>/var/spool/obex</filename>.
	+ the root folder
	+ is <filename class="directory">/var/spool/obex</filename>.
	Finally, start OBEX server on valid RFCOMM channel number.
	The OBEX server will automatically register OBEX Object Push
	service with the local SDP daemon. The example below shows
	how to start OBEX server.</para>

	<screen>&prompt.root; <userinput>obexapp -s -C 10</userinput></screen>
	</sect2>

	<sect2>
	<title>Serial Port Profile (SPP)</title>

	<para>The Serial Port Profile (SPP) allows Bluetooth devices to
	perform RS232 (or similar) serial cable emulation. The
	scenario covered by this profile deals with legacy
	applications using Bluetooth as a cable replacement, through a
	virtual serial port abstraction.</para>

	<para>The &man.rfcomm.sppd.1; utility implements the Serial Port
	profile. A pseudo tty is used as a virtual serial port
	abstraction. The example below shows how to connect to a
	remote device Serial Port service. Note that you do not have
	to specify a RFCOMM channel - &man.rfcomm.sppd.1; can obtain
	it from the remote device via SDP. If you would like to
	override this, specify a RFCOMM channel on the command
	line.</para>

	<screen>&prompt.root; <userinput>rfcomm_sppd -a 00:07:E0:00:0B:CA -t /dev/ttyp6</userinput>
	rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen>

	<para>Once connected, the pseudo tty can be used as serial
	port:</para>

	<screen>&prompt.root; <userinput>cu -l ttyp6</userinput></screen>
	</sect2>

	<sect2>
	<title>Troubleshooting</title>

	<sect3>
	<title>A Remote Device Cannot Connect</title>

	<para>Some older Bluetooth devices do not support role
	switching. By default, when &os; is accepting a new
	connection, it tries to perform a role switch and become
	master. Devices, which do not support this will not be able
	to connect. Note that role switching is performed when a
	new connection is being established, so it is not possible
	to ask the remote device if it does support role switching.
	There is a HCI option to disable role switching on the local
	side:</para>

	<screen>&prompt.root; <userinput>hccontrol -n ubt0hci write_node_role_switch 0</userinput></screen>
	</sect3>

	<sect3>
	<title>Something is Going Wrong, Can I See What Exactly is
	Happening?</title>

	<para>Yes, you can. Use the third-party package
	<application>hcidump</application>, which is available as
	<filename role="package">comms/hcidump</filename> port. The
	<application>hcidump</application> utility is similar to
	&man.tcpdump.1;. It can be used to display the content of
	the Bluetooth packets on the terminal and to dump the
	Bluetooth packets to a file.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="network-bridging">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Andrew</firstname>
	<surname>Thompson</surname>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Bridging</title>

	<sect2>
	<title>Introduction</title>

	<indexterm><primary>IP subnet</primary></indexterm>
	<indexterm><primary>bridge</primary></indexterm>
	<para>It is sometimes useful to divide one physical network
	(such as an Ethernet segment) into two separate network
	segments without having to create IP subnets and use a router
	to connect the segments together. A device that connects two
	networks together in this fashion is called a
	<quote>bridge</quote>. A FreeBSD system with two network
	interface cards can act as a bridge.</para>

	<para>The bridge works by learning the MAC layer addresses
	(Ethernet addresses) of the devices on each of its network
	interfaces. It forwards traffic between two networks only
	when its source and destination are on different
	networks.</para>

	<para>In many respects, a bridge is like an Ethernet switch with
	very few ports.</para>
	</sect2>

	<sect2>
	<title>Situations Where Bridging Is Appropriate</title>

	<para>There are many common situations in which a bridge is used
	today.</para>

	<sect3>
	<title>Connecting Networks</title>

	<para>The basic operation of a bridge is to join two or more
	network segments together. There are many reasons to use a
	host based bridge over plain networking equipment such as
	cabling constraints, firewalling or connecting pseudo
	networks such as a Virtual Machine interface. A bridge can
	also connect a wireless interface running in hostap mode to
	a wired network and act as an access point.</para>
	</sect3>

	<sect3>
	<title>Filtering/Traffic Shaping Firewall</title>

	<indexterm><primary>firewall</primary></indexterm>
	<indexterm><primary>NAT</primary></indexterm>

	<para>A common situation is where firewall functionality is
	needed without routing or network address translation
	(NAT).</para>

	<para>An example is a small company that is connected via DSL
	or ISDN to their ISP. They have a 13 globally-accessible IP
	addresses from their ISP and have 10 PCs on their network.
	In this situation, using a router-based firewall is
	difficult because of subnetting issues.</para>

	<indexterm><primary>router</primary></indexterm>
	<indexterm><primary>DSL</primary></indexterm>
	<indexterm><primary>ISDN</primary></indexterm>
	<para>A bridge-based firewall can be configured and dropped
	into the path just downstream of their DSL/ISDN router
	without any IP numbering issues.</para>
	</sect3>

	<sect3>
	<title>Network Tap</title>

	<para>A bridge can join two network segments and be used to
	inspect all Ethernet frames that pass between them. This
	can either be from using &man.bpf.4;/&man.tcpdump.1; on the
	bridge interface or by sending a copy of all frames out an
	additional interface (span port).</para>
	</sect3>

	<sect3>
	<title>Layer 2 VPN</title>

	<para>Two Ethernet networks can be joined across an IP link by
	bridging the networks to an EtherIP tunnel or a &man.tap.4;
	based solution such as OpenVPN.</para>
	</sect3>

	<sect3>
	<title>Layer 2 Redundancy</title>

	<para>A network can be connected together with multiple links
	and use the Spanning Tree Protocol to block redundant paths.
	For an Ethernet network to function properly only one active
	path can exist between two devices, Spanning Tree will
	detect loops and put the redundant links into a blocked
	state. Should one of the active links fail then the
	protocol will calculate a different tree and reenable one of
	the blocked paths to restore connectivity to all points in
	the network.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Kernel Configuration</title>

	<para>This section covers &man.if.bridge.4; bridge
	implementation, a netgraph bridging driver is also available,
	for more information see &man.ng.bridge.4; manual page.</para>

	<para>The bridge driver is a kernel module and will be
	automatically loaded by &man.ifconfig.8; when creating a
	bridge interface. It is possible to compile the bridge in to
	the kernel by adding <literal>device if_bridge</literal> to
	your kernel configuration file.</para>

	<para>Packet filtering can be used with any firewall package
	that hooks in via the &man.pfil.9; framework. The firewall
	can be loaded as a module or compiled into the kernel.</para>

	<para>The bridge can be used as a traffic shaper with
	&man.altq.4; or &man.dummynet.4;.</para>
	</sect2>

	<sect2>
	<title>Enabling the Bridge</title>

	<para>The bridge is created using interface cloning. To create
	a bridge use &man.ifconfig.8;, if the bridge driver is not
	present in the kernel then it will be loaded
	automatically.</para>

	<screen>&prompt.root; <userinput>ifconfig bridge create</userinput>
	bridge0
	&prompt.root; <userinput>ifconfig bridge0</userinput>
	bridge0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> metric 0 mtu 1500
	ether 96:3d:4b:f1:79:7a
	id 00:00:00:00:00:00 priority 32768 hellotime 2 fwddelay 15
	maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
	root id 00:00:00:00:00:00 priority 0 ifcost 0 port 0</screen>

	<para>A bridge interface is created and is automatically
	assigned a randomly generated Ethernet address. The
	<literal>maxaddr</literal> and <literal>timeout</literal>
	parameters control how many MAC addresses the bridge will keep
	in its forwarding table and how many seconds before each entry
	is removed after it is last seen. The other parameters
	control how Spanning Tree operates.</para>

	<para>Add the member network interfaces to the bridge. For the
	bridge to forward packets all member interfaces and the bridge
	need to be up:</para>

	<screen>&prompt.root; <userinput>ifconfig bridge0 addm fxp0 addm fxp1 up</userinput>
	&prompt.root; <userinput>ifconfig fxp0 up</userinput>
	&prompt.root; <userinput>ifconfig fxp1 up</userinput></screen>

	<para>The bridge is now forwarding Ethernet frames between
	<devicename>fxp0</devicename> and
	<devicename>fxp1</devicename>. The equivalent configuration
	in <filename>/etc/rc.conf</filename> so the bridge is created
	at startup is:</para>

	<programlisting>cloned_interfaces="bridge0"
	ifconfig_bridge0="addm fxp0 addm fxp1 up"
	ifconfig_fxp0="up"
	ifconfig_fxp1="up"</programlisting>

	<para>If the bridge host needs an IP address then the correct
	place to set this is on the bridge interface itself rather
	than one of the member interfaces. This can be set statically
	or via DHCP:</para>

	<screen>&prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen>

	<para>It is also possible to assign an IPv6 address to a bridge
	interface.</para>
	</sect2>

	<sect2>
	<title>Firewalling</title>

	<indexterm><primary>firewall</primary></indexterm>

	<para>When packet filtering is enabled, bridged packets will
	pass through the filter inbound on the originating interface,
	on the bridge interface and outbound on the appropriate
	interfaces. Either stage can be disabled. When direction of
	the packet flow is important it is best to firewall on the
	member interfaces rather than the bridge itself.</para>

	<para>The bridge has several configurable settings for passing
	non-IP and ARP packets, and layer2 firewalling with IPFW. See
	&man.if.bridge.4; for more information.</para>
	</sect2>

	<sect2>
	<title>Spanning Tree</title>

	<para>The bridge driver implements the Rapid Spanning Tree
	Protocol (RSTP or 802.1w) with backwards compatibility with
	the legacy Spanning Tree Protocol (STP). Spanning Tree is
	used to detect and remove loops in a network topology. RSTP
	provides faster Spanning Tree convergence than legacy STP, the
	protocol will exchange information with neighbouring switches
	to quickly transition to forwarding without creating
	loops.
	&os; supports RSTP and STP as operating modes, with RSTP
	being the default mode.</para>

	<para>Spanning Tree can be enabled on member interfaces using
	the <literal>stp</literal> command. For a bridge with
	<devicename>fxp0</devicename> and
	<devicename>fxp1</devicename> as the current interfaces,
	enable STP with the following:</para>

	<screen>&prompt.root; <userinput>ifconfig bridge0 stp fxp0 stp fxp1</userinput>
	bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	ether d6:cf:d5:a0:94:6d
	id 00:01:02:4b:d4:50 priority 32768 hellotime 2 fwddelay 15
	maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
	root id 00:01:02:4b:d4:50 priority 32768 ifcost 0 port 0
	member: fxp0 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP>
	port 3 priority 128 path cost 200000 proto rstp
	role designated state forwarding
	member: fxp1 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP>
	port 4 priority 128 path cost 200000 proto rstp
	role designated state forwarding</screen>

	<para>This bridge has a spanning tree ID of
	<literal>00:01:02:4b:d4:50</literal> and a priority of
	<literal>32768</literal>. As the <literal>root id</literal>
	is the same it indicates that this is the root bridge for the
	tree.</para>

	<para>Another bridge on the network also has spanning tree
	enabled:</para>

	<screen>bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	ether 96:3d:4b:f1:79:7a
	id 00:13:d4:9a:06:7a priority 32768 hellotime 2 fwddelay 15
	maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
	root id 00:01:02:4b:d4:50 priority 32768 ifcost 400000 port 4
	member: fxp0 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP>
	port 4 priority 128 path cost 200000 proto rstp
	role root state forwarding
	member: fxp1 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP>
	port 5 priority 128 path cost 200000 proto rstp
	role designated state forwarding</screen>

	<para>The line <literal>root id 00:01:02:4b:d4:50 priority 32768
	ifcost 400000 port 4</literal> shows that the root bridge is
	<literal>00:01:02:4b:d4:50</literal> as above and has a path
	cost of <literal>400000</literal> from this bridge, the path
	to the root bridge is via <literal>port 4</literal> which is
	<devicename>fxp0</devicename>.</para>
	</sect2>

	<sect2>
	<title>Advanced Bridging</title>

	<sect3>
	<title>Reconstruct Traffic Flows</title>

	<para>The bridge supports monitor mode, where the packets are
	discarded after &man.bpf.4; processing, and are not
	processed or forwarded further. This can be used to
	multiplex the input of two or more interfaces into a single
	&man.bpf.4; stream. This is useful for reconstructing the
	traffic for network taps that transmit the RX/TX signals out
	through two separate interfaces.</para>

	<para>To read the input from four network interfaces as one
	stream:</para>

	<screen>&prompt.root; <userinput>ifconfig bridge0 addm fxp0 addm fxp1 addm fxp2 addm fxp3 monitor up</userinput>
	&prompt.root; <userinput>tcpdump -i bridge0</userinput></screen>
	</sect3>

	<sect3>
	<title>Span Ports</title>

	<para>A copy of every Ethernet frame received by the bridge
	will be transmitted out a designated span port. The number
	of span ports configured on a bridge is unlimited, if an
	interface is designated as a span port then it may not also
	be used as a regular bridge port. This is most useful for
	snooping a bridged network passively on another host
	connected to one of the span ports of the bridge.</para>

	<para>To send a copy of all frames out the interface named
	<devicename>fxp4</devicename>:</para>

	<screen>&prompt.root; <userinput>ifconfig bridge0 span fxp4</userinput></screen>
	</sect3>

	<sect3>
	<title>Private Interfaces</title>

	<para>A private interface does not forward any traffic to any
	other port that is also a private interface. The traffic is
	blocked unconditionally so no Ethernet frames will be
	forwarded, including ARP. If traffic needs to be
	selectively blocked then a firewall should be used
	instead.</para>
	</sect3>

	<sect3>
	<title>Sticky Interfaces</title>

	<para>If a bridge member interface is marked as sticky then
	dynamically learned address entries are treated at static
	once entered into the forwarding cache. Sticky entries are
	never aged out of the cache or replaced, even if the address
	is seen on a different interface. This gives the benefit of
	static address entries without the need to pre-populate the
	forwarding table, clients learnt on a particular segment of
	the bridge can not roam to another segment.</para>

	<para>Another example of using sticky addresses would be to
	combine the bridge with VLANs to create a router where
	customer networks are isolated without wasting IP address
	space. Consider that
	<hostid role="hostname">CustomerA</hostid> is on
	<literal>vlan100</literal> and
	<hostid role="hostname">CustomerB</hostid> is on
	<literal>vlan101</literal>. The bridge has the address
	<hostid role="ipaddr">192.168.0.1</hostid> and is also an
	internet router.</para>

	<screen>&prompt.root; <userinput>ifconfig bridge0 addm vlan100 sticky vlan100 addm vlan101 sticky vlan101</userinput>
	&prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen>

	<para>Both clients see
	<hostid role="ipaddr">192.168.0.1</hostid> as their default
	gateway and since the bridge cache is sticky they can not
	spoof the MAC address of the other customer to intercept
	their traffic.</para>

	<para>Any communication between the VLANs can be blocked using
	private interfaces (or a firewall):</para>

	<screen>&prompt.root; <userinput>ifconfig bridge0 private vlan100 private vlan101</userinput></screen>

	<para>The customers are completely isolated from each other,
	the full <hostid role="netmask">/24</hostid> address range
	can be allocated without subnetting.</para>
	</sect3>

	<sect3>
	<title>Address Limits</title>

	<para>The number of unique source MAC addresses behind an
	interface can be limited. Once the limit is reached packets
	with unknown source addresses are dropped until an
	existing host cache entry expires or is removed.</para>

	<para>The following example sets the maximum number of
	Ethernet devices for
	<hostid role="hostname">CustomerA</hostid> on
	<literal>vlan100</literal> to 10.</para>

	<screen>&prompt.root; <userinput>ifconfig bridge0 ifmaxaddr vlan100 10</userinput></screen>
	</sect3>

	<sect3>
	<title>SNMP Monitoring</title>

	<para>The bridge interface and STP parameters can be monitored
	via the SNMP daemon which is included in the &os; base
	system. The exported bridge MIBs conform to the IETF
	standards so any SNMP client or monitoring package can be
	used to retrieve the data.</para>

	<para>On the bridge machine uncomment the
	<literal>begemotSnmpdModulePath."bridge" =
	"/usr/lib/snmp_bridge.so"</literal> line from
	<filename>/etc/snmp.config</filename> and start the
	<application>bsnmpd</application> daemon. Other
	configuration such as community names and access lists may
	need to be modified. See &man.bsnmpd.1; and
	&man.snmp.bridge.3; for more information.</para>

	<para>The following examples use the
	<application>Net-SNMP</application> software
	(<filename role="package">net-mgmt/net-snmp</filename>) to
	query a bridge, the
	<filename role="package">net-mgmt/bsnmptools</filename> port
	can also be used. From the SNMP client host add to
	<filename>$HOME/.snmp/snmp.conf</filename> the following
	lines to import the bridge MIB definitions in to
	<application>Net-SNMP</application>:</para>

	<programlisting>mibdirs +/usr/share/snmp/mibs
	mibs +BRIDGE-MIB:RSTP-MIB:BEGEMOT-MIB:BEGEMOT-BRIDGE-MIB</programlisting>

	<para>To monitor a single bridge via the IETF BRIDGE-MIB
	(RFC4188) do</para>

	<screen>&prompt.user; <userinput>snmpwalk -v 2c -c public bridge1.example.com mib-2.dot1dBridge</userinput>
	BRIDGE-MIB::dot1dBaseBridgeAddress.0 = STRING: 66:fb:9b:6e:5c:44
	BRIDGE-MIB::dot1dBaseNumPorts.0 = INTEGER: 1 ports
	BRIDGE-MIB::dot1dStpTimeSinceTopologyChange.0 = Timeticks: (189959) 0:31:39.59 centi-seconds
	BRIDGE-MIB::dot1dStpTopChanges.0 = Counter32: 2
	BRIDGE-MIB::dot1dStpDesignatedRoot.0 = Hex-STRING: 80 00 00 01 02 4B D4 50
	...
	BRIDGE-MIB::dot1dStpPortState.3 = INTEGER: forwarding(5)
	BRIDGE-MIB::dot1dStpPortEnable.3 = INTEGER: enabled(1)
	BRIDGE-MIB::dot1dStpPortPathCost.3 = INTEGER: 200000
	BRIDGE-MIB::dot1dStpPortDesignatedRoot.3 = Hex-STRING: 80 00 00 01 02 4B D4 50
	BRIDGE-MIB::dot1dStpPortDesignatedCost.3 = INTEGER: 0
	BRIDGE-MIB::dot1dStpPortDesignatedBridge.3 = Hex-STRING: 80 00 00 01 02 4B D4 50
	BRIDGE-MIB::dot1dStpPortDesignatedPort.3 = Hex-STRING: 03 80
	BRIDGE-MIB::dot1dStpPortForwardTransitions.3 = Counter32: 1
	RSTP-MIB::dot1dStpVersion.0 = INTEGER: rstp(2)</screen>

	<para>The <literal>dot1dStpTopChanges.0</literal> value is two
	which means that the STP bridge topology has changed twice,
	a topology change means that one or more links in the
	network have changed or failed and a new tree has been
	calculated. The
	<literal>dot1dStpTimeSinceTopologyChange.0</literal> value
	will show when this happened.</para>

	<para>To monitor multiple bridge interfaces one may use the
	private BEGEMOT-BRIDGE-MIB:</para>

	<screen>&prompt.user; <userinput>snmpwalk -v 2c -c public bridge1.example.com</userinput>
	enterprises.fokus.begemot.begemotBridge
	BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge0" = STRING: bridge0
	BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge2" = STRING: bridge2
	BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge0" = STRING: e:ce:3b:5a:9e:13
	BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge2" = STRING: 12:5e:4d:74:d:fc
	BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge0" = INTEGER: 1
	BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge2" = INTEGER: 1
	...
	BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge0" = Timeticks: (116927) 0:19:29.27 centi-seconds
	BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge2" = Timeticks: (82773) 0:13:47.73 centi-seconds
	BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge0" = Counter32: 1
	BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge2" = Counter32: 1
	BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge0" = Hex-STRING: 80 00 00 40 95 30 5E 31
	BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge2" = Hex-STRING: 80 00 00 50 8B B8 C6 A9</screen>

	<para>To change the bridge interface being monitored via the
	<literal>mib-2.dot1dBridge</literal> subtree do:</para>

	<screen>&prompt.user; <userinput>snmpset -v 2c -c private bridge1.example.com</userinput>
	BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="network-aggregation">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Andrew</firstname>
	<surname>Thompson</surname>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Link Aggregation and Failover</title>

	<indexterm><primary>lagg</primary></indexterm>
	<indexterm><primary>failover</primary></indexterm>
	<indexterm><primary>fec</primary></indexterm>
	<indexterm><primary>lacp</primary></indexterm>
	<indexterm><primary>loadbalance</primary></indexterm>
	<indexterm><primary>roundrobin</primary></indexterm>

	<sect2>
	<title>Introduction</title>

	<para>The &man.lagg.4; interface allows aggregation of multiple
	network interfaces as one virtual interface for the purpose of
	providing fault-tolerance and high-speed links.</para>
	</sect2>

	<sect2>
	<title>Operating Modes</title>

	<variablelist>
	<varlistentry>
	<term>Failover</term>
	<listitem>
	<para>Sends and receives traffic only through the master
	port. If the master port becomes unavailable, the next
	active port is used. The first interface added is the
	master port; any interfaces added after that are used as
	failover devices. If failover to a non-master port
	occurs, the original port will become master when it
	becomes available again.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&cisco; Fast &etherchannel;</term>
	<listitem>
	<para>&cisco; Fast &etherchannel; (FEC), is a static setup
	and does not negotiate aggregation with the peer or
	exchange frames to monitor the link. If the switch
	supports LACP then that should be used instead.</para>

	<para><acronym>FEC</acronym> balances outgoing traffic
	across the active ports based on hashed protocol header
	information and accepts incoming traffic from any active
	port. The hash includes the Ethernet source and
	destination address, and, if available, the VLAN tag,
	and the IPv4/IPv6 source and destination address.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>LACP</term>
	<listitem>
	<para>The &ieee; 802.3ad Link Aggregation Control Protocol
	(LACP) and the Marker Protocol. LACP will negotiate a
	set of aggregable links with the peer in to one or more
	Link Aggregated Groups (LAG). Each LAG is composed of
	ports of the same speed, set to full-duplex operation.
	The traffic will be balanced across the ports in the LAG
	with the greatest total speed, in most cases there will
	only be one LAG which contains all ports. In the event
	of changes in physical connectivity, Link Aggregation
	will quickly converge to a new configuration.</para>

	<para><acronym>LACP</acronym> balances outgoing traffic
	across the active ports based on hashed protocol header
	information and accepts incoming traffic from any active
	port. The hash includes the Ethernet source and
	destination address, and, if available, the VLAN tag,
	and the IPv4/IPv6 source and destination address.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Loadbalance</term>
	<listitem>
	<para>This is an alias of <emphasis>FEC</emphasis>
	mode.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Round-robin</term>
	<listitem>
	<para>Distributes outgoing traffic using a round-robin
	scheduler through all active ports and accepts incoming
	traffic from any active port. This mode violates
	Ethernet Frame ordering and should be used with
	caution.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect2>

	<sect2>
	<title>Examples</title>

	<example id="networking-lacp-aggregation-cisco">
	<title>LACP Aggregation with a &cisco; Switch</title>

	<para>This example connects two interfaces on a &os; machine
	to the switch as a single load balanced and fault tolerant
	link. More interfaces can be added to increase throughput
	and fault tolerance. Since frame ordering is mandatory on
	Ethernet links then any traffic between two stations always
	flows over the same physical link limiting the maximum speed
	to that of one interface. The transmit algorithm attempts
	to use as much information as it can to distinguish
	different traffic flows and balance across the available
	interfaces.</para>

	<para>On the &cisco; switch add the
	<replaceable>FastEthernet0/1</replaceable> and
	<replaceable>FastEthernet0/2</replaceable> interfaces to the
	channel-group <replaceable>1</replaceable>:</para>

	<screen><userinput>interface <replaceable>FastEthernet0/1</replaceable>
	channel-group <replaceable>1</replaceable> mode active
	channel-protocol lacp</userinput>
	!
	<userinput>interface <replaceable>FastEthernet0/2</replaceable>
	channel-group <replaceable>1</replaceable> mode active
	channel-protocol lacp</userinput></screen>

	<para>Create the &man.lagg.4; interface using
	<replaceable>fxp0</replaceable> and
	<replaceable>fxp1</replaceable>, and bring the interfaces up
	with the IP Address of
	<replaceable>10.0.0.3/24</replaceable>:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput>
	&prompt.root; <userinput>ifconfig <replaceable>fxp1</replaceable> up</userinput>
	&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create </userinput>
	&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable></userinput></screen>

	<para>View the interface status by running:</para>

	<screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput></screen>

	<para>Ports marked as <emphasis>ACTIVE</emphasis> are part of
	the active aggregation group that has been negotiated with
	the remote switch and traffic will be transmitted and
	received. Use the verbose output of &man.ifconfig.8; to
	view the LAG identifiers.</para>

	<screen>lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	options=8<VLAN_MTU>
	ether 00:05:5d:71:8d:b8
	media: Ethernet autoselect
	status: active
	laggproto lacp
	laggport: fxp1 flags=1c<ACTIVE,COLLECTING,DISTRIBUTING>
	laggport: fxp0 flags=1c<ACTIVE,COLLECTING,DISTRIBUTING></screen>

	<para>To see the port status on the switch, use
	<userinput>show lacp neighbor</userinput>:</para>

	<screen>switch# show lacp neighbor
	Flags: S - Device is requesting Slow LACPDUs
	F - Device is requesting Fast LACPDUs
	A - Device is in Active mode P - Device is in Passive mode

	Channel group 1 neighbors

	Partner's information:

	LACP port Oper Port Port
	Port Flags Priority Dev ID Age Key Number State
	Fa0/1 SA 32768 0005.5d71.8db8 29s 0x146 0x3 0x3D
	Fa0/2 SA 32768 0005.5d71.8db8 29s 0x146 0x4 0x3D</screen>

	<para>For more detail use the <userinput>show lacp neighbor
	detail</userinput> command.</para>

	<para>To retain this configuration across reboots, the
	following entries can be added to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>ifconfig_<replaceable>fxp0</replaceable>="up"
	ifconfig_<replaceable>fxp1</replaceable>="up"
	cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>"
	ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable>"</programlisting>
	</example>

	<example id="networking-lagg-failover">
	<title>Failover Mode</title>

	<para>Failover mode can be used to switch over to a secondary
	interface if the link is lost on the master interface.
	Bring the underlying physical interfaces up. Create the
	&man.lagg.4; interface, using
	<replaceable>fxp0</replaceable> as the master interface and
	<replaceable>fxp1</replaceable> as the secondary interface
	and assign an IP Address of
	<replaceable>10.0.0.15/24</replaceable>:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput>
	&prompt.root; <userinput>ifconfig <replaceable>fxp1</replaceable> up</userinput>
	&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput>
	&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable></userinput></screen>

	<para>The interface will look something like this, the major
	differences will be the <acronym>MAC</acronym> address and
	the device names:</para>

	<screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput>
	lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	options=8<VLAN_MTU>
	ether 00:05:5d:71:8d:b8
	inet 10.0.0.15 netmask 0xffffff00 broadcast 10.0.0.255
	media: Ethernet autoselect
	status: active
	laggproto failover
	laggport: fxp1 flags=0<>
	laggport: fxp0 flags=5<MASTER,ACTIVE></screen>

	<para>Traffic will be transmitted and received on
	<replaceable>fxp0</replaceable>. If the link is lost on
	<replaceable>fxp0</replaceable> then
	<replaceable>fxp1</replaceable> will become the active link.
	If the link is restored on the master interface then it will
	once again become the active link.</para>

	<para>To retain this configuration across reboots, the
	following entries can be added to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>ifconfig_<replaceable>fxp0</replaceable>="up"
	ifconfig_<replaceable>fxp1</replaceable>="up"
	cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>"
	ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable>"</programlisting>
	</example>

	<example id="networking-lagg-wired-and-wireless">
	<title>Failover Mode Between Wired and Wireless
	Interfaces</title>

	<para>For laptop users, it is usually desirable to make
	wireless as a secondary interface, which is to be used when
	the wired connection is not available. With &man.lagg.4;,
	it is possible to use one IP address, prefer the wired
	connection for both performance and security reasons, while
	maintaining the ability to transfer data over the wireless
	connection.</para>

	<para>In this setup, we will need to override the underlying
	wireless interface's <acronym>MAC</acronym> address to match
	the &man.lagg.4;'s, which is inherited from the master
	interface being used, the wired interface.</para>

	<para>In this setup, we will treat the wired interface,
	<replaceable>bge0</replaceable>, as the master, and the
	wireless interface, <replaceable>wlan0</replaceable>, as the
	failover interface. The <replaceable>wlan0</replaceable>
	was created from <replaceable>iwn0</replaceable> which we
	will set up with the wired connection's
	<acronym>MAC</acronym> address. The first step would be to
	obtain the <acronym>MAC</acronym> address from the wired
	interface:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable></userinput>
	bge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	options=19b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,TSO4>
	ether 00:21:70:da:ae:37
	inet6 fe80::221:70ff:feda:ae37%bge0 prefixlen 64 scopeid 0x2
	nd6 options=29<PERFORMNUD,IFDISABLED,AUTO_LINKLOCAL>
	media: Ethernet autoselect (1000baseT <full-duplex>)
	status: active</screen>

	<para>You can replace the <replaceable>bge0</replaceable> to
	match your reality, and will get a different
	<literal>ether</literal> line which is the
	<acronym>MAC</acronym> address of your wired interface.
	Now, we change the underlying wireless interface,
	<replaceable>iwn0</replaceable>:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>iwn0</replaceable> ether <replaceable>00:21:70:da:ae:37</replaceable></userinput></screen>

	<para>Bring the wireless interface up, but do not set an IP
	address on it:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>iwn0</replaceable> ssid <replaceable>my_router</replaceable> up</userinput></screen>

	<para>Bring the <replaceable>bge0</replaceable> interface up.
	Create the &man.lagg.4; interface with
	<replaceable>bge0</replaceable> as master, and failover to
	<replaceable>wlan0</replaceable> if necessary:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable> up</userinput>
	&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput>
	&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>bge0</replaceable> laggport <replaceable>wlan0</replaceable></userinput></screen>

	<para>The interface will look something like this, the major
	differences will be the <acronym>MAC</acronym> address and
	the device names:</para>

	<screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput>
	lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	options=8<VLAN_MTU>
	ether 00:21:70:da:ae:37
	media: Ethernet autoselect
	status: active
	laggproto failover
	laggport: wlan0 flags=0<>
	laggport: bge0 flags=5<MASTER,ACTIVE></screen>

	<para>Then start the DHCP client to obtain an IP
	address:</para>

	<screen>&prompt.root; <userinput>dhclient <literal>lagg<replaceable>0</replaceable></literal></userinput></screen>

	<para>To retain this configuration across reboots, the
	following entries can be added to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>ifconfig_bge0="up"
	ifconfig_iwn0="ether 00:21:70:da:ae:37"
	wlans_iwn0="wlan0"
	ifconfig_wlan0="WPA"
	cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>"
	ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover laggport bge0 laggport wlan0 DHCP"</programlisting>
	</example>
	</sect2>
	</sect1>

	<sect1 id="network-diskless">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Jean-François</firstname>
	<surname>Dockès</surname>
	<contrib>Updated by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Alex</firstname>
	<surname>Dupre</surname>
	<contrib>Reorganized and enhanced by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Diskless Operation</title>

	<indexterm><primary>diskless workstation</primary></indexterm>
	<indexterm><primary>diskless operation</primary></indexterm>

	<para>A FreeBSD machine can boot over the network and operate
	without a local disk, using file systems mounted from an
	<acronym>NFS</acronym> server. No system modification is
	necessary, beyond standard configuration files. Such a system
	is relatively easy to set up because all the necessary elements
	are readily available:</para>

	<itemizedlist>
	<listitem>
	<para>There are at least two possible methods to load the
	kernel over the network:</para>

	<itemizedlist>
	<listitem>
	<para><acronym>PXE</acronym>: The &intel; Preboot
	eXecution Environment system is a form of smart boot ROM
	built into some networking cards or motherboards. See
	&man.pxeboot.8; for more details.</para>
	</listitem>

	<listitem>
	<para>The <application>Etherboot</application> port
	(<filename role="package">net/etherboot</filename>)
	produces ROM-able code to boot kernels over the network.
	The code can be either burnt into a boot PROM on a
	network card, or loaded from a local floppy (or hard)
	disk drive, or from a running &ms-dos; system. Many
	network cards are supported.</para>
	</listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<para>A sample script
	(<filename>/usr/share/examples/diskless/clone_root</filename>)
	eases the creation and maintenance of the workstation's root
	file system on the server. The script will probably require
	a little customization but it will get you started very
	quickly.</para>
	</listitem>

	<listitem>
	- <para>Standard system startup files exist in
	- <filename>/etc</filename> to detect and support a diskless
	- system startup.</para>
	+ <para>Standard system startup files exist
	+ in <filename class="directory">/etc</filename>
	+ to detect and support a diskless system startup.</para>
	</listitem>

	<listitem>
	<para>Swapping, if needed, can be done either to an
	<acronym>NFS</acronym> file or to a local disk.</para>
	</listitem>
	</itemizedlist>

	<para>There are many ways to set up diskless workstations. Many
	elements are involved, and most can be customized to suit local
	taste. The following will describe variations on the setup of a
	complete system, emphasizing simplicity and compatibility with
	the standard FreeBSD startup scripts. The system described has
	the following characteristics:</para>

	<itemizedlist>
	<listitem>
	<para>The diskless workstations use a shared read-only
	- <filename>/</filename> file system, and a shared
	- read-only <filename>/usr</filename>.</para>
	+ <filename class="directory">/</filename> file system,
	+ and a shared read-only
	+ <filename class="directory">/usr</filename>.</para>

	<para>The root file system is a copy of a standard FreeBSD
	root (typically the server's), with some configuration files
	overridden by ones specific to diskless operation or,
	possibly, to the workstation they belong to.</para>

	<para>The parts of the root which have to be writable are
	overlaid with &man.md.4; file systems. Any changes will be
	lost when the system reboots.</para>
	</listitem>

	<listitem>
	<para>The kernel is transferred and loaded either with
	<application>Etherboot</application> or
	<acronym>PXE</acronym> as some situations may mandate the
	use of either method.</para>
	</listitem>
	</itemizedlist>

	<caution>
	<para>As described, this system is insecure. It should live in
	a protected area of a network, and be untrusted by other
	hosts.</para>
	</caution>

	<para>All the information in this section has been tested using
	&os; 5.2.1-RELEASE.</para>

	<sect2>
	<title>Background Information</title>

	<para>Setting up diskless workstations is both relatively
	straightforward and prone to errors. These are sometimes
	difficult to diagnose for a number of reasons. For
	example:</para>

	<itemizedlist>
	<listitem>
	<para>Compile time options may determine different behaviors
	at runtime.</para>
	</listitem>

	<listitem>
	<para>Error messages are often cryptic or totally
	absent.</para>
	</listitem>
	</itemizedlist>

	<para>In this context, having some knowledge of the background
	mechanisms involved is very useful to solve the problems that
	may arise.</para>

	<para>Several operations need to be performed for a successful
	bootstrap:</para>

	<itemizedlist>
	<listitem>
	<para>The machine needs to obtain initial parameters such as
	its IP address, executable filename, server name, root
	path. This is done using the <acronym>DHCP</acronym> or
	BOOTP protocols. <acronym>DHCP</acronym> is a compatible
	extension of BOOTP, and uses the same port numbers and
	basic packet format.</para>

	<para>It is possible to configure a system to use only
	BOOTP. The &man.bootpd.8; server program is included in
	the base &os; system.</para>

	<para>However, <acronym>DHCP</acronym> has a number of
	advantages over BOOTP (nicer configuration files,
	possibility of using <acronym>PXE</acronym>, plus many
	others not directly related to diskless operation), and we
	will describe mainly a <acronym>DHCP</acronym>
	configuration, with equivalent examples using
	&man.bootpd.8; when possible. The sample configuration
	will use the <application>ISC DHCP</application> software
	package (release 3.0.1.r12 was installed on the test
	server).</para>
	</listitem>

	<listitem>
	<para>The machine needs to transfer one or several programs
	to local memory. Either <acronym>TFTP</acronym> or
	<acronym>NFS</acronym> are used. The choice between
	<acronym>TFTP</acronym> and <acronym>NFS</acronym> is a
	compile time option in several places. A common source of
	error is to specify filenames for the wrong protocol:
	<acronym>TFTP</acronym> typically transfers all files from
	a single directory on the server, and would expect
	filenames relative to this directory.
	<acronym>NFS</acronym> needs absolute file paths.</para>
	</listitem>

	<listitem>
	<para>The possible intermediate bootstrap programs and the
	kernel need to be initialized and executed. There are
	several important variations in this area:</para>

	<itemizedlist>
	<listitem>

	<para><acronym>PXE</acronym> will load &man.pxeboot.8;,
	which is a modified version of the &os; third stage
	loader. The &man.loader.8; will obtain most
	parameters necessary to system startup, and leave them
	in the kernel environment before transferring control.
	It is possible to use a <filename>GENERIC</filename>
	kernel in this case.</para>
	</listitem>

	<listitem>
	<para><application>Etherboot</application>, will
	directly load the kernel, with less preparation. You
	will need to build a kernel with specific
	options.</para>
	</listitem>
	</itemizedlist>

	<para><acronym>PXE</acronym> and
	<application>Etherboot</application> work equally well;
	however, because kernels normally let the &man.loader.8;
	do more work for them, <acronym>PXE</acronym> is the
	preferred method.</para>

	<para>If your <acronym>BIOS</acronym> and network cards
	support <acronym>PXE</acronym>, you should probably use
	it.</para>
	</listitem>

	<listitem>
	<para>Finally, the machine needs to access its file systems.
	<acronym>NFS</acronym> is used in all cases.</para>
	</listitem>
	</itemizedlist>

	<para>See also &man.diskless.8; manual page.</para>
	</sect2>

	<sect2>
	<title>Setup Instructions</title>

	<sect3>
	<title>Configuration Using <application>ISC
	DHCP</application></title>

	<indexterm>
	<primary>DHCP</primary>
	<secondary>diskless operation</secondary>
	</indexterm>

	<para>The <application>ISC DHCP</application> server can
	answer both BOOTP and <acronym>DHCP</acronym>
	requests.</para>

	<para><application>ISC DHCP 4.2</application> is not part of
	the base system. You will first need to install the
	<filename role="package">net/isc-dhcp42-server</filename>
	port or the corresponding package.</para>

	<para>Once <application>ISC DHCP</application> is installed,
	it needs a configuration file to run (normally named
	<filename>/usr/local/etc/dhcpd.conf</filename>). Here
	follows a commented example, where host
	<hostid>margaux</hostid> uses
	<application>Etherboot</application> and host
	<hostid>corbieres</hostid> uses
	<acronym>PXE</acronym>:</para>

	<programlisting>default-lease-time 600;
	max-lease-time 7200;
	authoritative;

	option domain-name "example.com";
	option domain-name-servers 192.168.4.1;
	option routers 192.168.4.1;

	subnet 192.168.4.0 netmask 255.255.255.0 {
	use-host-decl-names on; <co id="co-dhcp-host-name"/>
	option subnet-mask 255.255.255.0;
	option broadcast-address 192.168.4.255;

	host margaux {
	hardware ethernet 01:23:45:67:89:ab;
	fixed-address margaux.example.com;
	next-server 192.168.4.4; <co id="co-dhcp-next-server"/>
	filename "/data/misc/kernel.diskless"; <co id="co-dhcp-filename"/>
	option root-path "192.168.4.4:/data/misc/diskless"; <co id="co-dhcp-root-path"/>
	}
	host corbieres {
	hardware ethernet 00:02:b3:27:62:df;
	fixed-address corbieres.example.com;
	next-server 192.168.4.4;
	filename "pxeboot";
	option root-path "192.168.4.4:/data/misc/diskless";
	}
	}</programlisting>

	<calloutlist>
	<callout arearefs="co-dhcp-host-name">
	<para>This option tells <application>dhcpd</application>
	to send the value in the <literal>host</literal>
	declarations as the hostname for the diskless host.
	An alternate way would be to add an <literal>option
	host-name
	<replaceable>margaux</replaceable></literal> inside
	the <literal>host</literal> declarations.</para>
	</callout>

	<callout arearefs="co-dhcp-next-server">
	<para>The <literal>next-server</literal> directive
	designates the <acronym>TFTP</acronym> or
	<acronym>NFS</acronym> server to use for loading
	loader or kernel file (the default is to use the same
	host as the <acronym>DHCP</acronym> server).</para>
	</callout>

	<callout arearefs="co-dhcp-filename">
	<para>The <literal>filename</literal> directive
	defines the file that
	<application>Etherboot</application> or
	<acronym>PXE</acronym> will load for the next execution
	step. It must be specified according to the transfer
	method used. <application>Etherboot</application> can
	be compiled to use <acronym>NFS</acronym> or
	<acronym>TFTP</acronym>. The &os; port configures
	<acronym>NFS</acronym> by default.
	<acronym>PXE</acronym> uses <acronym>TFTP</acronym>,
	which is why a relative filename is used here (this may
	depend on the <acronym>TFTP</acronym> server
	configuration, but would be fairly typical). Also,
	<acronym>PXE</acronym> loads
	<filename>pxeboot</filename>, not the kernel. There are
	other interesting possibilities, like loading
	<filename>pxeboot</filename> from a &os; CD-ROM
	<filename class="directory">/boot</filename> directory
	(as &man.pxeboot.8; can load a
	<filename>GENERIC</filename> kernel, this makes it
	possible to use <acronym>PXE</acronym> to boot from a
	remote CD-ROM).</para>
	</callout>

	<callout arearefs="co-dhcp-root-path">
	<para>The <literal>root-path</literal> option defines
	the path to the root file system, in usual
	<acronym>NFS</acronym> notation. When using
	<acronym>PXE</acronym>, it is possible to leave off the
	host's IP as long as you do not enable the kernel option
	BOOTP. The <acronym>NFS</acronym> server will then be
	the same as the <acronym>TFTP</acronym> one.</para>
	</callout>
	</calloutlist>
	</sect3>

	<sect3>
	<title>Configuration Using BOOTP</title>

	<indexterm>
	<primary>BOOTP</primary>
	<secondary>diskless operation</secondary>
	</indexterm>

	<para>Here follows an equivalent
	<application>bootpd</application> configuration (reduced to
	one client). This would be found in
	<filename>/etc/bootptab</filename>.</para>

	<para>Please note that <application>Etherboot</application>
	must be compiled with the non-default option
	<literal>NO_DHCP_SUPPORT</literal> in order to use BOOTP,
	and that <acronym>PXE</acronym> <emphasis>needs</emphasis>
	<acronym>DHCP</acronym>. The only obvious advantage of
	<application>bootpd</application> is that it exists in the
	base system.</para>

	<programlisting>.def100:\
	:hn:ht=1:sa=192.168.4.4:vm=rfc1048:\
	:sm=255.255.255.0:\
	:ds=192.168.4.1:\
	:gw=192.168.4.1:\
	:hd="/tftpboot":\
	:bf="/kernel.diskless":\
	:rp="192.168.4.4:/data/misc/diskless":

	margaux:ha=0123456789ab:tc=.def100</programlisting>
	</sect3>

	<sect3>
	<title>Preparing a Boot Program with
	<application>Etherboot</application></title>

	<indexterm>
	<primary>Etherboot</primary>
	</indexterm>

	<para><ulink
	url="http://etherboot.sourceforge.net">Etherboot's Web
	site</ulink> contains <ulink
	url="http://etherboot.sourceforge.net/doc/html/userman/t1.html">
	extensive documentation</ulink> mainly intended for Linux
	systems, but nonetheless containing useful information. The
	following will just outline how you would use
	<application>Etherboot</application> on a FreeBSD
	system.</para>

	<para>You must first install the
	<filename role="package">net/etherboot</filename> package or
	port.</para>

	<para>You can change the <application>Etherboot</application>
	configuration (i.e., to use <acronym>TFTP</acronym> instead
	of <acronym>NFS</acronym>) by editing the
	<filename>Config</filename> file in the
	<application>Etherboot</application> source
	directory.</para>

	<para>For our setup, we shall use a boot floppy. For other
	methods (PROM, or &ms-dos; program), please refer to the
	<application>Etherboot</application> documentation.</para>

	<para>To make a boot floppy, insert a floppy in the drive on
	the machine where you installed
	<application>Etherboot</application>, then change your
	- current directory to the <filename>src</filename> directory
	- in the <application>Etherboot</application> tree and
	+ current directory to
	+ the <filename class="directory">src</filename>
	+ directory in the <application>Etherboot</application> tree and
	type:</para>

	<screen>&prompt.root; <userinput>gmake bin32/<replaceable>devicetype</replaceable>.fd0</userinput></screen>

	<para><replaceable>devicetype</replaceable> depends on the
	type of the Ethernet card in the diskless workstation.
	Refer to the <filename>NIC</filename> file in the same
	directory to determine the right
	<replaceable>devicetype</replaceable>.</para>
	</sect3>

	<sect3>
	<title>Booting with <acronym>PXE</acronym></title>

	<para>By default, the &man.pxeboot.8; loader loads the kernel
	via <acronym>NFS</acronym>. It can be compiled to use
	<acronym>TFTP</acronym> instead by specifying the
	<literal>LOADER_TFTP_SUPPORT</literal> option in
	<filename>/etc/make.conf</filename>. See the comments in
	<filename>/usr/share/examples/etc/make.conf</filename> for
	instructions.</para>

	<para>There are two other <filename>make.conf</filename>
	options which may be useful for setting up a serial console
	diskless machine:
	<literal>BOOT_PXELDR_PROBE_KEYBOARD</literal>, and
	<literal>BOOT_PXELDR_ALWAYS_SERIAL</literal>.</para>

	<para>To use <acronym>PXE</acronym> when the machine starts,
	you will usually need to select the <literal>Boot from
	network</literal> option in your <acronym>BIOS</acronym>
	setup, or type a function key during the PC
	initialization.</para>
	</sect3>

	<sect3>
	<title>Configuring the <acronym>TFTP</acronym> and
	<acronym>NFS</acronym> Servers</title>

	<indexterm>
	<primary>TFTP</primary>
	<secondary>diskless operation</secondary>
	</indexterm>
	<indexterm>
	<primary>NFS</primary>
	<secondary>diskless operation</secondary>
	</indexterm>

	<para>If you are using <acronym>PXE</acronym> or
	<application>Etherboot</application> configured to use
	<acronym>TFTP</acronym>, you need to enable
	<application>tftpd</application> on the file server:</para>

	<procedure>
	<step>
	<para>Create a directory from which
	<application>tftpd</application> will serve the files,
	- e.g., <filename>/tftpboot</filename>.</para>
	+ e.g., <filename class="directory">/tftpboot</filename>.</para>
	</step>

	<step>
	<para>Add this line to your
	<filename>/etc/inetd.conf</filename>:</para>

	<programlisting>tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /tftpboot</programlisting>

	<note>
	<para>It appears that at least some
	<acronym>PXE</acronym> versions want the
	<acronym>TCP</acronym> version of
	<acronym>TFTP</acronym>. In this case, add a second
	line, replacing <literal>dgram udp</literal> with
	<literal>stream tcp</literal>.</para>
	</note>
	</step>

	<step>
	<para>Tell <application>inetd</application> to reread its
	configuration file. The
	<option>inetd_enable="YES"</option> must be in the
	<filename>/etc/rc.conf</filename> file for this command
	to execute correctly:</para>

	<screen>&prompt.root; <userinput>service inetd restart</userinput></screen>
	</step>
	</procedure>

	- <para>You can place the <filename>tftpboot</filename>
	+ <para>You can place
	+ the <filename class="directory">tftpboot</filename>
	directory anywhere on the server. Make sure that the
	location is set in both <filename>inetd.conf</filename> and
	<filename>dhcpd.conf</filename>.</para>

	<para>In all cases, you also need to enable
	<acronym>NFS</acronym> and export the appropriate file
	system on the <acronym>NFS</acronym> server.</para>

	<procedure>
	<step>
	<para>Add this to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>nfs_server_enable="YES"</programlisting>
	</step>

	<step>
	<para>Export the file system where the diskless root
	directory is located by adding the following to
	<filename>/etc/exports</filename> (adjust the volume
	mount point and replace <replaceable>margaux
	corbieres</replaceable> with the names of the diskless
	workstations):</para>

	<programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux corbieres</replaceable></programlisting>
	</step>

	<step>
	<para>Tell <application>mountd</application> to reread its
	configuration file. If you actually needed to enable
	<acronym>NFS</acronym> in
	<filename>/etc/rc.conf</filename> at the first step, you
	probably want to reboot instead.</para>

	<screen>&prompt.root; <userinput>service mountd restart</userinput></screen>
	</step>
	</procedure>
	</sect3>

	<sect3>
	<title>Building a Diskless Kernel</title>

	<indexterm>
	<primary>diskless operation</primary>
	<secondary>kernel configuration</secondary>
	</indexterm>

	<para>If using <application>Etherboot</application>, you need
	to create a kernel configuration file for the diskless
	client with the following options (in addition to the usual
	ones):</para>

	<programlisting>options BOOTP # Use BOOTP to obtain IP address/hostname
	options BOOTP_NFSROOT # NFS mount root file system using BOOTP info</programlisting>

	<para>You may also want to use <literal>BOOTP_NFSV3</literal>,
	<literal>BOOT_COMPAT</literal> and
	<literal>BOOTP_WIRED_TO</literal> (refer to
	<filename>NOTES</filename>).</para>

	<para>These option names are historical and slightly
	misleading as they actually enable indifferent use of
	<acronym>DHCP</acronym> and BOOTP inside the kernel (it is
	also possible to force strict BOOTP or
	<acronym>DHCP</acronym> use).</para>

	<para>Build the kernel (see <xref linkend="kernelconfig"/>),
	and copy it to the place specified in
	<filename>dhcpd.conf</filename>.</para>

	<note>
	<para>When using <acronym>PXE</acronym>, building a kernel
	with the above options is not strictly necessary (though
	suggested). Enabling them will cause more
	<acronym>DHCP</acronym> requests to be issued during
	kernel startup, with a small risk of inconsistency between
	the new values and those retrieved by &man.pxeboot.8; in
	some special cases. The advantage of using them is that
	the host name will be set as a side effect. Otherwise you
	will need to set the host name by another method, for
	example in a client-specific <filename>rc.conf</filename>
	file.</para>
	</note>

	<note>
	<para>In order to be loadable with
	<application>Etherboot</application>, a kernel needs to
	have the device hints compiled in. You would typically
	set the following option in the configuration file (see
	the <filename>NOTES</filename> configuration comments
	file):</para>

	<programlisting>hints "GENERIC.hints"</programlisting>
	</note>
	</sect3>

	<sect3>
	<title>Preparing the Root Filesystem</title>

	<indexterm>
	<primary>root file system</primary>
	<secondary>diskless operation</secondary>
	</indexterm>

	<para>You need to create a root file system for the diskless
	workstations, in the location listed as
	<literal>root-path</literal> in
	<filename>dhcpd.conf</filename>.</para>

	<sect4>
	<title>Using <command>make world</command> to Populate
	Root</title>

	<para>This method is quick and will install a complete
	virgin system (not only the root file system) into
	<envar>DESTDIR</envar>. All you have to do is simply
	execute the following script:</para>

	<programlisting>#!/bin/sh
	export DESTDIR=/data/misc/diskless
	mkdir -p ${DESTDIR}
	cd /usr/src; make buildworld && make buildkernel
	make installworld && make installkernel
	cd /usr/src/etc; make distribution</programlisting>

	<para>Once done, you may need to customize your
	<filename>/etc/rc.conf</filename> and
	<filename>/etc/fstab</filename> placed into
	<envar>DESTDIR</envar> according to your needs.</para>
	</sect4>
	</sect3>

	<sect3>
	<title>Configuring Swap</title>

	<para>If needed, a swap file located on the server can be
	accessed via <acronym>NFS</acronym>.</para>

	<sect4>
	<title><acronym>NFS</acronym> Swap</title>

	<para>The kernel does not support enabling
	<acronym>NFS</acronym> swap at boot time. Swap must be
	enabled by the startup scripts, by mounting a writable
	file system and creating and enabling a swap file. To
	create a swap file of appropriate size, you can do like
	this:</para>

	<screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/path/to/swapfile</replaceable> bs=1k count=1 oseek=<replaceable>100000</replaceable></userinput></screen>

	<para>To enable it you have to add the following line to
	your <filename>rc.conf</filename>:</para>

	<programlisting>swapfile=<replaceable>/path/to/swapfile</replaceable></programlisting>
	</sect4>
	</sect3>

	<sect3>
	<title>Miscellaneous Issues</title>

	<sect4>
	<title>Running with a Read-only
	- <filename>/usr</filename></title>
	+ <filename class="directory">/usr</filename></title>

	<indexterm>
	<primary>diskless operation</primary>
	<secondary>/usr read-only</secondary>
	</indexterm>

	<para>If the diskless workstation is configured to run X,
	you will have to adjust the
	<application>XDM</application> configuration file, which
	- puts the error log on <filename>/usr</filename> by
	+ puts the error log
	+ on <filename class="directory">/usr</filename> by
	default.</para>
	</sect4>

	<sect4>
	<title>Using a Non-FreeBSD Server</title>

	<para>When the server for the root file system is not
	running FreeBSD, you will have to create the root file
	system on a FreeBSD machine, then copy it to its
	destination, using <command>tar</command> or
	<command>cpio</command>.</para>

	<para>In this situation, there are sometimes problems with
	- the special files in <filename>/dev</filename>, due to
	+ the special files
	+ in <filename class="directory">/dev</filename>, due to
	differing major/minor integer sizes. A solution to this
	problem is to export a directory from the non-FreeBSD
	server, mount this directory onto a FreeBSD machine, and
	use &man.devfs.5; to allocate device nodes transparently
	for the user.</para>
	</sect4>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="network-pxe-nfs">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Craig</firstname>
	<surname>Rodrigues</surname>
	<affiliation>
	<address>rodrigc@FreeBSD.org</address>
	</affiliation>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>PXE Booting with an NFS Root File System</title>

	<para>The &intel; Preboot eXecution Environment
	(<acronym>PXE</acronym>) allows booting the operating system
	over the network. <acronym>PXE</acronym> support is usually
	provided in the <acronym>BIOS</acronym> of modern motherboards,
	where it can be enabled in the <acronym>BIOS</acronym> settings
	which enable booting from the network. A fully functioning
	<acronym>PXE</acronym> setup also requires properly configured
	<acronym>DHCP</acronym> and <acronym>TFTP</acronym>
	servers.</para>

	<para>When the host computer boots, it receives information over
	<acronym>DHCP</acronym> about where to obtain the initial boot
	loader via TFTP. After the host computer receives this
	information, it downloads the boot loader via
	<acronym>TFTP</acronym>, and then executes the boot loader.
	This is documented in section 2.2.1 of the <ulink
	url="http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf">Preboot
	Execution Environment (PXE) Specification</ulink>. In &os;,
	the boot loader retrieved during the <acronym>PXE</acronym>
	process is <filename>/boot/pxeboot</filename>. After
	<filename>/boot/pxeboot</filename> executes, the &os; kernel is
	loaded, and the rest of the &os; bootup sequence proceeds.
	Refer to <xref linkend="boot"/> for more information about the
	&os; booting process.</para>

	<sect2>
	<title>Setting Up the <command>chroot</command> Environment for
	the NFS Root File System</title>

	<procedure>
	<step>
	<para>Choose a directory which will have a &os;
	installation which will be NFS mountable. For example, a
	directory such as
	- <filename>/b/tftpboot/FreeBSD/install</filename> can be
	+ <filename class="directory">/b/tftpboot/FreeBSD/install</filename> can be
	used.</para>

	<screen>&prompt.root; <userinput>export NFSROOTDIR=/b/tftpboot/FreeBSD/install</userinput>
	&prompt.root; <userinput>mkdir -p ${NFSROOTDIR}</userinput></screen>
	</step>

	<step>
	<para>Enable the NFS server by following the instructions
	in <xref linkend="network-configuring-nfs"/>.</para>
	</step>

	<step>
	<para>Export the directory via NFS by adding the following
	to <filename>/etc/exports</filename>:</para>

	<programlisting>/b -ro -alldirs</programlisting>
	</step>

	<step>
	<para>Restart the NFS server:</para>

	<screen>&prompt.root; <userinput>service nfsd restart</userinput></screen>
	</step>

	<step>
	<para>Enable &man.inetd.8; by following the steps outlined
	in <xref linkend="network-inetd-settings"/>.</para>
	</step>

	<step>
	<para>Add the following line to
	<filename>/etc/inetd.conf</filename>:</para>

	<programlisting>tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /b/tftpboot</programlisting>
	</step>

	<step>
	<para>Restart inetd:</para>

	<screen>&prompt.root; <userinput>service inetd restart</userinput></screen>
	</step>

	<step>
	<para><link linkend="makeworld">Rebuild the &os; kernel and
	userland</link>:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput>
	&prompt.root; <userinput>make buildworld</userinput>
	&prompt.root; <userinput>make buildkernel</userinput></screen>
	</step>

	<step>
	<para>Install &os; into the directory mounted over
	<acronym>NFS</acronym>:</para>

	<screen>&prompt.root; <userinput>make installworld DESTDIR=${NFSROOTDIR}</userinput>
	&prompt.root; <userinput>make installkernel DESTDIR=${NFSROOTDIR}</userinput>
	&prompt.root; <userinput>make distribution DESTDIR=${NFSROOTDIR}</userinput></screen>
	</step>

	<step>
	<para>Test that the <acronym>TFTP</acronym> server works and
	can download the boot loader which will be obtained
	via PXE:</para>

	<screen>&prompt.root; <userinput>tftp localhost</userinput>
	tftp> <userinput>get FreeBSD/install/boot/pxeboot</userinput>
	Received 264951 bytes in 0.1 seconds</screen>
	</step>

	<step>
	<para>Edit <filename>${NFSROOTDIR}/etc/fstab</filename> and
	create an entry to mount the root file system over
	NFS:</para>

	<programlisting># Device Mountpoint FSType Options Dump Pass
	myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro 0 0</programlisting>

	<para>Replace
	<replaceable>myhost.example.com</replaceable> with the
	hostname or IP address of your <acronym>NFS</acronym>
	server. In this example, the root file system is mounted
	"read-only" in order to prevent <acronym>NFS</acronym>
	clients from potentially deleting the contents of the root
	file system.</para>
	</step>

	<step>
	<para>Set the root password in the &man.chroot.8;
	environment.</para>

	<screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput>
	&prompt.root; <userinput>passwd</userinput></screen>

	<para>This will set the root password for client
	machines which are <acronym>PXE</acronym>
	booting.</para>
	</step>

	<step>
	<para>Enable ssh root logins for client machines which are
	<acronym>PXE</acronym> booting by editing
	<filename>${NFSROOTDIR}/etc/ssh/sshd_config</filename> and
	enabling the <literal>PermitRootLogin</literal> option.
	This is documented in &man.sshd.config.5;.</para>
	</step>

	<step>
	<para>Perform other customizations of the &man.chroot.8;
	environment in ${NFSROOTDIR}. These customizations could
	include things like adding packages with &man.pkg.add.1;,
	editing the password file with &man.vipw.8;, or editing
	&man.amd.conf.5; maps for automounting. For
	example:</para>

	<screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput>
	&prompt.root; <userinput>pkg_add -r bash</userinput></screen>
	</step>
	</procedure>
	</sect2>

	<sect2>
	<title>Configuring Memory File Systems Used by
	<filename>/etc/rc.initdiskless</filename></title>

	<para>If you boot from an NFS root volume,
	<filename>/etc/rc</filename> detects that you booted over NFS
	and runs the <filename>/etc/rc.initdiskless</filename> script.
	Read the comments in this script to understand what is going
	- on. We need to make <filename>/etc</filename> and
	- <filename>/var</filename> memory backed file systems because
	+ on. We need to
	+ make <filename class="directory">/etc</filename>
	+ and <filename class="directory">/var</filename>
	+ memory backed file systems because
	these directories need to be writable, but the NFS root
	directory is read-only.</para>

	<screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput>
	&prompt.root; <userinput>mkdir -p conf/base</userinput>
	&prompt.root; <userinput>tar -c -v -f conf/base/etc.cpio.gz --format cpio --gzip etc</userinput>
	&prompt.root; <userinput>tar -c -v -f conf/base/var.cpio.gz --format cpio --gzip var</userinput></screen>

	- <para>When the system boots, memory file systems for
	- <filename>/etc</filename> and <filename>/var</filename> will
	+ <para>When the system boots, memory file systems
	+ for <filename class="directory">/etc</filename>
	+ and <filename class="directory">/var</filename> will
	be created and mounted, and the contents of the
	<filename>cpio.gz</filename> files will be copied into
	them.</para>
	</sect2>

	<sect2 id="network-pxe-setting-up-dhcp">
	<title>Setting up the DHCP Server</title>

	<para>PXE requires a <acronym>TFTP</acronym> server and a
	<acronym>DHCP</acronym> server to be set up. The
	<acronym>DHCP</acronym> server does not necessarily need to be
	the same machine as the <acronym>TFTP</acronym> server, but it
	needs to be accessible in your network.</para>

	<procedure>
	<step>
	<para>Install the <acronym>DHCP</acronym> server by
	following the instructions documented at
	<xref linkend="network-dhcp-server"/>. Make sure that
	<filename>/etc/rc.conf</filename> and
	<filename>/usr/local/etc/dhcpd.conf</filename> are
	correctly configured.</para>
	</step>

	<step>
	<para>In <filename>/usr/local/etc/dhcpd.conf</filename>,
	configure the <literal>next-server</literal>,
	<literal>filename</literal>, and
	<literal>option root-path</literal> settings, to specify
	your <acronym>TFTP</acronym> server IP address, the path
	to <filename>/boot/pxeboot</filename> in
	<acronym>TFTP</acronym>, and the path to the
	<acronym>NFS</acronym> root file system. Here is a sample
	<filename>dhcpd.conf</filename> setup:</para>

	<programlisting>subnet 192.168.0.0 netmask 255.255.255.0 {
	range 192.168.0.2 192.168.0.3 ;
	option subnet-mask 255.255.255.0 ;
	option routers 192.168.0.1 ;
	option broadcast-address 192.168.0.255 ;
	option domain-name-server 192.168.35.35, 192.168.35.36 ;
	option domain-name "example.com";

	# IP address of TFTP server
	next-server 192.168.0.1 ;

	# path of boot loader obtained
	# via tftp
	filename "FreeBSD/install/boot/pxeboot" ;

	# pxeboot boot loader will try to NFS mount this directory for root FS
	option root-path "192.168.0.1:/b/tftpboot/FreeBSD/install/" ;

	}</programlisting>
	</step>
	</procedure>
	</sect2>

	<sect2>
	<title>Configuring the PXE Client and Debugging Connection
	Problems</title>

	<procedure>
	<step>
	<para>When the client machine boots up, enter the
	<acronym>BIOS</acronym> configuration menu. Configure the
	<acronym>BIOS</acronym> to boot from the network. If all
	your previous configuration steps are correct, then
	everything should "just work".</para>
	</step>

	<step>

	<para>Use the
	<filename role="package">net/wireshark</filename> port to
	debug the network traffic involved during the
	<acronym>PXE</acronym> booting process, which is
	illustrated in the diagram below. In
	<xref linkend="network-pxe-setting-up-dhcp"/>, an example
	configuration is shown where the <acronym>DHCP</acronym>,
	<acronym>TFTP</acronym>, and <acronym>NFS</acronym>
	servers are actually on the same machine. However, these
	severs can be on separate machines.</para>

	<figure>
	<title>PXE Booting Process with NFS Root Mount</title>

	<mediaobjectco>
	<imageobjectco>
	<areaspec units="calspair">
	<area id="co-pxenfs1" coords="2873,8133 3313,7266"/>
	<area id="co-pxenfs2" coords="3519,6333 3885,5500"/>
	<area id="co-pxenfs3" coords="4780,5866 5102,5200"/>
	<area id="co-pxenfs4" coords="4794,4333 5102,3600"/>
	<area id="co-pxenfs5" coords="3108,2666 3519,1800"/>
	</areaspec>
	<imageobject>
	<imagedata fileref="advanced-networking/pxe-nfs"/>
	</imageobject>
	<calloutlist>
	<callout arearefs="co-pxenfs1">
	<para>Client broadcasts DHCPDISCOVER.</para>
	</callout>
	<callout arearefs="co-pxenfs2">
	<para>DHCP server responds with IP address,
	<literal>next-server</literal>,
	<literal>filename</literal>, and
	<literal>root-path</literal>.</para>
	</callout>
	<callout arearefs="co-pxenfs3">
	<para>Client sends <acronym>TFTP</acronym>
	request to <literal>next-server</literal>
	asking to retrieve
	<literal>filename</literal>.</para>
	</callout>
	<callout arearefs="co-pxenfs4">
	<para>TFTP server responds and sends
	<literal>filename</literal> to client.</para>
	</callout>
	<callout arearefs="co-pxenfs5">
	<para>Client executes
	<literal>filename</literal> which is
	&man.pxeboot.8;. &man.pxeboot.8; loads the
	kernel. When the kernel executes, the root
	filesystem specified by
	<literal>root-path</literal> is mounted over
	<acronym>NFS</acronym>.</para>
	</callout>
	</calloutlist>
	</imageobjectco>
	</mediaobjectco>
	</figure>
	</step>

	<step>
	<para>Make sure that the <filename>pxeboot</filename> file
	can be retrieved by <acronym>TFTP</acronym>. On your
	<acronym>TFTP</acronym> server, look in
	<filename>/var/log/xferlog</filename> to ensure that the
	<filename>pxeboot</filename> file is being retrieved from
	the correct location. To test the configuration from
	<filename>dhcpd.conf</filename> above:</para>

	<screen>&prompt.root; <userinput>tftp 192.168.0.1</userinput>
	tftp> <userinput>get FreeBSD/install/boot/pxeboot</userinput>
	Received 264951 bytes in 0.1 seconds</screen>

	<para>Read &man.tftpd.8; and &man.tftp.1;. The
	<literal>BUGS</literal> sections in these pages document
	some limitations with <acronym>TFTP</acronym>.</para>
	</step>

	<step>
	<para>Make sure that the root file system can be mounted
	via <acronym>NFS</acronym>. To test configuration from
	<filename>dhcpd.conf</filename> above:</para>

	<screen>&prompt.root; <userinput>mount -t nfs 192.168.0.1:/b/tftpboot/FreeBSD/install /mnt</userinput></screen>
	</step>

	<step>
	<para>Read the code in
	<filename>src/sys/boot/i386/libi386/pxe.c</filename> to
	understand how the <filename>pxeboot</filename> loader
	sets variables like <literal>boot.nfsroot.server</literal>
	and <literal>boot.nfsroot.path</literal>. These variables
	are then used in the NFS diskless root mount code in
	<filename>src/sys/nfsclient/nfs_diskless.c</filename>.</para>
	</step>

	<step>
	<para>Read &man.pxeboot.8; and &man.loader.8;.</para>
	</step>
	</procedure>
	</sect2>
	</sect1>

	<sect1 id="network-isdn">
	<title>ISDN</title>

	<indexterm>
	<primary>ISDN</primary>
	</indexterm>

	<para>A good resource for information on ISDN technology and
	hardware is
	<ulink url="http://www.alumni.caltech.edu/~dank/isdn/">Dan
	Kegel's ISDN Page</ulink>.</para>

	<para>A quick simple road map to ISDN follows:</para>

	<itemizedlist>
	<listitem>
	<para>If you live in Europe you might want to investigate the
	ISDN card section.</para>
	</listitem>

	<listitem>
	<para>If you are planning to use ISDN primarily to connect to
	the Internet with an Internet Provider on a dial-up
	non-dedicated basis, you might look into Terminal Adapters.
	This will give you the most flexibility, with the fewest
	problems, if you change providers.</para>
	</listitem>

	<listitem>
	<para>If you are connecting two LANs together, or connecting
	to the Internet with a dedicated ISDN connection, you might
	consider the stand alone router/bridge option.</para>
	</listitem>
	</itemizedlist>

	<para>Cost is a significant factor in determining what solution
	you will choose. The following options are listed from least
	expensive to most expensive.</para>

	<sect2 id="network-isdn-cards">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Hellmuth</firstname>
	<surname>Michaelis</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>
	<title>ISDN Cards</title>

	<indexterm>
	<primary>ISDN</primary>
	<secondary>cards</secondary>
	</indexterm>

	<para>FreeBSD's ISDN implementation supports only the DSS1/Q.931
	(or Euro-ISDN) standard using passive cards. Some active
	cards are supported where the firmware also supports other
	signaling protocols; this also includes the first supported
	Primary Rate (PRI) ISDN card.</para>

	<para>The <application>isdn4bsd</application> software allows
	you to connect to other ISDN routers using either IP over raw
	HDLC or by using synchronous PPP: either by using kernel PPP
	with <literal>isppp</literal>, a modified &man.sppp.4; driver,
	or by using userland &man.ppp.8;. By using userland
	&man.ppp.8;, channel bonding of two or more ISDN B-channels is
	possible. A telephone answering machine application is also
	available as well as many utilities such as a software 300
	Baud modem.</para>

	<para>Some growing number of PC ISDN cards are supported under
	FreeBSD and the reports show that it is successfully used all
	over Europe and in many other parts of the world.</para>

	<para>The passive ISDN cards supported are mostly the ones with
	the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets,
	but also ISDN cards with chips from Cologne Chip (ISA bus
	only), PCI cards with Winbond W6692 chips, some cards with the
	Tiger300/320/ISAC chipset combinations and some vendor
	specific chipset based cards such as the AVM Fritz!Card PCI
	V.1.0 and the AVM Fritz!Card PnP.</para>

	<para>Currently the active supported ISDN cards are the AVM B1
	(ISA and PCI) BRI cards and the AVM T1 PCI PRI cards.</para>

	<para>For documentation on <application>isdn4bsd</application>,
	have a look at the
	<ulink url="http://www.freebsd-support.de/i4b/">homepage of
	isdn4bsd</ulink> which also has pointers to hints, erratas
	and much more documentation such as the <ulink
	url="http://people.FreeBSD.org/~hm/">isdn4bsd
	handbook</ulink>.</para>

	<para>In case you are interested in adding support for a
	different ISDN protocol, a currently unsupported ISDN PC card
	or otherwise enhancing <application>isdn4bsd</application>,
	please get in touch with &a.hm.email;.</para>

	<para>For questions regarding the installation, configuration
	and troubleshooting <application>isdn4bsd</application>, a
	&a.isdn.name; mailing list is available.</para>
	</sect2>

	<sect2>
	<title>ISDN Terminal Adapters</title>

	<para>Terminal adapters (TA), are to ISDN what modems are to
	regular phone lines.</para>

	<indexterm><primary>modem</primary></indexterm>
	<para>Most TA's use the standard Hayes modem AT command set, and
	can be used as a drop in replacement for a modem.</para>

	<para>A TA will operate basically the same as a modem except
	connection and throughput speeds will be much faster than your
	old modem. You will need to configure
	<link linkend="ppp">PPP</link> exactly the same as for a modem
	setup. Make sure you set your serial speed as high as
	possible.</para>

	<indexterm><primary>PPP</primary></indexterm>
	<para>The main advantage of using a TA to connect to an Internet
	Provider is that you can do Dynamic PPP. As IP address space
	becomes more and more scarce, most providers are not willing
	to provide you with a static IP any more. Most stand-alone
	routers are not able to accommodate dynamic IP
	allocation.</para>

	<para>TA's completely rely on the PPP daemon that you are
	running for their features and stability of connection. This
	allows you to upgrade easily from using a modem to ISDN on a
	FreeBSD machine, if you already have PPP set up. However, at
	the same time any problems you experienced with the PPP
	program and are going to persist.</para>

	<para>If you want maximum stability, use the kernel
	<link linkend="ppp">PPP</link> option, not the
	<link linkend="userppp">userland PPP</link>.</para>

	<para>The following TA's are known to work with FreeBSD:</para>

	<itemizedlist>
	<listitem>
	<para>Motorola BitSurfer and Bitsurfer Pro</para>
	</listitem>

	<listitem>
	<para>Adtran</para>
	</listitem>
	</itemizedlist>

	<para>Most other TA's will probably work as well, TA vendors try
	to make sure their product can accept most of the standard
	modem AT command set.</para>

	<para>The real problem with external TA's is that, like modems,
	you need a good serial card in your computer.</para>

	<para>You should read the <ulink
	url="&url.articles.serial-uart;/index.html">FreeBSD Serial
	Hardware</ulink> tutorial for a detailed understanding of
	serial devices, and the differences between asynchronous and
	synchronous serial ports.</para>

	<para>A TA running off a standard PC serial port (asynchronous)
	limits you to 115.2 Kbs, even though you have a
	128 Kbs connection. To fully utilize the 128 Kbs
	that ISDN is capable of, you must move the TA to a synchronous
	serial card.</para>

	<para>Do not be fooled into buying an internal TA and thinking
	you have avoided the synchronous/asynchronous issue. Internal
	TA's simply have a standard PC serial port chip built into
	them. All this will do is save you having to buy another
	serial cable and find another empty electrical socket.</para>

	<para>A synchronous card with a TA is at least as fast as a
	stand-alone router, and with a simple 386 FreeBSD box driving
	it, probably more flexible.</para>

	<para>The choice of synchronous card/TA versus stand-alone
	router is largely a religious issue. There has been some
	discussion of this in the mailing lists. We suggest you
	search the
	<ulink url="&url.base;/search/index.html">archives</ulink> for
	the complete discussion.</para>
	</sect2>

	<sect2>
	<title>Stand-alone ISDN Bridges/Routers</title>

	<indexterm>
	<primary>ISDN</primary>
	<secondary>stand-alone bridges/routers</secondary>
	</indexterm>
	<para>ISDN bridges or routers are not at all specific to FreeBSD
	or any other operating system. For a more complete
	description of routing and bridging technology, please refer
	to a networking reference book.</para>

	<para>In the context of this section, the terms router and
	bridge will be used interchangeably.</para>

	<para>As the cost of low end ISDN routers/bridges comes down, it
	will likely become a more and more popular choice. An ISDN
	router is a small box that plugs directly into your local
	Ethernet network, and manages its own connection to the other
	bridge/router. It has built in software to communicate via
	PPP and other popular protocols.</para>

	<para>A router will allow you much faster throughput than a
	standard TA, since it will be using a full synchronous ISDN
	connection.</para>

	<para>The main problem with ISDN routers and bridges is that
	interoperability between manufacturers can still be a problem.
	If you are planning to connect to an Internet provider, you
	should discuss your needs with them.</para>

	<para>If you are planning to connect two LAN segments together,
	such as your home LAN to the office LAN, this is the simplest
	lowest
	maintenance solution. Since you are buying the equipment for
	both sides of the connection you can be assured that the link
	will work.</para>

	<para>For example to connect a home computer or branch office
	network to a head office network the following setup could be
	used:</para>

	<example>
	<title>Branch Office or Home Network</title>

	<indexterm><primary>10 base 2</primary></indexterm>
	<para>Network uses a bus based topology with 10 base 2
	Ethernet (<quote>thinnet</quote>). Connect router to
	network cable with AUI/10BT transceiver, if
	necessary.</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="advanced-networking/isdn-bus"/>
	</imageobject>

	<textobject>
	<literallayout class="monospaced">---Sun workstation
	\|
	---FreeBSD box
	\|
	---Windows 95
	\|
	Stand-alone router
	\|
	ISDN BRI line</literallayout>
	</textobject>

	<textobject>
	<phrase>10 Base 2 Ethernet</phrase>
	</textobject>
	</mediaobject>

	<para>If your home/branch office is only one computer you can
	use a twisted pair crossover cable to connect to the
	stand-alone router directly.</para>
	</example>

	<example>
	<title>Head Office or Other LAN</title>

	<indexterm><primary>10 base T</primary></indexterm>
	<para>Network uses a star topology with 10 base T Ethernet
	(<quote>Twisted Pair</quote>).</para>

	<mediaobject>
	<imageobject>
	<imagedata
	fileref="advanced-networking/isdn-twisted-pair"/>
	</imageobject>

	<textobject>
	<literallayout class="monospaced"> -------Novell Server
	\| H \|
	\| ---Sun
	\| \|
	\| U ---FreeBSD
	\| \|
	\| ---Windows 95
	\| B \|
	\|___---Stand-alone router
	\|
	ISDN BRI line</literallayout>
	</textobject>

	<textobject>
	<phrase>ISDN Network Diagram</phrase>
	</textobject>
	</mediaobject>
	</example>

	<para>One large advantage of most routers/bridges is that they
	allow you to have 2 <emphasis>separate independent</emphasis>
	PPP connections to 2 separate sites at the
	<emphasis>same</emphasis> time. This is not supported on most
	TA's, except for specific (usually expensive) models that have
	two serial ports. Do not confuse this with channel bonding,
	MPP, etc.</para>

	<para>This can be a very useful feature if, for example, you
	have an dedicated ISDN connection at your office and would
	like to tap into it, but do not want to get another ISDN line
	at work. A router at the office location can manage a
	dedicated B channel connection (64 Kbps) to the Internet
	and use the other B channel for a separate data connection.
	The second B channel can be used for dial-in, dial-out or
	dynamically bonding (MPP, etc.) with the first B channel for
	more bandwidth.</para>

	<indexterm><primary>IPX/SPX</primary></indexterm>
	<para>An Ethernet bridge will also allow you to transmit more
	than just IP traffic. You can also send IPX/SPX or whatever
	other protocols you use.</para>
	</sect2>
	</sect1>

	<sect1 id="network-natd">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Chern</firstname>
	<surname>Lee</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Network Address Translation</title>

	<sect2 id="network-natoverview">
	<title>Overview</title>

	<indexterm>
	<primary><application>natd</application></primary>
	</indexterm>
	<para>FreeBSD's Network Address Translation daemon, commonly
	known as &man.natd.8; is a daemon that accepts incoming raw IP
	packets, changes the source to the local machine and
	re-injects these packets back into the outgoing IP packet
	stream. &man.natd.8; does this by changing the source IP
	address and port such that when data is received back, it is
	able to determine the original location of the data and
	forward it back to its original requester.</para>

	<indexterm>
	<primary>Internet connection sharing</primary>
	</indexterm>
	<indexterm>
	<primary>NAT</primary>
	</indexterm>
	<para>The most common use of NAT is to perform what is commonly
	known as Internet Connection Sharing.</para>
	</sect2>

	<sect2 id="network-natsetup">
	<title>Setup</title>

	<para>Due to the diminishing IP space in IPv4, and the increased
	number of users on high-speed consumer lines such as cable or
	DSL, people are increasingly in need of an Internet Connection
	Sharing solution. The ability to connect several computers
	online through one connection and IP address makes
	&man.natd.8; a reasonable choice.</para>

	<para>Most commonly, a user has a machine connected to a cable
	or DSL line with one IP address and wishes to use this one
	connected computer to provide Internet access to several more
	over a LAN.</para>

	<para>To do this, the FreeBSD machine on the Internet must act
	as a gateway. This gateway machine must have two
	NICs—one for connecting to the Internet router, the
	other connecting to a LAN. All the machines on the LAN are
	connected through a hub or switch.</para>

	<note>
	<para>There are many ways to get a LAN connected to the
	Internet through a &os; gateway. This example will only
	cover a gateway with at least two NICs.</para>
	</note>

	<mediaobject>
	<imageobject>
	<imagedata fileref="advanced-networking/natd"/>
	</imageobject>

	<textobject>
	<literallayout class="monospaced"> _______ __________ ________
	\| \| \| \| \| \|
	\| Hub \|-----\| Client B \|-----\| Router \|----- Internet
	\|_______\| \|__________\| \|________\|
	\|
	____\|_____
	\| \|
	\| Client A \|
	\|__________\|</literallayout>
	</textobject>

	<textobject>
	<phrase>Network Layout</phrase>
	</textobject>
	</mediaobject>

	<para>A setup like this is commonly used to share an Internet
	connection. One of the <acronym>LAN</acronym> machines is
	connected to the Internet. The rest of the machines access
	the Internet through that <quote>gateway</quote>
	machine.</para>
	</sect2>

	<sect2 id="network-natdloaderconfiguration">
	<title>Boot Loader Configuration</title>

	<indexterm>
	<primary>boot loader</primary>
	<secondary>configuration</secondary>
	</indexterm>

	<para>The kernel features for network address translation with
	&man.natd.8; are not enabled in the
	<filename>GENERIC</filename> kernel, but they can be preloaded
	at boot time, by adding a couple of options to
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>ipfw_load="YES"
	ipdivert_load="YES"</programlisting>

	<para>Additionally, the
	<literal>net.inet.ip.fw.default_to_accept</literal> tunable
	option may be set to <literal>1</literal>:</para>

	<programlisting>net.inet.ip.fw.default_to_accept="1"</programlisting>

	<note>
	<para>It is a very good idea to set this option during the
	first attempts to setup a firewall and NAT gateway. This
	way the default policy of &man.ipfw.8; will be
	<literal>allow ip from any to any</literal> instead of the
	less permissive <literal>deny ip from any to any</literal>,
	and it will be slightly more difficult to get locked out of
	the system right after a reboot.</para>
	</note>
	</sect2>

	<sect2 id="network-natdkernconfiguration">
	<title>Kernel Configuration</title>

	<indexterm>
	<primary>kernel</primary>
	<secondary>configuration</secondary>
	</indexterm>
	<para>When modules are not an option or if it is preferrable to
	build all the required features into the running kernel, the
	following options must be in the kernel configuration
	file:</para>

	<programlisting>options IPFIREWALL
	options IPDIVERT</programlisting>

	<para>Additionally, at choice, the following may also be
	suitable:</para>

	<programlisting>options IPFIREWALL_DEFAULT_TO_ACCEPT
	options IPFIREWALL_VERBOSE</programlisting>
	</sect2>

	<sect2 id="network-natdsystemconfiguration">
	<title>System Startup Configuration</title>

	<para>To enable firewall and NAT support at boot time, the
	following must be in <filename>/etc/rc.conf</filename>:</para>

	<programlisting>gateway_enable="YES" <co id="co-natd-gateway-enable"/>
	firewall_enable="YES" <co id="co-natd-firewall-enable"/>
	firewall_type="OPEN" <co id="co-natd-firewall-type"/>
	natd_enable="YES"
	natd_interface="<replaceable>fxp0</replaceable>" <co id="co-natd-natd-interface"/>
	natd_flags="" <co id="co-natd-natd-flags"/></programlisting>

	<calloutlist>
	<callout arearefs="co-natd-gateway-enable">
	<para>Sets up the machine to act as a gateway. Running
	<command>sysctl net.inet.ip.forwarding=1</command> would
	have the same effect.</para>
	</callout>

	<callout arearefs="co-natd-firewall-enable">
	<para>Enables the firewall rules in
	<filename>/etc/rc.firewall</filename> at boot.</para>
	</callout>

	<callout arearefs="co-natd-firewall-type">
	<para>This specifies a predefined firewall ruleset that
	allows anything in. See
	<filename>/etc/rc.firewall</filename> for additional
	types.</para>
	</callout>

	<callout arearefs="co-natd-natd-interface">
	<para>Indicates which interface to forward packets through
	(the interface connected to the Internet).</para>
	</callout>

	<callout arearefs="co-natd-natd-flags">
	<para>Any additional configuration options passed to
	&man.natd.8; on boot.</para>
	</callout>
	</calloutlist>

	<para>Having the previous options defined in
	<filename>/etc/rc.conf</filename> would run
	<command>natd -interface fxp0</command> at boot. This can
	also be run manually.</para>

	<note>
	<para>It is also possible to use a configuration file for
	&man.natd.8; when there are too many options to pass. In
	this case, the configuration file must be defined by adding
	the following line to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>natd_flags="-f /etc/natd.conf"</programlisting>

	<para>The <filename>/etc/natd.conf</filename> file will
	contain a list of configuration options, one per line. For
	example the next section case would use the following
	file:</para>

	<programlisting>redirect_port tcp 192.168.0.2:6667 6667
	redirect_port tcp 192.168.0.3:80 80</programlisting>

	<para>For more information about the configuration file,
	consult the &man.natd.8; manual page about the
	<option>-f</option> option.</para>
	</note>

	<para>Each machine and interface behind the LAN should be
	assigned IP address numbers in the private network space as
	defined by
	<ulink url="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC
	1918</ulink> and have a default gateway of the
	<application>natd</application> machine's internal IP
	address.</para>

	<para>For example, client <hostid>A</hostid> and
	<hostid>B</hostid> behind the LAN have IP addresses of
	<hostid role="ipaddr">192.168.0.2</hostid> and
	<hostid role="ipaddr">192.168.0.3</hostid>, while the natd
	machine's LAN interface has an IP address of
	<hostid role="ipaddr">192.168.0.1</hostid>. Client
	<hostid>A</hostid> and <hostid>B</hostid>'s default gateway
	must be set to that of the <application>natd</application>
	machine, <hostid role="ipaddr">192.168.0.1</hostid>. The
	<application>natd</application> machine's external, or
	Internet interface does not require any special modification
	for &man.natd.8; to work.</para>
	</sect2>

	<sect2 id="network-natdport-redirection">
	<title>Port Redirection</title>

	<para>The drawback with &man.natd.8; is that the LAN clients are
	not accessible from the Internet. Clients on the LAN can make
	outgoing connections to the world but cannot receive incoming
	ones. This presents a problem if trying to run Internet
	services on one of the LAN client machines. A simple way
	around this is to redirect selected Internet ports on the
	<application>natd</application> machine to a LAN
	client.</para>

	<para>For example, an IRC server runs on client
	<hostid>A</hostid>, and a web server runs on client
	<hostid>B</hostid>. For this to work properly, connections
	received on ports 6667 (IRC) and 80 (web) must be redirected
	to the respective machines.</para>

	<para>The <option>-redirect_port</option> must be passed to
	&man.natd.8; with the proper options. The syntax is as
	follows:</para>

	<programlisting> -redirect_port proto targetIP:targetPORT[-targetPORT]
	[aliasIP:]aliasPORT[-aliasPORT]
	[remoteIP[:remotePORT[-remotePORT]]]</programlisting>

	<para>In the above example, the argument should be:</para>

	<programlisting> -redirect_port tcp 192.168.0.2:6667 6667
	-redirect_port tcp 192.168.0.3:80 80</programlisting>

	<para>This will redirect the proper <emphasis>tcp</emphasis>
	ports to the LAN client machines.</para>

	<para>The <option>-redirect_port</option> argument can be used
	to indicate port ranges over individual ports. For example,
	<replaceable>tcp 192.168.0.2:2000-3000 2000-3000</replaceable>
	would redirect all connections received on ports 2000 to 3000
	to ports 2000 to 3000 on client <hostid>A</hostid>.</para>

	<para>These options can be used when directly running
	&man.natd.8;, placed within the
	<literal>natd_flags=""</literal> option in
	<filename>/etc/rc.conf</filename>, or passed via a
	configuration file.</para>

	<para>For further configuration options, consult
	&man.natd.8;</para>
	</sect2>

	<sect2 id="network-natdaddress-redirection">
	<title>Address Redirection</title>

	<indexterm><primary>address redirection</primary></indexterm>
	<para>Address redirection is useful if several IP addresses are
	available, yet they must be on one machine. With this,
	&man.natd.8; can assign each LAN client its own external IP
	address. &man.natd.8; then rewrites outgoing packets from the
	LAN clients with the proper external IP address and redirects
	all traffic incoming on that particular IP address back to the
	specific LAN client. This is also known as static NAT. For
	example, the IP addresses
	<hostid role="ipaddr">128.1.1.1</hostid>,
	<hostid role="ipaddr">128.1.1.2</hostid>, and
	<hostid role="ipaddr">128.1.1.3</hostid> belong to the
	<application>natd</application> gateway machine.
	<hostid role="ipaddr">128.1.1.1</hostid> can be used as the
	<application>natd</application> gateway machine's external IP
	address, while <hostid role="ipaddr">128.1.1.2</hostid> and
	<hostid role="ipaddr">128.1.1.3</hostid> are forwarded back to
	LAN clients <hostid>A</hostid> and <hostid>B</hostid>.</para>

	<para>The <option>-redirect_address</option> syntax is as
	follows:</para>

	<programlisting>-redirect_address localIP publicIP</programlisting>


	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<tbody>
	<row>
	<entry>localIP</entry>
	<entry>The internal IP address of the LAN
	client.</entry>
	</row>

	<row>
	<entry>publicIP</entry>
	<entry>The external IP address corresponding to the LAN
	client.</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>In the example, this argument would read:</para>

	<programlisting>-redirect_address 192.168.0.2 128.1.1.2
	-redirect_address 192.168.0.3 128.1.1.3</programlisting>

	<para>Like <option>-redirect_port</option>, these arguments are
	also placed within the <literal>natd_flags=""</literal> option
	of <filename>/etc/rc.conf</filename>, or passed via a
	configuration file. With address redirection, there is no
	need for port redirection since all data received on a
	particular IP address is redirected.</para>

	<para>The external IP addresses on the
	<application>natd</application> machine must be active and
	aliased to the external interface. Look at &man.rc.conf.5; to
	do so.</para>
	</sect2>
	</sect1>

	<sect1 id="network-ipv6">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Aaron</firstname>
	<surname>Kaplan</surname>
	<contrib>Originally Written by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Restructured and Added by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Brad</firstname>
	<surname>Davis</surname>
	<contrib>Extended by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>IPv6</title>

	<para>IPv6 (also known as IPng <quote>IP next generation</quote>)
	is the new version of the well known IP protocol (also known as
	<acronym>IPv4</acronym>). Like the other current *BSD systems,
	FreeBSD includes the KAME IPv6 reference implementation. So
	your FreeBSD system comes with all you will need to experiment
	with IPv6. This section focuses on getting IPv6 configured and
	running.</para>

	<para>In the early 1990s, people became aware of the rapidly
	diminishing address space of IPv4. Given the expansion rate of
	the Internet there were two major concerns:</para>

	<itemizedlist>
	<listitem>
	<para>Running out of addresses. Today this is not so much of
	a concern any more, since RFC1918 private address space
	(<hostid role="ipaddr">10.0.0.0/8</hostid>,
	<hostid role="ipaddr">172.16.0.0/12</hostid>, and
	<hostid role="ipaddr">192.168.0.0/16</hostid>) and Network
	Address Translation (<acronym>NAT</acronym>) are being
	employed.</para>
	</listitem>

	<listitem>
	<para>Router table entries were getting too large. This is
	still a concern today.</para>
	</listitem>
	</itemizedlist>

	<para>IPv6 deals with these and many other issues:</para>

	<itemizedlist>
	<listitem>
	<para>128 bit address space. In other words theoretically
	there are
	340,282,366,920,938,463,463,374,607,431,768,211,456
	addresses available. This means there are approximately
	6.67 * 10^27 IPv6 addresses per square meter on our
	planet.</para>
	</listitem>

	<listitem>
	<para>Routers will only store network aggregation addresses in
	their routing tables thus reducing the average space of a
	routing table to 8192 entries.</para>
	</listitem>
	</itemizedlist>

	<para>There are also lots of other useful features of IPv6 such
	as:</para>

	<itemizedlist>
	<listitem>
	<para>Address autoconfiguration (<ulink
	url="http://www.ietf.org/rfc/rfc2462.txt">RFC2462</ulink>)</para>
	</listitem>

	<listitem>
	<para>Anycast addresses (<quote>one-out-of
	many</quote>)</para>
	</listitem>

	<listitem>
	<para>Mandatory multicast addresses</para>
	</listitem>

	<listitem>
	<para>IPsec (IP security)</para>
	</listitem>

	<listitem>
	<para>Simplified header structure</para>
	</listitem>

	<listitem>
	<para>Mobile <acronym>IP</acronym></para>
	</listitem>

	<listitem>
	<para>IPv6-to-IPv4 transition mechanisms</para>
	</listitem>
	</itemizedlist>


	<para>For more information see:</para>

	<itemizedlist>
	<listitem>
	<para>IPv6 overview at <ulink
	url="http://playground.sun.com/pub/ipng/html/ipng-main.html">playground.sun.com</ulink></para>
	</listitem>

	<listitem>
	<para><ulink url="http://www.kame.net">KAME.net</ulink></para>
	</listitem>
	</itemizedlist>

	<sect2>
	<title>Background on IPv6 Addresses</title>

	<para>There are different types of IPv6 addresses: Unicast,
	Anycast and Multicast.</para>

	<para>Unicast addresses are the well known addresses. A packet
	sent to a unicast address arrives exactly at the interface
	belonging to the address.</para>

	<para>Anycast addresses are syntactically indistinguishable from
	unicast addresses but they address a group of interfaces. The
	packet destined for an anycast address will arrive at the
	nearest (in router metric) interface. Anycast addresses may
	only be used by routers.</para>

	<para>Multicast addresses identify a group of interfaces. A
	packet destined for a multicast address will arrive at all
	interfaces belonging to the multicast group.</para>

	<note>
	<para>The IPv4 broadcast address (usually
	<hostid role="ipaddr">xxx.xxx.xxx.255</hostid>) is expressed
	by multicast addresses in IPv6.</para>
	</note>

	<table frame="none">
	<title>Reserved IPv6 Addresses</title>

	<tgroup cols="4">
	<thead>
	<row>
	<entry>IPv6 address</entry>
	<entry>Prefixlength (Bits)</entry>
	<entry>Description</entry>
	<entry>Notes</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><hostid role="ip6addr">::</hostid></entry>
	<entry>128 bits</entry>
	<entry>unspecified</entry>
	<entry>cf. <hostid role="ipaddr">0.0.0.0</hostid> in
	IPv4</entry>
	</row>

	<row>
	<entry><hostid role="ip6addr">::1</hostid></entry>
	<entry>128 bits</entry>
	<entry>loopback address</entry>
	<entry>cf. <hostid role="ipaddr">127.0.0.1</hostid> in
	IPv4</entry>
	</row>

	<row>
	<entry><hostid
	role="ip6addr">::00:xx:xx:xx:xx</hostid></entry>
	<entry>96 bits</entry>
	<entry>embedded IPv4</entry>
	<entry>The lower 32 bits are the IPv4 address. Also
	called <quote>IPv4 compatible IPv6
	address</quote></entry>
	</row>

	<row>
	<entry><hostid
	role="ip6addr">::ff:xx:xx:xx:xx</hostid></entry>
	<entry>96 bits</entry>
	<entry>IPv4 mapped IPv6 address</entry>
	<entry>The lower 32 bits are the IPv4 address.
	For hosts which do not support IPv6.</entry>
	</row>

	<row>
	<entry><hostid role="ip6addr">fe80::</hostid> - <hostid
	role="ip6addr">feb::</hostid></entry>
	<entry>10 bits</entry>
	<entry>link-local</entry>
	<entry>cf. loopback address in IPv4</entry>
	</row>

	<row>
	<entry><hostid role="ip6addr">fec0::</hostid> - <hostid
	role="ip6addr">fef::</hostid></entry>
	<entry>10 bits</entry>
	<entry>site-local</entry>
	<entry> </entry>
	</row>

	<row>
	<entry><hostid role="ip6addr">ff::</hostid></entry>
	<entry>8 bits</entry>
	<entry>multicast</entry>
	<entry> </entry>
	</row>

	<row>
	<entry><hostid role="ip6addr">001</hostid> (base
	2)</entry>
	<entry>3 bits</entry>
	<entry>global unicast</entry>
	<entry>All global unicast addresses are assigned from
	this pool. The first 3 bits are
	<quote>001</quote>.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect2>

	<sect2>
	<title>Reading IPv6 Addresses</title>

	<para>The canonical form is represented as:
	<hostid role="ip6addr">x:x:x:x:x:x:x:x</hostid>, each
	<quote>x</quote> being a 16 Bit hex value. For example
	<hostid
	role="ip6addr">FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</hostid></para>

	<para>Often an address will have long substrings of all zeros
	therefore one such substring per address can be abbreviated by
	<quote>::</quote>. Also up to three leading <quote>0</quote>s
	per hexquad can be omitted. For example
	<hostid role="ip6addr">fe80::1</hostid> corresponds to the
	canonical form <hostid
	role="ip6addr">fe80:0000:0000:0000:0000:0000:0000:0001</hostid>.</para>

	<para>A third form is to write the last 32 Bit part in the
	well known (decimal) IPv4 style with dots <quote>.</quote>
	as separators. For example
	<hostid role="ip6addr">2002::10.0.0.1</hostid>
	corresponds to the (hexadecimal) canonical representation
	<hostid
	role="ip6addr">2002:0000:0000:0000:0000:0000:0a00:0001</hostid>
	which in turn is equivalent to writing
	<hostid role="ip6addr">2002::a00:1</hostid>.</para>

	<para>By now the reader should be able to understand the
	following:</para>

	<screen>&prompt.root; <userinput>ifconfig</userinput></screen>

	<programlisting>rl0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> mtu 1500
	inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255
	inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1
	ether 00:00:21:03:08:e1
	media: Ethernet autoselect (100baseTX )
	status: active</programlisting>

	<para><hostid
	role="ip6addr">fe80::200:21ff:fe03:8e1%rl0</hostid>
	is an auto configured link-local address. It is generated
	from the MAC address as part of the auto configuration.</para>

	<para>For further information on the structure of IPv6 addresses
	see <ulink
	url="http://www.ietf.org/rfc/rfc3513.txt">RFC3513</ulink>.</para>
	</sect2>

	<sect2>
	<title>Getting Connected</title>

	<para>Currently there are four ways to connect to other IPv6
	hosts and networks:</para>

	<itemizedlist>
	<listitem>
	<para>Contact your Internet Service Provider to see if they
	offer IPv6 yet.</para>
	</listitem>

	<listitem>
	<para><ulink url="http://www.sixxs.net">SixXS</ulink> offers
	tunnels with end-points all around the globe.</para>
	</listitem>

	<listitem>
	<para>Tunnel via 6-to-4 (<ulink
	url="http://www.ietf.org/rfc/rfc3068.txt">RFC3068</ulink>)</para>
	</listitem>

	<listitem>
	<para>Use the
	<filename role="package">net/freenet6</filename> port if
	you are on a dial-up connection.</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2>
	<title>DNS in the IPv6 World</title>

	<para>There used to be two types of DNS records for IPv6. The
	IETF has declared A6 records obsolete. AAAA records are the
	standard now.</para>

	<para>Using AAAA records is straightforward. Assign your
	hostname to the new IPv6 address you just received by
	adding:</para>

	<programlisting>MYHOSTNAME AAAA MYIPv6ADDR</programlisting>

	<para>To your primary zone DNS file. In case you do not serve
	your own <acronym>DNS</acronym> zones ask your
	<acronym>DNS</acronym> provider. Current versions of
	<application>bind</application> (version 8.3 and 9) and
	<filename role="package">dns/djbdns</filename> (with the IPv6
	patch) support AAAA records.</para>
	</sect2>

	<sect2>
	<title>Applying the Needed Changes to
	<filename>/etc/rc.conf</filename></title>

	<sect3>
	<title>IPv6 Client Settings</title>

	<para>These settings will help you configure a machine that
	will be on your LAN and act as a client, not a router. To
	have &man.rtsol.8; autoconfigure your interface on boot on
	&os; 9.<replaceable>x</replaceable> and later,
	add:</para>

	<programlisting>ipv6_prefer="YES"</programlisting>

	<para>to <filename>rc.conf</filename>.</para>

	<para>For &os; 8.<replaceable>x</replaceable> and
	earlier, add:</para>

	<programlisting>ipv6_enable="YES"</programlisting>

	<para>To statically assign an IP address such as <hostid
	role="ip6addr">2001:471:1f11:251:290:27ff:fee0:2093</hostid>,
	to your <devicename>fxp0</devicename> interface, add the
	following for
	&os; 9.<replaceable>x</replaceable>:</para>

	<programlisting>ifconfig_fxp0_ipv6="inet6 2001:471:1f11:251:290:27ff:fee0:2093 prefixlen <replaceable>64</replaceable>"</programlisting>

	<note>
	<para>Be sure to change <replaceable>prefixlen
	64</replaceable> to the appropriate value for the subnet
	within which the computer is networked.</para>
	</note>

	<para>For &os; 8<replaceable>x</replaceable> and earlier,
	add:</para>

	<programlisting>ipv6_ifconfig_fxp0="2001:471:1f11:251:290:27ff:fee0:2093"</programlisting>

	<para>To assign a default router of
	<hostid role="ip6addr">2001:471:1f11:251::1</hostid> add the
	following to <filename>/etc/rc.conf</filename>:</para>

	<programlisting>ipv6_defaultrouter="2001:471:1f11:251::1"</programlisting>
	</sect3>

	<sect3>
	<title>IPv6 Router/Gateway Settings</title>

	<para>This will help you take the directions that your tunnel
	provider has given you and convert it into settings that
	will persist through reboots. To restore your tunnel on
	startup use something like the following in
	<filename>/etc/rc.conf</filename>:</para>

	<para>List the Generic Tunneling interfaces that will be
	configured, for example
	<devicename>gif0</devicename>:</para>

	<programlisting>gif_interfaces="gif0"</programlisting>

	<para>To configure the interface with a local endpoint of
	<replaceable>MY_IPv4_ADDR</replaceable> to a remote endpoint
	of <replaceable>REMOTE_IPv4_ADDR</replaceable>:</para>

	<programlisting>gifconfig_gif0="<replaceable>MY_IPv4_ADDR REMOTE_IPv4_ADDR</replaceable>"</programlisting>

	<para>To apply the IPv6 address you have been assigned for use
	as your IPv6 tunnel endpoint, add the following for
	&os; 9.<replaceable>x</replaceable> and later:</para>

	<programlisting>ifconfig_gif0_ipv6="inet6 <replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>

	<para>For &os; 8.<replaceable>x</replaceable> and
	earlier, add:</para>

	<programlisting>ipv6_ifconfig_gif0="<replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>

	<para>Then all you have to do is set the default route for
	IPv6. This is the other side of the IPv6 tunnel:</para>

	<programlisting>ipv6_defaultrouter="<replaceable>MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>
	</sect3>

	<sect3>
	<title>IPv6 Tunnel Settings</title>

	<para>If the server is to route IPv6 between the rest of your
	network and the world, the following
	<filename>/etc/rc.conf</filename> setting will also be
	needed:</para>

	<programlisting>ipv6_gateway_enable="YES"</programlisting>
	</sect3>
	</sect2>

	<sect2>
	<title>Router Advertisement and Host Auto Configuration</title>

	<para>This section will help you setup &man.rtadvd.8; to
	advertise the IPv6 default route.</para>

	<para>To enable &man.rtadvd.8; you will need the following in
	your <filename>/etc/rc.conf</filename>:</para>

	<programlisting>rtadvd_enable="YES"</programlisting>

	<para>It is important that you specify the interface on which to
	do IPv6 router solicitation. For example to tell
	&man.rtadvd.8; to use <devicename>fxp0</devicename>:</para>

	<programlisting>rtadvd_interfaces="fxp0"</programlisting>

	<para>Now we must create the configuration file,
	<filename>/etc/rtadvd.conf</filename>. Here is an
	example:</para>

	<programlisting>fxp0:\
	:addrs#1:addr="2001:471:1f11:246::":prefixlen#64:tc=ether:</programlisting>

	<para>Replace <devicename>fxp0</devicename> with the interface
	you are going to be using.</para>

	<para>Next, replace
	<hostid role="ip6addr">2001:471:1f11:246::</hostid> with the
	prefix of your allocation.</para>

	<para>If you are dedicated a <hostid role="netmask">/64</hostid>
	subnet you will not need to change anything else. Otherwise,
	you will need to change the <literal>prefixlen#</literal> to
	the correct value.</para>
	</sect2>
	</sect1>

	<sect1 id="network-atm">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Harti</firstname>
	<surname>Brandt</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>Asynchronous Transfer Mode (ATM)</title>

	<sect2>
	<title>Configuring Classical IP over ATM (PVCs)</title>

	<para>Classical IP over ATM (<acronym>CLIP</acronym>) is the
	simplest method to use Asynchronous Transfer Mode (ATM)
	with IP. It can be used with
	switched connections (SVCs) and with permanent connections
	(PVCs). This section describes how to set up a network based
	on PVCs.</para>

	<sect3>
	<title>Fully Meshed Configurations</title>

	<para>The first method to set up a <acronym>CLIP</acronym>
	with PVCs is to connect each machine to each other machine
	in the network via a dedicated PVC. While this is simple to
	configure it tends to become impractical for a larger number
	of machines. The example supposes that we have four
	machines in the network, each connected to the
	<acronym role="Asynchronous Transfer Mode">ATM</acronym>
	network with an
	<acronym role="Asynchronous Transfer Mode">ATM</acronym>
	adapter card. The first step is the planning of the IP
	addresses and the
	<acronym role="Asynchronous Transfer Mode">ATM</acronym>
	connections between the machines. We use the
	following:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<colspec colwidth="1*"/>
	<colspec colwidth="1*"/>
	<thead>
	<row>
	<entry>Host</entry>
	<entry>IP Address</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><hostid>hostA</hostid></entry>
	<entry><hostid
	role="ipaddr">192.168.173.1</hostid></entry>
	</row>

	<row>
	<entry><hostid>hostB</hostid></entry>
	<entry><hostid
	role="ipaddr">192.168.173.2</hostid></entry>
	</row>

	<row>
	<entry><hostid>hostC</hostid></entry>
	<entry><hostid
	role="ipaddr">192.168.173.3</hostid></entry>
	</row>

	<row>
	<entry><hostid>hostD</hostid></entry>
	<entry><hostid
	role="ipaddr">192.168.173.4</hostid></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>To build a fully meshed net we need one ATM connection
	between each pair of machines:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<colspec colwidth="1*"/>
	<colspec colwidth="1*"/>
	<thead>
	<row>
	<entry>Machines</entry>
	<entry>VPI.VCI couple</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><hostid>hostA</hostid> -
	<hostid>hostB</hostid></entry>
	<entry>0.100</entry>
	</row>

	<row>
	<entry><hostid>hostA</hostid> -
	<hostid>hostC</hostid></entry>
	<entry>0.101</entry>
	</row>

	<row>
	<entry><hostid>hostA</hostid> -
	<hostid>hostD</hostid></entry>
	<entry>0.102</entry>
	</row>

	<row>
	<entry><hostid>hostB</hostid> -
	<hostid>hostC</hostid></entry>
	<entry>0.103</entry>
	</row>

	<row>
	<entry><hostid>hostB</hostid> -
	<hostid>hostD</hostid></entry>
	<entry>0.104</entry>
	</row>

	<row>
	<entry><hostid>hostC</hostid> -
	<hostid>hostD</hostid></entry>
	<entry>0.105</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>The VPI and VCI values at each end of the connection may
	of course differ, but for simplicity we assume that they are
	the same. Next we need to configure the ATM interfaces on
	each host:</para>

	<screen>hostA&prompt.root; <userinput>ifconfig hatm0 192.168.173.1 up</userinput>
	hostB&prompt.root; <userinput>ifconfig hatm0 192.168.173.2 up</userinput>
	hostC&prompt.root; <userinput>ifconfig hatm0 192.168.173.3 up</userinput>
	hostD&prompt.root; <userinput>ifconfig hatm0 192.168.173.4 up</userinput></screen>

	<para>assuming that the ATM interface is
	<devicename>hatm0</devicename> on all hosts. Now the PVCs
	need to be configured on <hostid>hostA</hostid> (we assume
	that they are already configured on the ATM switches, you
	need to consult the manual for the switch on how to do
	this).</para>

	<screen>hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 100 llc/snap ubr</userinput>
	hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 101 llc/snap ubr</userinput>
	hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 102 llc/snap ubr</userinput>

	hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 100 llc/snap ubr</userinput>
	hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 103 llc/snap ubr</userinput>
	hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 104 llc/snap ubr</userinput>

	hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 101 llc/snap ubr</userinput>
	hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 103 llc/snap ubr</userinput>
	hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 105 llc/snap ubr</userinput>

	hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 102 llc/snap ubr</userinput>
	hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 104 llc/snap ubr</userinput>
	hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 105 llc/snap ubr</userinput></screen>

	<para>Of course other traffic contracts than UBR can be used
	given the ATM adapter supports those. In this case the name
	of the traffic contract is followed by the parameters of the
	traffic. Help for the &man.atmconfig.8; tool can be
	obtained with:</para>

	<screen>&prompt.root; <userinput>atmconfig help natm add</userinput></screen>

	<para>or in the &man.atmconfig.8; manual page.</para>

	<para>The same configuration can also be done via
	<filename>/etc/rc.conf</filename>. For
	<hostid>hostA</hostid> this would look like:</para>

	<programlisting>network_interfaces="lo0 hatm0"
	ifconfig_hatm0="inet 192.168.173.1 up"
	natm_static_routes="hostB hostC hostD"
	route_hostB="192.168.173.2 hatm0 0 100 llc/snap ubr"
	route_hostC="192.168.173.3 hatm0 0 101 llc/snap ubr"
	route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"</programlisting>

	<para>The current state of all <acronym>CLIP</acronym> routes
	can be obtained with:</para>

	<screen>hostA&prompt.root; <userinput>atmconfig natm show</userinput></screen>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="carp">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>Common Address Redundancy Protocol (CARP)</title>

	<indexterm>
	<primary>CARP</primary>
	</indexterm>
	<indexterm>
	<primary>Common Address Redundancy Protocol</primary>
	</indexterm>

	<para>The Common Address Redundancy Protocol, or
	<acronym>CARP</acronym> allows multiple hosts to share the same
	<acronym>IP</acronym> address. In some configurations, this may
	be used for availability or load balancing. Hosts may use
	separate <acronym>IP</acronym> addresses as well, as in the
	example provided here.</para>

	<para>To enable support for <acronym>CARP</acronym>, the &os;
	kernel must be rebuilt as described in
	<xref linkend="kernelconfig"/> with the following option:</para>

	<programlisting>device carp</programlisting>

	<para>Alternatively, the <filename>if_carp.ko</filename> module
	can be loaded at boot time. Add the following line to the
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>if_carp_load="YES"</programlisting>

	<para><acronym>CARP</acronym> functionality should now be
	available and may be tuned via several <command>sysctl</command>
	<acronym>OID</acronym>s:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>OID</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><varname>net.inet.carp.allow</varname></entry>
	<entry>Accept incoming <acronym>CARP</acronym> packets.
	Enabled by default.</entry>
	</row>

	<row>
	<entry><varname>net.inet.carp.preempt</varname></entry>
	<entry>This option downs all of the
	<acronym>CARP</acronym> interfaces on the host when one
	of them goes down. Disabled by default</entry>
	</row>

	<row>
	<entry><varname>net.inet.carp.log</varname></entry>
	<entry>A value of <literal>0</literal> disables any
	logging. A Value of <literal>1</literal> enables
	logging of bad <acronym>CARP</acronym> packets. Values
	greater than <literal>1</literal> enables logging of
	state changes for the <acronym>CARP</acronym>
	interfaces. The default value is
	<literal>1</literal>.</entry>
	</row>

	<row>
	<entry><varname>net.inet.carp.arpbalance</varname></entry>
	<entry>Balance local network traffic using
	<acronym>ARP</acronym>. Disabled by default.</entry>
	</row>

	<row>
	<entry><varname>net.inet.carp.suppress_preempt</varname></entry>
	<entry>A read only <acronym>OID</acronym> showing the
	status of preemption suppression. Preemption can be
	suppressed if link on an interface is down. A value of
	<literal>0</literal>, means that preemption is not
	suppressed. Every problem increments this
	<acronym>OID</acronym>.</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>The <acronym>CARP</acronym> devices themselves may be
	created via the <command>ifconfig</command> command:</para>

	<screen>&prompt.root; <userinput>ifconfig carp0 create</userinput></screen>

	<para>In a real environment, these interfaces will need unique
	identification numbers known as a <acronym>VHID</acronym>. This
	<acronym>VHID</acronym> or Virtual Host Identification will be
	used to distinguish the host on the network.</para>

	<sect2>
	<title>Using CARP for Server Availability (CARP)</title>

	<para>One use of <acronym>CARP</acronym>, as noted above, is for
	server availability. This example will provide failover
	support for three hosts, all with unique <acronym>IP</acronym>
	addresses and providing the same web content. These machines
	will act in conjunction with a Round Robin
	<acronym>DNS</acronym> configuration. The failover machine
	will have two additional <acronym>CARP</acronym> interfaces,
	one for each of the content server's <acronym>IP</acronym>s.
	When a failure occurs, the failover server should pick up the
	failed machine's <acronym>IP</acronym> address. This means
	the failure should go completely unnoticed to the user. The
	failover server requires identical content and services as the
	other content servers it is expected to pick up load
	for.</para>

	<para>The two machines should be configured identically other
	than their issued hostnames and <acronym>VHID</acronym>s.
	This example calls these machines
	<hostid>hosta.example.org</hostid> and
	<hostid>hostb.example.org</hostid> respectively. First, the
	required lines for a <acronym>CARP</acronym> configuration
	have to be added to <filename>rc.conf</filename>. For
	<hostid>hosta.example.org</hostid>, the
	<filename>rc.conf</filename> file should contain the following
	lines:</para>

	<programlisting>hostname="hosta.example.org"
	ifconfig_fxp0="inet 192.168.1.3 netmask 255.255.255.0"
	cloned_interfaces="carp0"
	ifconfig_carp0="vhid 1 pass testpass 192.168.1.50/24"</programlisting>

	<para>On <hostid>hostb.example.org</hostid> the following lines
	should be in <filename>rc.conf</filename>:</para>

	<programlisting>hostname="hostb.example.org"
	ifconfig_fxp0="inet 192.168.1.4 netmask 255.255.255.0"
	cloned_interfaces="carp0"
	ifconfig_carp0="vhid 2 pass testpass 192.168.1.51/24"</programlisting>

	<note>
	<para>It is very important that the passwords, specified by
	the <option>pass</option> option to
	<command>ifconfig</command>, are identical. The
	<devicename>carp</devicename> devices will only listen to
	and accept advertisements from machines with the correct
	password. The <acronym>VHID</acronym> must also be
	different for each machine.</para>
	</note>

	<para>The third machine, <hostid>provider.example.org</hostid>,
	should be prepared so that it may handle failover from either
	host. This machine will require two
	<devicename>carp</devicename> devices, one to handle each
	host. The appropriate <filename>rc.conf</filename>
	configuration lines will be similar to the following:</para>

	<programlisting>hostname="provider.example.org"
	ifconfig_fxp0="inet 192.168.1.5 netmask 255.255.255.0"
	cloned_interfaces="carp0 carp1"
	ifconfig_carp0="vhid 1 advskew 100 pass testpass 192.168.1.50/24"
	ifconfig_carp1="vhid 2 advskew 100 pass testpass 192.168.1.51/24"</programlisting>

	<para>Having the two <devicename>carp</devicename> devices will
	allow <hostid>provider.example.org</hostid> to notice and pick
	up the <acronym>IP</acronym> address of either machine should
	it stop responding.</para>

	<note>
	<para>The default &os; kernel <emphasis>may</emphasis> have
	preemption enabled. If so,
	<hostid>provider.example.org</hostid> may not relinquish the
	<acronym>IP</acronym> address back to the original content
	server. In this case, an administrator may have to manually
	force the IP back to the master. The following command
	should be issued on
	<hostid>provider.example.org</hostid>:</para>

	<screen>&prompt.root; <userinput>ifconfig carp0 down && ifconfig carp0 up</userinput></screen>

	<para>This should be done on the <devicename>carp</devicename>
	interface which corresponds to the correct host.</para>
	</note>

	<para>At this point, <acronym>CARP</acronym> should be
	completely enabled and available for testing. For testing,
	either networking has to be restarted or the machines need to
	be rebooted.</para>

	<para>More information is always available in the &man.carp.4;
	manual page.</para>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/audit/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/audit/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/audit/chapter.xml (revision 41355)
	@@ -1,750 +1,750 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project
	$FreeBSD$
	-->

	<!-- Need more documentation on praudit, auditreduce, etc. Plus more info
	on the triggers from the kernel (log rotation, out of space, etc).
	And the /dev/audit special file if we choose to support that. Could use
	some coverage of integrating MAC with Event auditing and perhaps discussion
	on how some companies or organizations handle auditing and auditing
	requirements. -->

	<chapter id="audit">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Written by </contrib>
	</author>
	<author>
	<firstname>Robert</firstname>
	<surname>Watson</surname>
	</author>
	</authorgroup>
	</chapterinfo>

	<title>Security Event Auditing</title>

	<sect1 id="audit-synopsis">
	<title>Synopsis</title>

	<indexterm><primary>AUDIT</primary></indexterm>
	<indexterm>
	<primary>Security Event Auditing</primary>
	<see>MAC</see>
	</indexterm>

	<para>The &os; operating system includes support for fine-grained
	security event auditing. Event auditing allows the reliable,
	fine-grained, and configurable logging of a variety of
	security-relevant system events, including logins, configuration
	changes, and file and network access. These log records can be
	invaluable for live system monitoring, intrusion detection, and
	postmortem analysis. &os; implements &sun;'s published
	<acronym>BSM</acronym> API and file format, and is interoperable
	with both &sun;'s &solaris; and &apple;'s &macos; X audit
	implementations.</para>

	<para>This chapter focuses on the installation and configuration
	of Event Auditing. It explains audit policies, and provides an
	example audit configuration.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>What Event Auditing is and how it works.</para>
	</listitem>

	<listitem>
	<para>How to configure Event Auditing on &os; for users
	and processes.</para>
	</listitem>

	<listitem>
	<para>How to review the audit trail using the audit reduction
	and review tools.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	<para>Understand &unix; and &os; basics
	(<xref linkend="basics"/>).</para>
	</listitem>

	<listitem>
	<para>Be familiar with the basics of kernel
	configuration/compilation
	(<xref linkend="kernelconfig"/>).</para>
	</listitem>

	<listitem>
	<para>Have some familiarity with security and how it
	pertains to &os; (<xref linkend="security"/>).</para>
	</listitem>
	</itemizedlist>

	<warning>
	<para>The audit facility has some known limitations which
	include that not all security-relevant system events are
	currently auditable, and that some login mechanisms, such as
	X11-based display managers and third party daemons, do not
	properly configure auditing for user login sessions.</para>

	<para>The security event auditing facility is able to generate
	very detailed logs of system activity: on a busy system, trail
	file data can be very large when configured for high detail,
	exceeding gigabytes a week in some configurations.
	Administrators should take into account disk space
	requirements associated with high volume audit configurations.
	For example, it may be desirable to dedicate a file system to
	- the <filename>/var/audit</filename> tree so that other file
	+ the <filename class="directory">/var/audit</filename> tree so that other file
	systems are not affected if the audit file system becomes
	full.</para>
	</warning>
	</sect1>

	<sect1 id="audit-inline-glossary">
	<title>Key Terms in This Chapter</title>

	<para>Before reading this chapter, a few key audit-related terms
	must be explained:</para>

	<itemizedlist>
	<listitem>
	<para><emphasis>event</emphasis>: An auditable event is any
	event that can be logged using the audit subsystem.
	Examples of security-relevant events include the creation of
	a file, the building of a network connection, or a user
	logging in. Events are either <quote>attributable</quote>,
	meaning that they can be traced to an authenticated user, or
	<quote>non-attributable</quote> if they cannot be. Examples
	of non-attributable events are any events that occur before
	authentication in the login process, such as bad password
	attempts.</para>
	</listitem>

	<listitem>
	<para><emphasis>class</emphasis>: Event classes are named sets
	of related events, and are used in selection expressions.
	Commonly used classes of events include
	<quote>file creation</quote> (fc), <quote>exec</quote> (ex)
	and <quote>login_logout</quote> (lo).</para>
	</listitem>

	<listitem>
	<para><emphasis>record</emphasis>: A record is an audit log
	entry describing a security event. Records contain a record
	event type, information on the subject (user) performing the
	action, date and time information, information on any
	objects or arguments, and a success or failure
	condition.</para>
	</listitem>

	<listitem>
	<para><emphasis>trail</emphasis>: An audit trail, or log file,
	consists of a series of audit records describing security
	events. Typically, trails are in roughly chronological
	order with respect to the time events completed. Only
	authorized processes are allowed to commit records to the
	audit trail.</para>
	</listitem>

	<listitem>
	<para><emphasis>selection expression</emphasis>: A selection
	expression is a string containing a list of prefixes and
	audit event class names used to match events.</para>
	</listitem>

	<listitem>
	<para><emphasis>preselection</emphasis>: The process by which
	the system identifies which events are of interest to the
	administrator in order to avoid generating audit records
	describing events that are not of interest. The
	preselection configuration uses a series of selection
	expressions to identify which classes of events to audit for
	which users, as well as global settings that apply to both
	authenticated and unauthenticated processes.</para>
	</listitem>

	<listitem>
	<para><emphasis>reduction</emphasis>: The process by which
	records from existing audit trails are selected for
	preservation, printing, or analysis. Likewise, the process
	by which undesired audit records are removed from the audit
	trail. Using reduction, administrators can implement
	policies for the preservation of audit data. For example,
	detailed audit trails might be kept for one month, but after
	that, trails might be reduced in order to preserve only
	login information for archival purposes.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="audit-install">
	<title>Installing Audit Support</title>

	<para>User space support for Event Auditing is installed as part
	of the base &os; operating system. Kernel support for Event
	Auditing is compiled in by default, but support for this feature
	must be explicitly compiled into the custom kernel by adding the
	following line to the kernel configuration file:</para>

	<programlisting>options AUDIT</programlisting>

	<para>Rebuild and reinstall
	the kernel via the normal process explained in
	<xref linkend="kernelconfig"/>.</para>

	<para>Once an audit-enabled kernel is built, installed, and the
	system has been rebooted, enable the audit daemon by adding the
	following line to &man.rc.conf.5;:</para>

	<programlisting>auditd_enable="YES"</programlisting>

	<para>Audit support must then be started by a reboot, or by
	manually starting the audit daemon:</para>

	<programlisting>service auditd start</programlisting>
	</sect1>

	<sect1 id="audit-config">
	<title>Audit Configuration</title>

	<para>All configuration files for security audit are found in
	<filename class="directory">/etc/security</filename>. The
	following files must be present before the audit daemon is
	started:</para>

	<itemizedlist>
	<listitem>
	<para><filename>audit_class</filename> - Contains the
	definitions of the audit classes.</para>
	</listitem>

	<listitem>
	<para><filename>audit_control</filename> - Controls aspects
	of the audit subsystem, such as default audit classes,
	minimum disk space to leave on the audit log volume,
	maximum audit trail size, etc.</para>
	</listitem>

	<listitem>
	<para><filename>audit_event</filename> - Textual names and
	descriptions of system audit events, as well as a list of
	which classes each event is in.</para>
	</listitem>

	<listitem>
	<para><filename>audit_user</filename> - User-specific audit
	requirements, which are combined with the global defaults at
	login.</para>
	</listitem>

	<listitem>
	<para><filename>audit_warn</filename> - A customizable shell
	script used by <application>auditd</application> to generate
	warning messages in exceptional situations, such as when
	space for audit records is running low or when the audit
	trail file has been rotated.</para>
	</listitem>
	</itemizedlist>

	<warning>
	<para>Audit configuration files should be edited and maintained
	carefully, as errors in configuration may result in improper
	logging of events.</para>
	</warning>

	<sect2>
	<title>Event Selection Expressions</title>

	<para>Selection expressions are used in a number of places in
	the audit configuration to determine which events should be
	audited. Expressions contain a list of event classes to match,
	each with a prefix indicating whether matching records should
	be accepted or ignored, and optionally to indicate if the
	entry is intended to match successful or failed operations.
	Selection expressions are evaluated from left to right, and
	two expressions are combined by appending one onto the
	other.</para>

	<para>The following list contains the default audit event
	classes present in <filename>audit_class</filename>:</para>

	<itemizedlist>
	<listitem>
	<para><literal>all</literal> - <emphasis>all</emphasis> -
	Match all event classes.</para>
	</listitem>

	<listitem>
	<para><literal>ad</literal> -
	<emphasis>administrative</emphasis> - Administrative
	actions performed on the system as a whole.</para>
	</listitem>

	<listitem>
	<para><literal>ap</literal> -
	<emphasis>application</emphasis> - Application defined
	action.</para>
	</listitem>

	<listitem>
	<para><literal>cl</literal> -
	<emphasis>file close</emphasis> - Audit calls to the
	<function>close</function> system call.</para>
	</listitem>

	<listitem>
	<para><literal>ex</literal> - <emphasis>exec</emphasis> -
	Audit program execution. Auditing of command line
	arguments and environmental variables is controlled via
	&man.audit.control.5; using the <literal>argv</literal>
	and <literal>envv</literal> parameters to the
	<literal>policy</literal> setting.</para>
	</listitem>

	<listitem>
	<para><literal>fa</literal> -
	<emphasis>file attribute access</emphasis> - Audit the
	access of object attributes such as &man.stat.1;,
	&man.pathconf.2; and similar events.</para>
	</listitem>

	<listitem>
	<para><literal>fc</literal> -
	<emphasis>file create</emphasis> - Audit events where a
	file is created as a result.</para>
	</listitem>

	<listitem>
	<para><literal>fd</literal> -
	<emphasis>file delete</emphasis> - Audit events where file
	deletion occurs.</para>
	</listitem>

	<listitem>
	<para><literal>fm</literal> -
	<emphasis>file attribute modify</emphasis> - Audit events
	where file attribute modification occurs, such as
	&man.chown.8;, &man.chflags.1;, &man.flock.2;, etc.</para>
	</listitem>

	<listitem>
	<para><literal>fr</literal> - <emphasis>file read</emphasis>
	- Audit events in which data is read, files are opened for
	reading, etc.</para>
	</listitem>

	<listitem>
	<para><literal>fw</literal> -
	<emphasis>file write</emphasis> - Audit events in which
	data is written, files are written or modified,
	etc.</para>
	</listitem>

	<listitem>
	<para><literal>io</literal> - <emphasis>ioctl</emphasis> -
	Audit use of the &man.ioctl.2; system call.</para>
	</listitem>

	<listitem>
	<para><literal>ip</literal> - <emphasis>ipc</emphasis> -
	Audit various forms of Inter-Process Communication,
	including POSIX pipes and System V <acronym>IPC</acronym>
	operations.</para>
	</listitem>

	<listitem>
	<para><literal>lo</literal> -
	<emphasis>login_logout</emphasis> - Audit &man.login.1;
	and &man.logout.1; events occurring on the system.</para>
	</listitem>

	<listitem>
	<para><literal>na</literal> -
	<emphasis>non attributable</emphasis> - Audit
	non-attributable events.</para>
	</listitem>

	<listitem>
	<para><literal>no</literal> -
	<emphasis>invalid class</emphasis> - Match no audit
	events.</para>
	</listitem>

	<listitem>
	<para><literal>nt</literal> - <emphasis>network</emphasis> -
	Audit events related to network actions, such as
	&man.connect.2; and &man.accept.2;.</para>
	</listitem>

	<listitem>
	<para><literal>ot</literal> - <emphasis>other</emphasis> -
	Audit miscellaneous events.</para>
	</listitem>

	<listitem>
	<para><literal>pc</literal> - <emphasis>process</emphasis> -
	Audit process operations, such as &man.exec.3; and
	&man.exit.3;.</para>
	</listitem>

	</itemizedlist>

	<para>These audit event classes may be customized by modifying
	the <filename>audit_class</filename> and
	<filename>audit_event</filename> configuration files.</para>

	<para>Each audit class in the list is combined with a prefix
	indicating whether successful/failed operations are matched,
	and whether the entry is adding or removing matching for the
	class and type.</para>

	<itemizedlist>
	<listitem>
	<para>(none) Audit both successful and failed instances of
	the event.</para>
	</listitem>

	<listitem>
	<para><literal>+</literal> Audit successful events in this
	class.</para>
	</listitem>

	<listitem>
	<para><literal>-</literal> Audit failed events in this
	class.</para>
	</listitem>

	<listitem>
	<para><literal>^</literal> Audit neither successful nor
	failed events in this class.</para>
	</listitem>

	<listitem>
	<para><literal>^+</literal> Do not audit successful events
	in this class.</para>
	</listitem>

	<listitem>
	<para><literal>^-</literal> Do not audit failed events in
	this class.</para>
	</listitem>
	</itemizedlist>

	<para>The following example selection string selects both
	successful and failed login/logout events, but only successful
	execution events:</para>

	<programlisting>lo,+ex</programlisting>
	</sect2>

	<sect2>
	<title>Configuration Files</title>

	<para>In most cases, administrators will need to modify only two
	files when configuring the audit system:
	<filename>audit_control</filename> and
	<filename>audit_user</filename>. The first controls
	system-wide audit properties and policies; the second may be
	used to fine-tune auditing by user.</para>

	<sect3 id="audit-auditcontrol">
	<title>The <filename>audit_control</filename> File</title>

	<para>The <filename>audit_control</filename> file specifies a
	number of defaults for the audit subsystem. Viewing the
	contents of this file, we see the following:</para>

	<programlisting>dir:/var/audit
	flags:lo
	minfree:20
	naflags:lo
	policy:cnt
	filesz:0</programlisting>

	<para>The <option>dir</option> option is used to set one or
	more directories where audit logs will be stored. If more
	than one directory entry appears, they will be used in order
	as they fill. It is common to configure audit so that audit
	logs are stored on a dedicated file system, in order to
	prevent interference between the audit subsystem and other
	subsystems if the file system fills.</para>

	<para>The <option>flags</option> field sets the system-wide
	default preselection mask for attributable events. In the
	example above, successful and failed login and logout events
	are audited for all users.</para>

	<para>The <option>minfree</option> option defines the minimum
	percentage of free space for the file system where the audit
	trail is stored. When this threshold is exceeded, a warning
	will be generated. The above example sets the minimum free
	space to twenty percent.</para>

	<para>The <option>naflags</option> option specifies audit
	classes to be audited for non-attributed events, such as the
	login process and system daemons.</para>

	<para>The <option>policy</option> option specifies a
	comma-separated list of policy flags controlling various
	aspects of audit behavior. The default
	<literal>cnt</literal> flag indicates that the system should
	continue running despite an auditing failure (this flag is
	highly recommended). Another commonly used flag is
	<literal>argv</literal>, which causes command line arguments
	to the &man.execve.2; system call to be audited as part of
	command execution.</para>

	<para>The <option>filesz</option> option specifies the maximum
	size in bytes to allow an audit trail file to grow to before
	automatically terminating and rotating the trail file. The
	default, 0, disables automatic log rotation. If the
	requested file size is non-zero and below the minimum 512k,
	it will be ignored and a log message will be
	generated.</para>
	</sect3>

	<sect3 id="audit-audituser">
	<title>The <filename>audit_user</filename> File</title>

	<para>The <filename>audit_user</filename> file permits the
	administrator to specify further audit requirements for
	specific users. Each line configures auditing for a user
	via two fields: the first is the
	<literal>alwaysaudit</literal> field, which specifies a set
	of events that should always be audited for the user, and
	the second is the <literal>neveraudit</literal> field, which
	specifies a set of events that should never be audited for
	the user.</para>

	<para>The following example <filename>audit_user</filename>
	file audits login/logout events and successful command
	execution for the <username>root</username> user, and audits
	file creation and successful command execution for the
	<username>www</username> user. If used with the example
	<filename>audit_control</filename> file above, the
	<literal>lo</literal> entry for <username>root</username> is
	redundant, and login/logout events will also be audited for
	the <username>www</username> user.</para>

	<programlisting>root:lo,+ex:no
	www:fc,+ex:no</programlisting>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="audit-administration">
	<title>Administering the Audit Subsystem</title>

	<sect2>
	<title>Viewing Audit Trails</title>

	<para>Audit trails are stored in the BSM binary format, so tools
	must be used to modify or convert to text. The
	&man.praudit.1; command converts trail files to a simple text
	format; the &man.auditreduce.1; command may be used to reduce
	the audit trail file for analysis, archiving, or printing
	purposes. <command>auditreduce</command> supports a variety
	of selection parameters, including event type, event class,
	user, date or time of the event, and the file path or object
	acted on.</para>

	<para>For example, the <command>praudit</command> utility will
	dump the entire contents of a specified audit log in plain
	text:</para>

	<screen>&prompt.root; <userinput>praudit /var/audit/AUDITFILE</userinput></screen>

	<para>Where
	<filename><replaceable>AUDITFILE</replaceable></filename> is
	the audit log to dump.</para>

	<para>Audit trails consist of a series of audit records made up
	of tokens, which <command>praudit</command> prints
	sequentially one per line. Each token is of a specific type,
	such as <literal>header</literal> holding an audit record
	header, or <literal>path</literal> holding a file path from a
	name lookup. The following is an example of an
	<literal>execve</literal> event:</para>

	<programlisting>header,133,10,execve(2),0,Mon Sep 25 15:58:03 2006, + 384 msec
	exec arg,finger,doug
	path,/usr/bin/finger
	attribute,555,root,wheel,90,24918,104944
	subject,robert,root,wheel,root,wheel,38439,38032,42086,128.232.9.100
	return,success,0
	trailer,133</programlisting>

	<para>This audit represents a successful
	<literal>execve</literal> call, in which the command
	<literal>finger doug</literal> has been run. The arguments
	token contains both the processed command line presented by
	the shell to the kernel. The <literal>path</literal> token
	holds the path to the executable as looked up by the kernel.
	The <literal>attribute</literal> token describes the binary,
	and in particular, includes the file mode which can be used to
	determine if the application was setuid. The
	<literal>subject</literal> token describes the subject
	process, and stores in sequence the audit user ID, effective
	user ID and group ID, real user ID and group ID, process ID,
	session ID, port ID, and login address. Notice that the audit
	user ID and real user ID differ: the user
	<username>robert</username> has switched to the
	<username>root</username> account before running this command,
	but it is audited using the original authenticated user.
	Finally, the <literal>return</literal> token indicates the
	successful execution, and the <literal>trailer</literal>
	concludes the record.</para>

	<para><command>praudit</command> also supports
	an XML output format, which can be selected using the
	<option>-x</option> argument.</para>
	</sect2>

	<sect2>
	<title>Reducing Audit Trails</title>

	<para>Since audit logs may be very large, an administrator will
	likely want to select a subset of records for using, such as
	records associated with a specific user:</para>

	<screen>&prompt.root; <userinput>auditreduce -u trhodes /var/audit/AUDITFILE \| praudit</userinput></screen>

	<para>This will select all audit records produced for the user
	<username>trhodes</username> stored in the
	<filename><replaceable>AUDITFILE</replaceable></filename>
	file.</para>
	</sect2>

	<sect2>
	<title>Delegating Audit Review Rights</title>

	<para>Members of the <groupname>audit</groupname> group are
	given permission to read audit trails in
	- <filename>/var/audit</filename>; by default, this group is
	+ <filename class="directory">/var/audit</filename>; by default, this group is
	empty, so only the <username>root</username> user may read
	audit trails. Users may be added to the
	<groupname>audit</groupname> group in order to delegate audit
	review rights to the user. As the ability to track audit log
	contents provides significant insight into the behavior of
	users and processes, it is recommended that the delegation of
	audit review rights be performed with caution.</para>
	</sect2>

	<sect2>
	<title>Live Monitoring Using Audit Pipes</title>

	<para>Audit pipes are cloning pseudo-devices in the device file
	system which allow applications to tap the live audit record
	stream. This is primarily of interest to authors of intrusion
	detection and system monitoring applications. However, for
	the administrator the audit pipe device is a convenient way to
	allow live monitoring without running into problems with audit
	trail file ownership or log rotation interrupting the event
	stream. To track the live audit event stream, use the
	following command line:</para>

	<screen>&prompt.root; <userinput>praudit /dev/auditpipe</userinput></screen>

	<para>By default, audit pipe device nodes are accessible only to
	the <username>root</username> user. To make them accessible
	to the members of the <groupname>audit</groupname> group, add
	a <literal>devfs</literal> rule to
	<filename>devfs.rules</filename>:</para>

	<programlisting>add path 'auditpipe*' mode 0440 group audit</programlisting>

	<para>See &man.devfs.rules.5; for more information on
	configuring the devfs file system.</para>

	<warning>
	<para>It is easy to produce audit event feedback cycles, in
	which the viewing of each audit event results in the
	generation of more audit events. For example, if all
	network I/O is audited, and &man.praudit.1; is run from an
	SSH session, then a continuous stream of audit events will
	be generated at a high rate, as each event being printed
	will generate another event. It is advisable to run
	<command>praudit</command> on an audit pipe device from
	sessions without fine-grained I/O auditing in order to avoid
	this happening.</para>
	</warning>
	</sect2>

	<sect2>
	<title>Rotating Audit Trail Files</title>

	<para>Audit trails are written to only by the kernel, and
	managed only by the audit daemon,
	<application>auditd</application>. Administrators should not
	attempt to use &man.newsyslog.conf.5; or other tools to
	directly rotate audit logs. Instead, the
	<command>audit</command> management tool may be used to shut
	down auditing, reconfigure the audit system, and perform log
	rotation. The following command causes the audit daemon to
	create a new audit log and signal the kernel to switch to
	using the new log. The old log will be terminated and
	renamed, at which point it may then be manipulated by the
	administrator.</para>

	<screen>&prompt.root; <userinput>audit -n</userinput></screen>

	<warning>
	<para>If the <application>auditd</application> daemon is not
	currently running, this command will fail and an error
	message will be produced.</para>
	</warning>

	<para>Adding the following line to
	<filename>/etc/crontab</filename> will force the rotation
	every twelve hours from &man.cron.8;:</para>

	<programlisting>0 /12 * * root /usr/sbin/audit -n</programlisting>

	<para>The change will take effect once you have saved the
	new <filename>/etc/crontab</filename>.</para>

	<para>Automatic rotation of the audit trail file based on file
	size is possible via the <option>filesz</option> option in
	&man.audit.control.5;, and is described in the configuration
	files section of this chapter.</para>
	</sect2>

	<sect2>
	<title>Compressing Audit Trails</title>

	<para>As audit trail files can become very large, it is often
	desirable to compress or otherwise archive trails once they
	have been closed by the audit daemon. The
	<filename>audit_warn</filename> script can be used to perform
	customized operations for a variety of audit-related events,
	including the clean termination of audit trails when they are
	rotated. For example, the following may be added to the
	<filename>audit_warn</filename> script to compress audit
	trails on close:</para>

	<programlisting>#
	# Compress audit trail files on close.
	#
	if [ "$1" = closefile ]; then
	gzip -9 $2
	fi</programlisting>

	<para>Other archiving activities might include copying trail
	files to a centralized server, deleting old trail files, or
	reducing the audit trail to remove unneeded records. The
	script will be run only when audit trail files are cleanly
	terminated, so will not be run on trails left unterminated
	following an improper shutdown.</para>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/basics/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/basics/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/basics/chapter.xml (revision 41355)
	@@ -1,2675 +1,2680 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="basics">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Chris</firstname>
	<surname>Shumway</surname>
	<contrib>Rewritten by </contrib>
	</author>
	</authorgroup>
	<!-- 10 Mar 2000 -->
	</chapterinfo>

	<title>UNIX Basics</title>

	<sect1 id="basics-synopsis">
	<title>Synopsis</title>

	<para>This chapter covers the basic commands and functionality of
	the &os; operating system. Much of this material is relevant
	for any &unix;-like operating system. New &os; users are
	encouraged to read through this chapter carefully.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>How to use the <quote>virtual consoles</quote> of
	&os;.</para>
	</listitem>

	<listitem>
	<para>How &unix; file permissions and &os; file flags
	work.</para>
	</listitem>

	<listitem>
	<para>The default &os; file system layout.</para>
	</listitem>

	<listitem>
	<para>The &os; disk organization.</para>
	</listitem>

	<listitem>
	<para>How to mount and unmount file systems.</para>
	</listitem>

	<listitem>
	<para>What processes, daemons, and signals are.</para>
	</listitem>

	<listitem>
	<para>What a shell is, and how to change your default login
	environment.</para>
	</listitem>

	<listitem>
	<para>How to use basic text editors.</para>
	</listitem>

	<listitem>
	<para>What devices and device nodes are.</para>
	</listitem>

	<listitem>
	<para>What binary format is used under &os;.</para>
	</listitem>

	<listitem>
	<para>How to read manual pages for more information.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="consoles">
	<title>Virtual Consoles and Terminals</title>

	<indexterm><primary>virtual consoles</primary></indexterm>
	<indexterm><primary>terminals</primary></indexterm>

	<para>&os; can be used in various ways. One of them is typing
	commands to a text terminal. A lot of the flexibility and power
	of a &unix; operating system is readily available at your hands
	when using &os; this way. This section describes what
	<quote>terminals</quote> and <quote>consoles</quote> are, and
	how you can use them in &os;.</para>

	<sect2 id="consoles-intro">
	<title>The Console</title>

	<indexterm><primary>console</primary></indexterm>

	<para>Unless &os; has been configured to automatically start
	a graphical environment during startup, the system will boot
	into a command line login prompt, as seen in this
	example:</para>

	<screen>FreeBSD/amd64 (pc3.example.org) (ttyv0)

	login:</screen>

	<para>The first line contains some information about the
	system. The <literal>amd64</literal> indicates that the
	system in this example is running a 64-bit version of &os;.
	The hostname is <hostid>pc3.example.org</hostid>, and
	<devicename>ttyv0</devicename> indicates that this is the
	system console.</para>

	<para>The second line is the login prompt. The next section
	describes how to log into &os; at this prompt.</para>
	</sect2>

	<sect2 id="consoles-login">
	<title>Logging into &os;</title>

	<para>&os; is a multiuser, multiprocessing system. This is
	the formal description that is usually given to a system that
	can be used by many different people, who simultaneously run a
	lot of programs on a single machine.</para>

	<para>Every multiuser system needs some way to distinguish one
	<quote>user</quote> from the rest. In &os; (and all the
	&unix;-like operating systems), this is accomplished by
	requiring that every user must <quote>log into</quote> the
	system before being able to run programs. Every user has a
	unique name (the <quote>username</quote>) and a personal,
	secret key (the <quote>password</quote>). &os; will ask
	for these two before allowing a user to run any
	programs.</para>

	<indexterm><primary>startup scripts</primary></indexterm>
	<para>When a &os; system boots, startup scripts are
	automatically executed in order to prepare the system and to
	start any services which have been configured to start at
	system boot. Once the system finishes running its startup
	scripts, it will present a login prompt:</para>

	<screen>login:</screen>

	<para>Type the username that was configured during <link
	linkend="bsdinstall-addusers">system installation</link> and
	press <keycap>Enter</keycap>. Then enter the password
	associated with the username and press <keycap>Enter</keycap>.
	The password is <emphasis>not echoed</emphasis> for security
	reasons.</para>

	<para>Once the correct password is input, the message of
	the day (<acronym>MOTD</acronym>) will be displayed followed
	by a command prompt (a <literal>#</literal>,
	<literal>$</literal>, or <literal>%</literal> character). You
	are now logged into the &os; console and ready to try the
	available commands.</para>
	</sect2>

	<sect2 id="consoles-virtual">
	<title>Virtual Consoles</title>

	<para>&os; can be configured to provide many virtual consoles
	for inputting commands. Each virtual console has its own
	login prompt and output channel, and &os; takes care of
	properly redirecting keyboard input and monitor output as you
	switch between virtual consoles.</para>

	<para>Special key combinations have been reserved by &os; for
	switching consoles.<footnote>
	<para>Refer to &man.syscons.4;, &man.atkbd.4;,
	&man.vidcontrol.1; and &man.kbdcontrol.1; for a more
	technical description of the &os; console and its keyboard
	drivers.</para></footnote>. Use
	<keycombo><keycap>Alt</keycap><keycap>F1</keycap></keycombo>,
	<keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo>,
	through
	<keycombo><keycap>Alt</keycap><keycap>F8</keycap></keycombo>
	to switch to a different virtual console in &os;.</para>

	<para>When switching from one console to the next, &os; takes
	care of saving and restoring the screen output. The result is
	an <quote>illusion</quote> of having multiple
	<quote>virtual</quote> screens and keyboards that can be used
	to type commands for &os; to run. The programs that are
	launched in one virtual console do not stop running when that
	console is not visible because the user has switched to a
	different virtual console.</para>
	</sect2>

	<sect2 id="consoles-ttys">
	<title>The <filename>/etc/ttys</filename> File</title>

	<para>By default, &os; is configured to start eight virtual
	consoles. The configuration can be customized to start
	more or fewer virtual consoles. To change the number of and
	the settings of the virtual consoles, edit
	<filename>/etc/ttys</filename>.</para>

	<para>Each uncommented line in <filename>/etc/ttys</filename>
	(lines that do not start with a <literal>#</literal>
	character) contains settings for a single terminal or virtual
	console. The default version configures nine virtual
	consoles, and enables eight of them. They are the lines that
	start with <literal>ttyv</literal>:</para>

	<programlisting># name getty type status comments
	#
	ttyv0 "/usr/libexec/getty Pc" cons25 on secure
	# Virtual terminals
	ttyv1 "/usr/libexec/getty Pc" cons25 on secure
	ttyv2 "/usr/libexec/getty Pc" cons25 on secure
	ttyv3 "/usr/libexec/getty Pc" cons25 on secure
	ttyv4 "/usr/libexec/getty Pc" cons25 on secure
	ttyv5 "/usr/libexec/getty Pc" cons25 on secure
	ttyv6 "/usr/libexec/getty Pc" cons25 on secure
	ttyv7 "/usr/libexec/getty Pc" cons25 on secure
	ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure</programlisting>

	<para>For a detailed description of every column in this file
	and the available options for the virtual consoles, refer to
	&man.ttys.5;.</para>
	</sect2>

	<sect2 id="consoles-singleuser">
	<title>Single User Mode Console</title>

	<para>A detailed description of <quote>single user mode</quote>
	can be found <link linkend="boot-singleuser">here</link>.
	There is only one console when &os; is in single user mode as
	no other virtual consoles are available in this mode. The
	settings for single user mode are found in this section of
	<filename>/etc/ttys</filename>:</para>

	<programlisting># name getty type status comments
	#
	# If console is marked "insecure", then init will ask for the root password
	# when going to single-user mode.
	console none unknown off secure</programlisting>

	<note>
	<para>As the comments above the <literal>console</literal>
	line indicate, editing <literal>secure</literal> to
	<literal>insecure</literal> will prompt for the
	<username>root</username> password when booting into single
	user mode. The default setting enters single user mode
	without prompting for a password.</para>

	<para><emphasis>Be careful when changing this setting to
	<literal>insecure</literal></emphasis>. If you ever
	forget the <username>root</username> password, booting into
	single user mode is still possible, but may be difficult for
	someone who is not comfortable with the &os; booting
	process.</para>
	</note>
	</sect2>

	<sect2 id="consoles-vidcontrol">
	<title>Changing Console Video Modes</title>

	<para>The &os; console default video mode may be adjusted to
	1024x768, 1280x1024, or any other size supported by the
	graphics chip and monitor. To use a different video mode
	load the <literal>VESA</literal> module:</para>

	<screen>&prompt.root; <userinput>kldload vesa</userinput></screen>

	<para>To determine which video modes are supported by the
	hardware, use &man.vidcontrol.1;. To get a list of supported
	video modes issue the following:</para>

	<screen>&prompt.root; <userinput>vidcontrol -i mode</userinput></screen>

	<para>The output of this command lists the video modes that
	are supported by the hardware. To select a new video mode,
	specify the mode using &man.vidcontrol.1; as the
	<username>root</username> user:</para>

	<screen>&prompt.root; <userinput>vidcontrol MODE_279</userinput></screen>

	<para>If the new video mode is acceptable, it can be permanently
	set on boot by adding it to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>allscreens_flags="MODE_279"</programlisting>
	</sect2>
	</sect1>

	<sect1 id="permissions">
	<title>Permissions</title>

	<indexterm><primary>UNIX</primary></indexterm>

	<para>&os;, being a direct descendant of BSD &unix;, is based
	on several key &unix; concepts. The first and most pronounced
	is that &os; is a multi-user operating system that can handle
	several users working simultaneously on completely unrelated
	tasks. The system is responsible for properly sharing and
	managing requests for hardware devices, peripherals, memory, and
	CPU time fairly to each user.</para>

	<para>Because the system is capable of supporting multiple users,
	everything the system manages has a set of permissions governing
	who can read, write, and execute the resource. These
	permissions are stored as three octets broken into three pieces,
	one for the owner of the file, one for the group that the file
	belongs to, and one for everyone else. This numerical
	representation works like this:</para>

	<indexterm><primary>permissions</primary></indexterm>
	<indexterm>
	<primary>file permissions</primary>
	</indexterm>
	<informaltable frame="none" pgwide="1">
	<tgroup cols="3">
	<thead>
	<row>
	<entry>Value</entry>
	<entry>Permission</entry>
	<entry>Directory Listing</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>0</entry>
	<entry>No read, no write, no execute</entry>
	<entry><literal>---</literal></entry>
	</row>

	<row>
	<entry>1</entry>
	<entry>No read, no write, execute</entry>
	<entry><literal>--x</literal></entry>
	</row>

	<row>
	<entry>2</entry>
	<entry>No read, write, no execute</entry>
	<entry><literal>-w-</literal></entry>
	</row>

	<row>
	<entry>3</entry>
	<entry>No read, write, execute</entry>
	<entry><literal>-wx</literal></entry>
	</row>

	<row>
	<entry>4</entry>
	<entry>Read, no write, no execute</entry>
	<entry><literal>r--</literal></entry>
	</row>

	<row>
	<entry>5</entry>
	<entry>Read, no write, execute</entry>
	<entry><literal>r-x</literal></entry>
	</row>

	<row>
	<entry>6</entry>
	<entry>Read, write, no execute</entry>
	<entry><literal>rw-</literal></entry>
	</row>

	<row>
	<entry>7</entry>
	<entry>Read, write, execute</entry>
	<entry><literal>rwx</literal></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	<indexterm>
	<primary><command>ls</command></primary>
	</indexterm>
	<indexterm><primary>directories</primary></indexterm>

	<para>Use the <option>-l</option> argument to &man.ls.1; to view a
	long directory listing that includes a column of information
	about a file's permissions for the owner, group, and everyone
	else. For example, a <command>ls -l</command> in an arbitrary
	directory may show:</para>

	<screen>&prompt.user; <userinput>ls -l</userinput>
	total 530
	-rw-r--r-- 1 root wheel 512 Sep 5 12:31 myfile
	-rw-r--r-- 1 root wheel 512 Sep 5 12:31 otherfile
	-rw-r--r-- 1 root wheel 7680 Sep 5 12:31 email.txt</screen>

	<para>The first (leftmost) character in the first column indicates
	whether this file is a regular file, a directory, a special
	character device, a socket, or any other special pseudo-file
	device. In this example, the <literal>-</literal> indicates a
	regular file. The next three characters, <literal>rw-</literal>
	in this example, give the permissions for the owner of the file.
	The next three characters, <literal>r--</literal>, give the
	permissions for the group that the file belongs to. The final
	three characters, <literal>r--</literal>, give the permissions
	for the rest of the world. A dash means that the permission is
	turned off. In this example, the permissions are set so the
	owner can read and write to the file, the group can read the
	file, and the rest of the world can only read the file.
	According to the table above, the permissions for this file
	would be <literal>644</literal>, where each digit represents the
	three parts of the file's permission.</para>

	<para>How does the system control permissions on devices? &os;
	treats most hardware devices as a file that programs can open,
	read, and write data to. These special device files are
	stored in <filename class="directory">/dev/</filename>.</para>

	<para>Directories are also treated as files. They have read,
	write, and execute permissions. The executable bit for a
	directory has a slightly different meaning than that of files.
	When a directory is marked executable, it means it is possible
	to change into that directory using
	<application>cd</application>. This also means that it is
	possible to access the files within that directory, subject to
	the permissions on the files themselves.</para>

	<para>In order to perform a directory listing, the read permission
	must be set on the directory. In order to delete a file that
	one knows the name of, it is necessary to have write
	<emphasis>and</emphasis> execute permissions to the directory
	containing the file.</para>

	<para>There are more permission bits, but they are primarily used
	in special circumstances such as setuid binaries and sticky
	directories. For more information on file permissions and how
	to set them, refer to &man.chmod.1;.</para>

	<sect2>
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>Symbolic Permissions</title>

	<indexterm>
	<primary>permissions</primary>
	<secondary>symbolic</secondary>
	</indexterm>

	<para>Symbolic permissions use characters instead of octal
	values to assign permissions to files or directories.
	Symbolic permissions use the syntax of (who) (action)
	(permissions), where the following values are
	available:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="3">
	<thead>
	<row>
	<entry>Option</entry>
	<entry>Letter</entry>
	<entry>Represents</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>(who)</entry>
	<entry>u</entry>
	<entry>User</entry>
	</row>

	<row>
	<entry>(who)</entry>
	<entry>g</entry>
	<entry>Group owner</entry>
	</row>

	<row>
	<entry>(who)</entry>
	<entry>o</entry>
	<entry>Other</entry>
	</row>

	<row>
	<entry>(who)</entry>
	<entry>a</entry>
	<entry>All (<quote>world</quote>)</entry>
	</row>

	<row>
	<entry>(action)</entry>
	<entry>+</entry>
	<entry>Adding permissions</entry>
	</row>

	<row>
	<entry>(action)</entry>
	<entry>-</entry>
	<entry>Removing permissions</entry>
	</row>

	<row>
	<entry>(action)</entry>
	<entry>=</entry>
	<entry>Explicitly set permissions</entry>
	</row>

	<row>
	<entry>(permissions)</entry>
	<entry>r</entry>
	<entry>Read</entry>
	</row>

	<row>
	<entry>(permissions)</entry>
	<entry>w</entry>
	<entry>Write</entry>
	</row>

	<row>
	<entry>(permissions)</entry>
	<entry>x</entry>
	<entry>Execute</entry>
	</row>

	<row>
	<entry>(permissions)</entry>
	<entry>t</entry>
	<entry>Sticky bit</entry>
	</row>

	<row>
	<entry>(permissions)</entry>
	<entry>s</entry>
	<entry>Set UID or GID</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>These values are used with &man.chmod.1;, but with
	letters instead of numbers. For example, the following
	command would block other users from accessing
	<replaceable>FILE</replaceable>:</para>

	<screen>&prompt.user; <userinput>chmod go= FILE</userinput></screen>

	<para>A comma separated list can be provided when more than one
	set of changes to a file must be made. For example, the
	following command removes the group and
	<quote>world</quote> write permission on
	<replaceable>FILE</replaceable>, and adds the execute
	permissions for everyone:</para>

	<screen>&prompt.user; <userinput>chmod go-w,a+x <replaceable>FILE</replaceable></userinput></screen>

	<!--
	<para>Most users will not notice this, but it should be pointed
	out that using the octal method will only set or assign
	permissions to a file; it does not add or delete them.</para>
	-->
	</sect2>

	<sect2>
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>&os; File Flags</title>

	<para>In addition to file permissions, &os; supports the use of
	<quote>file flags</quote>. These flags add an additional
	level of security and control over files, but not
	directories. With file flags, even
	<username>root</username> can be prevented from removing or
	altering files.</para>

	<para>File flags are modified using &man.chflags.1;. For
	example, to enable the system undeletable flag on the file
	<filename>file1</filename>, issue the following
	command:</para>

	<screen>&prompt.root; <userinput>chflags sunlink <filename>file1</filename></userinput></screen>

	<para>To disable the system undeletable flag, put a
	<quote>no</quote> in front of the
	<option>sunlink</option>:</para>

	<screen>&prompt.root; <userinput>chflags nosunlink <filename>file1</filename></userinput></screen>

	<para>To view the flags of a file, use <option>-lo</option> with
	&man.ls.1;:</para>

	<screen>&prompt.root; <userinput>ls -lo <filename>file1</filename></userinput></screen>

	<programlisting>-rw-r--r-- 1 trhodes trhodes sunlnk 0 Mar 1 05:54 file1</programlisting>

	<para>Several file flags may only added or removed by the
	<username>root</username> user. In other cases, the file
	owner may set its file flags. Refer to &man.chflags.1; and
	&man.chflags.2; for more information.</para>
	</sect2>

	<sect2>
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>The <literal>setuid</literal>, <literal>setgid</literal>,
	and <literal>sticky</literal> Permissions</title>

	<para>Other than the permissions already discussed, there are
	three other specific settings that all administrators should
	know about. They are the <literal>setuid</literal>,
	<literal>setgid</literal>, and <literal>sticky</literal>
	permissions.</para>

	<para>These settings are important for some &unix; operations
	as they provide functionality not normally granted to normal
	users. To understand them, the difference between the real
	user ID and effective user ID must be noted.</para>

	<para>The real user ID is the <acronym>UID</acronym> who owns
	or starts the process. The effective <acronym>UID</acronym>
	is the user ID the process runs as. As an example,
	&man.passwd.1; runs with the real user ID when a user changes
	their password. However, in order to update the password
	database, the command runs as the effective ID of the
	<username>root</username> user. This allows users to change
	their passwords without seeing a
	<errorname>Permission Denied</errorname> error.</para>

	<para>The setuid permission may be set by prefixing a permission
	set with the number four (4) as shown in the following
	example:</para>

	<screen>&prompt.root; <userinput>chmod 4755 suidexample.sh</userinput></screen>

	<para>The permissions on
	<filename><replaceable>suidexample.sh</replaceable></filename>
	now look like the following:</para>

	<programlisting>-rwsr-xr-x 1 trhodes trhodes 63 Aug 29 06:36 suidexample.sh</programlisting>

	<para>Note that a <literal>s</literal> is now part of the
	permission set designated for the file owner, replacing the
	executable bit. This allows utilities which need elevated
	permissions, such as <command>passwd</command>.</para>

	<note>
	<para>The <literal>nosuid</literal> &man.mount.8; option will
	cause such binaries to silently fail without alerting
	the user. That option is not completely reliable as a
	<literal>nosuid</literal> wrapper may be able to circumvent
	it.</para>
	</note>

	<para>To view this in real time, open two terminals. On
	one, start the <command>passwd</command> process as a normal
	user. While it waits for a new password, check the process
	table and look at the user information for
	<command>passwd</command>:</para>

	<para>In terminal A:</para>

	<screen>Changing local password for trhodes
	Old Password:</screen>

	<para>In terminal B:</para>

	<screen>&prompt.root; <userinput>ps aux \| grep passwd</userinput></screen>

	<screen>trhodes 5232 0.0 0.2 3420 1608 0 R+ 2:10AM 0:00.00 grep passwd
	root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen>

	<para>As stated above, the <command>passwd</command> is run
	by a normal user, but is using the effective
	<acronym>UID</acronym> of <username>root</username>.</para>

	<para>The <literal>setgid</literal> permission performs the
	same function as the <literal>setuid</literal> permission;
	except that it alters the group settings. When an application
	or utility executes with this setting, it will be granted the
	permissions based on the group that owns the file, not the
	user who started the process.</para>

	<para>To set the <literal>setgid</literal> permission on a
	file, provide <command>chmod</command> with a leading two
	(2):</para>

	<screen>&prompt.root; <userinput>chmod 2755 sgidexample.sh</userinput></screen>

	<para>In the following listing, notice that the
	<literal>s</literal> is now in the field designated for the
	group permission settings:</para>

	<screen>-rwxr-sr-x 1 trhodes trhodes 44 Aug 31 01:49 sgidexample.sh</screen>

	<note>
	<para>In these examples, even though the shell script in
	question is an executable file, it will not run with
	a different <acronym>EUID</acronym> or effective user ID.
	This is because shell scripts may not access the
	&man.setuid.2; system calls.</para>
	</note>

	<para>The <literal>setuid</literal> and
	<literal>setgid</literal> permission bits may lower system
	security, by allowing for elevated permissions. The third
	special permission, the <literal>sticky bit</literal>, can
	strengthen the security of a system.</para>

	<para>When the <literal>sticky bit</literal> is set on a
	directory, it allows file deletion only by the file owner.
	This is useful to prevent file deletion in public directories,
	such as <filename class="directory">/tmp</filename>, by users
	who do not own the file. To utilize this permission, prefix
	the permission set with a one (1):</para>

	<screen>&prompt.root; <userinput>chmod 1777 /tmp</userinput></screen>

	<para>The <literal>sticky bit</literal> permission will display
	as a <literal>t</literal> at the very end of the permission
	set:</para>

	<screen>&prompt.root; <userinput>ls -al / \| grep tmp</userinput></screen>

	<screen>drwxrwxrwt 10 root wheel 512 Aug 31 01:49 tmp</screen>

	</sect2>
	</sect1>

	<sect1 id="dirstructure">
	<title>Directory Structure</title>

	<indexterm><primary>directory hierarchy</primary></indexterm>

	<para>The &os; directory hierarchy is fundamental to obtaining
	an overall understanding of the system. The most important
	directory is root or, <quote>/</quote>. This directory is the
	first one mounted at boot time and it contains the base system
	necessary to prepare the operating system for multi-user
	operation. The root directory also contains mount points for
	other file systems that are mounted during the transition to
	multi-user operation.</para>

	<para>A mount point is a directory where additional file systems
	can be grafted onto a parent file system (usually the root file
	system). This is further described in <xref
	linkend="disk-organization"/>. Standard mount points
	include <filename class="directory">/usr/</filename>,
	<filename class="directory">/var/</filename>,
	<filename class="directory">/tmp/</filename>,
	<filename class="directory">/mnt/</filename>, and
	<filename class="directory">/cdrom/</filename>. These
	directories are usually referenced to entries in
	<filename>/etc/fstab</filename>. This file is a table of
	various file systems and mount points and is read by the system.
	Most of the file systems in <filename>/etc/fstab</filename> are
	mounted automatically at boot time from the script &man.rc.8;
	unless their entry includes <option>noauto</option>. Details
	can be found in <xref linkend="disks-fstab"/>.</para>

	<para>A complete description of the file system hierarchy is
	available in &man.hier.7;. The following table provides a brief
	overview of the most common directories.</para>

	<para>
	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Directory</entry>
	<entry>Description</entry>
	</row>
	</thead>
	<tbody valign="top">
	<row>
	<entry><filename class="directory">/</filename></entry>
	<entry>Root directory of the file system.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/bin/</filename></entry>
	<entry>User utilities fundamental to both single-user
	and multi-user environments.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/boot/</filename></entry>
	<entry>Programs and configuration files used during
	operating system bootstrap.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/boot/defaults/</filename></entry>
	<entry>Default boot configuration files. Refer to
	&man.loader.conf.5; for details.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/dev/</filename></entry>
	<entry>Device nodes. Refer to &man.intro.4; for
	details.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/etc/</filename></entry>
	<entry>System configuration files and scripts.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/etc/defaults/</filename></entry>
	<entry>Default system configuration files. Refer to
	&man.rc.8; for details.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/etc/mail/</filename></entry>
	<entry>Configuration files for mail transport agents
	such as &man.sendmail.8;.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/etc/namedb/</filename></entry>
	<entry><command>named</command> configuration files.
	Refer to &man.named.8; for details.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/etc/periodic/</filename></entry>
	<entry>Scripts that run daily, weekly, and monthly,
	via &man.cron.8;. Refer to &man.periodic.8; for
	details.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/etc/ppp/</filename></entry>
	<entry><command>ppp</command> configuration files as
	described in &man.ppp.8;.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/mnt/</filename></entry>
	<entry>Empty directory commonly used by system
	administrators as a temporary mount point.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/proc/</filename></entry>
	<entry>Process file system. Refer to &man.procfs.5;,
	&man.mount.procfs.8; for details.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/rescue/</filename></entry>
	<entry>Statically linked programs for emergency
	recovery as described in &man.rescue.8;.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/root/</filename></entry>
	<entry>Home directory for the <username>root</username>
	account.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/sbin/</filename></entry>
	<entry>System programs and administration utilities
	fundamental to both single-user and multi-user
	environments.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/tmp/</filename></entry>
	<entry>Temporary files which are usually
	<emphasis>not</emphasis> preserved across a system
	reboot. A memory-based file system is often mounted
	at <filename class="directory">/tmp</filename>. This
	can be automated using the tmpmfs-related variables of
	&man.rc.conf.5; or with an entry in
	<filename>/etc/fstab</filename>; refer to
	&man.mdmfs.8; for details.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/</filename></entry>
	<entry>The majority of user utilities and
	applications.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/bin/</filename></entry>
	<entry>Common utilities, programming tools, and
	applications.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/include/</filename></entry>
	<entry>Standard C include files.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/lib/</filename></entry>
	<entry>Archive libraries.</entry>
	</row>


	<row>
	<entry><filename
	class="directory">/usr/libdata/</filename></entry>
	<entry>Miscellaneous utility data files.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/libexec/</filename></entry>
	<entry>System daemons and system utilities executed
	by other programs.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/local/</filename></entry>
	<entry>Local executables and libraries. Also used as
	the default destination for the &os; ports
	- framework. Within <filename>/usr/local</filename>,
	- the general layout sketched out by &man.hier.7; for
	- <filename>/usr</filename> should be used. Exceptions
	- are the man directory, which is directly under
	- <filename>/usr/local</filename> rather than under
	- <filename>/usr/local/share</filename>, and the ports
	- documentation is in
	- <filename>share/doc/<replaceable>port</replaceable></filename>.</entry>
	+ framework. Within
	+ <filename class="directory">/usr/local</filename>, the
	+ general layout sketched out by &man.hier.7; for
	+ <filename class="directory">/usr</filename> should be
	+ used. Exceptions are the man directory, which is
	+ directly under
	+ <filename class="directory">/usr/local</filename>
	+ rather than under
	+ <filename class="directory">/usr/local/share</filename>,
	+ and the ports documentation is in
	+ <filename class="directory">share/doc/<replaceable>port</replaceable></filename>.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/obj/</filename></entry>
	<entry>Architecture-specific target tree produced by
	- building the <filename>/usr/src</filename>
	+ building the
	+ <filename class="directory">/usr/src</filename>
	tree.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/ports/</filename></entry>
	<entry>The &os; Ports Collection (optional).</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/sbin/</filename></entry>
	<entry>System daemons and system utilities executed
	by users.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/share/</filename></entry>
	<entry>Architecture-independent files.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/src/</filename></entry>
	<entry>BSD and/or local source files.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/var/</filename></entry>
	<entry>Multi-purpose log, temporary, transient, and
	spool files. A memory-based file system is sometimes
	mounted at <filename
	class="directory">/var</filename>. This can be
	automated using the varmfs-related variables in
	&man.rc.conf.5; or with an entry in
	<filename>/etc/fstab</filename>; refer to
	&man.mdmfs.8; for details.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/var/log/</filename></entry>
	<entry>Miscellaneous system log files.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/var/mail/</filename></entry>
	<entry>User mailbox files.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/var/spool/</filename></entry>
	<entry>Miscellaneous printer and mail system spooling
	directories.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/var/tmp/</filename></entry>
	<entry>Temporary files which are usually preserved
	across a system reboot, unless
	<filename class="directory">/var</filename> is a
	memory-based file system.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/var/yp/</filename></entry>
	<entry>NIS maps.</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable></para>
	</sect1>

	<sect1 id="disk-organization">
	<title>Disk Organization</title>

	<para>The smallest unit of organization that &os; uses to find
	files is the filename. Filenames are case-sensitive, which
	means that <filename>readme.txt</filename> and
	<filename>README.TXT</filename> are two separate files. &os;
	does not use the extension of a file to determine whether the
	file is a program, document, or some other form of data.</para>

	<para>Files are stored in directories. A directory may contain no
	files, or it may contain many hundreds of files. A directory
	can also contain other directories, allowing you to build up a
	hierarchy of directories within one another in order to organize
	data.</para>

	<para>Files and directories are referenced by giving the file or
	directory name, followed by a forward slash,
	<literal>/</literal>, followed by any other directory names that
	are necessary. For example, if the directory
	- <filename>foo</filename> contains a directory
	- <filename>bar</filename> which contains the file
	- <filename>readme.txt</filename>, the full name, or
	+ <filename class="directory">foo</filename> contains a directory
	+ <filename class="directory">bar</filename> which contains the
	+ file <filename>readme.txt</filename>, the full name, or
	<firstterm>path</firstterm>, to the file is
	<filename>foo/bar/readme.txt</filename>. Note that this is
	different from &windows; which uses
	<literal>\</literal> to separate file and directory
	names. &os; does not use drive letters, or other drive names in
	the path. For example, you would not type
	<filename>c:/foo/bar/readme.txt</filename> on &os;.</para>

	<para>Directories and files are stored in a file system. Each
	file system contains exactly one directory at the very top
	level, called the <firstterm>root directory</firstterm> for that
	file system. This root directory can contain other
	directories. One file system is designated the
	<firstterm>root file system</firstterm> or <literal>/</literal>.
	Every other file system is <firstterm>mounted</firstterm> under
	the root file system. No matter how many disks you have on your
	&os; system, every directory appears to be part of the same
	disk.</para>

	<para>Suppose you have three file systems, called
	<literal>A</literal>, <literal>B</literal>, and
	<literal>C</literal>. Each file system has one root directory,
	which contains two other directories, called
	<literal>A1</literal>, <literal>A2</literal> (and likewise
	<literal>B1</literal>, <literal>B2</literal> and
	<literal>C1</literal>, <literal>C2</literal>).</para>

	<para>Call <literal>A</literal> the root file system. If you used
	<command>ls</command> to view the contents of this directory you
	would see two subdirectories, <literal>A1</literal> and
	<literal>A2</literal>. The directory tree looks like
	this:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/example-dir1" format="EPS"/>
	</imageobject>

	<textobject>
	<literallayout class="monospaced"> /
	\|
	+--- A1
	\|
	`--- A2</literallayout>
	</textobject>
	</mediaobject>

	<para>A file system must be mounted on to a directory in another
	file system. When mounting file system
	<literal>B</literal> on to the directory <literal>A1</literal>,
	the root directory of <literal>B</literal> replaces
	<literal>A1</literal>, and the directories in
	<literal>B</literal> appear accordingly:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/example-dir2" format="EPS"/>
	</imageobject>

	<textobject>
	<literallayout class="monospaced"> /
	\|
	+--- A1
	\| \|
	\| +--- B1
	\| \|
	\| `--- B2
	\|
	`--- A2</literallayout>
	</textobject>
	</mediaobject>

	<para>Any files that are in the <literal>B1</literal> or
	<literal>B2</literal> directories can be reached with the path
	- <filename>/A1/B1</filename> or <filename>/A1/B2</filename> as
	- necessary. Any files that were in <filename>/A1</filename> have
	+ <filename class="directory">/A1/B1</filename> or
	+ <filename class="directory">/A1/B2</filename> as
	+ necessary. Any files that were in
	+ <filename class="directory">/A1</filename> have
	been temporarily hidden. They will reappear if
	<literal>B</literal> is <firstterm>unmounted</firstterm> from
	- A.</para>
	+ <literal>A</literal>.</para>

	<para>If <literal>B</literal> had been mounted on
	<literal>A2</literal> then the diagram would look like
	this:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/example-dir3" format="EPS"/>
	</imageobject>

	<textobject>
	<literallayout class="monospaced"> /
	\|
	+--- A1
	\|
	`--- A2
	\|
	+--- B1
	\|
	`--- B2</literallayout>
	</textobject>
	</mediaobject>

	- <para>and the paths would be <filename>/A2/B1</filename> and
	- <filename>/A2/B2</filename> respectively.</para>
	+ <para>and the paths would be
	+ <filename class="directory">/A2/B1</filename> and
	+ <filename class="directory">/A2/B2</filename>
	+ respectively.</para>

	<para>File systems can be mounted on top of one another.
	Continuing the last example, the <literal>C</literal> file
	system could be mounted on top of the <literal>B1</literal>
	directory in the <literal>B</literal> file system, leading to
	this arrangement:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/example-dir4" format="EPS"/>
	</imageobject>

	<textobject>
	<literallayout class="monospaced"> /
	\|
	+--- A1
	\|
	`--- A2
	\|
	+--- B1
	\| \|
	\| +--- C1
	\| \|
	\| `--- C2
	\|
	`--- B2</literallayout>
	</textobject>
	</mediaobject>

	<para>Or <literal>C</literal> could be mounted directly on to the
	<literal>A</literal> file system, under the
	<literal>A1</literal> directory:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/example-dir5" format="EPS"/>
	</imageobject>

	<textobject>
	<literallayout class="monospaced"> /
	\|
	+--- A1
	\| \|
	\| +--- C1
	\| \|
	\| `--- C2
	\|
	`--- A2
	\|
	+--- B1
	\|
	`--- B2</literallayout>
	</textobject>
	</mediaobject>

	<para>This is similar, although not identical, to a &ms-dos;
	<command>join</command>.</para>

	<para>Typically you create file systems when installing &os;
	and decide where to mount them, and then never change them
	unless you add a new disk.</para>

	<para>It is entirely possible to have one large root file system,
	and not need to create any others. There are some drawbacks to
	this approach, and one advantage.</para>

	<itemizedlist>
	<title>Benefits of Multiple File Systems</title>

	<listitem>
	<para>Different file systems can have different
	<firstterm>mount options</firstterm>. For example, the root
	file system can be mounted read-only, making it impossible
	for users to inadvertently delete or edit a critical file.
	Separating user-writable file systems, such as
	- <filename>/home</filename>, from other file systems allows
	- them to be mounted <firstterm>nosuid</firstterm>. This
	- option prevents the
	+ <filename class="directory">/home</filename>, from other
	+ file systems allows them to be mounted
	+ <firstterm>nosuid</firstterm>. This option prevents the
	<firstterm>suid</firstterm>/<firstterm>guid</firstterm> bits
	on executables stored on the file system from taking effect,
	possibly improving security.</para>
	</listitem>

	<listitem>
	<para>&os; automatically optimizes the layout of files on a
	file system, depending on how the file system is being used.
	So a file system that contains many small files that are
	written frequently will have a different optimization to one
	that contains fewer, larger files. By having one big file
	system this optimization breaks down.</para>
	</listitem>

	<listitem>
	<para>&os;'s file systems are very robust should you lose
	power. However, a power loss at a critical point could
	still damage the structure of the file system. By splitting
	data over multiple file systems it is more likely that the
	system will still come up, making it easier to restore from
	backup as necessary.</para>
	</listitem>
	</itemizedlist>

	<itemizedlist>
	<title>Benefit of a Single File System</title>

	<listitem>
	<para>File systems are a fixed size. If you create a file
	system when you install &os; and give it a specific size,
	you may later discover that you need to make the partition
	bigger. This is not easily accomplished without backing up,
	recreating the file system with the new size, and then
	restoring the backed up data.</para>

	<important>
	<para>&os; features the &man.growfs.8; command, which
	makes it possible to increase the size of file system on
	the fly, removing this limitation.</para>
	</important>
	</listitem>
	</itemizedlist>

	<para>File systems are contained in partitions. This does not
	have the same meaning as the common usage of the term partition
	(for example, &ms-dos; partition), because of &os;'s &unix;
	heritage. Each partition is identified by a letter from
	<literal>a</literal> through to <literal>h</literal>. Each
	partition can contain only one file system, which means that
	file systems are often described by either their typical mount
	point in the file system hierarchy, or the letter of the
	partition they are contained in.</para>

	<para>&os; also uses disk space for <firstterm>swap
	space</firstterm> to provide
	<firstterm>virtual memory</firstterm>. This allows your
	computer to behave as though it has much more memory than it
	actually does. When &os; runs out of memory, it moves some of
	the data that is not currently being used to the swap space, and
	moves it back in (moving something else out) when it needs
	it.</para>

	<para>Some partitions have certain conventions associated with
	them.</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<colspec colwidth="1*"/>
	<colspec colwidth="5*"/>

	<thead>
	<row>
	<entry>Partition</entry>
	<entry>Convention</entry>
	</row>
	</thead>

	<tbody valign="top">
	<row>
	<entry><literal>a</literal></entry>
	<entry>Normally contains the root file system.</entry>
	</row>

	<row>
	<entry><literal>b</literal></entry>
	<entry>Normally contains swap space.</entry>
	</row>

	<row>
	<entry><literal>c</literal></entry>
	<entry>Normally the same size as the enclosing slice.
	This allows utilities that need to work on the entire
	slice, such as a bad block scanner, to work on the
	<literal>c</literal> partition. You would not normally
	create a file system on this partition.</entry>
	</row>

	<row>
	<entry><literal>d</literal></entry>
	<entry>Partition <literal>d</literal> used to have a
	special meaning associated with it, although that is now
	gone and <literal>d</literal> may work as any normal
	partition.</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>Each partition-that-contains-a-file-system is stored in what
	&os; calls a <firstterm>slice</firstterm>. Slice is
	&os;'s term for what the common call partitions, and again,
	this is because of &os;'s &unix; background. Slices are
	numbered, starting at 1, through to 4.</para>

	<indexterm><primary>slices</primary></indexterm>
	<indexterm><primary>partitions</primary></indexterm>
	<indexterm><primary>dangerously dedicated</primary></indexterm>

	<para>Slice numbers follow the device name, prefixed with an
	<literal>s</literal>, starting at 1. So
	<quote>da0<emphasis>s1</emphasis></quote> is the first slice on
	the first SCSI drive. There can only be four physical slices on
	a disk, but you can have logical slices inside physical slices
	of the appropriate type. These extended slices are numbered
	starting at 5, so <quote>ad0<emphasis>s5</emphasis></quote> is
	the first extended slice on the first IDE disk. These devices
	are used by file systems that expect to occupy a slice.</para>

	<para>Slices, <quote>dangerously dedicated</quote> physical
	drives, and other drives contain
	<firstterm>partitions</firstterm>, which are represented as
	letters from <literal>a</literal> to <literal>h</literal>. This
	letter is appended to the device name, so
	<quote>da0<emphasis>a</emphasis></quote> is the a partition on
	the first da drive, which is <quote>dangerously
	dedicated</quote>. <quote>ad1s3<emphasis>e</emphasis></quote> is
	the fifth partition in the third slice of the second IDE disk
	drive.</para>

	<para>Finally, each disk on the system is identified. A disk name
	starts with a code that indicates the type of disk, and then a
	number, indicating which disk it is. Unlike slices, disk
	numbering starts at 0. Common codes that you will see are
	listed in <xref linkend="basics-dev-codes"/>.</para>

	<para>When referring to a partition, include the disk name,
	<literal>s</literal>, the slice number, and then the partition
	letter. Examples are shown in <xref
	linkend="basics-disk-slice-part"/>.</para>

	<para><xref linkend="basics-concept-disk-model"/> shows a
	conceptual model of a disk layout.</para>

	<para>When installing &os;, configure the disk slices, create
	partitions within the slice to be used for &os;, create a file
	system or swap space in each partition, and decide where each
	file system will be mounted.</para>

	<table frame="none" pgwide="1" id="basics-dev-codes">
	<title>Disk Device Codes</title>

	<tgroup cols="2">
	<colspec colwidth="1*"/>
	<colspec colwidth="5*"/>

	<thead>
	<row>
	<entry>Code</entry>
	<entry>Meaning</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><devicename>ad</devicename></entry>
	<entry>ATAPI (IDE) disk</entry>
	</row>

	<row>
	<entry><devicename>da</devicename></entry>
	<entry>SCSI direct access disk</entry>
	</row>

	<row>
	<entry><devicename>acd</devicename></entry>
	<entry>ATAPI (IDE) CDROM</entry>
	</row>

	<row>
	<entry><devicename>cd</devicename></entry>
	<entry>SCSI CDROM</entry>
	</row>

	<row>
	<entry><devicename>fd</devicename></entry>
	<entry>Floppy disk</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<example id="basics-disk-slice-part">
	<title>Sample Disk, Slice, and Partition Names</title>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<colspec colwidth="1*"/>
	<colspec colwidth="5*"/>

	<thead>
	<row>
	<entry>Name</entry>
	<entry>Meaning</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>ad0s1a</literal></entry>
	<entry>The first partition (<literal>a</literal>) on the
	first slice (<literal>s1</literal>) on the first IDE
	disk (<literal>ad0</literal>).</entry>
	</row>

	<row>
	<entry><literal>da1s2e</literal></entry>

	<entry>The fifth partition (<literal>e</literal>) on the
	second slice (<literal>s2</literal>) on the second
	SCSI disk (<literal>da1</literal>).</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</example>

	<example id="basics-concept-disk-model">
	<title>Conceptual Model of a Disk</title>

	<para>This diagram shows &os;'s view of the first IDE disk
	attached to the system. Assume that the disk is 4 GB in
	size, and contains two 2 GB slices (&ms-dos; partitions).
	The first slice contains a &ms-dos; disk,
	<devicename>C:</devicename>, and the second slice contains a
	&os; installation. This example &os; installation has
	three data partitions, and a swap partition.</para>

	<para>The three partitions will each hold a file system.
	Partition <literal>a</literal> will be used for the root file
	system, <literal>e</literal> for the <filename
	class="directory">/var/</filename> directory hierarchy, and
	<literal>f</literal> for the <filename
	class="directory">/usr/</filename> directory
	hierarchy.</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/disk-layout" format="EPS"/>
	</imageobject>

	<textobject>
	<literallayout class="monospaced">.-----------------. --.
	\| \| \|
	\| DOS / Windows \| \|
	: : > First slice, ad0s1
	: : \|
	\| \| \|
	:=================: ==: --.
	\| \| \| Partition a, mounted as / \|
	\| \| > referred to as ad0s2a \|
	\| \| \| \|
	:-----------------: ==: \|
	\| \| \| Partition b, used as swap \|
	\| \| > referred to as ad0s2b \|
	\| \| \| \|
	:-----------------: ==: \| Partition c, no
	\| \| \| Partition e, used as /var > file system, all
	\| \| > referred to as ad0s2e \| of FreeBSD slice,
	\| \| \| \| ad0s2c
	:-----------------: ==: \|
	\| \| \| \|
	: : \| Partition f, used as /usr \|
	: : > referred to as ad0s2f \|
	: : \| \|
	\| \| \| \|
	\| \| --' \|
	`-----------------' --'</literallayout>
	</textobject>
	</mediaobject>
	</example>
	</sect1>

	<sect1 id="mount-unmount">
	<title>Mounting and Unmounting File Systems</title>

	<para>The file system is best visualized as a tree,
	rooted, as it were, at <filename class="directory">/</filename>.
	<filename class="directory">/dev</filename>,
	<filename class="directory">/usr</filename>, and the
	other directories in the root directory are branches, which may
	have their own branches, such as
	<filename class="directory">/usr/local</filename>, and so
	on.</para>

	<indexterm><primary>root file system</primary></indexterm>
	<para>There are various reasons to house some of these
	directories on separate file systems. <filename
	class="directory">/var</filename> contains the directories
	<filename class="directory">log/</filename>,
	<filename class="directory">spool/</filename>, and various types
	of temporary files, and as such, may get filled up. Filling up
	the root file system is not a good idea, so splitting <filename
	class="directory">/var</filename> from
	<filename class="directory">/</filename> is often
	favorable.</para>

	<para>Another common reason to contain certain directory trees on
	other file systems is if they are to be housed on separate
	physical disks, or are separate virtual disks, such as
	<link linkend="network-nfs">Network File System</link> mounts,
	or CDROM drives.</para>

	<sect2 id="disks-fstab">
	<title>The <filename>fstab</filename> File</title>

	<indexterm>
	<primary>file systems</primary>
	<secondary>mounted with fstab</secondary>
	</indexterm>

	<para>During the <link linkend="boot">boot process</link>,
	file systems listed in <filename>/etc/fstab</filename> are
	automatically mounted except for the entries containing
	<option>noauto</option>. This file contains entries in the
	following format:</para>

	<programlisting><replaceable>device</replaceable> <replaceable>/mount-point</replaceable> <replaceable>fstype</replaceable> <replaceable>options</replaceable> <replaceable>dumpfreq</replaceable> <replaceable>passno</replaceable></programlisting>

	<variablelist>
	<varlistentry>
	<term><literal>device</literal></term>
	<listitem>
	<para>An existing device name as explained in
	<xref linkend="disks-naming"/>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>mount-point</literal></term>

	<listitem>
	<para>An existing directory on which to mount the file
	system.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>fstype</literal></term>

	<listitem>
	<para>The file system type to pass to &man.mount.8;. The
	default &os; file system is
	<literal>ufs</literal>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>options</literal></term>

	<listitem>
	<para>Either <option>rw</option> for read-write
	file systems, or <option>ro</option> for read-only file
	systems, followed by any other options that may be
	needed. A common option is <option>noauto</option> for
	file systems not normally mounted during the boot
	sequence. Other options are listed in
	&man.mount.8;.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>dumpfreq</literal></term>

	<listitem>
	<para>Used by &man.dump.8; to determine which file systems
	require dumping. If the field is missing, a value of
	zero is assumed.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>passno</literal></term>

	<listitem>
	<para>Determines the order in which file systems should be
	checked. File systems that should be skipped should
	have their <literal>passno</literal> set to zero. The
	root file system needs to be checked before everything
	else and should have its <literal>passno</literal> set
	to one. The other file systems should be set to
	values greater than one. If more than one file system
	has the same <literal>passno</literal>, &man.fsck.8;
	will attempt to check file systems in parallel if
	possible.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>Refer to &man.fstab.5; for more information on the format
	of <filename>/etc/fstab</filename> and its options.</para>
	</sect2>

	<sect2 id="disks-mount">
	<title>The <command>mount</command> Command</title>

	<indexterm>
	<primary>file systems</primary>
	<secondary>mounting</secondary>
	</indexterm>

	<para>File systems are mounted using &man.mount.8;. The most
	basic syntax is as follows:</para>

	<informalexample>
	<screen>&prompt.root; <userinput>mount <replaceable>device</replaceable> <replaceable>mountpoint</replaceable></userinput></screen>
	</informalexample>

	<para>This command provides many options which are described in
	&man.mount.8;, The most commonly used options include:</para>

	<variablelist>
	<title>Mount Options</title>

	<varlistentry>
	<term><option>-a</option></term>

	<listitem>
	<para>Mount all the file systems listed in
	<filename>/etc/fstab</filename>, except those marked as
	<quote>noauto</quote>, excluded by the
	<option>-t</option> flag, or those that are already
	mounted.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-d</option></term>

	<listitem>

	<para>Do everything except for the actual mount system
	call. This option is useful in conjunction with the
	<option>-v</option> flag to determine what &man.mount.8;
	is actually trying to do.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-f</option></term>

	<listitem>
	<para>Force the mount of an unclean file system
	(dangerous), or the revocation of write access when
	downgrading a file system's mount status from read-write
	to read-only.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-r</option></term>

	<listitem>
	<para>Mount the file system read-only. This is identical
	to using <option>-o ro</option>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-t</option>
	<replaceable>fstype</replaceable></term>

	<listitem>
	<para>Mount the specified file system type or mount only
	file systems of the given type, if <option>-a</option>
	is included. <quote>ufs</quote> is the default file
	system type.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-u</option></term>

	<listitem>
	<para>Update mount options on the file system.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-v</option></term>

	<listitem>
	<para>Be verbose.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-w</option></term>

	<listitem>
	<para>Mount the file system read-write.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>The following options can be passed to <option>-o</option>
	as a comma-separated list:</para>

	<variablelist>
	<varlistentry>
	<term>noexec</term>

	<listitem>
	<para>Do not allow execution of binaries on this file
	system. This is also a useful security option.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>nosuid</term>

	<listitem>
	<para>Do not interpret setuid or setgid flags on the
	file system. This is also a useful security
	option.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect2>

	<sect2 id="disks-umount">
	<title>The <command>umount</command> Command</title>

	<indexterm>
	<primary>file systems</primary>
	<secondary>unmounting</secondary>
	</indexterm>

	<para>To unmount a filesystem use &man.umount.8;. This command
	takes one parameter which can be a mountpoint, device name,
	<option>-a</option> or <option>-A</option>.</para>

	<para>All forms take <option>-f</option> to force unmounting,
	and <option>-v</option> for verbosity. Be warned that
	<option>-f</option> is not generally a good idea as it might
	crash the computer or damage data on the file system.</para>

	<para>To unmount all mounted file systems, or just the file
	system types listed after <option>-t</option>, use
	<option>-a</option> or <option>-A</option>. Note that
	<option>-A</option> does not attempt to unmount the root file
	system.</para>
	</sect2>
	</sect1>

	<sect1 id="basics-processes">
	<title>Processes</title>

	<para>&os; is a multi-tasking operating system. Each program
	running at any one time is called a
	<firstterm>process</firstterm>. Every running command starts
	at least one new process and there are a number of system
	processes that are run by &os;.</para>

	<para>Each process is uniquely identified by a number called a
	<firstterm>process ID</firstterm>
	(<firstterm>PID</firstterm>). Similar to files, each process
	has one owner and group, and the owner and group permissions are
	used to determine which files and devices the process can open.
	Most processes also have a parent process that started them.
	For example, the shell is a process, and any command started in
	the shell is a process which has the shell as its parent
	process. The exception is a special process called
	&man.init.8; which is always the first process to start at boot
	time and which always has a PID of 1.</para>

	<para>To see the processes on the system, use &man.ps.1; and
	&man.top.1;. To display a static list of the currently running
	processes, their PIDs, how much memory they are using, and the
	command they were started with, use <command>ps</command>. To
	display all the running processes and update the display every
	few seconds so that you can interactively see what the computer
	is doing, use <command>top</command>.</para>

	<para>By default, <command>ps</command> only shows the commands
	that are running and owned by the user. For example:</para>

	<screen>&prompt.user; <userinput>ps</userinput>
	PID TT STAT TIME COMMAND
	298 p0 Ss 0:01.10 tcsh
	7078 p0 S 2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
	37393 p0 I 0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
	-48630 p0 S 2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
	72210 p0 R+ 0:00.00 ps
	390 p1 Is 0:01.14 tcsh
	7059 p2 Is+ 1:36.18 /usr/local/bin/mutt -y
	6688 p3 IWs 0:00.00 tcsh
	10735 p4 IWs 0:00.00 tcsh
	20256 p5 IWs 0:00.00 tcsh
	262 v0 IWs 0:00.00 -tcsh (tcsh)
	270 v0 IW+ 0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
	280 v0 IW+ 0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
	284 v0 IW 0:00.00 /bin/sh /home/nik/.xinitrc
	285 v0 S 0:38.45 /usr/X11R6/bin/sawfish</screen>

	<para>The output from &man.ps.1; is organized into a number of
	columns. The <literal>PID</literal> column displays the process
	ID. PIDs are assigned starting at 1, go up to 99999, then wrap
	around back to the beginning. However, a PID is not reassigned
	if it is already in use. The <literal>TT</literal> column shows
	the tty the program is running on and <literal>STAT</literal>
	shows the program's state. <literal>TIME</literal> is the
	amount of time the program has been running on the CPU. This is
	usually not the elapsed time since the program was started, as
	most programs spend a lot of time waiting for things to happen
	before they need to spend time on the CPU. Finally,
	<literal>COMMAND</literal> is the command that was used to start
	the program.</para>

	<para>&man.ps.1; supports a number of different options to change
	the information that is displayed. One of the most useful sets
	is <literal>auxww</literal>. <option>a</option> displays
	information about all the running processes of all users.
	<option>u</option> displays the username of the process' owner,
	as well as memory usage. <option>x</option> displays
	information about daemon processes, and <option>ww</option>
	causes &man.ps.1; to display the full command line for each
	process, rather than truncating it once it gets too long to fit
	on the screen.</para>

	<para>The output from &man.top.1; is similar. A sample session
	looks like this:</para>

	<screen>&prompt.user; <userinput>top</userinput>
	last pid: 72257; load averages: 0.13, 0.09, 0.03 up 0+13:38:33 22:39:10
	47 processes: 1 running, 46 sleeping
	CPU states: 12.6% user, 0.0% nice, 7.8% system, 0.0% interrupt, 79.7% idle
	Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
	Swap: 256M Total, 38M Used, 217M Free, 15% Inuse

	PID USERNAME PRI NICE SIZE RES STATE TIME WCPU CPU COMMAND
	72257 nik 28 0 1960K 1044K RUN 0:00 14.86% 1.42% top
	7078 nik 2 0 15280K 10960K select 2:54 0.88% 0.88% xemacs-21.1.14
	281 nik 2 0 18636K 7112K select 5:36 0.73% 0.73% XF86_SVGA
	296 nik 2 0 3240K 1644K select 0:12 0.05% 0.05% xterm
	-48630 nik 2 0 29816K 9148K select 3:18 0.00% 0.00% navigator-linu
	175 root 2 0 924K 252K select 1:41 0.00% 0.00% syslogd
	7059 nik 2 0 7260K 4644K poll 1:38 0.00% 0.00% mutt
	...</screen>

	<para>The output is split into two sections. The header (the
	first five lines) shows the PID of the last process to run, the
	system load averages (which are a measure of how busy the system
	is), the system uptime (time since the last reboot) and the
	current time. The other figures in the header relate to how
	many processes are running (47 in this case), how much memory
	and swap space has been used, and how much time the system is
	spending in different CPU states.</para>

	<para>Below the header is a series of columns containing similar
	information to the output from &man.ps.1;, such as the PID,
	username, amount of CPU time, and the command that started the
	process. By default, &man.top.1; also displays the amount of
	memory space taken by the process. This is split into two
	columns: one for total size and one for resident size. Total
	size is how much memory the application has needed and the
	resident size is how much it is actually using at the moment.
	- In this example, <application>&netscape;</application> has
	- required almost 30 MB of RAM, but is currently only using
	- 9 MB.</para>
	+ In this example, <application>mutt</application> has
	+ required almost 8 MB of RAM, but is currently only using
	+ 5 MB.</para>

	<para>&man.top.1; automatically updates the display every two
	seconds. A different interval can be specified with
	<option>-s</option>.</para>
	</sect1>

	<sect1 id="basics-daemons">
	<title>Daemons, Signals, and Killing Processes</title>

	<para>When using an editor, it is easy to control the editor and
	load files because the editor provides facilities to do so, and
	because the editor is attached to a
	<firstterm>terminal</firstterm>. Some programs are not designed
	to be run with continuous user input and disconnect from the
	terminal at the first opportunity. For example, a web server
	responds to web requests, rather than user input. Mail servers
	are another example of this type of application.</para>

	<para>These programs are known as <firstterm>daemons</firstterm>.
	The term daemon comes from Greek mythology and represents an
	entity that is neither good or evil, and which invisibly
	performs useful tasks. This is why the BSD mascot is the
	cheerful-looking daemon with sneakers and a pitchfork.</para>

	<para>There is a convention to name programs that normally run as
	daemons with a trailing <quote>d</quote>.
	<application>BIND</application> is the Berkeley Internet Name
	Domain, but the actual program that executes is
	<command>named</command>. The <application>Apache</application>
	web server program is <command>httpd</command> and the
	line printer spooling daemon is <command>lpd</command>. This is
	only a naming convention. For example, the main mail daemon for
	the <application>Sendmail</application> application is
	<command>sendmail</command>, and not
	<command>maild</command>.</para>

	<para>One way to communicate with a daemon, or any running
	process, is to send a <firstterm>signal</firstterm> using
	&man.kill.1;. There are a number of different signals; some
	have a specific meaning while others are described in the
	application's documentation. A user can only send a signal to a
	process they own and sending a signal to someone else's process
	will result in a permission denied error. The exception is the
	<username>root</username> user, who can send signals to anyone's
	processes.</para>

	<para>&os; can also send a signal to a process. If an application
	is badly written and tries to access memory that it is not
	supposed to, &os; will send the process the
	<firstterm>Segmentation Violation</firstterm> signal
	(<literal>SIGSEGV</literal>). If an application has used the
	&man.alarm.3; system call to be alerted after a period of time
	has elapsed, it will be sent the Alarm signal
	(<literal>SIGALRM</literal>).</para>

	<para>Two signals can be used to stop a process:
	<literal>SIGTERM</literal> and <literal>SIGKILL</literal>.
	<literal>SIGTERM</literal> is the polite way to kill a process
	as the process can read the signal, close any log files it may
	have open, and attempt to finish what it is doing before
	shutting down. In some cases, a process may ignore
	<literal>SIGTERM</literal> if it is in the middle of some task
	that can not be interrupted.</para>

	<para><literal>SIGKILL</literal> can not be ignored by a process.
	This is the <quote>I do not care what you are doing, stop right
	now</quote> signal. Sending a <literal>SIGKILL</literal> to a
	process will usually stop that process there and then.<footnote>
	<para>There are a few tasks that can not be interrupted. For
	example, if the process is trying to read from a file that
	is on another computer on the network, and the other
	computer is unavailable, the process is said to be
	<quote>uninterruptible</quote>. Eventually the process will
	time out, typically after two minutes. As soon as this time
	out occurs the process will be killed.</para>
	</footnote>.</para>

	<para>Other commonly used signals are <literal>SIGHUP</literal>,
	<literal>SIGUSR1</literal>, and <literal>SIGUSR2</literal>.
	These are general purpose signals and different applications
	will respond differently.</para>

	<para>For example, after changing a web server's configuration
	file, the web server needs to be told to re-read its
	configuration. Restarting <command>httpd</command> would result
	in a brief outage period on the web server. Instead, send the
	daemon the <literal>SIGHUP</literal> signal. Be aware that
	different daemons will have different behavior, so refer to the
	documentation for the daemon to determine if
	<literal>SIGHUP</literal> will achieve the desired
	results.</para>

	<procedure>
	<title>Sending a Signal to a Process</title>

	<para>This example shows how to send a signal to &man.inetd.8;.
	The <command>inetd</command> configuration file is
	<filename>/etc/inetd.conf</filename>, and
	<command>inetd</command> will re-read this configuration file
	when it is sent a <literal>SIGHUP</literal>.</para>

	<step>
	<para>Find the PID of the process you want to send the signal
	to using &man.pgrep.1;. In this example, the PID for
	&man.inetd.8; is 198:</para>

	<screen>&prompt.user; <userinput>pgrep -l inetd</userinput>
	198 inetd -wW</screen>

	</step>

	<step>
	<para>Use &man.kill.1; to send the signal. Because
	&man.inetd.8; is owned by <username>root</username>, use
	&man.su.1; to become <username>root</username> first.</para>

	<screen>&prompt.user; <userinput>su</userinput>
	<prompt>Password:</prompt>
	&prompt.root; <userinput>/bin/kill -s HUP 198</userinput></screen>

	<para>Like most &unix; commands, &man.kill.1; will not print
	any output if it is successful. If you send a signal to a
	process that you do not own, you will instead see
	<errorname>kill: <replaceable>PID</replaceable>: Operation
	not permitted</errorname>. Mistyping the PID will either
	send the signal to the wrong process, which could have
	negative results, or will send the signal to a PID that is
	not currently in use, resulting in the error
	<errorname>kill: <replaceable>PID</replaceable>: No such
	process</errorname>.</para>

	<note>
	<title>Why Use <command>/bin/kill</command>?</title>

	<para>Many shells provide <command>kill</command> as a built
	in command, meaning that the shell will send the signal
	directly, rather than running
	<filename>/bin/kill</filename>. Be aware that different
	shells have a different syntax for specifying the name of
	the signal to send. Rather than try to learn all of them,
	it can be simpler to use <command>/bin/kill
	<replaceable>...</replaceable></command>
	directly.</para>
	</note>
	</step>
	</procedure>

	<para>When sending other signals, substitute
	<literal>TERM</literal> or <literal>KILL</literal> in the
	command line as necessary.</para>

	<important>
	<para>Killing a random process on the system can be a bad idea.
	In particular, &man.init.8;, PID 1, is special. Running
	<command>/bin/kill -s KILL 1</command> is a quick, and
	unrecommended, way to shutdown the system.
	<emphasis>Always</emphasis> double check the arguments to
	&man.kill.1; <emphasis>before</emphasis> pressing
	<keycap>Return</keycap>.</para>
	</important>
	</sect1>

	<sect1 id="shells">
	<title>Shells</title>

	<indexterm><primary>shells</primary></indexterm>
	<indexterm><primary>command line</primary></indexterm>

	<para>&os; provides a command line interface called a shell. A
	shell receives commands from the input channel and executes
	them. Many shells provide built in functions to help with
	everyday tasks such as file management, file globbing, command
	line editing, command macros, and environment variables. &os;
	comes with several shells, including <command>sh</command>, the
	Bourne Shell, and <command>tcsh</command>, the improved C-shell.
	Other shells are available from the &os; Ports Collection, such
	as <command>zsh</command> and <command>bash</command>.</para>

	<para>The shell that is used is really a matter of taste. A C
	programmer might feel more comfortable with a C-like shell such
	as <command>tcsh</command>. A Linux user might prefer
	<command>bash</command>. Each shell has unique properties that
	may or may not work with a user's preferred working environment,
	which is why there is a choice of which shell to use.</para>

	<para>One common shell feature is filename completion. After a
	user types the first few letters of a command or filename and
	presses <keycap>Tab</keycap>, the shell will automatically
	complete the rest of the command or filename. Consider two
	files called <filename>foobar</filename> and
	<filename>foo.bar</filename>. To delete
	<filename>foo.bar</filename>, type <command>rm
	fo[<keycap>Tab</keycap>].[<keycap>Tab</keycap>]</command>.</para>

	<para>The shell should print out <command>rm
	foo[BEEP].bar</command>.</para>

	<para>The [BEEP] is the console bell, which the shell used to
	indicate it was unable to complete the filename because there
	is more than one match. Both <filename>foobar</filename> and
	<filename>foo.bar</filename> start with <literal>fo</literal>.
	By typing <literal>.</literal>, then pressing
	<keycap>Tab</keycap> again, the shell would be able to fill in
	the rest of the filename.</para>

	<indexterm><primary>environment variables</primary></indexterm>

	<para>Another feature of the shell is the use of environment
	variables. Environment variables are a variable/key pair stored
	in the shell's environment. This environment can be read by any
	program invoked by the shell, and thus contains a lot of program
	configuration. Here is a list of common environment variables
	and their meanings:</para>

	- <indexterm><primary>environment variables</primary></indexterm>
	-
	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><envar>USER</envar></entry>
	<entry>Current logged in user's name.</entry>
	</row>

	<row>
	<entry><envar>PATH</envar></entry>
	<entry>Colon-separated list of directories to search for
	binaries.</entry>
	</row>

	<row>
	<entry><envar>DISPLAY</envar></entry>
	<entry>Network name of the <application>Xorg</application>
	display to connect to, if available.</entry>
	</row>

	<row>
	<entry><envar>SHELL</envar></entry>
	<entry>The current shell.</entry>
	</row>

	<row>
	<entry><envar>TERM</envar></entry>

	<entry>The name of the user's type of terminal. Used to
	determine the capabilities of the terminal.</entry>
	</row>

	<row>
	<entry><envar>TERMCAP</envar></entry>

	<entry>Database entry of the terminal escape codes to
	perform various terminal functions.</entry>
	</row>

	<row>
	<entry><envar>OSTYPE</envar></entry>
	<entry>Type of operating system.</entry>
	</row>

	<row>
	<entry><envar>MACHTYPE</envar></entry>
	<entry>The system's CPU architecture.</entry>
	</row>

	<row>
	<entry><envar>EDITOR</envar></entry>
	<entry>The user's preferred text editor.</entry>
	</row>

	<row>
	<entry><envar>PAGER</envar></entry>
	<entry>The user's preferred text pager.</entry>
	</row>

	<row>
	<entry><envar>MANPATH</envar></entry>
	<entry>Colon-separated list of directories to search for
	manual pages.</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<indexterm><primary>Bourne shells</primary></indexterm>

	<para>How to set an environment variable differs between shells.
	In <command>tcsh</command> and <command>csh</command>, use
	<command>setenv</command> to set environment variables. In
	<command>sh</command> and <command>bash</command>, use
	<command>export</command> to set the current environment
	variables. This example sets the default <envar>EDITOR</envar>
	to <filename>/usr/local/bin/emacs</filename> for the
	<command>tcsh</command> shell:</para>

	<screen>&prompt.user; <userinput>setenv EDITOR /usr/local/bin/emacs</userinput></screen>

	<para>The equivalent command for <command>bash</command>
	would be:</para>

	<screen>&prompt.user; <userinput>export EDITOR="/usr/local/bin/emacs"</userinput></screen>

	<para>To expand an environment variable in order to see its
	current setting, type a <literal>$</literal> character in front
	of its name on the command line. For example,
	<command>echo $TERM</command> displays the current
	<envar>$TERM</envar> setting.</para>

	<para>Shells treat special characters, known as meta-characters,
	as special representations of data. The most common
	meta-character is <literal>*</literal>, which
	represents any number of characters in a filename.
	Meta-characters can be used to perform filename globbing. For
	example, <command>echo *</command> is equivalent to
	<command>ls</command> because the shell takes all the files that
	match <literal>*</literal> and <command>echo</command> lists
	them on the command line.</para>

	<para>To prevent the shell from interpreting a special character,
	escape it from the shell by starting it with a backslash
	(<literal>\</literal>). For example,
	<command>echo $TERM</command> prints the terminal setting
	whereas <command>echo \$TERM</command> literally prints the
	string <literal>$TERM</literal>.</para>

	<sect2 id="changing-shells">
	<title>Changing Your Shell</title>

	<para>The easiest way to permanently change the default shell is
	to use <command>chsh</command>. Running this command will
	open the editor that is configured in the
	<envar>EDITOR</envar> environment variable, which by default
	is set to <command>vi</command>. Change
	the <quote>Shell:</quote> line to the full path of the
	new shell.</para>

	<para>Alternately, use <command>chsh -s</command> which will set
	the specified shell without opening an editor. For example,
	to change the shell to <command>bash</command>:</para>

	<screen>&prompt.user; <userinput>chsh -s /usr/local/bin/bash</userinput></screen>

	<note>
	<para>The new shell <emphasis>must</emphasis> be present in
	<filename>/etc/shells</filename>. If the shell was
	installed from the &os; <link linkend="ports">Ports
	Collection</link>, it should be automatically added to
	this file. If it is missing, add it using this
	command, replacing the path with the path of the
	shell:</para>

	<screen>&prompt.root; <userinput>echo <replaceable>/usr/local/bin/bash</replaceable> >> /etc/shells</userinput></screen>

	<para>Then rerun <command>chsh</command>.</para>
	</note>
	</sect2>
	</sect1>

	<sect1 id="editors">
	<title>Text Editors</title>

	<indexterm><primary>text editors</primary></indexterm>
	<indexterm><primary>editors</primary></indexterm>

	<para>Most &os; configuration is done by editing text files.
	Because of this, it is a good idea to become familiar with a
	text editor. &os; comes with a few as part of the base system,
	and many more are available in the Ports Collection.</para>

	<indexterm>
	<primary><command>ee</command></primary>
	</indexterm>
	<indexterm>
	<primary>editors</primary>
	<secondary><command>ee</command></secondary>
	</indexterm>

	<para>A simple editor to learn is <application>ee</application>,
	which stands for easy editor. To start this editor, type
	<command>ee <replaceable>filename</replaceable></command> where
	<replaceable>filename</replaceable> is the name of the file to
	be edited. Once inside the editor, all of the commands for
	manipulating the editor's functions are listed at the top of the
	display. The caret <literal>^</literal> represents
	<keycap>Ctrl</keycap>, so <literal>^e</literal> expands to
	<keycombo
	action="simul"><keycap>Ctrl</keycap><keycap>e</keycap></keycombo>.
	To leave <application>ee</application>, press
	<keycap>Esc</keycap>, then choose the <quote>leave
	editor</quote> option from the main menu. The editor will
	prompt you to save any changes if the file has been
	modified.</para>

	<indexterm>
	<primary><command>vi</command></primary>
	</indexterm>
	<indexterm>
	<primary>editors</primary>
	<secondary><command>vi</command></secondary>
	</indexterm>
	<indexterm>
	<primary><command>emacs</command></primary>
	</indexterm>
	<indexterm>
	<primary>editors</primary>
	<secondary><command>emacs</command></secondary>
	</indexterm>

	<para>&os; also comes with more powerful text editors such as
	<application>vi</application> as part of the base system.
	Other editors, like <filename
	role="package">editors/emacs</filename> and
	<filename role="package">editors/vim</filename>, are part of the
	&os; Ports Collection. These editors offer more functionality
	at the expense of being a more complicated to learn. Learning a
	more powerful editor such as <application>vim</application> or
	<application>Emacs</application> can save more time in the long
	run.</para>

	<para>Many applications which modify files or require typed input
	will automatically open a text editor. To alter the default
	editor used, set the <envar>EDITOR</envar> environment
	variable as described in the <link
	linkend="shells">shells</link> section.</para>
	</sect1>

	<sect1 id="basics-devices">
	<title>Devices and Device Nodes</title>

	<para>A device is a term used mostly for hardware-related
	activities in a system, including disks, printers, graphics
	cards, and keyboards. When &os; boots, the majority of the boot
	messages refer to devices being detected. A copy of the boot
	messages are saved to
	<filename>/var/run/dmesg.boot</filename>.</para>

	<para>Each device has a device name and number. For example,
	<devicename>acd0</devicename> is the first IDE CD-ROM drive,
	while <devicename>kbd0</devicename> represents the
	keyboard.</para>

	<para>Most devices in a &os; must be accessed through special
	files called device nodes, which are located in
	- <filename>/dev</filename>.</para>
	+ <filename class="directory">/dev</filename>.</para>

	<sect2>
	<title>Creating Device Nodes</title>

	<para>When adding a new device to your system, or compiling
	in support for additional devices, new device nodes must
	be created.</para>

	<sect3>
	<title><literal>DEVFS</literal> (DEVice File System)</title>

	<para> The device file system, <literal>DEVFS</literal>,
	provides access to the kernel's device namespace in the
	global file system namespace. Instead of having to
	manually create and modify device nodes,
	<literal>DEVFS</literal> automatically maintains this
	particular file system. Refer to &man.devfs.5; for
	more information.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="binary-formats">
	<title>Binary Formats</title>

	<para>To understand why &os; uses the &man.elf.5; format,the three
	currently <quote>dominant</quote> executable formats for &unix;
	must be described:</para>

	<itemizedlist>
	<listitem>
	<para>&man.a.out.5;</para>

	<para>The oldest and <quote>classic</quote> &unix; object
	format. It uses a short and compact header with a
	&man.magic.5; number at the beginning that is often used to
	characterize the format. It contains three loaded segments:
	.text, .data, and .bss, plus a symbol table and a string
	table.</para>
	</listitem>

	<listitem>
	<para><acronym>COFF</acronym></para>

	<para>The SVR3 object format. The header comprises a section
	table which can contain more than just .text, .data, and
	.bss sections.</para>
	</listitem>

	<listitem>
	<para>&man.elf.5;</para>

	<para>The successor to <acronym>COFF</acronym>, featuring
	multiple sections and 32-bit or 64-bit possible values. One
	major drawback is that <acronym>ELF</acronym> was designed
	with the assumption that there would be only one ABI per
	system architecture. That assumption is actually incorrect,
	and not even in the commercial SYSV world (which has at
	least three ABIs: SVR4, Solaris, SCO) does it hold
	true.</para>

	<para>&os; tries to work around this problem somewhat by
	providing a utility for <emphasis>branding</emphasis> a
	known <acronym>ELF</acronym> executable with information
	about its compliant ABI. Refer to &man.brandelf.1; for more
	information.</para>
	</listitem>
	</itemizedlist>

	<para>&os; comes from the <quote>classic</quote> camp and used
	the &man.a.out.5; format, a technology tried and proven through
	many generations of BSD releases, until the beginning of the 3.X
	branch. Though it was possible to build and run native
	<acronym>ELF</acronym> binaries and kernels on a &os;
	system for some time before that, &os; initially resisted the
	<quote>push</quote> to switch to <acronym>ELF</acronym> as the
	default format. Why? When Linux made its painful transition to
	<acronym>ELF</acronym>, it was due to their inflexible
	jump-table based shared library mechanism, which made the
	construction of shared libraries difficult for vendors and
	developers. Since <acronym>ELF</acronym> tools offered a
	solution to the shared library problem and were generally seen
	as <quote>the way forward</quote>, the migration cost was
	accepted as necessary and the transition made. &os;'s shared
	library mechanism is based more closely on the &sunos; style
	shared library mechanism and is easy to use.</para>

	<para>So, why are there so many different formats? Back in the
	PDP-11 days when simple hardware supported a simple, small
	system, <filename>a.out</filename> was adequate for the job of
	representing binaries. As &unix; was ported, the
	<filename>a.out</filename> format was retained because it was
	sufficient for the early ports of &unix; to architectures like
	the Motorola 68k or VAXen.</para>

	<para>Then some hardware engineer decided that if he could force
	software to do some sleazy tricks, a few gates could be shaved
	off the design and the CPU core could run faster.
	<filename>a.out</filename> was ill-suited for this new kind of
	hardware, known as <acronym>RISC</acronym>. Many formats were
	developed to get better performance from this hardware than the
	limited, simple <filename>a.out</filename> format could offer.
	<acronym>COFF</acronym>, <acronym>ECOFF</acronym>, and a few
	others were invented and their limitations explored before
	settling on <acronym>ELF</acronym>.</para>

	<para>In addition, program sizes were getting huge while disks
	and physical memory were still relatively small, so the concept
	of a shared library was born. The virtual memory system became
	more sophisticated. While each advancement was done using the
	<filename>a.out</filename> format, its usefulness was stretched
	with each new feature. In addition, people wanted to
	dynamically load things at run time, or to junk parts of their
	program after the init code had run to save in core memory and
	swap space. Languages became more sophisticated and people
	wanted code called before the main() function automatically.
	Lots of hacks were done to the <filename>a.out</filename> format
	to allow all of these things to happen, and they basically
	worked for a time. In time, <filename>a.out</filename> was not
	up to handling all these problems without an ever increasing
	overhead in code and complexity. While <acronym>ELF</acronym>
	solved many of these problems, it would be painful to switch
	from the system that basically worked. So
	<acronym>ELF</acronym> had to wait until it was more painful to
	remain with <filename>a.out</filename> than it was to migrate to
	<acronym>ELF</acronym>.</para>

	<para>As time passed, the build tools that &os; derived their
	build tools from, especially the assembler and loader, evolved
	in two parallel trees. The &os; tree added shared libraries and
	fixed some bugs. The GNU folks that originally wrote these
	programs rewrote them and added simpler support for building
	cross compilers and plugging in different formats. Those who
	wanted to build cross compilers targeting &os; were out of luck
	since the older sources that &os; had for
	<application>as</application> and <application>ld</application>
	were not up to the task. The new GNU tools chain
	(<application>binutils</application>) supports cross
	compiling, <acronym>ELF</acronym>, shared libraries, and C++
	extensions. In addition, many vendors release
	<acronym>ELF</acronym> binaries, and &os; should be able to run
	them.</para>

	<para><acronym>ELF</acronym> is more expressive than
	<filename>a.out</filename> and allows more extensibility in the
	base system. The <acronym>ELF</acronym> tools are better
	maintained and offer cross compilation support.
	<acronym>ELF</acronym> may be a little slower than
	<filename>a.out</filename>, but trying to measure it can be
	difficult. There are also numerous details that are different
	between the two such as how they map pages and handle init code.
	In time, support for <filename>a.out</filename> will be moved
	out of the <filename>GENERIC</filename> kernel, and eventually
	removed from the kernel once the need to run legacy
	<filename>a.out</filename> programs is past.</para>
	</sect1>

	<sect1 id="basics-more-information">
	<title>For More Information</title>

	<sect2 id="basics-man">
	<title>Manual Pages</title>

	<indexterm><primary>manual pages</primary></indexterm>

	<para>The most comprehensive documentation on &os; is in the
	form of manual pages. Nearly every program on the system
	comes with a short reference manual explaining the basic
	operation and available arguments. These manuals can be
	viewed using <command>man</command>:</para>

	<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>

	<para>where <replaceable>command</replaceable> is the name of
	the command you wish to learn about. For example, to learn
	more about <command>ls</command>, type:</para>

	<screen>&prompt.user; <userinput>man ls</userinput></screen>

	<para>The online manual is divided into numbered
	sections:</para>

	<orderedlist>
	<listitem>
	<para>User commands.</para>
	</listitem>

	<listitem>
	<para>System calls and error numbers.</para>
	</listitem>

	<listitem>
	<para>Functions in the C libraries.</para>
	</listitem>

	<listitem>
	<para>Device drivers.</para>
	</listitem>

	<listitem>
	<para>File formats.</para>
	</listitem>

	<listitem>
	<para>Games and other diversions.</para>
	</listitem>

	<listitem>
	<para>Miscellaneous information.</para>
	</listitem>

	<listitem>
	<para>System maintenance and operation commands.</para>
	</listitem>

	<listitem>
	<para>Kernel developers.</para>
	</listitem>
	</orderedlist>

	<para>In some cases, the same topic may appear in more than one
	section of the online manual. For example, there is a
	<command>chmod</command> user command and a
	<function>chmod()</function> system call. To tell
	<command>man</command> which section to display, specify the
	section number:</para>

	<screen>&prompt.user; <userinput>man 1 chmod</userinput></screen>

	<para>This will display the manual page for the user command
	<command>chmod</command>. References to a particular section
	of the online manual are traditionally placed in parenthesis
	in written documentation, so &man.chmod.1; refers to the
	<command>chmod</command> user command and &man.chmod.2; refers
	to the system call.</para>

	<para>If you do not know the command name, use <command>man
	-k</command> to search for keywords in the command
	descriptions:</para>

	<screen>&prompt.user; <userinput>man -k <replaceable>mail</replaceable></userinput></screen>

	<para>This command displays a list of commands that have the
	keyword <quote>mail</quote> in their descriptions. This is
	equivalent to using &man.apropos.1;.</para>

	<para>To determine what the commands in
	- <filename>/usr/bin</filename> do, type:</para>
	+ <filename class="directory">/usr/bin</filename> do,
	+ type:</para>

	<screen>&prompt.user; <userinput>cd /usr/bin</userinput>
	&prompt.user; <userinput>man -f *</userinput></screen>

	<para>or</para>

	<screen>&prompt.user; <userinput>cd /usr/bin</userinput>
	&prompt.user; <userinput>whatis *</userinput></screen>

	</sect2>

	<sect2 id="basics-info">
	<title>GNU Info Files</title>

	<indexterm>
	<primary>Free Software Foundation</primary>
	</indexterm>

	<para>&os; includes many applications and utilities produced
	by the Free Software Foundation (FSF). In addition to manual
	pages, these programs may include hypertext documents called
	<literal>info</literal> files. These can be viewed using
	<command>info</command> or, if <filename
	role="package">editors/emacs</filename> is installed, the
	info mode of <application>emacs</application>.</para>

	<para>To use &man.info.1;, type:</para>

	<screen>&prompt.user; <userinput>info</userinput></screen>

	<para>For a brief introduction, type <literal>h</literal>. For
	a quick command reference, type <literal>?</literal>.</para>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/book.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/book.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/book.xml (revision 41355)
	@@ -1,312 +1,311 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;

	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<!ENTITY % chapters SYSTEM "chapters.ent">
	%chapters;
	<!ENTITY % txtfiles SYSTEM "txtfiles.ent">
	%txtfiles;
	]>

	<book lang='en'>
	<bookinfo>
	<title>FreeBSD Handbook</title>

	<corpauthor>The FreeBSD Documentation Project</corpauthor>

	<pubdate>February 1999</pubdate>

	<releaseinfo>$FreeBSD$</releaseinfo>

	<copyright>
	<year>1995</year>
	<year>1996</year>
	<year>1997</year>
	<year>1998</year>
	<year>1999</year>
	<year>2000</year>
	<year>2001</year>
	<year>2002</year>
	<year>2003</year>
	<year>2004</year>
	<year>2005</year>
	<year>2006</year>
	<year>2007</year>
	<year>2008</year>
	<year>2009</year>
	<year>2010</year>
	<year>2011</year>
	<year>2012</year>
	<year>2013</year>
	<holder>The FreeBSD Documentation Project</holder>
	</copyright>

	&legalnotice;

	<legalnotice id="trademarks" role="trademarks">
	&tm-attrib.freebsd;
	&tm-attrib.3com;
	&tm-attrib.3ware;
	&tm-attrib.arm;
	&tm-attrib.adaptec;
	&tm-attrib.adobe;
	&tm-attrib.apple;
	&tm-attrib.creative;
	&tm-attrib.cvsup;
	&tm-attrib.heidelberger;
	&tm-attrib.ibm;
	&tm-attrib.ieee;
	&tm-attrib.intel;
	&tm-attrib.intuit;
	&tm-attrib.linux;
	&tm-attrib.lsilogic;
	&tm-attrib.m-systems;
	&tm-attrib.macromedia;
	&tm-attrib.microsoft;
	- &tm-attrib.netscape;
	&tm-attrib.nexthop;
	&tm-attrib.opengroup;
	&tm-attrib.oracle;
	&tm-attrib.powerquest;
	&tm-attrib.realnetworks;
	&tm-attrib.redhat;
	&tm-attrib.sap;
	&tm-attrib.sun;
	&tm-attrib.symantec;
	&tm-attrib.themathworks;
	&tm-attrib.thomson;
	&tm-attrib.usrobotics;
	&tm-attrib.vmware;
	&tm-attrib.waterloomaple;
	&tm-attrib.wolframresearch;
	&tm-attrib.xfree86;
	&tm-attrib.xiph;
	&tm-attrib.general;
	</legalnotice>

	<abstract>
	<para>Welcome to FreeBSD! This handbook covers the installation
	and day to day use of
	<emphasis>FreeBSD &rel2.current;-RELEASE</emphasis> and
	<emphasis>FreeBSD &rel.current;-RELEASE</emphasis>. This
	manual is a <emphasis>work in progress</emphasis> and is the
	work of many individuals. As such, some sections may become
	dated and require updating. If you are interested in helping
	out 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/">FreeBSD web site</ulink>
	(previous versions of this handbook can be obtained from
	<ulink url="http://docs.FreeBSD.org/doc/"></ulink>). It may
	also be downloaded in a variety of formats and compression
	options from the
	<ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD
	FTP server</ulink> or one of the numerous
	<link linkend="mirrors-ftp">mirror sites</link>. If you would
	prefer to have a hard copy of the handbook, you can purchase
	one at the
	<ulink url="http://www.freebsdmall.com/">FreeBSD Mall</ulink>.
	You may also want to
	<ulink url="&url.base;/search/index.html">search the
	handbook</ulink>.</para>
	</abstract>
	</bookinfo>

	&chap.preface;

	<part id="getting-started">
	<title>Getting Started</title>

	<partintro>
	<para>This part of the FreeBSD Handbook is for users and
	administrators who are new to FreeBSD. These chapters:</para>

	<itemizedlist>
	<listitem>
	<para>Introduce you to FreeBSD.</para>
	</listitem>

	<listitem>
	<para>Guide you through the installation process.</para>
	</listitem>

	<listitem>
	<para>Teach you &unix; basics and fundamentals.</para>
	</listitem>

	<listitem>
	<para>Show you how to install the wealth of third party
	applications available for FreeBSD.</para>
	</listitem>

	<listitem>
	<para>Introduce you to X, the &unix; windowing system, and
	detail how to configure a desktop environment that makes
	you more productive.</para>
	</listitem>
	</itemizedlist>

	<para>We have tried to keep the number of forward references in
	the text to a minimum so that you can read this section of the
	Handbook from front to back with the minimum page flipping
	required.</para>
	</partintro>

	&chap.introduction;
	&chap.bsdinstall;
	&chap.install;
	&chap.basics;
	&chap.ports;
	&chap.x11;
	</part>

	<part id="common-tasks">
	<title>Common Tasks</title>

	<partintro>
	<para>Now that the basics have been covered, this part of the
	FreeBSD Handbook will discuss some frequently used features of
	FreeBSD. These chapters:</para>

	<itemizedlist>
	<listitem>
	<para>Introduce you to popular and useful desktop
	applications: browsers, productivity tools, document
	viewers, etc.</para>
	</listitem>

	<listitem>
	<para>Introduce you to a number of multimedia tools
	available for FreeBSD.</para>
	</listitem>

	<listitem>
	<para>Explain the process of building a customized FreeBSD
	kernel, to enable extra functionality on your
	system.</para>
	</listitem>

	<listitem>
	<para>Describe the print system in detail, both for desktop
	and network-connected printer setups.</para>
	</listitem>

	<listitem>
	<para>Show you how to run Linux applications on your FreeBSD
	system.</para>
	</listitem>
	</itemizedlist>

	<para>Some of these chapters recommend that you do some prior
	reading, and this is noted in the synopsis at the beginning of
	each chapter.</para>
	</partintro>

	&chap.desktop;
	&chap.multimedia;
	&chap.kernelconfig;
	&chap.printing;
	&chap.linuxemu;
	</part>

	<part id="system-administration">
	<title>System Administration</title>

	<partintro>
	<para>The remaining chapters of the FreeBSD Handbook cover all
	aspects of FreeBSD system administration. Each chapter starts
	by describing what you will learn as a result of reading the
	chapter, and also details what you are expected to know before
	tackling the material.</para>

	<para>These chapters are designed to be read when you need
	the information. You do not have to read them in any
	particular order, nor do you need to read all of them before
	you can begin using FreeBSD.</para>
	</partintro>

	&chap.config;
	&chap.boot;
	&chap.users;
	&chap.security;
	&chap.jails;
	&chap.mac;
	&chap.audit;
	&chap.disks;
	&chap.geom;
	&chap.filesystems;
	&chap.vinum;
	&chap.virtualization;
	&chap.l10n;
	&chap.cutting-edge;
	&chap.dtrace;
	</part>

	<part id="network-communication">
	<title>Network Communication</title>

	<partintro>
	<para>FreeBSD is one of the most widely deployed operating
	systems for high performance network servers. The chapters in
	this part cover:</para>

	<itemizedlist>
	<listitem>
	<para>Serial communication</para>
	</listitem>

	<listitem>
	<para>PPP and PPP over Ethernet</para>
	</listitem>

	<listitem>
	<para>Electronic Mail</para>
	</listitem>

	<listitem>
	<para>Running Network Servers</para>
	</listitem>

	<listitem>
	<para>Firewalls</para>
	</listitem>

	<listitem>
	<para>Other Advanced Networking Topics</para>
	</listitem>
	</itemizedlist>

	<para>These chapters are designed to be read when
	you need the information. You do not have to read them in any
	particular order, nor do you need to read all of them before
	you can begin using FreeBSD in a network environment.</para>
	</partintro>

	&chap.serialcomms;
	&chap.ppp-and-slip;
	&chap.mail;
	&chap.network-servers;
	&chap.firewalls;
	&chap.advanced-networking;

	</part>

	<part id="appendices">
	<title>Appendices</title>

	&chap.mirrors;
	&chap.bibliography;
	&chap.eresources;
	&chap.pgpkeys;
	</part>
	&freebsd-glossary;
	&chap.index;
	&chap.colophon;
	</book>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/config/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/config/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/config/chapter.xml (revision 41355)
	@@ -1,3492 +1,3492 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="config-tuning">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Chern</firstname>
	<surname>Lee</surname>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Mike</firstname>
	<surname>Smith</surname>
	<contrib>Based on a tutorial written by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Matt</firstname>
	<surname>Dillon</surname>
	<contrib>Also based on tuning(7) written by </contrib>
	</author>
	</authorgroup>
	</chapterinfo>

	<title>Configuration and Tuning</title>

	<sect1 id="config-synopsis">
	<title>Synopsis</title>

	<indexterm><primary>system configuration</primary></indexterm>
	<indexterm><primary>system optimization</primary></indexterm>

	<para>One of the important aspects of &os; is proper system
	configuration. This chapter explains much of the &os;
	configuration process, including some of the parameters which
	can be set to tune a &os; system.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>How to efficiently work with file systems and swap
	partitions.</para>
	</listitem>

	<listitem>
	<para>The basics of <filename>rc.conf</filename> configuration
	and <filename
	class="directory">/usr/local/etc/rc.d</filename> startup
	scripts.</para>
	</listitem>

	<listitem>
	<para>How to configure and test a network card.</para>
	</listitem>

	<listitem>
	<para>How to configure virtual hosts on network
	devices.</para>
	</listitem>

	<listitem>
	<para>How to use the various configuration files in
	<filename class="directory">/etc</filename>.</para>
	</listitem>

	<listitem>
	<para>How to tune &os; using <command>sysctl</command>
	variables.</para>
	</listitem>

	<listitem>
	<para>How to tune disk performance and modify kernel
	limitations.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	<para>Understand &unix; and &os; basics (<xref
	linkend="basics"/>).</para>
	</listitem>

	<listitem>
	<para>Be familiar with the basics of kernel configuration and
	compilation (<xref linkend="kernelconfig"/>).</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="configtuning-initial">
	<title>Initial Configuration</title>

	<sect2>
	<title>Partition Layout</title>

	<indexterm><primary>partition layout</primary></indexterm>
	<indexterm>
	<primary><filename class="directory">/etc</filename></primary>
	</indexterm>
	<indexterm>
	<primary><filename class="directory">/var</filename></primary>
	</indexterm>
	<indexterm>
	<primary><filename class="directory">/usr</filename></primary>
	</indexterm>

	<sect3>
	<title>Base Partitions</title>

	<para>When laying out file systems with &man.bsdlabel.8; or
	&man.sysinstall.8;, remember that hard drives transfer data
	faster from the outer tracks to the inner. Thus smaller and
	heavier-accessed file systems should be closer to the
	outside of the drive, while larger partitions like
	<filename class="directory">/usr</filename> should be placed
	toward the inner parts of the disk. It is a good idea to
	create partitions in an order similar to: root, swap,
	<filename class="directory">/var</filename>,
	<filename class="directory">/usr</filename>.</para>

	<para>The size of the
	<filename class="directory">/var</filename> partition
	reflects the intended machine's usage. This partition
	<filename class="directory">/var</filename> is used to hold
	mailboxes, log files, and printer spools. Mailboxes and log
	files can grow to unexpected sizes depending on how many
	users exist and how long log files are kept. Most users
	rarely need more than about a gigabyte of free disk space in
	<filename class="directory">/var</filename>.</para>

	<note>
	<para>There are a few times that a lot of disk space is
	required in
	<filename class="directory">/var/tmp</filename>. When new
	software is installed with &man.pkg.add.1; the packaging
	tools extract a temporary copy of the packages under
	<filename class="directory">/var/tmp</filename>. Large
	software packages, like
	<application>Firefox</application>,
	<application>OpenOffice</application> or
	<application>LibreOffice</application> may be tricky to
	install if there is not enough disk space under
	<filename class="directory">/var/tmp</filename>.</para>
	</note>

	<para>The <filename class="directory">/usr</filename>
	partition holds many of the files which support the system,
	including the &os; Ports Collection and system source code.
	At least 2 gigabytes is recommended for this
	partition.</para>

	<para>When selecting partition sizes, keep the space
	requirements in mind. Running out of space in
	one partition while barely using another can be a
	hassle.</para>

	<note>
	<para>Some users have found that &man.sysinstall.8;'s
	<literal>Auto-defaults</literal> partition sizer will
	sometimes select smaller than adequate
	<filename class="directory">/var</filename> and
	<filename class="directory">/</filename> partitions.
	Partition wisely and generously.</para>
	</note>
	</sect3>

	<sect3 id="swap-design">
	<title>Swap Partition</title>

	<indexterm><primary>swap sizing</primary></indexterm>
	<indexterm><primary>swap partition</primary></indexterm>

	<para>As a rule of thumb, the swap partition should be about
	double the size of physical memory (RAM) as the kernel's
	virtual memory (VM) paging algorithms are tuned to perform
	best when the swap partition is at least two times
	the size of main memory. Systems with minimal RAM may
	perform better with more swap. Configuring too little swap
	can lead to inefficiencies in the VM page scanning code and
	might create issues later if more memory is added.</para>

	<para>On larger systems with multiple SCSI disks or multiple
	IDE disks operating on different controllers, it is
	recommended that swap be configured on each drive (up to
	four drives). The swap partitions should be approximately
	the same size. The kernel can handle arbitrary sizes but
	internal data structures scale to 4 times the largest swap
	partition. Keeping the swap partitions near the same size
	will allow the kernel to optimally stripe swap space across
	disks. Large swap sizes are fine, even if swap is not used
	much. It might be easier to recover from a runaway program
	before being forced to reboot.</para>
	</sect3>

	<sect3>
	<title>Why Partition?</title>

	<para>Several users think a single large partition will be
	fine, but there are several reasons why this is a bad idea.
	First, each partition has different operational
	characteristics and separating them allows the file system
	to tune accordingly. For example, the root and
	<filename class="directory">/usr</filename> partitions are
	read-mostly, with few writes, while a lot of reads and
	writes could occur in
	<filename class="directory">/var</filename> and
	<filename class="directory">/var/tmp</filename>.</para>

	<para>By properly partitioning a system, fragmentation
	introduced in the smaller write heavy partitions will not
	bleed over into the mostly-read partitions. Keeping the
	write-loaded partitions closer to the disk's edge, will
	increase I/O performance in the partitions where it occurs
	the most. Now while I/O performance in the larger
	partitions may be needed, shifting them more toward the edge
	of the disk will not lead to a significant performance
	improvement over moving
	<filename class="directory">/var</filename> to the edge.
	Finally, there are safety concerns. A smaller, neater root
	partition which is mostly read-only has a greater chance of
	surviving a bad crash.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="configtuning-core-configuration">
	<title>Core Configuration</title>

	<indexterm>
	<primary>rc files</primary>
	<secondary><filename>rc.conf</filename></secondary>
	</indexterm>

	<para>The principal location for system configuration information
	is <filename>/etc/rc.conf</filename>. This file contains
	a wide range of configuration information and it is read at
	system startup to configure the system. It provides the
	configuration information for the <filename>rc*</filename>
	files.</para>

	<para>The entries in <filename>/etc/rc.conf</filename> override
	the default settings in
	<filename>/etc/defaults/rc.conf</filename>. The file containing
	the default settings should not be edited. Instead, all
	system-specific changes should be made to
	<filename>/etc/rc.conf</filename>.</para>

	<para>A number of strategies may be applied in clustered
	applications to separate site-wide configuration from
	system-specific configuration in order to keep administration
	overhead down. The recommended approach is to place
	system-specific configuration into
	<filename>/etc/rc.conf.local</filename>. For
	example:</para>

	<itemizedlist>
	<listitem>
	<para><filename>/etc/rc.conf</filename>:</para>

	<programlisting>sshd_enable="YES"
	keyrate="fast"
	defaultrouter="10.1.1.254"</programlisting>

	</listitem>

	<listitem>
	<para><filename>/etc/rc.conf.local</filename>:</para>

	<programlisting>hostname="node1.example.org"
	ifconfig_fxp0="inet 10.1.1.1/8"</programlisting>

	</listitem>
	</itemizedlist>

	<para><filename>rc.conf</filename> can then be
	distributed to every system using <command>rsync</command> or a
	similar program, while <filename>rc.conf.local</filename>
	remains unique.</para>

	<para>Upgrading the system using &man.sysinstall.8; or
	<command>make world</command> will not overwrite
	<filename>rc.conf</filename>, so system configuration
	information will not be lost.</para>

	<tip>
	<para>The <filename>/etc/rc.conf</filename> configuration file
	is parsed by &man.sh.1;. This allows system operators to
	add a certain amount of logic to this file, which may help to
	create very complex configuration scenarios. Refer to
	&man.rc.conf.5; for further information on this topic.</para>
	</tip>
	</sect1>

	<sect1 id="configtuning-appconfig">
	<title>Application Configuration</title>

	<para>Typically, installed applications have their own
	configuration files and syntax. It is important that these
	files be kept separate from the base system, so that they may be
	easily located and managed by the package management
	tools.</para>

	<indexterm><primary>/usr/local/etc</primary></indexterm>

	<para>Typically, these files are installed in
	<filename class="directory">/usr/local/etc</filename>. In the
	case where an application has a large number of configuration
	files, a subdirectory will be created to hold them.</para>

	<para>Normally, when a port or package is installed, sample
	configuration files are also installed. These are usually
	identified with a <filename>.default</filename> suffix. If
	there are no existing configuration files for the application,
	they will be created by copying the
	<filename>.default</filename> files.</para>

	<para>For example, consider the contents of the directory
	<filename
	class="directory">/usr/local/etc/apache</filename>:</para>

	<literallayout class="monospaced">-rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf
	-rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf.default
	-rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf
	-rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf.default
	-rw-r--r-- 1 root wheel 12205 May 20 1998 magic
	-rw-r--r-- 1 root wheel 12205 May 20 1998 magic.default
	-rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types
	-rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types.default
	-rw-r--r-- 1 root wheel 7980 May 20 1998 srm.conf
	-rw-r--r-- 1 root wheel 7933 May 20 1998 srm.conf.default</literallayout>

	<para>The file sizes show that only
	<filename>srm.conf</filename> has been changed. A later
	update of the <application>Apache</application> port would not
	overwrite this changed file.</para>
	</sect1>

	<sect1 id="configtuning-starting-services">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>Starting Services</title>

	<indexterm><primary>services</primary></indexterm>

	<para>Many users install third party software on &os; from the
	Ports Collection and require the installed services to be
	started upon system initialization. Services,
	such as <filename role="package">mail/postfix</filename> or
	<filename role="package">www/apache22</filename> are just two of
	the many software packages which may be started during system
	initialization. This section explains the procedures available
	for starting third party software.</para>

	<para>In &os;, most included services, such as &man.cron.8;, are
	started through the system start up scripts.</para>

	<sect2>
	<title>Extended Application Configuration</title>

	<para>Now that &os; includes <filename>rc.d</filename>,
	configuration of application startup is easier and provides
	more features. Using the key words discussed in the
	<link linkend="configtuning-rcd">rc.d</link> section,
	applications can be set to start after certain other services
	and extra flags can be passed through
	<filename>/etc/rc.conf</filename> in place of hard coded flags
	in the start up script. A basic script may look similar to
	the following:</para>

	<programlisting>#!/bin/sh
	#
	# PROVIDE: utility
	# REQUIRE: DAEMON
	# KEYWORD: shutdown

	. /etc/rc.subr

	name=utility
	rcvar=utility_enable

	command="/usr/local/sbin/utility"

	load_rc_config $name

	#
	# DO NOT CHANGE THESE DEFAULT VALUES HERE
	# SET THEM IN THE /etc/rc.conf FILE
	#
	utility_enable=${utility_enable-"NO"}
	pidfile=${utility_pidfile-"/var/run/utility.pid"}

	run_rc_command "$1"</programlisting>

	<para>This script will ensure that the provided
	<application>utility</application> will be started after the
	<literal>DAEMON</literal> pseudo-service. It also provides a
	method for setting and tracking the <acronym>PID</acronym>, or
	process <acronym>ID</acronym> file.</para>

	<para>This application could then have the following line placed
	in <filename>/etc/rc.conf</filename>:</para>

	<programlisting>utility_enable="YES"</programlisting>

	<para>This method also allows for easier manipulation of the
	command line arguments, inclusion of the default functions
	provided in <filename>/etc/rc.subr</filename>, compatibility
	with the &man.rcorder.8; utility and provides for easier
	configuration via <filename>rc.conf</filename>.</para>
	</sect2>

	<sect2>
	<title>Using Services to Start Services</title>

	<para>Other services, such as the <acronym>POP</acronym>3 server
	daemons or <acronym>IMAP</acronym>, could be started using
	&man.inetd.8;. This involves installing the service utility
	from the Ports Collection with a configuration line added to
	<filename>/etc/inetd.conf</filename>, or by
	uncommenting one of the current configuration lines. Working
	with <application>inetd</application> and its configuration is
	described in depth in the
	<link linkend="network-inetd">inetd</link> section.</para>

	<para>In some cases it may make more sense to use the
	&man.cron.8; daemon to start system services. This approach
	has a number of advantages because <command>cron</command>
	runs these processes as the <filename>crontab</filename>'s
	file owner. This allows regular users to start and maintain
	some applications.</para>

	<para>The <command>cron</command> utility provides a unique
	feature, <literal>@reboot</literal>, which may be used in
	place of the time specification. This will cause the job to
	be run when &man.cron.8; is started, normally during system
	initialization.</para>
	</sect2>
	</sect1>

	<sect1 id="configtuning-cron">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	<!-- 20 May 2003 -->
	</author>
	</authorgroup>
	</sect1info>
	<title>Configuring the <command>cron</command> Utility</title>

	<indexterm><primary>cron</primary>
	<secondary>configuration</secondary></indexterm>

	<para>One of the most useful utilities in &os; is &man.cron.8;.
	This utility runs in the background and regularly checks
	<filename>/etc/crontab</filename> for tasks to execute and
	searches
	<filename class="directory">/var/cron/tabs</filename> for custom
	<filename>crontab</filename> files. These files store
	information about specific functions which
	<command>cron</command> is supposed to perform at certain
	times.</para>

	<para>The <command>cron</command> utility uses two different types
	of configuration files, the system crontab and user crontabs.
	These formats only differ in the sixth field and later. In the
	system crontab, <command>cron</command> will run the command as
	the user specified in the sixth field. In a user crontab, all
	commands run as the user who created the crontab, so the sixth
	field is the last field; this is an important security feature.
	The final field is always the command to run.</para>

	<note>
	<para>User crontabs allow individual users to schedule tasks
	without the need for <username>root</username> privileges.
	Commands in a user's crontab run with the permissions of the
	user who owns the crontab.</para>

	<para>The <username>root</username> user can have a user crontab
	just like any other user. The <username>root</username> user
	crontab is separate from <filename>/etc/crontab</filename>
	(the system crontab). Because the system crontab effectively
	invokes the specified commands as root there is usually no
	need to create a user crontab for
	<username>root</username>.</para>
	</note>

	<para>Let us take a look at <filename>/etc/crontab</filename>,
	the system crontab:</para>

	<programlisting># /etc/crontab - root's crontab for &os;
	#
	# &dollar;&os;: src/etc/crontab,v 1.32 2002/11/22 16:13:39 tom Exp &dollar;
	# <co id="co-comments"/>
	#
	SHELL=/bin/sh
	PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co id="co-env"/>
	HOME=/var/log
	#
	#
	#minute hour mday month wday who command <co id="co-field-descr"/>
	#
	#
	/5 * * * root /usr/libexec/atrun <co id="co-main"/></programlisting>

	<calloutlist>
	<callout arearefs="co-comments">
	<para>Like most &os; configuration files, lines that begin
	with the <literal>#</literal> character are comments. A
	comment can be placed in the file as a reminder of what and
	why a desired action is performed. Comments cannot be on
	the same line as a command or else they will be interpreted
	as part of the command; they must be on a new line. Blank
	lines are ignored.</para>
	</callout>

	<callout arearefs="co-env">
	<para>First, the environment must be defined. The equals
	(<literal>=</literal>) character is used to define any
	environment settings, as with this example where it is used
	for the <envar>SHELL</envar>, <envar>PATH</envar>, and
	<envar>HOME</envar> options. If the shell line is omitted,
	<command>cron</command> will use the default, which is
	<command>sh</command>. If the <envar>PATH</envar> variable
	is omitted, no default will be used and file locations will
	need to be absolute. If <envar>HOME</envar> is omitted,
	<command>cron</command> will use the invoking users home
	directory.</para>
	</callout>

	<callout arearefs="co-field-descr">
	<para>This line defines a total of seven fields. Listed here
	are the values <literal>minute</literal>,
	<literal>hour</literal>, <literal>mday</literal>,
	<literal>month</literal>, <literal>wday</literal>,
	<literal>who</literal>, and <literal>command</literal>.
	These are almost all self explanatory.
	<literal>minute</literal> is the time in minutes the command
	will be run. <literal>hour</literal> is similar to the
	<literal>minute</literal> option, just in hours.
	<literal>mday</literal> stands for day of the month.
	<literal>month</literal> is similar to
	<literal>hour</literal> and <literal>minute</literal>, as it
	designates the month. The <literal>wday</literal> option
	stands for day of the week. All these fields must be
	numeric values, and follow the twenty-four hour clock. The
	<literal>who</literal> field is special, and only exists in
	<filename>/etc/crontab</filename>. This field specifies
	which user the command should be run as. The last field is
	the command to be executed.</para>
	</callout>

	<callout arearefs="co-main">
	<para>This last line will define the values discussed above.
	This example has a <literal>*/5</literal> listing,followed
	by several more <literal>*</literal> characters. These
	<literal>*</literal> characters mean
	<quote>first-last</quote>, and can be interpreted as
	<emphasis>every</emphasis> time. In this example,
	<command>atrun</command> is invoked by
	<username>root</username> every five minutes regardless of
	the day or month. For more information on
	<command>atrun</command>, refer to &man.atrun.8;.</para>

	<para>Commands can have any number of flags passed to them;
	however, commands which extend to multiple lines need to be
	broken with the backslash <quote>\</quote> continuation
	character.</para>
	</callout>
	</calloutlist>

	<para>This is the basic setup for every
	<filename>crontab</filename>, although there is one thing
	different about this one. Field number six, which specifies
	the username, only exists in the system
	<filename>crontab</filename>. This field should be omitted for
	individual user <filename>crontab</filename> files.</para>

	<sect2 id="configtuning-installcrontab">
	<title>Installing a Crontab</title>

	<important>
	<para>Do not use the procedure described here to edit and
	install the system crontab,
	<filename>/etc/crontab</filename>. Instead, use an
	editor: <command>cron</command> will notice that the file
	has changed and immediately begin using the updated version.
	See <ulink
	url="&url.books.faq;/admin.html#root-not-found-cron-errors">
	this FAQ entry</ulink> for more information.</para>
	</important>

	<para>To install a freshly written user
	<filename>crontab</filename>, first use an editor to create
	and save a file in the proper format. Then, specify the file
	name with <command>crontab</command>:</para>

	<screen>&prompt.user; <userinput>crontab crontab-file</userinput></screen>

	<para>In this example, <filename>crontab-file</filename> is the
	filename of a <filename>crontab</filename> that was previously
	created.</para>

	<para>To list installed <filename>crontab</filename> files, pass
	<option>-l</option> to <command>crontab</command>.</para>

	<para>For users who wish to begin their own crontab file from
	scratch, without the use of a template, the
	<command>crontab -e</command> option is available. This will
	invoke the selected editor with an empty file. When the file
	is saved, it will be automatically installed by
	<command>crontab</command>.</para>

	<para>In order to remove a user <filename>crontab</filename>
	completely, use <command>crontab -r</command>.</para>
	</sect2>
	</sect1>

	<sect1 id="configtuning-rcd">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	<!-- 16 May 2003 -->
	</author>
	</authorgroup>
	</sect1info>

	<title>Using &man.rc.8; Under &os;</title>

	<para>In 2002 &os; integrated the NetBSD <filename>rc.d</filename>
	system for system initialization. Users should notice the files
	listed in the <filename class="directory">/etc/rc.d</filename>
	directory. Many of these files are for basic services which can
	be controlled with the <option>start</option>,
	<option>stop</option>, and <option>restart</option> options.
	For instance, &man.sshd.8; can be restarted with the following
	command:</para>

	<screen>&prompt.root; <userinput>service sshd restart</userinput></screen>

	<para>This procedure is similar for other services. Of course,
	services are usually started automatically at boot time as
	specified in &man.rc.conf.5;. For example, enabling the Network
	Address Translation daemon at startup is as simple as adding the
	following line to <filename>/etc/rc.conf</filename>:</para>

	<programlisting>natd_enable="YES"</programlisting>

	<para>If a <option>natd_enable="NO"</option> line is already
	present, then simply change the <option>NO</option> to
	<option>YES</option>. The rc scripts will automatically load
	any other dependent services during the next reboot, as
	described below.</para>

	<para>Since the <filename>rc.d</filename> system is primarily
	intended to start/stop services at system startup/shutdown time,
	the standard <option>start</option>, <option>stop</option> and
	<option>restart</option> options will only perform their action
	if the appropriate <filename>/etc/rc.conf</filename> variables
	are set. For instance, <command>sshd restart</command> will
	only work if <varname>sshd_enable</varname> is set to
	<option>YES</option> in <filename>/etc/rc.conf</filename>.
	To <option>start</option>, <option>stop</option> or
	<option>restart</option> a service regardless of the settings in
	<filename>/etc/rc.conf</filename>, the commands should be
	prefixed with <quote>one</quote>. For instance, to restart
	<command>sshd</command> regardless of the current
	<filename>/etc/rc.conf</filename> setting, execute the following
	command:</para>

	<screen>&prompt.root; <userinput>service sshd onerestart</userinput></screen>

	<para>It is easy to check if a service is enabled in
	<filename>/etc/rc.conf</filename> by running the appropriate
	<filename>rc.d</filename> script with the option
	<option>rcvar</option>. Thus, an administrator can check that
	<command>sshd</command> is in fact enabled in
	<filename>/etc/rc.conf</filename> by running:</para>

	<screen>&prompt.root; <userinput>service sshd rcvar</userinput>
	# sshd
	$sshd_enable=YES</screen>

	<note>
	<para>The second line (<literal># sshd</literal>) is the output
	from <command>sshd</command>, not a
	<username>root</username> console.</para>
	</note>

	- <para>To determine if a service is running, use
	+ <para>To determine whether or not a service is running, use
	<option>status</option>. For instance, to verify that
	<command>sshd</command> is running:</para>

	<screen>&prompt.root; <userinput>service sshd status</userinput>
	sshd is running as pid 433.</screen>

	<para>In some cases it is also possible to <option>reload</option>
	a service. This will attempt to send a signal to an individual
	service, forcing the service to reload its configuration files.
	In most cases this means sending the service a
	<literal>SIGHUP</literal> signal. Support for this feature is
	not included for every service.</para>

	<para>The <filename>rc.d</filename> system is not only used for
	network services, it also contributes to most of the system
	initialization. For instance, when the
	<filename>bgfsck</filename> script is executed, it will print
	out the following message:</para>

	<screen>Starting background file system checks in 60 seconds.</screen>

	<para>Therefore this file is used for background file system
	checks, which are done only during system initialization.</para>

	<para>Many system services depend on other services to function
	properly. For example, NIS and other RPC-based services may
	fail to start until after the <command>rpcbind</command>
	(portmapper) service has started. To resolve this issue,
	information about dependencies and other meta-data is included
	in the comments at the top of each startup script. The
	&man.rcorder.8; program is then used to parse these comments
	during system initialization to determine the order in which
	system services should be invoked to satisfy the
	dependencies.</para>

	<para>The following words must be included in all startup scripts
	(they are required by &man.rc.subr.8; to <quote>enable</quote>
	the startup script):</para>

	<itemizedlist>
	<listitem>
	<para><literal>PROVIDE</literal>: Specifies the services this
	file provides.</para>
	</listitem>
	</itemizedlist>

	<para>The following words may be included at the top of each
	startup file. They are not strictly necessary, but they are
	useful as hints to &man.rcorder.8;:</para>

	<itemizedlist>
	<listitem>
	<para><literal>REQUIRE</literal>: Lists services which are
	required for this service. This file will run
	<emphasis>after</emphasis> the specified services.</para>
	</listitem>

	<listitem>
	<para><literal>BEFORE</literal>: Lists services which depend
	on this service. This file will run
	<emphasis>before</emphasis> the specified services.</para>
	</listitem>
	</itemizedlist>

	<para>By carefully setting these keywords for each startup script,
	an administrator has a very fine-grained level of control of the
	startup order of the scripts, without the hassle of
	<quote>runlevels</quote> like some other &unix; operating
	systems.</para>

	<para>Additional information about the <filename>rc.d</filename>
	system can be found in &man.rc.8; and &man.rc.subr.8;. Refer to
	<ulink url="&url.articles.rc-scripting">this article</ulink> for
	instructions on how to create custom <filename>rc.d</filename>
	scripts.</para>
	</sect1>

	<sect1 id="config-network-setup">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Marc</firstname>
	<surname>Fonvieille</surname>
	<contrib>Contributed by </contrib>
	<!-- 6 October 2002 -->
	</author>
	</authorgroup>
	</sect1info>

	<title>Setting Up Network Interface Cards</title>

	<indexterm>
	<primary>network cards</primary>
	<secondary>configuration</secondary>
	</indexterm>

	<para>Adding and configuring a network card is a common task for
	any &os; administrator.</para>

	<sect2>
	<title>Locating the Correct Driver</title>

	<indexterm>
	<primary>network cards</primary>
	<secondary>driver</secondary>
	</indexterm>

	<para>First, determine the model of the network interface card
	and the chip it uses. &os; supports a wide variety of network
	interface cards. Check the Hardware Compatibility List for
	the &os; release to see if the card is supported.</para>

	<para>If the card is supported, determine the name of the &os;
	driver for the card. Refer to
	<filename>/usr/src/sys/conf/NOTES</filename> and
	<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename>
	for the list of network interface drivers with some
	information about the supported chipsets. When in doubt, read
	the manual page of the driver as it will provide more
	information about the supported hardware and any known
	limitations of the driver.</para>

	<para>The drivers for common network cards are already present
	in the <filename>GENERIC</filename> kernel, meaning the card
	should show up during boot, as in this example:</para>

	<screen>dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38
	000ff irq 15 at device 11.0 on pci0
	miibus0: <MII bus> on dc0
	bmtphy0: <BCM5201 10/100baseTX PHY> PHY 1 on miibus0
	bmtphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
	dc0: Ethernet address: 00:a0:cc:da:da:da
	dc0: [ITHREAD]
	dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30
	000ff irq 11 at device 12.0 on pci0
	miibus1: <MII bus> on dc1
	bmtphy1: <BCM5201 10/100baseTX PHY> PHY 1 on miibus1
	bmtphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
	dc1: Ethernet address: 00:a0:cc:da:da:db
	dc1: [ITHREAD]</screen>

	<para>In this example, two cards using the &man.dc.4; driver are
	present on the system.</para>

	<para>If the driver for the interface is not present in
	<filename>GENERIC</filename>, but a driver is available, the
	driver will need to be loaded before the interface can be
	configured and used. This may be accomplished in one of two
	ways:</para>

	<itemizedlist>
	<listitem>
	<para>The easiest way is to load a kernel module for the
	network card with &man.kldload.8;. To also automatically
	load the driver at boot time, add the appropriate line to
	<filename>/boot/loader.conf</filename>. Not all NIC
	drivers are available as modules; notable examples of
	devices for which modules do not exist are ISA
	cards.</para>
	</listitem>

	<listitem>
	<para>Alternatively, statically compile support for the card
	into a custom kernel. Refer to
	<filename>/usr/src/sys/conf/NOTES</filename>,
	<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename>
	and the manual page of the driver to determine which line
	to add to the custom kernel configuration file. For more
	information about recompiling the kernel, refer to
	<xref linkend="kernelconfig"/>. If the card was detected
	at boot, the kernel does not need to be recompiled.</para>
	</listitem>
	</itemizedlist>

	<sect3 id="config-network-ndis">
	<title>Using &windows; NDIS Drivers</title>

	<indexterm><primary>NDIS</primary></indexterm>
	<indexterm><primary>NDISulator</primary></indexterm>
	<indexterm><primary>&windows; drivers</primary></indexterm>
	<indexterm><primary>Microsoft Windows</primary></indexterm>
	<indexterm>
	<primary>Microsoft Windows</primary>
	<secondary>device drivers</secondary>
	</indexterm>
	<indexterm>
	<primary>KLD (kernel loadable object)</primary>
	</indexterm>
	<!-- We should probably omit the expanded name, and add a <see> entry
	for it. Whatever is done must also be done to the same indexterm in
	linuxemu/chapter.xml -->

	<para>Unfortunately, there are still many vendors that do not
	provide schematics for their drivers to the open source
	community because they regard such information as trade
	secrets. Consequently, the developers of &os; and other
	operating systems are left two choices: develop the drivers
	by a long and pain-staking process of reverse engineering or
	using the existing driver binaries available for the
	&microsoft.windows; platforms. Most developers, including
	those involved with &os;, have taken the latter
	approach.</para>

	<para>Thanks to the contributions of Bill Paul (wpaul) there
	is <quote>native</quote> support for the Network Driver
	Interface Specification (NDIS). The &os; NDISulator
	(otherwise known as Project Evil) takes a &windows; driver
	binary and basically tricks it into thinking it is running
	on &windows;. Because the &man.ndis.4; driver is using a
	&windows; binary, it only runs on &i386; and amd64 systems.
	PCI, CardBus, PCMCIA (PC-Card), and USB devices are
	supported.</para>

	<para>To use the NDISulator, three things are needed:</para>

	<orderedlist>
	<listitem>
	<para>Kernel sources</para>
	</listitem>

	<listitem>
	<para>&windowsxp; driver binary
	(<filename>.SYS</filename> extension)</para>
	</listitem>

	<listitem>
	<para>&windowsxp; driver configuration file
	(<filename>.INF</filename> extension)</para>
	</listitem>
	</orderedlist>

	<para>Locate the files for the specific card. Generally,
	they can be found on the included CDs or at the vendor's
	website. The following examples use
	<filename>W32DRIVER.SYS</filename> and
	<filename>W32DRIVER.INF</filename>.</para>

	<para>The driver bit width must match the version of &os;.
	For &os;/i386, use a &windows; 32-bit driver. For
	&os;/amd64, a &windows; 64-bit driver is needed.</para>

	<para>The next step is to compile the driver binary into a
	loadable kernel module. As <username>root</username>, use
	&man.ndisgen.8;:</para>

	<screen>&prompt.root; <userinput>ndisgen <replaceable>/path/to/W32DRIVER.INF</replaceable> <replaceable>/path/to/W32DRIVER.SYS</replaceable></userinput></screen>

	<para>&man.ndisgen.8; is interactive and prompts for any extra
	information it requires. A new kernel module is written in
	the current directory. Use &man.kldload.8; to load the new
	module:</para>

	<screen>&prompt.root; <userinput>kldload <replaceable>./W32DRIVER_SYS.ko</replaceable></userinput></screen>

	<para>In addition to the generated kernel module, the
	<filename>ndis.ko</filename> and
	<filename>if_ndis.ko</filename> modules must be loaded.
	This should happen automatically when any module that
	depends on &man.ndis.4; is loaded. If not, load them
	manually, using the following commands:</para>

	<screen>&prompt.root; <userinput>kldload ndis</userinput>
	&prompt.root; <userinput>kldload if_ndis</userinput></screen>

	<para>The first command loads the NDIS miniport driver
	wrapper, the second loads the actual network
	interface.</para>

	<para>Now, check &man.dmesg.8; to see if there were any errors
	loading. If all went well, the output should be similar to
	the following:</para>

	<screen>ndis0: <Wireless-G PCI Adapter> mem 0xf4100000-0xf4101fff irq 3 at device 8.0 on pci1
	ndis0: NDIS API version: 5.0
	ndis0: Ethernet address: 0a:b1:2c:d3:4e:f5
	ndis0: 11b rates: 1Mbps 2Mbps 5.5Mbps 11Mbps
	ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps</screen>

	<para>From here you can treat the
	<devicename>ndis0</devicename> device like any other network
	interface (e.g., <devicename>dc0</devicename>).</para>

	<para>To configure the system to load the NDIS modules at
	boot time, copy the generated module,
	<filename>W32DRIVER_SYS.ko</filename>, to the <filename
	class="directory">/boot/modules</filename> directory. Then,
	add the following line to
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>W32DRIVER_SYS_load="YES"</programlisting>
	</sect3>
	</sect2>

	<sect2>
	<title>Configuring the Network Card</title>

	<indexterm>
	<primary>network cards</primary>
	<secondary>configuration</secondary>
	</indexterm>

	<para>Once the right driver is loaded for the network card, the
	card needs to be configured. As with many other things, the
	network card may have been configured at installation time by
	<application>sysinstall</application>.</para>

	<para>To display the configuration for the network interfaces,
	enter the following command:</para>

	<screen>&prompt.user; <userinput>ifconfig</userinput>
	dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	options=80008<VLAN_MTU,LINKSTATE>
	ether 00:a0:cc:da:da:da
	inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
	media: Ethernet autoselect (100baseTX <full-duplex>)
	status: active
	dc1: flags=8802<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
	options=80008<VLAN_MTU,LINKSTATE>
	ether 00:a0:cc:da:da:db
	inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255
	media: Ethernet 10baseT/UTP
	status: no carrier
	lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384
	options=3<RXCSUM,TXCSUM>
	inet6 fe80::1%lo0 prefixlen 64 scopeid 0x4
	inet6 ::1 prefixlen 128
	inet 127.0.0.1 netmask 0xff000000
	nd6 options=3<PERFORMNUD,ACCEPT_RTADV></screen>

	<para>In this example, the following devices were
	displayed:</para>

	<itemizedlist>
	<listitem>
	<para><devicename>dc0</devicename>: The first Ethernet
	interface</para>
	</listitem>

	<listitem>
	<para><devicename>dc1</devicename>: The second Ethernet
	interface</para>
	</listitem>

	<listitem>
	<para><devicename>lo0</devicename>: The loopback
	device</para>
	</listitem>
	</itemizedlist>

	<para>&os; uses the driver name followed by the order in which
	one the card is detected at the kernel boot to name the
	network card. For example <devicename>sis2</devicename> would
	be the third network card on the system using the &man.sis.4;
	driver.</para>

	<para>In this example, the <devicename>dc0</devicename> device
	is up and running. The key indicators are:</para>

	<orderedlist>
	<listitem>
	<para><literal>UP</literal> means that the card is
	configured and ready.</para>
	</listitem>

	<listitem>
	<para>The card has an Internet (<literal>inet</literal>)
	address (in this case
	<hostid role="ipaddr">192.168.1.3</hostid>).</para>
	</listitem>

	<listitem>
	<para>It has a valid subnet mask
	(<literal>netmask</literal>;
	<hostid role="netmask">0xffffff00</hostid> is the same as
	<hostid role="netmask">255.255.255.0</hostid>).</para>
	</listitem>

	<listitem>
	<para>It has a valid broadcast address (in this case,
	<hostid role="ipaddr">192.168.1.255</hostid>).</para>
	</listitem>

	<listitem>
	<para>The MAC address of the card (<literal>ether</literal>)
	is <hostid role="mac">00:a0:cc:da:da:da</hostid></para>
	</listitem>

	<listitem>
	<para>The physical media selection is on autoselection mode
	(<literal>media: Ethernet autoselect (100baseTX
	<full-duplex>)</literal>). In this example,
	<devicename>dc1</devicename> was configured to run with
	<literal>10baseT/UTP</literal> media. For more
	information on available media types for a driver, refer
	to its manual page.</para>
	</listitem>

	<listitem>
	<para>The status of the link (<literal>status</literal>) is
	- <literal>active</literal>, indicating that the carrier is
	- detected. For <devicename>dc1</devicename>, the
	+ <literal>active</literal>, indicating that the carrier
	+ signal is detected. For <devicename>dc1</devicename>, the
	<literal>status: no carrier</literal> status is normal
	when an Ethernet cable is not plugged into the
	card.</para>
	</listitem>
	</orderedlist>

	<para>If the &man.ifconfig.8; output had shown something similar
	to:</para>

	<screen>dc0: flags=8843<BROADCAST,SIMPLEX,MULTICAST> metric 0 mtu 1500
	options=80008<VLAN_MTU,LINKSTATE>
	ether 00:a0:cc:da:da:da
	media: Ethernet autoselect (100baseTX <full-duplex>)
	status: active</screen>

	<para>it would indicate the card has not been configured.</para>

	<para>To configure the card, you will need
	<username>root</username> privileges. The network card
	configuration can be performed from the command line with
	- &man.ifconfig.8; but will not persist after a reboot.
	- Instead, add the network card's configuration to
	+ &man.ifconfig.8; but will not persist after a reboot unless
	+ the network card's configuration is also added to
	<filename>/etc/rc.conf</filename> using an editor. Add a
	line for each network card present on the system, as seen in
	this example:</para>

	<programlisting>ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0"
	ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlisting>

	<para>Replace <devicename>dc0</devicename> and
	<devicename>dc1</devicename> and the IP address information
	with the correct values for the system.
	Refer to the man page for the driver, &man.ifconfig.8; and
	&man.rc.conf.5; for more details about the allowed options and
	the syntax of <filename>/etc/rc.conf</filename>.</para>

	<para>If the network was configured during installation, some
	lines about the network card(s) may be already present.
	Double check <filename>/etc/rc.conf</filename> before adding
	any lines.</para>

	<para>If the network is not using DNS, edit
	<filename>/etc/hosts</filename> to add the names and the IP
	addresses of various machines of the LAN, if they are not
	already there. For more information, refer to &man.hosts.5;
	and to
	<filename>/usr/share/examples/etc/hosts</filename>.</para>

	<note>
	<para>If there is no DHCP server and access to the Internet is
	needed, manually configure the default gateway and the
	nameserver:</para>

	<screen>&prompt.root; <userinput>echo 'defaultrouter="<replaceable>your_default_router</replaceable>"' >> /etc/rc.conf</userinput>
	&prompt.root; <userinput>echo 'nameserver <replaceable>your_DNS_server</replaceable>' >> /etc/resolv.conf</userinput></screen>
	</note>
	</sect2>

	<sect2>
	<title>Testing and Troubleshooting</title>

	<para>Once the necessary changes in
	<filename>/etc/rc.conf</filename> are saved, a reboot can be
	used to test the network configuration and to verify that the
	system restarts without any configuration errors.
	Alternatively, apply the settings to the networking system
	with this command:</para>

	<screen>&prompt.root; <userinput>service netif restart</userinput></screen>

	<note>
	<para>If a default gateway has been set in
	<filename>/etc/rc.conf</filename>, use also this
	command:</para>

	<screen>&prompt.root; <userinput>service routing restart</userinput></screen>
	</note>

	<para>Once the networking system has been relaunched, test the
	network interfaces.</para>

	<sect3>
	<title>Testing the Ethernet Card</title>

	<indexterm>
	<primary>network cards</primary>
	<secondary>testing</secondary>
	</indexterm>

	<para>To verify that an Ethernet card is configured correctly,
	ping the interface itself, and then ping another machine on
	the LAN:</para>

	<screen>&prompt.user; <userinput>ping -c5 192.168.1.3</userinput>
	PING 192.168.1.3 (192.168.1.3): 56 data bytes
	64 bytes from 192.168.1.3: icmp_seq=0 ttl=64 time=0.082 ms
	64 bytes from 192.168.1.3: icmp_seq=1 ttl=64 time=0.074 ms
	64 bytes from 192.168.1.3: icmp_seq=2 ttl=64 time=0.076 ms
	64 bytes from 192.168.1.3: icmp_seq=3 ttl=64 time=0.108 ms
	64 bytes from 192.168.1.3: icmp_seq=4 ttl=64 time=0.076 ms

	--- 192.168.1.3 ping statistics ---
	5 packets transmitted, 5 packets received, 0% packet loss
	round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms</screen>

	<screen>&prompt.user; <userinput>ping -c5 192.168.1.2</userinput>
	PING 192.168.1.2 (192.168.1.2): 56 data bytes
	64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms
	64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.766 ms
	64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.700 ms
	64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.747 ms
	64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=0.704 ms

	--- 192.168.1.2 ping statistics ---
	5 packets transmitted, 5 packets received, 0% packet loss
	round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen>

	<para>To test network resolution, use the machine name instead
	of <hostid role="ipaddr">192.168.1.2</hostid>. If there is
	no DNS server on the network,
	<filename>/etc/hosts</filename> must first be
	configured.</para>
	</sect3>

	<sect3>
	<title>Troubleshooting</title>

	<indexterm>
	<primary>network cards</primary>
	<secondary>troubleshooting</secondary>
	</indexterm>

	<para>Troubleshooting hardware and software configurations is
	always a pain, and a pain which can be alleviated by
	checking the simple things first. Is the network cable
	plugged in? Are the network services properly configured?
	Is the firewall configured correctly? Is the network card
	supported by &os;? Always before sending a bug report,
	check the hardware notes, update the version of &os; to the
	latest STABLE version, check the mailing list archives, and
	search the Internet.</para>

	<para>If the card works, yet performance is poor, it would be
	worthwhile to read over the &man.tuning.7; manual page.
	Also, check the network configuration as incorrect network
	settings can cause slow connections.</para>

	<para>Some users experience one or two
	<errorname>device timeout</errorname> messages, which is
	normal for some cards. If they continue, or are bothersome,
	determine if the device is conflicting with another device.
	Double check the cable connections. Consider trying another
	card.</para>

	<para>At times, users see a few
	<errorname>watchdog timeout</errorname> errors. The first
	thing to do is to check the network cable. Many cards
	require a PCI slot which supports Bus Mastering. On some
	old motherboards, only one PCI slot allows it (usually slot
	0). Check the network card and the motherboard
	documentation to determine if that may be the
	problem.</para>

	<para><errorname>No route to host</errorname> messages occur
	if the system is unable to route a packet to the destination
	host. This can happen if no default route is specified, or
	if a cable is unplugged. Check the output of
	<command>netstat -rn</command> and make sure there is a
	valid route to the host. If there is not, read on to
	<xref linkend="advanced-networking"/>.</para>

	<para><errorname>ping: sendto: Permission denied</errorname>
	error messages are often caused by a misconfigured firewall.
	If <command>ipfw</command> is enabled in the kernel but no
	rules have been defined, then the default policy is to deny
	all traffic, even ping requests! Read on to
	<xref linkend="firewalls"/> for more information.</para>

	<para>Sometimes performance of the card is poor, or below
	average. In these cases it is best to set the media
	selection mode from <literal>autoselect</literal> to the
	correct media selection. While this usually works for most
	hardware, it may not resolve this issue for everyone.
	Again, check all the network settings, and read over the
	&man.tuning.7; manual page.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="configtuning-virtual-hosts">
	<title>Virtual Hosts</title>

	<indexterm><primary>virtual hosts</primary></indexterm>
	<indexterm><primary>IP aliases</primary></indexterm>

	<para>A very common use of &os; is virtual site hosting, where one
	server appears to the network as many servers. This is achieved
	by assigning multiple network addresses to a single
	interface.</para>

	<para>A given network interface has one <quote>real</quote>
	address, and may have any number of <quote>alias</quote>
	addresses. These aliases are normally added by placing alias
	entries in <filename>/etc/rc.conf</filename>.</para>

	<para>An alias entry for the interface
	<devicename>fxp0</devicename> looks like:</para>

	<programlisting>ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"</programlisting>

	<para>Note that alias entries must start with
	<literal>alias0</literal> and proceed upwards in order, (for
	example, <literal>_alias1</literal>, <literal>_alias2</literal>,
	and so on). The configuration process will stop at the first
	missing number.</para>

	<para>The calculation of alias netmasks is important, but
	fortunately quite simple. For a given interface, there must be
	one address which correctly represents the network's netmask.
	Any other addresses which fall within this network must have a
	netmask of all <literal>1</literal>s (expressed as either
	<hostid role="netmask">255.255.255.255</hostid> or
	<hostid role="netmask">0xffffffff</hostid>).</para>

	<para>For example, consider the case where the
	<devicename>fxp0</devicename> interface is connected to two
	networks: the <hostid role="ipaddr">10.1.1.0</hostid> network
	with a netmask of <hostid role="netmask">255.255.255.0</hostid>
	and the <hostid role="ipaddr">202.0.75.16</hostid> network with
	a netmask of <hostid role="netmask">255.255.255.240</hostid>.
	The system is to be configured to appear in the
	range
	<hostid role="ipaddr">10.1.1.1</hostid> through
	<hostid role="ipaddr">10.1.1.5</hostid> and
	<hostid role="ipaddr">202.0.75.17</hostid> through
	<hostid role="ipaddr">202.0.75.20</hostid>. Only the first
	address in a given network range should have a real
	netmask. All the rest (<hostid role="ipaddr">10.1.1.2</hostid>
	through <hostid role="ipaddr">10.1.1.5</hostid> and
	<hostid role="ipaddr">202.0.75.18</hostid> through
	<hostid role="ipaddr">202.0.75.20</hostid>) must be configured
	with a netmask of
	<hostid role="netmask">255.255.255.255</hostid>.</para>

	<para>The following <filename>/etc/rc.conf</filename> entries
	configure the adapter correctly for this arrangement:</para>

	<programlisting>ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
	ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
	ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255"
	ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255"
	ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255"
	ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240"
	ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255"
	ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255"
	ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting>

	</sect1>

	<sect1 id="configtuning-syslog">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Niclas</firstname>
	<surname>Zeising</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>Configuring the System Logger,
	<application>syslogd</application></title>

	<indexterm><primary>system logging</primary></indexterm>
	<indexterm><primary>syslog</primary></indexterm>
	<indexterm><primary>syslogd</primary></indexterm>

	<para>System logging is an important aspect of system
	administration. It is used both to detect hardware and software
	issues and errors in the system. It also plays a very
	important role in security auditing and incident response.
	System daemons without a controlling terminal also usually log
	information to a system logging facility or other log
	file.</para>

	<para>This section describes how to configure and use the &os;
	system logger, &man.syslogd.8;, and how to perform log rotation
	and log management using &man.newsyslog.8;. Focus
	will be on setting up and using <command>syslogd</command> on
	a local machine. For more advanced setups using a separate
	loghost, see <xref linkend="network-syslogd"/>.</para>

	<sect2>
	<title>Using <application>syslogd</application></title>

	<para>In the default &os; configuration &man.syslogd.8; is
	started at boot. This is controlled by the variable
	<literal>syslogd_enable</literal> in
	<filename>/etc/rc.conf</filename>. There are numerous
	application arguments that affect the behavior of
	&man.syslogd.8;. To change them, use
	<literal>syslogd_flags</literal> in
	<filename>/etc/rc.conf</filename>. Refer to &man.syslogd.8;
	for more information on the arguments, and &man.rc.conf.5;,
	<xref linkend="configtuning-core-configuration"/> and <xref
	linkend="configtuning-rcd"/> for more information about
	<filename>/etc/rc.conf</filename> and the &man.rc.8;
	subsystem.</para>
	</sect2>

	<sect2>
	<title>Configuring <application>syslogd</application></title>

	<indexterm><primary>syslog.conf</primary></indexterm>

	<para>The configuration file, by default
	<filename>/etc/syslog.conf</filename>, controls what
	&man.syslogd.8; does with the log entries once they are
	received. There are several parameters to control the
	handling of incoming events, of which the most basic are
	<firstterm>facility</firstterm> and
	<firstterm>level</firstterm>. The facility describes
	which subsystem generated the message, such as the kernel or a
	daemon, and the level describes the severity of the event that
	occurred. This makes it possible to log the message to
	different log files, or discard it, depending on the facility
	and level. It is also possible to take action depending on
	the application that sent the message, and in the case of
	remote logging, also the hostname of the machine generating
	the logging event.</para>

	<para>Configuring &man.syslogd.8; is quite straight
	forward. The configuration file contains one line per action,
	and the syntax for each line is a selector field followed by
	an action field. The syntax of the selector field is
	<replaceable>facility.level</replaceable> which will match
	log messages from <replaceable>facility</replaceable> at level
	<replaceable>level</replaceable> or higher. It is also
	possible to add an optional comparison flag before the level
	to specify more precisely what is logged. Multiple
	selector fields can be used for the same action, and are
	separated with a semicolon (<literal>;</literal>). Using
	<literal>*</literal> will match everything.
	The action field denotes where to send the log message,
	such as a file or a remote log host. As an example, here is
	the default <filename>syslog.conf</filename> from &os;:</para>

	<programlisting># &dollar;&os;&dollar;
	#
	# Spaces ARE valid field separators in this file. However,
	# other *nix-like systems still insist on using tabs as field
	# separators. If you are sharing this file between systems, you
	# may want to use only tabs as field separators here.
	# Consult the &man.syslog.conf.5; manpage.
	*.err;kern.warning;auth.notice;mail.crit /dev/console <co id="co-syslog-many-match"/>
	*.notice;authpriv.none;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
	security.* /var/log/security
	auth.info;authpriv.info /var/log/auth.log
	mail.info /var/log/maillog <co id="co-syslog-one-match"/>
	lpr.info /var/log/lpd-errs
	ftp.info /var/log/xferlog
	cron.* /var/log/cron
	*.=debug /var/log/debug.log <co id="co-syslog-comparison"/>
	.emerg
	# uncomment this to log all writes to /dev/console to /var/log/console.log
	#console.info /var/log/console.log
	# uncomment this to enable logging of all log messages to /var/log/all.log
	# touch /var/log/all.log and chmod it to mode 600 before it will work
	#. /var/log/all.log
	# uncomment this to enable logging to a remote loghost named loghost
	#. @loghost
	# uncomment these if you're running inn
	# news.crit /var/log/news/news.crit
	# news.err /var/log/news/news.err
	# news.notice /var/log/news/news.notice
	!ppp <co id="co-syslog-prog-spec"/>
	. /var/log/ppp.log
	!*</programlisting>

	<calloutlist>
	<callout arearefs="co-syslog-many-match">
	<para>Match all messages with a level of
	<literal>err</literal> or higher, as well as
	<literal>kern.warning</literal>,
	<literal>auth.notice</literal> and
	<literal>mail.crit</literal>, and send these log messages
	to the console (<filename>/dev/console</filename>).</para>
	</callout>

	<callout arearefs="co-syslog-one-match">
	<para>Match all messages from the <literal>mail</literal>
	facility at level <literal>info</literal> or above, and
	log the messages to
	<filename>/var/log/maillog</filename>.</para>
	</callout>

	<callout arearefs="co-syslog-comparison">
	<para>This line uses a comparison flag, <literal>=</literal>
	to only match messages at level <literal>debug</literal>,
	and log them in
	<filename>/var/log/debug.log</filename>.</para>
	</callout>

	<callout arearefs="co-syslog-prog-spec">
	<para>Here is an example usage of a
	<emphasis>program specification</emphasis>. This will
	make the rules following only be valid for the program
	in the program specification. In this case
	this line and the following makes all messages from
	<command>ppp</command>, but no other programs, end up in
	<filename>/var/log/ppp.log</filename>.</para>
	</callout>
	</calloutlist>

	<para>This example shows that there are plenty of levels and
	subsystems. The levels are, in order from most to least
	critical: <literal>emerg</literal>, <literal>alert</literal>,
	<literal>crit</literal>, <literal>err</literal>,
	<literal>warning</literal>, <literal>notice</literal>,
	<literal>info</literal> and <literal>debug</literal>.</para>

	<para>The facilities are, in no particular order:
	<literal>auth</literal>, <literal>authpriv</literal>,
	<literal>console</literal>, <literal>cron</literal>,
	<literal>daemon</literal>, <literal>ftp</literal>,
	<literal>kern</literal>, <literal>lpr</literal>,
	<literal>mail</literal>, <literal>mark</literal>,
	<literal>news</literal>, <literal>security</literal>,
	<literal>syslog</literal>, <literal>user</literal>,
	<literal>uucp</literal> and <literal>local0</literal> through
	<literal>local7</literal>. Be aware that other operating
	systems might have different facilities.</para>

	<para>With this knowledge it is easy to add a new line to
	<filename>/etc/syslog.conf</filename> to log everything from
	the different daemons on level <literal>notice</literal> and
	higher to <filename>/var/log/daemon.log</filename>. Just add
	the following:</para>

	<programlisting>daemon.notice /var/log/daemon.log</programlisting>

	<para>For more information about the different levels and
	facilities, refer to &man.syslog.3; and &man.syslogd.8;.
	For more information about <filename>syslog.conf</filename>,
	its syntax, and more advanced usage examples, see
	&man.syslog.conf.5; and
	<xref linkend="network-syslogd"/>.</para>
	</sect2>

	<sect2>
	<title>Log Management and Rotation with
	<application>newsyslog</application></title>

	<indexterm><primary>newsyslog</primary></indexterm>
	<indexterm><primary>newsyslog.conf</primary></indexterm>
	<indexterm><primary>log rotation</primary></indexterm>
	<indexterm><primary>log management</primary></indexterm>

	<para>Log files tend to grow quickly and accumulate steadily.
	This leads to the files being full of less immediately useful
	information while filling up the hard drive. Log management
	attempts to mitigate this. In &os;, &man.newsyslog.8; is used
	to manage log files. This program periodically rotates and
	compresses log files, and optionally creates missing log files
	and signals programs when log files are moved. The log files
	are not necessarily generated by syslog as &man.newsyslog.8;
	works with any logs written from any program. Note that
	<command>newsyslog</command> is normally run from
	&man.cron.8; and is not a system daemon. In the default
	configuration, it is run every hour.</para>

	<sect3>
	<title>Configuring
	<application>newsyslog</application></title>

	<para>To know what actions to take, &man.newsyslog.8; reads
	its configuration file, by default
	<filename>/etc/newsyslog.conf</filename>. This
	configuration file contains one line for each file that
	&man.newsyslog.8; manages. Each line states the file
	owner, permissions, when to rotate that file, optional flags
	that affect log rotation, such as compression, and programs
	to signal when the log is rotated. Here is the default
	configuration in &os;:</para>

	<programlisting># configuration file for newsyslog
	# &dollar;&os;&dollar;
	#
	# Entries which do not specify the '/pid_file' field will cause the
	# syslogd process to be signalled when that log file is rotated. This
	# action is only appropriate for log files which are written to by the
	# syslogd process (ie, files listed in /etc/syslog.conf). If there
	# is no process which needs to be signalled when a given log file is
	# rotated, then the entry for that file should include the 'N' flag.
	#
	# The 'flags' field is one or more of the letters: BCDGJNUXZ or a '-'.
	#
	# Note: some sites will want to select more restrictive protections than the
	# defaults. In particular, it may be desirable to switch many of the 644
	# entries to 640 or 600. For example, some sites will consider the
	# contents of maillog, messages, and lpd-errs to be confidential. In the
	# future, these defaults may change to more conservative ones.
	#
	# logfilename [owner:group] mode count size when flags [/pid_file] [sig_num]
	/var/log/all.log 600 7 * @T00 J
	/var/log/amd.log 644 7 100 * J
	/var/log/auth.log 600 7 100 @0101T JC
	/var/log/console.log 600 5 100 * J
	/var/log/cron 600 3 100 * JC
	/var/log/daily.log 640 7 * @T00 JN
	/var/log/debug.log 600 7 100 * JC
	/var/log/init.log 644 3 100 * J
	/var/log/kerberos.log 600 7 100 * J
	/var/log/lpd-errs 644 7 100 * JC
	/var/log/maillog 640 7 * @T00 JC
	/var/log/messages 644 5 100 @0101T JC
	/var/log/monthly.log 640 12 * $M1D0 JN
	/var/log/pflog 600 3 100 * JB /var/run/pflogd.pid
	/var/log/ppp.log root:network 640 3 100 * JC
	/var/log/security 600 10 100 * JC
	/var/log/sendmail.st 640 10 * 168 B
	/var/log/utx.log 644 3 * @01T05 B
	/var/log/weekly.log 640 5 1 $W6D0 JN
	/var/log/xferlog 600 7 100 * JC</programlisting>

	<para>Each line starts with the name of the file to be
	rotated, optionally followed by an owner
	and group for both rotated and newly created files.
	The next field, <literal>mode</literal> is the mode of the
	files and <literal>count</literal> denotes how many rotated
	log files should be kept. The <literal>size</literal> and
	<literal>when</literal> fields tell
	<command>newsyslog</command> when to rotate the file.
	A log file is rotated when either its size is larger than
	the <literal>size</literal> field, or when the time in the
	<literal>when</literal> filed has passed.
	<literal>*</literal> means that this field is ignored. The
	<replaceable>flags</replaceable> field gives
	&man.newsyslog.8; further instructions, such as
	how to compress the rotated file, or to create the log file
	if it is missing. The last two fields are optional, and
	specify the <acronym
	role="Process Identifier">PID</acronym>-file of a
	process and a signal number to send to that process with
	when the file is rotated. For more information on all
	fields, valid flags and how to specify the rotation time,
	refer to &man.newsyslog.conf.5;. Remember that
	<command>newsyslog</command> is run from
	<command>cron</command> and can not rotate files more
	often than it is run from &man.cron.8;.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="configtuning-configfiles">
	<title>Configuration Files</title>

	<sect2>
	<title><filename class="directory">/etc</filename>
	Layout</title>

	<para>There are a number of directories in which configuration
	information is kept. These include:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<colspec colwidth="1*"/>
	<colspec colwidth="2*"/>

	<tbody>
	<row>
	<entry><filename
	class="directory">/etc</filename></entry>
	<entry>Generic system configuration information; data
	here is system-specific.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/etc/defaults</filename></entry>
	<entry>Default versions of system configuration
	files.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/etc/mail</filename></entry>
	<entry>Extra &man.sendmail.8; configuration, other
	MTA configuration files.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/etc/ppp</filename></entry>
	<entry>Configuration for both user- and kernel-ppp
	programs.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/etc/namedb</filename></entry>
	<entry>Default location for &man.named.8; data.
	Normally <filename>named.conf</filename> and zone
	files are stored here.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/local/etc</filename></entry>
	<entry>Configuration files for installed applications.
	May contain per-application subdirectories.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/usr/local/etc/rc.d</filename></entry>
	<entry>Start/stop scripts for installed
	applications.</entry>
	</row>

	<row>
	<entry><filename
	class="directory">/var/db</filename></entry>
	<entry>Automatically generated system-specific database
	files, such as the package database, the locate
	database, and so on</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</sect2>

	<sect2>
	<title>Hostnames</title>

	<indexterm><primary>hostname</primary></indexterm>
	<indexterm><primary>DNS</primary></indexterm>

	<sect3>
	<title><filename>/etc/resolv.conf</filename></title>

	<indexterm>
	<primary><filename>resolv.conf</filename></primary>
	</indexterm>

	<para><filename>/etc/resolv.conf</filename> dictates how
	&os;'s resolver accesses the Internet Domain Name System
	(DNS).</para>

	<para>The most common entries to
	<filename>resolv.conf</filename> are:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<colspec colwidth="1*"/>
	<colspec colwidth="2*"/>

	<tbody>
	<row>
	<entry><literal>nameserver</literal></entry>
	<entry>The IP address of a name server the resolver
	should query. The servers are queried in the order
	listed with a maximum of three.</entry>
	</row>

	<row>
	<entry><literal>search</literal></entry>
	<entry>Search list for hostname lookup. This is
	normally determined by the domain of the local
	hostname.</entry>
	</row>

	<row>
	<entry><literal>domain</literal></entry>
	<entry>The local domain name.</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>A typical <filename>resolv.conf</filename>:</para>

	<programlisting>search example.com
	nameserver 147.11.1.11
	nameserver 147.11.100.30</programlisting>

	<note>
	<para>Only one of the <literal>search</literal> and
	<literal>domain</literal> options should be used.</para>
	</note>

	<para>When using DHCP, &man.dhclient.8; usually rewrites
	<filename>resolv.conf</filename> with information received
	from the DHCP server.</para>
	</sect3>

	<sect3>
	<title><filename>/etc/hosts</filename></title>

	<indexterm><primary>hosts</primary></indexterm>

	<para><filename>/etc/hosts</filename> is a simple text
	database reminiscent of the old Internet. It works in
	conjunction with DNS and NIS providing name to IP address
	mappings. Local computers connected via a LAN can be placed
	in here for simplistic naming purposes instead of setting up
	a &man.named.8; server. Additionally,
	<filename>/etc/hosts</filename> can be used to provide a
	local record of Internet names, reducing the need to query
	externally for commonly accessed names.</para>

	<programlisting># &dollar;&os;&dollar;
	#
	#
	# Host Database
	#
	# This file should contain the addresses and aliases for local hosts that
	# share this file. Replace 'my.domain' below with the domainname of your
	# machine.
	#
	# In the presence of the domain name service or NIS, this file may
	# not be consulted at all; see /etc/nsswitch.conf for the resolution order.
	#
	#
	::1 localhost localhost.my.domain
	127.0.0.1 localhost localhost.my.domain
	#
	# Imaginary network.
	#10.0.0.2 myname.my.domain myname
	#10.0.0.3 myfriend.my.domain myfriend
	#
	# According to RFC 1918, you can use the following IP networks for
	# private nets which will never be connected to the Internet:
	#
	# 10.0.0.0 - 10.255.255.255
	# 172.16.0.0 - 172.31.255.255
	# 192.168.0.0 - 192.168.255.255
	#
	# In case you want to be able to connect to the Internet, you need
	# real official assigned numbers. Do not try to invent your own network
	# numbers but instead get one from your network provider (if any) or
	# from your regional registry (ARIN, APNIC, LACNIC, RIPE NCC, or AfriNIC.)
	#</programlisting>

	<para><filename>/etc/hosts</filename> takes on the simple
	format of:</para>

	<programlisting>[Internet address] [official hostname] [alias1] [alias2] ...</programlisting>

	<para>For example:</para>

	<programlisting>10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2</programlisting>

	<para>Consult &man.hosts.5; for more information.</para>
	</sect3>
	</sect2>

	<sect2 id="configtuning-sysctlconf">
	<title><filename>sysctl.conf</filename></title>

	<indexterm><primary>sysctl.conf</primary></indexterm>
	<indexterm><primary>sysctl</primary></indexterm>

	<para><filename>sysctl.conf</filename> looks much like
	<filename>rc.conf</filename>. Values are set in a
	<literal>variable=value</literal> form. The specified values
	are set after the system goes into multi-user mode. Not all
	variables are settable in this mode.</para>

	<para>To turn off logging of fatal signal exits and prevent
	users from seeing processes started from other users, the
	following tunables can be set in
	<filename>sysctl.conf</filename>:</para>

	<programlisting># Do not log fatal signal exits (e.g., sig 11)
	kern.logsigexit=0

	# Prevent users from seeing information about processes that
	# are being run under another UID.
	security.bsd.see_other_uids=0</programlisting>

	</sect2>
	</sect1>

	<sect1 id="configtuning-sysctl">
	<title>Tuning with &man.sysctl.8;</title>

	<indexterm><primary>sysctl</primary></indexterm>
	<indexterm>
	<primary>tuning</primary>
	<secondary>with sysctl</secondary>
	</indexterm>

	<para>&man.sysctl.8; is used to make changes to a running &os;
	system. This includes many advanced options of the TCP/IP stack
	and virtual memory system that can dramatically improve
	performance for an experienced system administrator. Over five
	hundred system variables can be read and set using
	&man.sysctl.8;.</para>

	<para>At its core, &man.sysctl.8; serves two functions: to read
	and to modify system settings.</para>

	<para>To view all readable variables:</para>

	<screen>&prompt.user; <userinput>sysctl -a</userinput></screen>

	<para>To read a particular variable, for example,
	<varname>kern.maxproc</varname>:</para>

	<screen>&prompt.user; <userinput>sysctl kern.maxproc</userinput>
	kern.maxproc: 1044</screen>

	<para>To set a particular variable, use the intuitive
	<replaceable>variable</replaceable>=<replaceable>value</replaceable>
	syntax:</para>

	<screen>&prompt.root; <userinput>sysctl kern.maxfiles=5000</userinput>
	kern.maxfiles: 2088 -> 5000</screen>

	<para>Settings of sysctl variables are usually either strings,
	numbers, or booleans (a boolean being <literal>1</literal> for
	yes or a <literal>0</literal> for no).</para>

	<para>To automatically set some variables each time the machine
	boots, add them to <filename>/etc/sysctl.conf</filename>. For
	more information refer to &man.sysctl.conf.5; and <xref
	linkend="configtuning-sysctlconf"/>.</para>

	<sect2 id="sysctl-readonly">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	<!-- 31 January 2003 -->
	</author>
	</authorgroup>
	</sect2info>
	<title>&man.sysctl.8; Read-only</title>

	<para>In some cases it may be desirable to modify read-only
	&man.sysctl.8; values. While this is sometimes unavoidable,
	it can only be done on (re)boot.</para>

	<para>For instance on some laptop models the &man.cardbus.4;
	device will not probe memory ranges, and fail with errors
	which look similar to:</para>

	<screen>cbb0: Could not map register memory
	device_probe_and_attach: cbb0 attach returned 12</screen>

	<para>Cases like the one above usually require the modification
	of some default &man.sysctl.8; settings which are set read
	only. To overcome these situations a user can put
	&man.sysctl.8; <quote>OIDs</quote> in their local
	<filename>/boot/loader.conf</filename>. Default settings are
	located in
	<filename>/boot/defaults/loader.conf</filename>.</para>

	<para>Fixing the problem mentioned above would require a user to
	set <option>hw.pci.allow_unsupported_io_range=1</option> in
	the aforementioned file. Now &man.cardbus.4; will work
	properly.</para>
	</sect2>
	</sect1>

	<sect1 id="configtuning-disk">
	<title>Tuning Disks</title>

	<sect2>
	<title>Sysctl Variables</title>

	<sect3>
	<title><varname>vfs.vmiodirenable</varname></title>

	<indexterm>
	<primary><varname>vfs.vmiodirenable</varname></primary>
	</indexterm>

	<para>The <varname>vfs.vmiodirenable</varname> sysctl variable
	may be set to either 0 (off) or 1 (on); it is 1 by default.
	This variable controls how directories are cached by the
	system. Most directories are small, using just a single
	fragment (typically 1 K) in the file system and less
	(typically 512 bytes) in the buffer cache. With this
	variable turned off (to 0), the buffer cache will only cache
	a fixed number of directories even if the system has a huge
	amount of memory. When turned on (to 1), this sysctl allows
	the buffer cache to use the VM Page Cache to cache the
	directories, making all the memory available for caching
	directories. However, the minimum in-core memory used to
	cache a directory is the physical page size (typically
	4 K) rather than 512  bytes. Keeping this option
	enabled is recommended if the system is running any services
	which manipulate large numbers of files. Such services can
	include web caches, large mail systems, and news systems.
	Keeping this option on will generally not reduce performance
	even with the wasted memory but you should experiment to
	find out.</para>
	</sect3>

	<sect3>
	<title><varname>vfs.write_behind</varname></title>

	<indexterm>
	<primary><varname>vfs.write_behind</varname></primary>
	</indexterm>

	<para>The <varname>vfs.write_behind</varname> sysctl variable
	defaults to <literal>1</literal> (on). This tells the file
	system to issue media writes as full clusters are collected,
	which typically occurs when writing large sequential files.
	The idea is to avoid saturating the buffer cache with dirty
	buffers when it would not benefit I/O performance. However,
	this may stall processes and under certain circumstances
	should be turned off.</para>
	</sect3>

	<sect3>
	<title><varname>vfs.hirunningspace</varname></title>

	<indexterm>
	<primary><varname>vfs.hirunningspace</varname></primary>
	</indexterm>

	<para>The <varname>vfs.hirunningspace</varname> sysctl
	variable determines how much outstanding write I/O may be
	queued to disk controllers system-wide at any given
	instance. The default is usually sufficient but on machines
	with lots of disks, try bumping it up to four or five
	<emphasis>megabytes</emphasis>. Note that setting too
	high a value (exceeding the buffer cache's write threshold)
	can lead to extremely bad clustering performance. Do not
	set this value arbitrarily high! Higher write values may
	add latency to reads occurring at the same time.</para>

	<para>There are various other buffer-cache and VM page cache
	related sysctls. Modifying these values is not recommended
	as the VM system does an extremely good job of automatically
	tuning itself.</para>
	</sect3>

	<sect3>
	<title><varname>vm.swap_idle_enabled</varname></title>

	<indexterm>
	<primary><varname>vm.swap_idle_enabled</varname></primary>
	</indexterm>

	<para>The <varname>vm.swap_idle_enabled</varname> sysctl
	variable is useful in large multi-user systems with lots of
	users entering and leaving the system and lots of idle
	processes. Such systems tend to generate a great deal of
	continuous pressure on free memory reserves. Turning this
	feature on and tweaking the swapout hysteresis (in idle
	seconds) via <varname>vm.swap_idle_threshold1</varname> and
	<varname>vm.swap_idle_threshold2</varname> depresses the
	priority of memory pages associated with idle processes more
	quickly then the normal pageout algorithm. This gives a
	helping hand to the pageout daemon. Only turn this option
	on if needed, because the tradeoff is essentially pre-page
	memory sooner rather than later which eats more swap and
	disk bandwidth. In a small system this option will have a
	determinable effect, but in a large system that is already
	doing moderate paging this option allows the VM system to
	stage whole processes into and out of memory easily.</para>
	</sect3>

	<sect3>
	<title><varname>hw.ata.wc</varname></title>

	<indexterm>
	<primary><varname>hw.ata.wc</varname></primary>
	</indexterm>

	<para>&os; 4.3 flirted with turning off IDE write
	caching. This reduced write bandwidth to IDE disks but was
	considered necessary due to serious data consistency issues
	introduced by hard drive vendors. The problem is that IDE
	drives lie about when a write completes. With IDE write
	caching turned on, IDE hard drives not only write data to
	disk out of order, but will sometimes delay writing some
	blocks indefinitely when under heavy disk loads. A crash or
	power failure may cause serious file system corruption.
	&os;'s default was changed to be safe. Unfortunately, the
	result was such a huge performance loss that we changed
	write caching back to on by default after the release.
	Check the default on the system by observing the
	<varname>hw.ata.wc</varname> sysctl variable. If IDE write
	caching is turned off, setting this variable back to 1 will
	turn it back on. This must be done from the boot loader at
	boot time as attempting to do it after the kernel boots
	will have no effect.</para>

	<para>For more information, refer to &man.ata.4;.</para>
	</sect3>

	<sect3>
	<title><literal>SCSI_DELAY</literal>
	(<varname>kern.cam.scsi_delay</varname>)</title>

	<indexterm>
	<primary><varname>kern.cam.scsi_delay</varname></primary>
	</indexterm>

	<indexterm>
	<primary>kernel options</primary>
	<secondary><literal>SCSI_DELAY</literal></secondary>
	</indexterm>

	<para>The <literal>SCSI_DELAY</literal> kernel config may be
	used to reduce system boot times. The defaults are fairly
	high and can be responsible for <literal>15</literal>
	seconds of delay in the boot process. Reducing it to
	<literal>5</literal> seconds usually works (especially with
	modern drives). The <varname>kern.cam.scsi_delay</varname>
	boot time tunable should be used. The tunable, and kernel
	config option accept values in terms of
	<emphasis>milliseconds</emphasis> and
	<emphasis>not</emphasis>
	<emphasis>seconds</emphasis>.</para>
	</sect3>
	</sect2>

	<sect2 id="soft-updates">
	<title>Soft Updates</title>

	<indexterm><primary>Soft Updates</primary></indexterm>
	<indexterm><primary>tunefs</primary></indexterm>

	<para>The &man.tunefs.8; program can be used to fine-tune a
	file system. This program has many different options, but for
	now we are only concerned with toggling Soft Updates on and
	off, which is done by:</para>

	<screen>&prompt.root; <userinput>tunefs -n enable /filesystem</userinput>
	&prompt.root; <userinput>tunefs -n disable /filesystem</userinput></screen>

	<para>A filesystem cannot be modified with &man.tunefs.8; while
	it is mounted. A good time to enable Soft Updates is before
	any partitions have been mounted, in single-user mode.</para>

	<para>Soft Updates drastically improves meta-data performance,
	mainly file creation and deletion, through the use of a memory
	cache. We recommend to use Soft Updates on all of your file
	systems. There are two downsides to Soft Updates that you
	should be aware of: First, Soft Updates guarantees filesystem
	consistency in the case of a crash but could very easily be
	several seconds (even a minute!) behind updating the physical
	disk. If your system crashes you may lose more work than
	otherwise. Secondly, Soft Updates delays the freeing of
	filesystem blocks. If you have a filesystem (such as the root
	filesystem) which is almost full, performing a major update,
	such as <command>make installworld</command>, can cause the
	filesystem to run out of space and the update to fail.</para>

	<sect3>
	<title>More Details About Soft Updates</title>

	<indexterm>
	<primary>Soft Updates</primary>
	<secondary>details</secondary>
	</indexterm>

	<para>There are two traditional approaches to writing a file
	systems meta-data back to disk. (Meta-data updates are
	updates to non-content data like inodes or
	directories.)</para>

	<para>Historically, the default behavior was to write out
	meta-data updates synchronously. If a directory had been
	changed, the system waited until the change was actually
	written to disk. The file data buffers (file contents) were
	passed through the buffer cache and backed up to disk later
	on asynchronously. The advantage of this implementation is
	that it operates safely. If there is a failure during an
	update, the meta-data are always in a consistent state. A
	file is either created completely or not at all. If the
	data blocks of a file did not find their way out of the
	buffer cache onto the disk by the time of the crash,
	&man.fsck.8; is able to recognize this and repair the
	filesystem by setting the file length to 0. Additionally,
	the implementation is clear and simple. The disadvantage is
	that meta-data changes are slow. An
	<command>rm -r</command>, for instance, touches all the
	files in a directory sequentially, but each directory change
	(deletion of a file) will be written synchronously to the
	disk. This includes updates to the directory itself, to the
	inode table, and possibly to indirect blocks allocated by
	the file. Similar considerations apply for unrolling large
	hierarchies (<command>tar -x</command>).</para>

	<para>The second case is asynchronous meta-data updates. This
	is the default for Linux/ext2fs and
	<command>mount -o async</command> for *BSD ufs. All
	meta-data updates are simply being passed through the buffer
	cache too, that is, they will be intermixed with the updates
	of the file content data. The advantage of this
	implementation is there is no need to wait until each
	meta-data update has been written to disk, so all operations
	which cause huge amounts of meta-data updates work much
	faster than in the synchronous case. Also, the
	implementation is still clear and simple, so there is a low
	risk for bugs creeping into the code. The disadvantage is
	that there is no guarantee at all for a consistent state of
	the filesystem. If there is a failure during an operation
	that updated large amounts of meta-data (like a power
	failure, or someone pressing the reset button), the
	filesystem will be left in an unpredictable state. There is
	no opportunity to examine the state of the filesystem when
	the system comes up again; the data blocks of a file could
	already have been written to the disk while the updates of
	the inode table or the associated directory were not. It is
	actually impossible to implement a <command>fsck</command>
	which is able to clean up the resulting chaos (because the
	necessary information is not available on the disk). If the
	filesystem has been damaged beyond repair, the only choice
	is to use &man.newfs.8; on it and restore it from
	backup.</para>

	<para>The usual solution for this problem was to implement
	<emphasis>dirty region logging</emphasis>, which is also
	referred to as <emphasis>journaling</emphasis>, although
	that term is not used consistently and is occasionally
	applied to other forms of transaction logging as well.
	Meta-data updates are still written synchronously, but only
	into a small region of the disk. Later on they will be
	moved to their proper location. Because the logging area is
	a small, contiguous region on the disk, there are no long
	distances for the disk heads to move, even during heavy
	operations, so these operations are quicker than synchronous
	updates. Additionally the complexity of the implementation
	is fairly limited, so the risk of bugs being present is low.
	A disadvantage is that all meta-data are written twice (once
	into the logging region and once to the proper location) so
	for normal work, a performance <quote>pessimization</quote>
	might result. On the other hand, in case of a crash, all
	pending meta-data operations can be quickly either
	rolled-back or completed from the logging area after the
	system comes up again, resulting in a fast filesystem
	startup.</para>

	<para>Kirk McKusick, the developer of Berkeley FFS, solved
	this problem with Soft Updates: all pending meta-data
	updates are kept in memory and written out to disk in a
	sorted sequence (<quote>ordered meta-data updates</quote>).
	This has the effect that, in case of heavy meta-data
	operations, later updates to an item <quote>catch</quote>
	the earlier ones if the earlier ones are still in memory and
	have not already been written to disk. So all operations
	on, say, a directory are generally performed in memory
	before the update is written to disk (the data blocks are
	sorted according to their position so that they will not be
	on the disk ahead of their meta-data). If the system
	crashes, this causes an implicit <quote>log rewind</quote>:
	all operations which did not find their way to the disk
	appear as if they had never happened. A consistent
	filesystem state is maintained that appears to be the one of
	30 to 60 seconds earlier. The algorithm used guarantees
	that all resources in use are marked as such in their
	appropriate bitmaps: blocks and inodes. After a crash, the
	only resource allocation error that occurs is that resources
	are marked as <quote>used</quote> which are actually
	<quote>free</quote>. &man.fsck.8; recognizes this situation,
	and frees the resources that are no longer used. It is safe
	to ignore the dirty state of the filesystem after a crash by
	forcibly mounting it with <command>mount -f</command>. In
	order to free resources that may be unused, &man.fsck.8;
	needs to be run at a later time. This is the idea behind
	the <emphasis>background fsck</emphasis>: at system startup
	time, only a <emphasis>snapshot</emphasis> of the filesystem
	is recorded. The <command>fsck</command> can be run later
	on. All file systems can then be mounted
	<quote>dirty</quote>, so the system startup proceeds in
	multiuser mode. Then, background <command>fsck</command>s
	will be scheduled for all file systems where this is
	required, to free resources that may be unused. (File
	systems that do not use Soft Updates still need the usual
	foreground <command>fsck</command> though.)</para>

	<para>The advantage is that meta-data operations are nearly
	as fast as asynchronous updates which are, faster than
	<emphasis>logging</emphasis>, which has to write the
	meta-data twice. The disadvantages are the complexity of
	the code (implying a higher risk for bugs in an area that is
	highly sensitive regarding loss of user data), and a higher
	memory consumption. Additionally there are some
	idiosyncrasies one has to get used to. After a crash, the
	state of the filesystem appears to be somewhat
	<quote>older</quote>. In situations where the standard
	synchronous approach would have caused some zero-length
	files to remain after the <command>fsck</command>, these
	files do not exist at all with a Soft Updates filesystem
	because neither the meta-data nor the file contents have
	ever been written to disk. Disk space is not released until
	the updates have been written to disk, which may take place
	some time after running <command>rm</command>. This may
	cause problems when installing large amounts of data on a
	filesystem that does not have enough free space to hold all
	the files twice.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="configtuning-kernel-limits">
	<title>Tuning Kernel Limits</title>

	<indexterm>
	<primary>tuning</primary>
	<secondary>kernel limits</secondary>
	</indexterm>

	<sect2 id="file-process-limits">
	<title>File/Process Limits</title>

	<sect3 id="kern-maxfiles">
	<title><varname>kern.maxfiles</varname></title>

	<indexterm>
	<primary><varname>kern.maxfiles</varname></primary>
	</indexterm>

	<para><varname>kern.maxfiles</varname> can be raised or
	lowered based upon system requirements. This variable
	indicates the maximum number of file descriptors on the
	system. When the file descriptor table is full,
	<errorname>file: table is full</errorname> will show up
	repeatedly in the system message buffer, which can be viewed
	using <command>dmesg</command>.</para>

	<para>Each open file, socket, or fifo uses one file
	descriptor. A large-scale production server may easily
	require many thousands of file descriptors, depending on the
	kind and number of services running concurrently.</para>

	<para>In older &os; releases, the default value of
	<varname>kern.maxfiles</varname> is derived from
	<option>maxusers</option> in the kernel configuration file.
	<varname>kern.maxfiles</varname> grows proportionally to the
	value of <option>maxusers</option>. When compiling a custom
	kernel, consider setting this kernel configuration option
	according to the use of the system. From this number, the
	kernel is given most of its pre-defined limits. Even though
	a production machine may not have 256 concurrent users, the
	resources needed may be similar to a high-scale web
	server.</para>

	<para>The variable <varname>kern.maxusers</varname> is
	automatically sized at boot based on the amount of memory
	available in the system, and may be determined at run-time
	by inspecting the value of the read-only
	<varname>kern.maxusers</varname> sysctl. Some sites will
	require larger or smaller values of
	<varname>kern.maxusers</varname> and may set it as a loader
	tunable; values of 64, 128, and 256 are not uncommon. Going
	above 256 is not recommended unless a huge number of file
	descriptors are needed. Many of the tunable values set to
	their defaults by <varname>kern.maxusers</varname> may be
	individually overridden at boot-time or run-time in
	<filename>/boot/loader.conf</filename>. Refer to
	&man.loader.conf.5; and
	<filename>/boot/defaults/loader.conf</filename> for more
	details and some hints.</para>

	<para>In older releases, the system will auto-tune
	<literal>maxusers</literal> if it is set to
	<literal>0</literal>
	<footnote><para>The auto-tuning algorithm sets
	<literal>maxusers</literal> equal to the amount of
	memory in the system, with a minimum of 32, and a
	maximum of 384.</para></footnote>. When setting this
	option, set <literal>maxusers</literal> to at least 4,
	especially if the system runs
	<application>Xorg</application> or is used to
	compile software. The most important table set by
	<literal>maxusers</literal> is the maximum number of
	processes, which is set to
	<literal>20 + 16 * maxusers</literal>. If
	<literal>maxusers</literal> is set to 1, there can only be
	36 simultaneous processes, including the 18 or so that the
	system starts up at boot time and the 15 or so used by
	<application>Xorg</application>. Even a simple task like
	reading a manual page will start up nine processes to
	filter, decompress, and view it. Setting
	<literal>maxusers</literal> to 64 allows up to 1044
	simultaneous processes, which should be enough for nearly
	all uses. If, however, you see the dreaded
	<errortype>proc table full</errortype> error when trying to
	start another program, or are running a server with a large
	number of simultaneous users (like
	<hostid role="fqdn">ftp.FreeBSD.org</hostid>), increase the
	number and rebuild.</para>

	<note>
	<para><literal>maxusers</literal> does
	<emphasis>not</emphasis> limit the number of users which
	can log into your machine. It simply sets various table
	sizes to reasonable values considering the maximum number
	of users on the system and how many processes each user
	will be running.</para>
	</note>
	</sect3>

	<sect3>
	<title><varname>kern.ipc.somaxconn</varname></title>

	<indexterm>
	<primary><varname>kern.ipc.somaxconn</varname></primary>
	</indexterm>

	<para>The <varname>kern.ipc.somaxconn</varname> sysctl
	variable limits the size of the listen queue for accepting
	new TCP connections. The default value of
	<literal>128</literal> is typically too low for robust
	handling of new connections in a heavily loaded web server
	environment. For such environments, it is recommended to
	increase this value to <literal>1024</literal> or higher.
	The service daemon may itself limit the listen queue size
	(e.g., &man.sendmail.8;, or
	<application>Apache</application>) but will often have a
	directive in its configuration file to adjust the queue
	size. Large listen queues also do a better job of avoiding
	Denial of Service (<abbrev>DoS</abbrev>) attacks.</para>
	</sect3>
	</sect2>

	<sect2 id="nmbclusters">
	<title>Network Limits</title>

	<para>The <literal>NMBCLUSTERS</literal> kernel configuration
	option dictates the amount of network Mbufs available to the
	system. A heavily-trafficked server with a low number of
	Mbufs will hinder &os;'s ability. Each cluster represents
	approximately 2 K of memory, so a value of 1024
	represents 2 megabytes of kernel memory reserved for network
	buffers. A simple calculation can be done to figure out how
	many are needed. A web server which maxes out at 1000
	simultaneous connections where each connection uses a
	6 K receive and 16 K send buffer, requires
	approximately 32 MB worth of network buffers to cover the
	web server. A good rule of thumb is to multiply by 2, so
	2x32 MB / 2 KB =
	64 MB / 2 kB = 32768. Values between
	4096 and 32768 are recommended for machines with greater
	amounts of memory. Under no circumstances should you specify
	an arbitrarily high value for this parameter as it could lead
	to a boot time crash. To observe network cluster usage, use
	<option>-m</option> with &man.netstat.1;.</para>

	<para>The <varname>kern.ipc.nmbclusters</varname> loader tunable
	should be used to tune this at boot time. Only older versions
	of &os; will require the use of the
	<literal>NMBCLUSTERS</literal> kernel &man.config.8;
	option.</para>

	<para>For busy servers that make extensive use of the
	&man.sendfile.2; system call, it may be necessary to increase
	the number of &man.sendfile.2; buffers via the
	<literal>NSFBUFS</literal> kernel configuration option or by
	setting its value in <filename>/boot/loader.conf</filename>
	(see &man.loader.8; for details). A common indicator that
	this parameter needs to be adjusted is when processes are seen
	in the <literal>sfbufa</literal> state. The sysctl variable
	<varname>kern.ipc.nsfbufs</varname> is a read-only glimpse at
	the kernel configured variable. This parameter nominally
	scales with <varname>kern.maxusers</varname>, however it may
	be necessary to tune accordingly.</para>

	<important>
	<para>Even though a socket has been marked as non-blocking,
	calling &man.sendfile.2; on the non-blocking socket may
	result in the &man.sendfile.2; call blocking until enough
	<literal>struct sf_buf</literal>'s are made
	available.</para>
	</important>

	<sect3>
	<title><varname>net.inet.ip.portrange.*</varname></title>

	<indexterm>
	<primary>net.inet.ip.portrange.*</primary>
	</indexterm>

	<para>The <varname>net.inet.ip.portrange.*</varname> sysctl
	variables control the port number ranges automatically bound
	to TCP and UDP sockets. There are three ranges: a low
	range, a default range, and a high range. Most network
	programs use the default range which is controlled by the
	<varname>net.inet.ip.portrange.first</varname> and
	<varname>net.inet.ip.portrange.last</varname>, which default
	to 1024 and 5000, respectively. Bound port ranges are used
	for outgoing connections, and it is possible to run the
	system out of ports under certain circumstances. This most
	commonly occurs when running a heavily loaded web proxy.
	The port range is not an issue when running servers which
	handle mainly incoming connections, such as a normal web
	server, or has a limited number of outgoing connections,
	such as a mail relay. For situations where there is a
	shortage of ports, it is recommended to increase
	<varname>net.inet.ip.portrange.last</varname> modestly. A
	value of <literal>10000</literal>, <literal>20000</literal>
	or <literal>30000</literal> may be reasonable. Consider
	firewall effects when changing the port range. Some
	firewalls may block large ranges of ports (usually
	low-numbered ports) and expect systems to use higher ranges
	of ports for outgoing connections — for this reason it
	is not recommended that
	<varname>net.inet.ip.portrange.first</varname> be
	lowered.</para>
	</sect3>

	<sect3>
	<title>TCP Bandwidth Delay Product</title>

	<indexterm>
	<primary>TCP Bandwidth Delay Product Limiting</primary>
	<secondary><varname>net.inet.tcp.inflight.enable</varname></secondary>
	</indexterm>

	<para>The TCP Bandwidth Delay Product Limiting is similar to
	TCP/Vegas in NetBSD. It can be enabled by setting
	<varname>net.inet.tcp.inflight.enable</varname> sysctl
	variable to <literal>1</literal>. The system will attempt
	to calculate the bandwidth delay product for each connection
	and limit the amount of data queued to the network to just
	the amount required to maintain optimum throughput.</para>

	<para>This feature is useful when serving data over modems,
	Gigabit Ethernet, or even high speed WAN links (or any other
	link with a high bandwidth delay product), especially when
	also using window scaling or when a large send window has
	been configured. When enabling this option, also be sure to
	set <varname>net.inet.tcp.inflight.debug</varname> to
	<literal>0</literal> (disable debugging), and for production
	use setting <varname>net.inet.tcp.inflight.min</varname> to
	at least <literal>6144</literal> may be beneficial.
	However, note that setting high minimums may effectively
	disable bandwidth limiting depending on the link. The
	limiting feature reduces the amount of data built up in
	intermediate route and switch packet queues and reduces the
	amount of data built up in the local host's interface queue.
	With fewer queued packets, interactive connections,
	especially over slow modems, will operate with lower
	<emphasis>Round Trip Times</emphasis>. This feature only
	effects server side data transmission such as uploading. It
	has no effect on data reception or downloading.</para>

	<para>Adjusting <varname>net.inet.tcp.inflight.stab</varname>
	is <emphasis>not</emphasis> recommended. This parameter
	defaults to 20, representing 2 maximal packets added to the
	bandwidth delay product window calculation. The additional
	window is required to stabilize the algorithm and improve
	responsiveness to changing conditions, but it can also
	result in higher ping times over slow links, though still
	much lower than without the inflight algorithm. In such
	cases, try reducing this parameter to 15, 10, or 5; and
	reducing <varname>net.inet.tcp.inflight.min</varname> (for
	example, to 3500) to get the desired effect. Reducing these
	parameters should be done as a last resort only.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Virtual Memory</title>

	<sect3>
	<title><varname>kern.maxvnodes</varname></title>

	<para>A vnode is the internal representation of a file or
	directory. So increasing the number of vnodes available to
	the operating system cuts down on disk I/O. Normally this
	is handled by the operating system and does not need to be
	changed. In some cases where disk I/O is a bottleneck and
	the system is running out of vnodes, this setting will need
	to be increased. The amount of inactive and free RAM will
	need to be taken into account.</para>

	<para>To see the current number of vnodes in use:</para>

	<screen>&prompt.root; <userinput>sysctl vfs.numvnodes</userinput>
	vfs.numvnodes: 91349</screen>

	<para>To see the maximum vnodes:</para>

	<screen>&prompt.root; <userinput>sysctl kern.maxvnodes</userinput>
	kern.maxvnodes: 100000</screen>

	<para>If the current vnode usage is near the maximum,
	increasing <varname>kern.maxvnodes</varname> by a value of
	1,000 is probably a good idea. Keep an eye on the number of
	<varname>vfs.numvnodes</varname>. If it climbs up to the
	maximum again, <varname>kern.maxvnodes</varname> will need
	to be increased further. A shift in your memory usage as
	reported by &man.top.1; should be visible. More memory
	should be active.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="adding-swap-space">
	<title>Adding Swap Space</title>

	<para>Despite careful planning, sometimes a system does not run
	as expected. If more swap space is needed, it is simple enough
	to add. There are three ways to increase swap space: add a new
	hard drive, enable swap over NFS, or create a swap file on an
	existing partition.</para>

	<para>For information on how to encrypt swap space, what options
	for this task exist and why it should be done, refer to
	<xref linkend="swap-encrypting"/> of the Handbook.</para>

	<sect2 id="new-drive-swap">
	<title>Swap on a New or Existing Hard Drive</title>

	<para>Adding a new hard drive for swap gives better performance
	than adding a partition on an existing drive. Setting up
	partitions and hard drives is explained in
	<xref linkend="disks-adding"/>.
	<xref linkend="configtuning-initial"/> discusses partition
	layouts and swap partition size considerations.</para>

	<para>Use &man.swapon.8; to add a swap partition to the system.
	For example:</para>

	<screen>&prompt.root; <userinput>swapon<replaceable> /dev/ada1s1b</replaceable></userinput></screen>

	<warning>

	<para>It is possible to use any partition not currently
	mounted, even if it already contains data. Using
	&man.swapon.8; on a partition that contains data will
	overwrite and destroy that data. Make sure that the
	partition to be added as swap is really the intended
	partition before running &man.swapon.8;.</para>
	</warning>

	<para>To automatically add this swap partition on boot, add an
	entry to <filename>/etc/fstab</filename> for the
	partition:</para>

	<programlisting><replaceable>/dev/ada1s1b</replaceable> none swap sw 0 0</programlisting>

	<para>See &man.fstab.5; for an explanation of the entries in
	<filename>/etc/fstab</filename>.</para>
	</sect2>

	<sect2 id="nfs-swap">
	<title>Swapping over NFS</title>

	<para>Swapping over NFS is only recommended if you do not have a
	local hard disk to swap to; NFS swapping will be limited by
	the available network bandwidth and puts an additional burden
	on the NFS server.</para>
	</sect2>

	<sect2 id="create-swapfile">
	<title>Swapfiles</title>

	<para>You can create a file of a specified size to use as a swap
	file. The following example will create a 64MB file named
	<filename>/usr/swap0</filename>.</para>

	<example>
	<title>Creating a Swapfile on &os;</title>

	<orderedlist>
	<listitem>

	<para>The <filename>GENERIC</filename> kernel already
	includes the memory disk driver (&man.md.4;) required
	for this operation. When building a custom kernel, make
	sure to include the following line in the custom
	configuration file:</para>

	<programlisting>device md</programlisting>

	<para>For information on building a custom kernel, refer
	to <xref linkend="kernelconfig"/>.</para>
	</listitem>

	<listitem>
	<para>Create a swapfile
	(<filename>/usr/swap0</filename>):</para>

	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/usr/swap0 bs=1024k count=64</userinput></screen>
	</listitem>

	<listitem>
	<para>Set proper permissions on
	(<filename>/usr/swap0</filename>):</para>

	<screen>&prompt.root; <userinput>chmod 0600 /usr/swap0</userinput></screen>
	</listitem>

	<listitem>
	<para>Enable the swap file in
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired.</programlisting>
	</listitem>

	<listitem>
	<para>Reboot the machine or to enable the swap file
	immediately, type:</para>

	<screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /usr/swap0 -u 0 && swapon /dev/md0</userinput></screen>
	</listitem>
	</orderedlist>
	</example>
	</sect2>
	</sect1>

	<sect1 id="acpi-overview">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Hiten</firstname>
	<surname>Pandya</surname>
	<contrib>Written by </contrib>
	</author>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	</author>
	</authorgroup>
	</sect1info>

	<title>Power and Resource Management</title>

	<para>It is important to utilize hardware resources in an
	efficient manner. Before the Advanced Configuration and Power
	Interface (<acronym>ACPI</acronym>) was introduced, it was
	difficult and inflexible for operating systems to manage the
	power usage and thermal properties of a system. The hardware
	was managed by the <acronym>BIOS</acronym> and the user had less
	control and visibility into the power management settings. Some
	limited configurability was available via <emphasis>Advanced
	Power Management (APM)</emphasis>. Power and resource
	management is one of the key components of a modern operating
	system. It allows the operating system to monitor system
	limits and to possibly provide an alert if the system
	temperature increases unexpectedly.</para>

	<para>This section provides comprehensive information about
	<acronym>ACPI</acronym>. References will be provided for further
	reading.</para>

	<sect2 id="acpi-intro">
	<title>What Is ACPI?</title>

	<indexterm>
	<primary>ACPI</primary>
	</indexterm>

	<indexterm>
	<primary>APM</primary>
	</indexterm>

	<para><acronym>ACPI</acronym> is a standard written by an
	alliance of vendors to provide a standard interface for
	hardware resources and power management. It is a key
	element in <emphasis>Operating System-directed configuration
	and Power Management</emphasis> as it provides more control
	and flexibility to the operating system. Modern systems
	<quote>stretched</quote> the limits of the current Plug and
	Play interfaces prior to the introduction of
	<acronym>ACPI</acronym>. <acronym>ACPI</acronym> is the
	direct successor to <acronym>APM</acronym>.</para>
	</sect2>

	<sect2 id="acpi-old-spec">
	<title>Shortcomings of Advanced Power Management (APM)</title>

	<para>The <acronym>APM</acronym> facility controls the power
	usage of a system based on its activity. The APM BIOS is
	supplied by the (system) vendor and is specific to the
	hardware platform. An APM driver in the operating system
	mediates access to the <emphasis>APM Software
	Interface</emphasis>, which allows management of power
	levels. APM should still be used for systems manufactured at
	or before the year 2000.</para>

	<para>There are four major problems in APM. Firstly, power
	management is done by the (vendor-specific) BIOS, and the OS
	does not have any knowledge of it. One example of this, is
	when the user sets idle-time values for a hard drive in the
	APM BIOS, that when exceeded, it (BIOS) would spin down the
	hard drive, without the consent of the OS. Secondly, the APM
	logic is embedded in the BIOS, and it operates outside the
	scope of the OS. This means users can only fix problems in
	their APM BIOS by flashing a new one into the ROM; which is a
	very dangerous procedure with the potential to leave the
	system in an unrecoverable state if it fails. Thirdly, APM is
	a vendor-specific technology, which means that there is a lot
	of parity (duplication of efforts) and bugs found in one
	vendor's BIOS, may not be solved in others. Last but not the
	least, the APM BIOS did not have enough room to implement a
	sophisticated power policy, or one that can adapt very well to
	the purpose of the machine.</para>

	<para><emphasis>Plug and Play BIOS (PNPBIOS)</emphasis> was
	unreliable in many situations. PNPBIOS is 16-bit technology,
	so the OS has to use 16-bit emulation in order to
	<quote>interface</quote> with PNPBIOS methods.</para>

	<para>The &os; <acronym>APM</acronym> driver is documented in
	the &man.apm.4; manual page.</para>
	</sect2>

	<sect2 id="acpi-config">
	<title>Configuring <acronym>ACPI</acronym></title>

	<para>The <filename>acpi.ko</filename> driver is loaded by
	default at start up by the &man.loader.8; and should
	<emphasis>not</emphasis> be compiled into the kernel. The
	reasoning behind this is that modules are easier to work with,
	say if switching to another <filename>acpi.ko</filename>
	without doing a kernel rebuild. This has the advantage of
	making testing easier. Another reason is that starting
	<acronym>ACPI</acronym> after a system has been brought up
	often does not work well. If you are experiencing problems,
	<acronym>ACPI</acronym> can be disabled altogether. This
	driver should not and can not be unloaded because the system
	bus uses it for various hardware interactions.
	<acronym>ACPI</acronym> can be disabled by setting
	<literal>hint.acpi.0.disabled="1"</literal> in
	<filename>/boot/loader.conf</filename> or at the
	&man.loader.8; prompt.</para>

	<note>
	<para><acronym>ACPI</acronym> and <acronym>APM</acronym>
	cannot coexist and should be used separately. The last one
	to load will terminate if the driver notices the other
	running.</para>
	</note>

	<para><acronym>ACPI</acronym> can be used to put the system into
	a sleep mode with &man.acpiconf.8;, the <option>-s</option>
	flag, and a <literal>1-5</literal> option. Most users will
	only need <literal>1</literal> or <literal>3</literal>
	(suspend to RAM). Option <literal>5</literal> will do a
	soft-off which is the same action as:</para>

	<screen>&prompt.root; <userinput>halt -p</userinput></screen>

	<para>Other options are available via &man.sysctl.8;. Check out
	the &man.acpi.4; and &man.acpiconf.8; manual pages for more
	information.</para>
	</sect2>
	</sect1>

	<sect1 id="ACPI-debug">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Nate</firstname>
	<surname>Lawson</surname>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Peter</firstname>
	<surname>Schultz</surname>
	<contrib>With contributions from </contrib>
	</author>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	</author>
	</authorgroup>
	</sect1info>

	<title>Using and Debugging &os; <acronym>ACPI</acronym></title>

	<indexterm>
	<primary>ACPI</primary>
	<secondary>problems</secondary>
	</indexterm>

	<para><acronym>ACPI</acronym> is a fundamentally new way of
	discovering devices, managing power usage, and providing
	standardized access to various hardware previously managed by
	the <acronym>BIOS</acronym>. Progress is being made toward
	<acronym>ACPI</acronym> working on all systems, but bugs in some
	motherboards' <firstterm><acronym>ACPI</acronym> Machine
	Language</firstterm> (<acronym>AML</acronym>) bytecode,
	incompleteness in &os;'s kernel subsystems, and bugs in the
	&intel; <acronym>ACPI-CA</acronym> interpreter continue to
	appear.</para>

	<para>This section is intended to help users assist the &os;
	<acronym>ACPI</acronym> maintainers in identifying the root
	cause of problems you observe and debugging and developing a
	solution.</para>

	<sect2 id="ACPI-submitdebug">
	<title>Submitting Debugging Information</title>

	<note>
	<para>Before submitting a problem, be sure you are running the
	latest <acronym>BIOS</acronym> version and, if available,
	embedded controller firmware version.</para>
	</note>

	<para>When submitting a problem, send the following information
	to <ulink url="mailto:freebsd-acpi@FreeBSD.org">
	freebsd-acpi@FreeBSD.org</ulink>:</para>

	<itemizedlist>
	<listitem>
	<para>Description of the buggy behavior, including system
	type and model and anything that causes the bug to appear.
	Note as accurately as possible when the bug began
	occurring if it is new.</para>
	</listitem>

	<listitem>
	<para>The &man.dmesg.8; output after
	<command>boot -v</command>, including any error messages
	generated by the bug.</para>
	</listitem>

	<listitem>
	<para>The &man.dmesg.8; output from
	<command>boot -v</command> with <acronym>ACPI</acronym>
	disabled, if disabling it helps fix the problem.</para>
	</listitem>

	<listitem>
	<para>Output from <command>sysctl hw.acpi</command>. This
	is also a good way of figuring out what features the
	system offers.</para>
	</listitem>

	<listitem>
	<para><acronym>URL</acronym> where the
	<firstterm><acronym>ACPI</acronym> Source
	Language</firstterm> (<acronym>ASL</acronym>) can be
	found. Do <emphasis>not</emphasis> send the
	<acronym>ASL</acronym> directly to the list as it can be
	very large. Generate a copy of the
	<acronym>ASL</acronym> by running this command:</para>

	<screen>&prompt.root; <userinput>acpidump -dt > <replaceable>name</replaceable>-<replaceable>system</replaceable>.asl</userinput></screen>

	<para>(Substitute your login name for
	<replaceable>name</replaceable> and manufacturer/model for
	<replaceable>system</replaceable>. Example:
	<filename>njl-FooCo6000.asl</filename>)</para>
	</listitem>
	</itemizedlist>

	<para>Most &os; developers watch &a.current;, but one should
	submit problems to &a.acpi.name; to be sure it is
	seen. Be patient when waiting for a response. If the bug is
	not immediately apparent, you may be asked to submit a
	<acronym>PR</acronym> using &man.send-pr.1;. When entering a
	<acronym>PR</acronym>, include the same information as
	requested above. This helps developers to track the problem
	and resolve it. Do not send a <acronym>PR</acronym> without
	emailing &a.acpi.name; first as it is likely that the problem
	has been reported before.</para>
	</sect2>

	<sect2 id="ACPI-background">
	<title>Background</title>

	<indexterm>
	<primary>ACPI</primary>
	</indexterm>

	<para><acronym>ACPI</acronym> is present in all modern computers
	that conform to the ia32 (x86), ia64 (Itanium), and amd64
	(AMD) architectures. The full standard has many features
	including <acronym>CPU</acronym> performance management, power
	planes control, thermal zones, various battery systems,
	embedded controllers, and bus enumeration. Most systems
	implement less than the full standard. For instance, a
	desktop system usually only implements the bus enumeration
	parts while a laptop might have cooling and battery management
	support as well. Laptops also have suspend and resume, with
	their own associated complexity.</para>

	<para>An <acronym>ACPI</acronym>-compliant system has various
	components. The <acronym>BIOS</acronym> and chipset vendors
	provide various fixed tables (e.g., <acronym>FADT</acronym>)
	in memory that specify things like the <acronym>APIC</acronym>
	map (used for <acronym>SMP</acronym>), config registers, and
	simple configuration values. Additionally, a table of
	bytecode (the <firstterm>Differentiated System Description
	Table</firstterm> <acronym>DSDT</acronym>) is provided that
	specifies a tree-like name space of devices and
	methods.</para>

	<para>The <acronym>ACPI</acronym> driver must parse the fixed
	tables, implement an interpreter for the bytecode, and modify
	device drivers and the kernel to accept information from the
	<acronym>ACPI</acronym> subsystem. For &os;, &intel; has
	provided an interpreter (<acronym>ACPI-CA</acronym>) that is
	shared with Linux and NetBSD. The path to the
	<acronym>ACPI-CA</acronym> source code is <filename
	class="directory">src/sys/contrib/dev/acpica</filename>.
	The glue code that allows <acronym>ACPI-CA</acronym> to work
	on &os; is in
	<filename class="directory">src/sys/dev/acpica/Osd</filename>.
	Finally, drivers that implement various
	<acronym>ACPI</acronym> devices are found in <filename
	class="directory">src/sys/dev/acpica</filename>.</para>
	</sect2>

	<sect2 id="ACPI-comprob">
	<title>Common Problems</title>

	<indexterm>
	<primary>ACPI</primary>
	<secondary>problems</secondary>
	</indexterm>

	<para>For <acronym>ACPI</acronym> to work correctly, all the
	parts have to work correctly. Here are some common problems,
	in order of frequency of appearance, and some possible
	workarounds or fixes.</para>

	<sect3>
	<title>Mouse Issues</title>

	<para>In some cases, resuming from a suspend operation will
	cause the mouse to fail. A known work around is to add
	<literal>hint.psm.0.flags="0x3000"</literal> to
	<filename>/boot/loader.conf</filename>. If this does
	not work, consider sending a bug report using
	&man.send-pr.1;.</para>
	</sect3>

	<sect3>
	<title>Suspend/Resume</title>

	<para><acronym>ACPI</acronym> has three suspend to
	<acronym>RAM</acronym> (<acronym>STR</acronym>) states,
	<literal>S1</literal>-<literal>S3</literal>, and one suspend
	to disk state (<literal>STD</literal>), called
	<literal>S4</literal>. <literal>S5</literal> is
	<quote>soft off</quote> and is the normal state the system
	is in when plugged in but not powered up.
	<literal>S4</literal> can actually be implemented two
	separate ways. <literal>S4</literal><acronym>BIOS</acronym>
	is a <acronym>BIOS</acronym>-assisted suspend to disk.
	<literal>S4</literal><acronym>OS</acronym> is implemented
	entirely by the operating system.</para>

	<para>Start by checking <command>sysctl hw.acpi</command>
	for the suspend-related items. Here are the results for a
	Thinkpad:</para>

	<screen>hw.acpi.supported_sleep_state: S3 S4 S5
	hw.acpi.s4bios: 0</screen>

	<para>Use <command>acpiconf -s</command> to test
	<literal>S3</literal>,
	<literal>S4</literal><acronym>OS</acronym>, and
	<literal>S5</literal>. An <option>s4bios</option> of one
	(<literal>1</literal>), indicates
	<literal>S4</literal><acronym>BIOS</acronym> support instead
	of <literal>S4</literal> <acronym>OS</acronym>.</para>

	<para>When testing suspend/resume, start with
	<literal>S1</literal>, if supported. This state is most
	likely to work since it does not require much driver
	support. No one has implemented <literal>S2</literal> which
	is similar to <literal>S1</literal>. The next thing to try
	is <literal>S3</literal>. This is the deepest
	<acronym>STR</acronym> state and requires a lot of driver
	support to properly reinitialize the hardware. If you have
	problems resuming, feel free to email &a.acpi.name;, but do
	not expect the problem to be resolved since there are a lot
	of drivers and hardware that need more testing and
	work.</para>

	<para>A common problem with suspend/resume is that many device
	drivers do not save, restore, or reinitialize their
	firmware, registers, or device memory properly. As a first
	attempt at debugging the problem, try:</para>

	<screen>&prompt.root; <userinput>sysctl debug.bootverbose=1</userinput>
	&prompt.root; <userinput>sysctl debug.acpi.suspend_bounce=1</userinput>
	&prompt.root; <userinput>acpiconf -s 3</userinput></screen>

	<para>This test emulates suspend/resume cycle of all device
	drivers without actually going into <literal>S3</literal>
	state. In some cases, problems such as losing firmware
	state, device watchdog time out, and retrying forever, can
	be captured with this method. Note that the system will
	not really enter <literal>S3</literal> state, which means
	devices may not lose power, and many will work fine even if
	suspend/resume methods are totally missing, unlike real
	<literal>S3</literal> state.</para>

	<para>Harder cases require additional hardware, such as a
	serial port/cable for serial console or a Firewire
	port/cable for &man.dcons.4;, and kernel debugging
	skills.</para>

	<para>To help isolate the problem, remove as many drivers from
	the kernel as possible. If it works, narrow down which
	driver is the problem by loading drivers until it fails
	again. Typically binary drivers like
	<filename>nvidia.ko</filename>, display drivers, and
	<acronym>USB</acronym> will have the most problems while
	Ethernet interfaces usually work fine. If you can properly
	load/unload the drivers, automate this by putting the
	appropriate commands in
	<filename>/etc/rc.suspend</filename> and
	<filename>/etc/rc.resume</filename>. There is a
	commented-out example for unloading and loading a driver.
	Try setting <option>hw.acpi.reset_video</option> to zero
	(<literal>0</literal>) if the display is messed up after
	resume. Try setting longer or shorter values for
	<option>hw.acpi.sleep_delay</option> to see if that
	helps.</para>

	<para>Another thing to try is load a recent Linux distribution
	with <acronym>ACPI</acronym> support and test their
	suspend/resume support on the same hardware. If it works on
	Linux, it is likely a &os; driver problem and narrowing down
	which driver causes the problems will help us fix the
	problem. Note that the <acronym>ACPI</acronym> maintainers
	do not usually maintain other drivers, such as sound or
	<acronym>ATA</acronym>, so any work done on tracking
	down a driver problem should probably eventually be posted
	to the &a.current.name; list and mailed to the driver
	maintainer. Advanced users can start by putting some
	debugging &man.printf.3;s in a problematic driver to track
	down where in its resume function it hangs.</para>

	<para>Finally, try disabling <acronym>ACPI</acronym> and
	enabling <acronym>APM</acronym> instead. If suspend/resume
	works with <acronym>APM</acronym>, you may be better off
	sticking with <acronym>APM</acronym>, especially on older
	hardware (pre-2000). It took vendors a while to get
	<acronym>ACPI</acronym> support correct and older hardware
	is more likely to have <acronym>BIOS</acronym> problems with
	<acronym>ACPI</acronym>.</para>
	</sect3>

	<sect3>
	<title>System Hangs (Temporary or Permanent)</title>

	<para>Most system hangs are a result of lost interrupts or an
	interrupt storm. Chipsets have a lot of problems based on
	how the <acronym>BIOS</acronym> configures interrupts before
	boot, correctness of the <acronym>APIC</acronym>
	(<acronym>MADT</acronym>) table, and routing of the
	<firstterm>System Control Interrupt</firstterm>
	(<acronym>SCI</acronym>).</para>

	<indexterm>
	<primary>interrupt storms</primary>
	</indexterm>

	<para>Interrupt storms can be distinguished from lost
	interrupts by checking the output of

	<command>vmstat -i</command> and looking at the line that
	has <literal>acpi0</literal>. If the counter is increasing
	at more than a couple per second, there is an interrupt
	storm. If the system appears hung, try breaking to
	<acronym>DDB</acronym> (<keycombo action="simul">
	<keycap>CTRL</keycap>
	<keycap>ALT</keycap>
	<keycap>ESC</keycap>
	</keycombo> on console) and type
	<literal>show interrupts</literal>.</para>

	<indexterm>
	<primary>APIC</primary>
	<secondary>disabling</secondary>
	</indexterm>

	<para>When dealing with interrupt problems try disabling
	<acronym>APIC</acronym> support with
	<literal>hint.apic.0.disabled="1"</literal> in
	<filename>loader.conf</filename>.</para>
	</sect3>

	<sect3>
	<title>Panics</title>

	<para>Panics are relatively rare for <acronym>ACPI</acronym>
	and are the top priority to be fixed. The first step is to
	isolate the steps to reproduce the panic (if possible) and
	get a backtrace. Follow the advice for enabling
	<literal>options DDB</literal> and setting up a serial
	console (see <xref linkend="serialconsole-ddb"/>) or setting
	up a &man.dump.8; partition. To get a backtrace in
	<acronym>DDB</acronym>, use <literal>tr</literal>. When
	handwriting the backtrace, get at least the lowest five (5)
	and top five (5) lines in the trace.</para>

	<para>Then, try to isolate the problem by booting with
	<acronym>ACPI</acronym> disabled. If that works, isolate
	the <acronym>ACPI</acronym> subsystem by using various
	values of <option>debug.acpi.disable</option>. See
	&man.acpi.4; for some examples.</para>
	</sect3>

	<sect3>
	<title>System Powers Up After Suspend or Shutdown</title>

	<para>First, try setting
	<literal>hw.acpi.disable_on_poweroff="0"</literal>
	in &man.loader.conf.5;. This keeps <acronym>ACPI</acronym>
	from disabling various events during the shutdown process.
	Some systems need this value set to <literal>1</literal>
	(the default) for the same reason. This usually fixes the
	problem of a system powering up spontaneously after a
	suspend or poweroff.</para>
	</sect3>

	<sect3>
	<title>Other Problems</title>

	<para>For other problems with <acronym>ACPI</acronym> such as
	it not working with a docking station or devices not being
	detected, email a description to the mailing list. Some
	issues may be related to unfinished parts of the
	<acronym>ACPI</acronym> subsystem which might take a while
	to be implemented. Be patient and prepared to test
	patches.</para>
	</sect3>
	</sect2>

	<sect2 id="ACPI-aslanddump">
	<title><acronym>ASL</acronym>, <command>acpidump</command>, and
	<acronym>IASL</acronym></title>

	<indexterm>
	<primary>ACPI</primary>
	<secondary>ASL</secondary>
	</indexterm>

	<para>The most common problem is the <acronym>BIOS</acronym>
	vendors providing incorrect (or outright buggy!) bytecode.
	This is usually manifested by kernel console messages like
	this:</para>

	<screen>ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\
	(Node 0xc3f6d160), AE_NOT_FOUND</screen>

	<para>Often, these problems may be resolved by updating the
	<acronym>BIOS</acronym> to the latest revision. Most console
	messages are harmless but if when there are other problems
	like the battery status is not working, these messages are a
	good place to start looking for problems in the
	<acronym>AML</acronym>. The bytecode, known as
	<acronym>AML</acronym>, is compiled from a source language
	called <acronym>ASL</acronym>. The <acronym>AML</acronym> is
	found in the table known as the <acronym>DSDT</acronym>. To
	get a copy of the system's <acronym>ASL</acronym>, use
	&man.acpidump.8;. Include both <option>-t</option>, to
	show the contents of the fixed tables, and
	<option>-d</option>, to disassemble the
	<acronym>AML</acronym>. Refer to <link
	linkend="ACPI-submitdebug">Submitting Debugging
	Information</link> for an example syntax.</para>

	<para>The simplest first check is to recompile the
	<acronym>ASL</acronym> to check for errors. Warnings can
	usually be ignored, but errors are bugs that will usually
	prevent <acronym>ACPI</acronym> from working correctly. To
	recompile the <acronym>ASL</acronym>, issue the following
	command:</para>

	<screen>&prompt.root; <userinput>iasl your.asl</userinput></screen>
	</sect2>

	<sect2 id="ACPI-fixasl">
	<title>Fixing Your <acronym>ASL</acronym></title>

	<indexterm>
	<primary>ACPI</primary>
	<secondary>ASL</secondary>
	</indexterm>

	<para>In the long run, the goal of &os; is for almost everyone
	to have working <acronym>ACPI</acronym> without any user
	intervention. At this point, workarounds are still being
	developed for common mistakes made by the
	<acronym>BIOS</acronym> vendors. The &microsoft; interpreter
	(<filename>acpi.sys</filename> and
	<filename>acpiec.sys</filename>) does not strictly check for
	adherence to the standard, and thus many
	<acronym>BIOS</acronym> vendors who only test
	<acronym>ACPI</acronym> under &windows; never fix their
	<acronym>ASL</acronym>. &os; developers continue to identify
	and document exactly what non-standard behavior is allowed by
	&microsoft;'s interpreter and replicate it so &os; can work
	without forcing users to fix the <acronym>ASL</acronym>. As a
	workaround, and to help identify behavior, fix the
	<acronym>ASL</acronym> manually. If this works, send a
	&man.diff.1; of the old and new <acronym>ASL</acronym> so
	developers can possibly work around the buggy behavior in
	<acronym>ACPI-CA</acronym> and thus make the unnecessary
	fix.</para>

	<indexterm>
	<primary>ACPI</primary>
	<secondary>error messages</secondary>
	</indexterm>

	<para>Here is a list of common error messages, their cause, and
	how to fix them:</para>

	<sect3>
	<title>_OS Dependencies</title>

	<para>Some <acronym>AML</acronym> assumes the world consists
	of various &windows; versions. You can tell &os; to claim
	it is any <acronym>OS</acronym> to see if this fixes
	problems you may have. An easy way to override this is to
	set <literal>hw.acpi.osname="Windows 2001"</literal> in
	<filename>/boot/loader.conf</filename> or other similar
	strings you find in the <acronym>ASL</acronym>.</para>
	</sect3>

	<sect3>
	<title>Missing Return Statements</title>

	<para>Some methods do not explicitly return a value as the
	standard requires. While <acronym>ACPI-CA</acronym>
	does not handle this, &os; has a workaround that allows it
	to return the value implicitly. Explicit Return statements
	can be added where required if you know what value should be
	returned. To force <command>iasl</command> to compile the
	<acronym>ASL</acronym>, use the <option>-f</option>
	flag.</para>
	</sect3>

	<sect3>
	<title>Overriding the Default <acronym>AML</acronym></title>

	<para>After customizing <filename>your.asl</filename>, compile
	it with this command:</para>

	<screen>&prompt.root; <userinput>iasl your.asl</userinput></screen>

	<para>Adding the <option>-f</option> flag will force creation
	of the <acronym>AML</acronym>, even if there are errors
	during compilation. Some errors, such as missing Return
	statements, are automatically worked around by the
	interpreter.</para>

	<para><filename>DSDT.aml</filename> is the default output
	filename for <command>iasl</command>. Load this file
	instead of the <acronym>BIOS</acronym>'s buggy copy, which
	is still present in flash memory, by editing
	<filename>/boot/loader.conf</filename> as
	follows:</para>

	<programlisting>acpi_dsdt_load="YES"
	acpi_dsdt_name="/boot/DSDT.aml"</programlisting>

	<para>Be sure to copy <filename>DSDT.aml</filename> to
	<filename class="directory">/boot</filename>.</para>
	</sect3>
	</sect2>

	<sect2 id="ACPI-debugoutput">
	<title>Getting Debugging Output from
	<acronym>ACPI</acronym></title>

	<indexterm>
	<primary>ACPI</primary>
	<secondary>problems</secondary>
	</indexterm>

	<indexterm>
	<primary>ACPI</primary>
	<secondary>debugging</secondary>
	</indexterm>

	<para>The <acronym>ACPI</acronym> driver has a very flexible
	debugging facility. A set of subsystems and the level of
	verbosity can be specified. The subsystems to debug are
	specified as <quote>layers</quote> and are broken down into
	<acronym>ACPI-CA</acronym> components (ACPI_ALL_COMPONENTS)
	and <acronym>ACPI</acronym> hardware support
	(ACPI_ALL_DRIVERS). The verbosity of debugging output is
	specified as the <quote>level</quote> and ranges from
	ACPI_LV_ERROR (just report errors) to ACPI_LV_VERBOSE
	(everything). The <quote>level</quote> is a bitmask so
	multiple options can be set at once, separated by spaces. In
	practice, a serial console should be used to log the output if
	it is so long it flushes the console message buffer. A full
	list of the individual layers and levels is found in
	&man.acpi.4;.</para>

	<para>Debugging output is not enabled by default. To enable it,
	add <literal>options ACPI_DEBUG</literal> to the kernel
	configuration file if <acronym>ACPI</acronym> is compiled into
	the kernel. Add <literal>ACPI_DEBUG=1</literal> to
	<filename>/etc/make.conf</filename> to enable it
	globally. If it is a module, recompile just the
	<filename>acpi.ko</filename> module as follows:</para>

	<screen>&prompt.root; <userinput>cd /sys/modules/acpi/acpi
	&& make clean &&
	make ACPI_DEBUG=1</userinput></screen>

	<para>Install <filename>acpi.ko</filename> in
	<filename class="directory">/boot/kernel</filename> and add
	the desired level and layer to
	<filename>loader.conf</filename>. This example enables debug
	messages for all <acronym>ACPI-CA</acronym> components and all
	<acronym>ACPI</acronym> hardware drivers such as
	(<acronym>CPU</acronym> and <acronym>LID</acronym>. It only
	outputs error messages at the least verbose level.</para>

	<programlisting>debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS"
	debug.acpi.level="ACPI_LV_ERROR"</programlisting>

	<para>If the required information is triggered by a specific
	event, such as a suspend and then resume, leave out changes to
	<filename>loader.conf</filename> and instead use
	<command>sysctl</command> to specify the layer and level after
	booting and preparing the system for the specific event. The
	<command>sysctl</command>s are named the same as the tunables
	in <filename>loader.conf</filename>.</para>
	</sect2>

	<sect2 id="ACPI-References">
	<title>References</title>

	<para>More information about <acronym>ACPI</acronym> may be
	found in the following locations:</para>

	<itemizedlist>
	<listitem>
	<para>The &a.acpi;</para>
	</listitem>

	<listitem>
	<para>The <acronym>ACPI</acronym> Mailing List Archives
	<ulink
	url="http://lists.freebsd.org/pipermail/freebsd-acpi/"></ulink></para>
	</listitem>

	<listitem>
	<para>The old <acronym>ACPI</acronym> Mailing List Archives
	<ulink
	url="http://home.jp.FreeBSD.org/mail-list/acpi-jp/"></ulink></para>
	</listitem>

	<listitem>
	<para>The <acronym>ACPI</acronym> 2.0 Specification
	<ulink url="http://acpi.info/spec.htm"></ulink></para>
	</listitem>

	<listitem>
	<para>&os; Manual pages: &man.acpi.4;,
	&man.acpi.thermal.4;, &man.acpidump.8;, &man.iasl.8;,
	&man.acpidb.8;</para>
	</listitem>

	<listitem>
	<para><ulink
	url="http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt">
	<acronym>DSDT</acronym> debugging resource</ulink>.
	(Uses Compaq as an example but generally useful.)</para>
	</listitem>
	</itemizedlist>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml (revision 41355)
	@@ -1,3396 +1,3213 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="updating-upgrading">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Jim</firstname>
	<surname>Mock</surname>
	<contrib>Restructured, reorganized, and parts updated
	by </contrib>
	</author>
	<!-- Mar 2000 -->
	</authorgroup>

	<authorgroup>
	<author>
	<firstname>Jordan</firstname>
	<surname>Hubbard</surname>
	<contrib>Original work by </contrib>
	</author>

	<author>
	<firstname>Poul-Henning</firstname>
	<surname>Kamp</surname>
	</author>

	<author>
	<firstname>John</firstname>
	<surname>Polstra</surname>
	</author>

	<author>
	<firstname>Nik</firstname>
	<surname>Clayton</surname>
	</author>
	</authorgroup>
	<!-- with feedback from various others -->
	</chapterinfo>

	<title>Updating and Upgrading &os;</title>

	<sect1 id="updating-upgrading-synopsis">
	<title>Synopsis</title>

	<para>&os; is under constant development between releases. Some
	people prefer to use the officially released versions, while
	others prefer to keep in sync with the latest developments.
	However, even official releases are often updated with security
	and other critical fixes. Regardless of the version used, &os;
	- provides all necessary tools to keep your system updated, and
	- also allows for easy upgrades between versions. This chapter
	- will help you decide if you want to track the development
	- system, or stick with one of the released versions. The basic
	- tools for keeping your system up to date are also
	- presented.</para>
	+ provides all the necessary tools to keep the system updated, and
	+ allows for easy upgrades between versions. This chapter
	+ describes how to track the development system and the basic
	+ tools for keeping a &os; system up-to-date.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	- <para>What utilities may be used to update the system and
	+ <para>Which utilities are available to update the system and
	the Ports Collection.</para>
	</listitem>

	<listitem>
	- <para>How to keep your system up to date with
	+ <para>How to keep a &os; system up-to-date with
	<application>freebsd-update</application>,
	<application>Subversion</application>, or
	<application>CTM</application>.</para>
	</listitem>

	<listitem>
	<para>How to compare the state of an installed system against
	a known pristine copy.</para>
	</listitem>

	<listitem>
	- <para>How to keep your documentation up to date with
	+ <para>How to keep the installed documentation up-to-date with
	<application>Subversion</application> or documentation
	ports<!--, and <application>Docsnap</application>-->.</para>
	</listitem>

	<listitem>
	<para>The difference between the two development
	branches: &os.stable; and &os.current;.</para>
	</listitem>

	<listitem>
	<para>How to rebuild and reinstall the entire base
	- system with <command>make buildworld</command> (etc).</para>
	+ system.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	- <para>Properly set up your network connection (<xref
	+ <para>Properly set up the network connection (<xref
	linkend="advanced-networking"/>).</para>
	</listitem>

	<listitem>
	<para>Know how to install additional third-party
	software (<xref linkend="ports"/>).</para>
	</listitem>
	</itemizedlist>

	<note>
	- <para>Throughout this chapter, the <command>svn</command>
	- command is used to obtain and update &os; sources. To use it,
	- you will need to install the port or the package for <filename
	- role="package">devel/subversion</filename>.</para>
	+ <para>Throughout this chapter, <command>svn</command> is used to
	+ obtain and update &os; sources. To use it, first install the
	+ <filename role="package">devel/subversion</filename> port or
	+ package.</para>
	</note>
	</sect1>

	<sect1 id="updating-upgrading-freebsdupdate">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Colin</firstname>
	<surname>Percival</surname>
	<contrib>Based on notes provided by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	- <title>FreeBSD Update</title>
	+ <title>&os; Update</title>

	<indexterm><primary>Updating and Upgrading</primary></indexterm>
	<indexterm>
	<primary>freebsd-update</primary>
	<see>updating-upgrading</see>
	</indexterm>

	<para>Applying security patches is an important part of
	maintaining computer software, especially the operating system.
	- For the longest time on &os; this process was not an easy one.
	+ For the longest time on &os;, this process was not an easy one.
	Patches had to be applied to the source code, the code rebuilt
	into binaries, and then the binaries had to be
	re-installed.</para>

	<para>This is no longer the case as &os; now includes a utility
	- simply called <command>freebsd-update</command>. This utility
	+ called <command>freebsd-update</command>. This utility
	provides two separate functions. First, it allows for binary
	security and errata updates to be applied to the &os; base
	system without the build and install requirements. Second, the
	utility supports minor and major release upgrades.</para>

	<note>
	<para>Binary updates are available for all architectures and
	- releases currently supported by the security team.
	- Before updating to a new release, the current
	- release announcements should be reviewed as they may contain
	- important information pertinent to the desired release. These
	- announcements may be viewed at the following link:
	- <ulink url="http://www.FreeBSD.org/releases/"></ulink>.</para>
	+ releases currently supported by the security team. Before
	+ updating to a new release, its release announcement should be
	+ reviewed as it contains important information pertinent to the
	+ release. Release announcements are available from <ulink
	+ url="http://www.FreeBSD.org/releases/"></ulink>.</para>
	</note>

	<para>If a <command>crontab</command> utilizing the features
	of &man.freebsd-update.8; exists, it must be
	disabled before the following operation is started.</para>

	<sect2 id="freebsdupdate-config-file">
	<title>The Configuration File</title>

	<para>Some users may wish to tweak the default configuration
	- file in <filename>/etc/freebsd-update.conf</filename>,
	- allowing better control of the process. The options are very
	- well documented, but the following few may require a bit more
	+ in <filename>/etc/freebsd-update.conf</filename>, allowing
	+ better control of the process. The options are well
	+ documented, but the following may require a bit more
	explanation:</para>

	<programlisting># Components of the base system which should be kept updated.
	Components src world kernel</programlisting>

	- <para>This parameter controls what parts of &os; will be kept up
	- to date. The default is to update the source code, the entire
	- base system, and the kernel. Components are the same as those
	- available during the install, for instance, adding
	- <literal>world/games</literal> here would allow game patches
	- to be applied. Using <literal>src/bin</literal> would allow
	- the source code in
	- <filename class="directory">src/bin</filename> to be
	- updated.</para>
	+ <para>This parameter controls which parts of &os; will be kept
	+ up-to-date. The default is to update the source code, the
	+ entire base system, and the kernel. Components are the same
	+ as those available during installation. For instance, adding
	+ <literal>world/games</literal> would allow game patches to be
	+ applied. Using <literal>src/bin</literal> would allow the
	+ source code in <filename class="directory">src/bin</filename>
	+ to be updated.</para>

	<para>The best option is to leave this at the default as
	- changing it to include specific items will require the user
	- to list every item they prefer to be updated. This could
	- have disastrous consequences as source code and binaries may
	- become out of sync.</para>
	+ changing it to include specific items requires the user to
	+ list every item to be updated. This could have disastrous
	+ consequences as source code and binaries may become out of
	+ sync.</para>

	<programlisting># Paths which start with anything matching an entry in an IgnorePaths
	# statement will be ignored.
	IgnorePaths</programlisting>

	- <para>Add paths, such as
	+ <para>To leave specified directories, such as
	<filename class="directory">/bin</filename> or
	- <filename class="directory">/sbin</filename> to leave these
	- specific directories untouched during the update
	- process. This option may be used to prevent
	+ <filename class="directory">/sbin</filename>, untouched during
	+ the update process, add their paths to this statement. This
	+ option may be used to prevent
	<command>freebsd-update</command> from overwriting local
	modifications.</para>

	<programlisting># Paths which start with anything matching an entry in an UpdateIfUnmodified
	# statement will only be updated if the contents of the file have not been
	# modified by the user (unless changes are merged; see below).
	UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile</programlisting>

	- <para>Update configuration files in the specified directories
	- only if they have not been modified. Any changes made by the
	+ <para>This option will only update unmodified configuration
	+ files in the specified directories. Any changes made by the
	user will invalidate the automatic updating of these files.
	There is another option,
	<literal>KeepModifiedMetadata</literal>, which will instruct
	<command>freebsd-update</command> to save the changes during
	the merge.</para>

	<programlisting># When upgrading to a new &os; release, files which match MergeChanges
	# will have any local changes merged into the version from the new release.
	MergeChanges /etc/ /var/named/etc/</programlisting>

	<para>List of directories with configuration files that
	- <command>freebsd-update</command> should attempt merges in.
	+ <command>freebsd-update</command> should attempt to merge.
	The file merge process is a series of &man.diff.1; patches
	- similar to &man.mergemaster.8; with fewer options, the merges
	- are either accepted, open an editor, or
	+ similar to &man.mergemaster.8;, but with fewer options.
	+ Merges are either accepted, open an editor, or
	<command>freebsd-update</command> will abort. When in doubt,
	backup <filename class="directory">/etc</filename> and just
	accept the merges. See <xref linkend="mergemaster"/> for more
	- information about the <command>mergemaster</command>
	- command.</para>
	+ information about <command>mergemaster</command>.</para>

	<programlisting># Directory in which to store downloaded updates and temporary
	# files used by &os; Update.
	# WorkDir /var/db/freebsd-update</programlisting>

	- <para>This directory is where all patches and temporary
	- files will be placed. In cases where the user is doing
	- a version upgrade, this location should have a least a
	- gigabyte of disk space available.</para>
	+ <para>This directory is where all patches and temporary files
	+ are placed. In cases where the user is doing a version
	+ upgrade, this location should have a least a gigabyte of disk
	+ space available.</para>

	<programlisting># When upgrading between releases, should the list of Components be
	# read strictly (StrictComponents yes) or merely as a list of components
	# which might be installed of which &os; Update should figure out
	# which actually are installed and upgrade those (StrictComponents no)?
	# StrictComponents no</programlisting>

	- <para>When set to <literal>yes</literal>,
	+ <para>When this option is set to <literal>yes</literal>,
	<command>freebsd-update</command> will assume that the
	<literal>Components</literal> list is complete and will not
	attempt to make changes outside of the list. Effectively,
	<command>freebsd-update</command> will attempt to update
	every file which belongs to the <literal>Components</literal>
	list.</para>
	</sect2>

	<sect2 id="freebsdupdate-security-patches">
	<title>Security Patches</title>

	- <para>Security patches are stored on a remote machine and
	- may be downloaded and installed using the following
	- command:</para>
	+ <para>&os; security patches may be downloaded and installed
	+ using the following command:</para>

	<screen>&prompt.root; <userinput>freebsd-update fetch</userinput>
	&prompt.root; <userinput>freebsd-update install</userinput></screen>

	- <para>If any kernel patches have been applied the system will
	- need a reboot. If all went well the system should be patched
	- and <command>freebsd-update</command> may be run as a nightly
	- &man.cron.8; job. An entry in
	- <filename>/etc/crontab</filename> would be sufficient to
	- accomplish this task:</para>
	+ <para>If the update applied any kernel patches, the system will
	+ need a reboot in order to boot into the patched kernel.
	+ Otherwise, the system should be patched and
	+ <command>freebsd-update</command> may be run as a nightly
	+ &man.cron.8; job by adding this entry to
	+ <filename>/etc/crontab</filename>:</para>

	<programlisting>@daily root freebsd-update cron</programlisting>

	- <para>This entry states that once every day, the
	- <command>freebsd-update</command> utility will be run. In
	- this way, using the <option>cron</option> argument,
	+ <para>This entry states that <command>freebsd-update</command>
	+ will run once every day. When run with <option>cron</option>,
	<command>freebsd-update</command> will only check if updates
	exist. If patches exist, they will automatically be
	- downloaded to the local disk but not applied. The
	- <username>root</username> user will be sent an email so they
	- may install them manually.</para>
	+ downloaded to the local disk but will not be applied. The
	+ <username>root</username> user will be sent an email so that
	+ they may be reviewed and manually installed.</para>

	- <para>If anything went wrong, <command>freebsd-update</command>
	+ <para>If anything goes wrong, <command>freebsd-update</command>
	has the ability to roll back the last set of changes with
	the following command:</para>

	<screen>&prompt.root; <userinput>freebsd-update rollback</userinput></screen>

	<para>Once complete, the system should be restarted if the
	kernel or any kernel modules were modified. This will allow
	&os; to load the new binaries into memory.</para>

	- <para>The <command>freebsd-update</command> utility can
	- automatically update the <filename>GENERIC</filename> kernel
	- only. If a custom kernel is in use, it will have to be
	- rebuilt and reinstalled after
	- <command>freebsd-update</command> finishes installing the rest
	- of the updates. However, <command>freebsd-update</command>
	- will detect and update the <filename>GENERIC</filename> kernel
	- in
	- <filename class="directory">/boot/GENERIC</filename> (if it
	- exists), even if it is not the current (running) kernel of the
	+ <para>Only the <filename>GENERIC</filename> kernel can be
	+ automatically updated by <command>freebsd-update</command>.
	+ If a custom kernel is installed, it will have to be rebuilt
	+ and reinstalled after <command>freebsd-update</command>
	+ finishes installing the rest of the updates. However,
	+ <command>freebsd-update</command> will detect and update the
	+ <filename>GENERIC</filename> kernel if
	+ <filename class="directory">/boot/GENERIC</filename> exists,
	+ even if it is not the current running kernel of the
	system.</para>

	<note>
	<para>It is a good idea to always keep a copy of the
	<filename>GENERIC</filename> kernel in
	<filename class="directory">/boot/GENERIC</filename>. It
	will be helpful in diagnosing a variety of problems, and in
	performing version upgrades using
	<command>freebsd-update</command> as described in
	<xref linkend="freebsdupdate-upgrade"/>.</para>
	</note>

	<para>Unless the default configuration in
	<filename>/etc/freebsd-update.conf</filename> has been
	changed, <command>freebsd-update</command> will install the
	updated kernel sources along with the rest of the updates.
	- Rebuilding and reinstalling your new custom kernel can then be
	+ Rebuilding and reinstalling a new custom kernel can then be
	performed in the usual way.</para>

	<note>
	- <para>The updates distributed via
	- <command>freebsd-update</command>, do not always involve the
	- kernel. It will not be necessary to rebuild your custom
	- kernel if the kernel sources have not been modified by the
	- execution of <command>freebsd-update install</command>.
	+ <para>The updates distributed by
	+ <command>freebsd-update</command> do not always involve the
	+ kernel. It is not necessary to rebuild a custom kernel if
	+ the kernel sources have not been modified by the execution
	+ of <command>freebsd-update install</command>.
	However, <command>freebsd-update</command> will always
	- update the <filename>/usr/src/sys/conf/newvers.sh</filename>
	- file. The current patch level (as indicated by the
	+ update <filename>/usr/src/sys/conf/newvers.sh</filename>.
	+ The current patch level, as indicated by the
	<literal>-p</literal> number reported by
	- <command>uname -r</command>) is obtained from this file.
	- Rebuilding your custom kernel, even if nothing else changed,
	- will allow &man.uname.1; to accurately report the current
	+ <command>uname -r</command>, is obtained from this file.
	+ Rebuilding a custom kernel, even if nothing else changed,
	+ allows &man.uname.1; to accurately report the current
	patch level of the system. This is particularly helpful
	when maintaining multiple systems, as it allows for a quick
	assessment of the updates installed in each one.</para>
	</note>
	</sect2>

	<sect2 id="freebsdupdate-upgrade">
	<title>Major and Minor Version Upgrades</title>

	<para>Upgrades from one minor version of &os; to another, like
	from &os; 9.0 to &os; 9.1, are called
	<emphasis>minor version</emphasis> upgrades. Generally,
	installed applications will continue to work without problems
	after minor version upgrades.</para>

	- <para><emphasis>Major version</emphasis> upgrades are when &os;
	- is upgraded from one major version to another, like from
	- &os; 8.X to &os; 9.X. Major version upgrades will
	- remove old object files and libraries which will break most
	- third party applications. It is recommended that all
	- installed ports either be removed and re-installed or upgraded
	- after a major version upgrade by using the
	- <filename role="package">ports-mgmt/portupgrade</filename>
	- utility. A brute-force rebuild of all installed
	- applications can be accomplished with this command:</para>
	+ <para><emphasis>Major version</emphasis> upgrades occur when
	+ &os; is upgraded from one major version to another, like from
	+ &os; 8.X to &os; 9.X. Major version upgrades remove
	+ old object files and libraries which will break most third
	+ party applications. It is recommended that all installed
	+ ports either be removed and re-installed or upgraded after a
	+ major version upgrade using a utility such as
	+ <filename role="package">ports-mgmt/portmaster</filename>. A
	+ brute-force rebuild of all installed applications can be
	+ accomplished with this command:</para>

	- <screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>
	+ <screen>&prompt.root; <userinput>portmaster -f</userinput></screen>

	<para>This will ensure everything will be re-installed
	correctly. Note that setting the
	<makevar>BATCH</makevar> environment variable to
	<literal>yes</literal> will answer <literal>yes</literal> to
	any prompts during this process, removing the need for
	manual intervention during the build process.</para>

	<sect3 id="freebsd-update-custom-kernel">
	<title>Dealing with Custom Kernels</title>

	<para>If a custom kernel is in use, the upgrade process is
	slightly more involved, and the procedure varies depending
	on the version of &os;.</para>

	<sect4 id="freebsd-update-custom-kernel-8x">
	- <title>Custom Kernels with &os; 8.X and Earlier</title>
	+ <title>Custom Kernels with &os; 8.X</title>

	- <para>A copy of the
	- <filename>GENERIC</filename> kernel is needed, and it
	- should be placed in <filename
	+ <para>A copy of the <filename>GENERIC</filename> kernel is
	+ needed, and should be placed in <filename
	class="directory">/boot/GENERIC</filename>. If the
	- <filename>GENERIC</filename> kernel is not already present
	- in the system, it may be obtained using one of the
	- following methods:</para>
	+ <filename>GENERIC</filename> kernel is not present in the
	+ system, it may be obtained using one of the following
	+ methods:</para>

	<itemizedlist>
	<listitem>
	<para>If a custom kernel has only been built once, the
	kernel in <filename
	class="directory">/boot/kernel.old</filename> is
	- actually the <filename>GENERIC</filename> one. Simply
	- rename this directory to <filename
	+ actually <filename>GENERIC</filename>. Rename this
	+ directory to <filename
	class="directory">/boot/GENERIC</filename>.</para>
	</listitem>

	<listitem>
	<para>Assuming physical access to the machine is
	possible, a copy of the <filename>GENERIC</filename>
	- kernel can be installed from the CD-ROM media. Insert
	- your installation disc and use the following
	- commands:</para>
	+ kernel can be installed from the installation media
	+ using the following commands:</para>

	<screen>&prompt.root; <userinput>mount /cdrom</userinput>
	&prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput>
	&prompt.root; <userinput>./install.sh GENERIC</userinput></screen>

	<para>Replace <filename
	class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
	- with the actual version of the release you are using.
	+ with the actual version of the release being used.
	The <filename>GENERIC</filename> kernel will be
	installed in <filename
	class="directory">/boot/GENERIC</filename> by
	default.</para>
	</listitem>

	<listitem>
	<para>Failing all the above, the
	<filename>GENERIC</filename> kernel may be rebuilt and
	- installed from the sources:</para>
	+ installed from source:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput>
	&prompt.root; <userinput>env DESTDIR=/boot/GENERIC make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</userinput>
	&prompt.root; <userinput>mv /boot/GENERIC/boot/kernel/* /boot/GENERIC</userinput>
	&prompt.root; <userinput>rm -rf /boot/GENERIC/boot</userinput></screen>

	<para>For this kernel to be picked up as
	- <filename>GENERIC</filename>
	- by <command>freebsd-update</command>, the
	+ <filename>GENERIC</filename> by
	+ <command>freebsd-update</command>, the
	<filename>GENERIC</filename> configuration file must
	not have been modified in any way. It is also
	suggested that it is built without any other special
	options.</para>
	</listitem>
	</itemizedlist>

	<para>Rebooting to the <filename>GENERIC</filename> kernel
	is not required at this stage.</para>
	</sect4>

	<sect4 id="freebsd-update-custom-kernel-9x">
	<title>Custom Kernels with &os; 9.X and Later</title>

	<itemizedlist>
	<listitem>
	<para>If a custom kernel has only been built once, the
	kernel in
	<filename
	class="directory">/boot/kernel.old</filename>
	is actually the <literal>GENERIC</literal> kernel.
	Rename this directory to <filename
	class="directory">/boot/kernel</filename>.</para>
	</listitem>

	<listitem>
	<para>If physical access to the machine is available, a
	copy of the <literal>GENERIC</literal> kernel can be
	- installed from the CD-ROM media. Load the
	- installation disc and use these commands:</para>
	+ installed from the installation media using these
	+ commands:</para>

	<screen>&prompt.root; <userinput>mount /cdrom</userinput>
	&prompt.root; <userinput>cd /cdrom/usr/freebsd-dist</userinput>
	&prompt.root; <userinput>tar -C/ -xvf kernel.txz boot/kernel/kernel</userinput></screen>
	</listitem>

	<listitem>
	<para>If the options above cannot be used, the
	<literal>GENERIC</literal> kernel may be rebuilt and
	- installed from the sources:</para>
	+ installed from source:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput>
	&prompt.root; <userinput>make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</userinput></screen>

	<para>For this kernel to be identified as the
	<literal>GENERIC</literal> kernel by
	<command>freebsd-update</command>, the
	<filename>GENERIC</filename> configuration file must
	not have been modified in any way. It is also
	suggested that the kernel is built without any other
	special options.</para>
	</listitem>
	</itemizedlist>

	<para>Rebooting to the <filename>GENERIC</filename> kernel
	is not required at this stage.</para>
	</sect4>
	</sect3>

	<sect3 id="freebsdupdate-using">
	<title>Performing the Upgrade</title>

	<para>Major and minor version upgrades may be performed by
	providing <command>freebsd-update</command> with a release
	- version target, for example, the following command will
	- update to &os; 8.1:</para>
	+ version target. The following command will update to
	+ &os; 9.1:</para>

	- <screen>&prompt.root; <userinput>freebsd-update -r 8.1-RELEASE upgrade</userinput></screen>
	+ <screen>&prompt.root; <userinput>freebsd-update -r 9.1-RELEASE upgrade</userinput></screen>

	<para>After the command has been received,
	<command>freebsd-update</command> will evaluate the
	configuration file and current system in an attempt to
	- gather the information necessary to update the system. A
	- screen listing will display what components have been
	- detected and what components have not been detected. For
	- example:</para>
	+ gather the information necessary to perform the upgrade. A
	+ screen listing will display which components have and have
	+ not been detected. For example:</para>

	<screen>Looking up update.FreeBSD.org mirrors... 1 mirrors found.
	-Fetching metadata signature for 8.0-RELEASE from update1.FreeBSD.org... done.
	+Fetching metadata signature for 9.0-RELEASE from update1.FreeBSD.org... done.
	Fetching metadata index... done.
	Inspecting system... done.

	The following components of FreeBSD seem to be installed:
	kernel/smp src/base src/bin src/contrib src/crypto src/etc src/games
	src/gnu src/include src/krb5 src/lib src/libexec src/release src/rescue
	src/sbin src/secure src/share src/sys src/tools src/ubin src/usbin
	world/base world/info world/lib32 world/manpages

	The following components of FreeBSD do not seem to be installed:
	kernel/generic world/catpages world/dict world/doc world/games
	world/proflibs

	Does this look reasonable (y/n)? y</screen>

	<para>At this point, <command>freebsd-update</command> will
	attempt to download all files required for the upgrade. In
	some cases, the user may be prompted with questions
	regarding what to install or how to proceed.</para>

	<para>When using a custom kernel, the above step will produce
	a warning similar to the following:</para>

	<screen>WARNING: This system is running a "<replaceable>MYKERNEL</replaceable>" kernel, which is not a
	-kernel configuration distributed as part of FreeBSD 8.0-RELEASE.
	+kernel configuration distributed as part of FreeBSD 9.0-RELEASE.
	This kernel will not be updated: you MUST update the kernel manually
	before running "/usr/sbin/freebsd-update install"</screen>

	<para>This warning may be safely ignored at this point. The
	updated <filename>GENERIC</filename> kernel will be used as
	an intermediate step in the upgrade process.</para>

	- <para>After all patches have been downloaded to the local
	- system, they will then be applied. This process may take a
	- while depending on the speed and workload of the machine.
	- Configuration files will then be merged — this
	- part of the process requires some user intervention as a
	- file may be merged or an editor may appear on screen for a
	- manual merge. The results of every successful merge will be
	- shown to the user as the process continues. A failed or
	- ignored merge will cause the process to abort. Users may
	- wish to make a backup of <filename
	- class="directory">/etc</filename> and manually merge
	- important files, such as
	+ <para>Once all the patches have been downloaded to the local
	+ system, they will be applied. This process may take a
	+ while, depending on the speed and workload of the machine.
	+ Configuration files will then be merged. The merging
	+ process requires some user intervention as a file may be
	+ merged or an editor may appear on screen for a manual merge.
	+ The results of every successful merge will be shown to the
	+ user as the process continues. A failed or ignored merge
	+ will cause the process to abort. Users may wish to make a
	+ backup of <filename class="directory">/etc</filename> and
	+ manually merge important files, such as
	<filename>master.passwd</filename> or
	<filename>group</filename> at a later time.</para>

	<note>
	- <para>The system is not being altered yet, all patching and
	- merging is happening in another directory. When all
	+ <para>The system is not being altered yet as all patching
	+ and merging is happening in another directory. Once all
	patches have been applied successfully, all configuration
	files have been merged and it seems the process will go
	- smoothly, the changes will need to be committed by the
	- user.</para>
	- </note>
	+ smoothly, the changes can be committed to disk by the
	+ user using the following command:</para>

	- <para>Once this process is complete, the upgrade may be
	- committed to disk using the following command.</para>
	-
	<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>

	+ </note>
	+
	<para>The kernel and kernel modules will be patched first. At
	- this point the machine must be rebooted. If the system was
	- running with a custom kernel, use the &man.nextboot.8;
	- command to set the kernel for the next boot to
	- <filename class="directory">/boot/GENERIC</filename> (which
	- was updated):</para>
	+ this point, the machine must be rebooted. If the system is
	+ running with a custom kernel, use &man.nextboot.8; to set
	+ the kernel for the next boot to the updated
	+ <filename class="directory">/boot/GENERIC</filename>:</para>

	<screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen>

	<warning>
	<para>Before rebooting with the <filename>GENERIC</filename>
	- kernel, make sure it contains all drivers required for
	- your system to boot properly (and connect to the network,
	- if the machine that is being updated is accessed
	- remotely). In particular, if the previously running
	- custom kernel contained built-in functionality usually
	- provided by kernel modules, make sure to temporarily load
	- these modules into the <filename>GENERIC</filename> kernel
	- using the <filename>/boot/loader.conf</filename> facility.
	- You may also wish to disable non-essential services, disk
	- and network mounts, etc. until the upgrade process is
	- complete.</para>
	+ kernel, make sure it contains all the drivers required for
	+ the system to boot properly and connect to the network,
	+ if the machine being updated is accessed remotely. In
	+ particular, if the running custom kernel contains built-in
	+ functionality usually provided by kernel modules, make
	+ sure to temporarily load these modules into the
	+ <filename>GENERIC</filename> kernel using the
	+ <filename>/boot/loader.conf</filename> facility.
	+ It is recommended to disable non-essential services as
	+ well as any disk and network mounts until the upgrade
	+ process is complete.</para>
	</warning>

	<para>The machine should now be restarted with the updated
	kernel:</para>

	<screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>

	- <para>Once the system has come back online,
	- <command>freebsd-update</command> will need to be started
	- again. The state of the process has been saved and thus,
	+ <para>Once the system has come back online, restart
	+ <command>freebsd-update</command> using the following
	+ command. The state of the process has been saved and thus,
	<command>freebsd-update</command> will not start from the
	beginning, but will remove all old shared libraries and
	- object files. To continue to this stage, issue the
	- following command:</para>
	+ object files.</para>

	<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>

	<note>
	- <para>Depending on whether any libraries version numbers got
	- bumped, there may only be two install phases instead of
	- three.</para>
	+ <para>Depending upon whether any library version numbers
	+ were bumped, there may only be two install phases instead
	+ of three.</para>
	</note>
	</sect3>

	<sect3 id="freebsdupdate-portsrebuild">
	<title>Rebuilding Ports After a Major Version Upgrade</title>

	<para>After a major version upgrade, all third party software
	- will now need to be rebuilt and re-installed. This is
	- required as installed software may depend on libraries which
	- have been removed during the upgrade process. The
	- <filename role="package">ports-mgmt/portupgrade</filename>
	- command may be used to automate this process. The following
	- commands may be used to begin this process:</para>
	+ needs to be rebuilt and re-installed. This is required as
	+ installed software may depend on libraries which have been
	+ removed during the upgrade process. This process can be
	+ automated using <filename
	+ role="package">ports-mgmt/portmaster</filename>:</para>

	- <screen>&prompt.root; <userinput>portupgrade -f ruby</userinput>
	-&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db</userinput>
	-&prompt.root; <userinput>portupgrade -f ruby18-bdb</userinput>
	-&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db /usr/ports/INDEX-*.db</userinput>
	-&prompt.root; <userinput>portupgrade -af</userinput></screen>
	+ <screen>&prompt.root; <userinput>portmaster -f</userinput></screen>

	<para>Once this has completed, finish the upgrade process with
	- a final call to <command>freebsd-update</command>. Issue
	- the following command to tie up all loose ends in the
	- upgrade process:</para>
	+ a final call to <command>freebsd-update</command> in order
	+ to tie up all the loose ends in the upgrade process:</para>

	<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>

	<para>If the <filename>GENERIC</filename> kernel was
	temporarily used, this is the time to build and install a
	new custom kernel in the usual way.</para>

	<para>Reboot the machine into the new &os; version. The
	process is complete.</para>
	</sect3>
	</sect2>

	<sect2 id="freebsdupdate-system-comparison">
	<title>System State Comparison</title>

	- <para>The <command>freebsd-update</command> utility may be used
	- to test the state of the installed &os; version against a
	- known good copy. This option evaluates the current version
	- of system utilities, libraries, and configuration files.
	- To begin the comparison, issue the following command:</para>
	+ <para><command>freebsd-update</command> can be used to test the
	+ state of the installed &os; version against a known good copy.
	+ This option evaluates the current version of system utilities,
	+ libraries, and configuration files. To begin the comparison,
	+ issue the following command:</para>

	<screen>&prompt.root; <userinput>freebsd-update IDS >> outfile.ids</userinput></screen>

	<warning>
	- <para>While the command name is <acronym>IDS</acronym> it
	- should in no way be a replacement for an intrusion detection
	- system such as
	- <filename role="package">security/snort</filename>. As
	+ <para>While the command name is <acronym>IDS</acronym> it is
	+ not a replacement for a real intrusion detection system such
	+ as <filename role="package">security/snort</filename>. As
	<command>freebsd-update</command> stores data on disk, the
	possibility of tampering is evident. While this possibility
	- may be reduced by using the
	- <varname>kern.securelevel</varname> setting and storing the
	- <command>freebsd-update</command> data on a read only file
	- system when not in use, a better solution would be to
	- compare the system against a secure disk, such as a
	- <acronym>DVD</acronym> or securely stored external
	+ may be reduced using <varname>kern.securelevel</varname> and
	+ by storing the <command>freebsd-update</command> data on a
	+ read only file system when not in use, a better solution
	+ would be to compare the system against a secure disk, such
	+ as a <acronym>DVD</acronym> or securely stored external
	<acronym>USB</acronym> disk device.</para>
	</warning>

	- <para>The system will now be inspected, and a list of files
	- along with their &man.sha256.1; hash values, both the known
	- value in the release and the current installed value, will be
	- printed. This is why the output has been sent to the
	- <filename>outfile.ids</filename> file. It scrolls by too
	- quickly for eye comparisons, and soon it fills up the console
	- buffer.</para>
	+ <para>The system will now be inspected, and a lengthy listing of
	+ files, along with the &man.sha256.1; hash values for both the
	+ known value in the release and the current installation, will
	+ be sent to the specified
	+ <filename>outfile.ids</filename> file.</para>

	- <para>These lines are also extremely long, but the output format
	- may be parsed quite easily. For instance, to obtain a list of
	- all files different from those in the release, issue the
	- following command:</para>
	+ <para>The entries in the listing are extremely long, but the
	+ output format may be easily parsed. For instance, to obtain a
	+ list of all files which differ from those in the release,
	+ issue the following command:</para>

	<screen>&prompt.root; <userinput>cat outfile.ids \| awk '{ print $1 }' \| more</userinput>
	/etc/master.passwd
	/etc/motd
	/etc/passwd
	/etc/pf.conf</screen>

	- <para>This output has been truncated, many more files exist.
	- Some of these files have natural modifications, the
	+ <para>This sample output has been truncated as many more files
	+ exist. Some files have natural modifications. For example,
	<filename>/etc/passwd</filename> has been modified because
	- users have been added to the system. In some cases, there
	- may be other files, such as kernel modules, which differ
	- as <command>freebsd-update</command> may have updated them.
	+ users have been added to the system. Other files, such as
	+ kernel modules, may differ as
	+ <command>freebsd-update</command> may have updated them.
	To exclude specific files or directories, add them to the
	<literal>IDSIgnorePaths</literal> option in
	<filename>/etc/freebsd-update.conf</filename>.</para>

	<para>This system may be used as part of an elaborate upgrade
	method, aside from the previously discussed version.</para>
	</sect2>
	</sect1>

	<sect1 id="updating-upgrading-portsnap">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Colin</firstname>
	<surname>Percival</surname>
	<contrib>Based on notes provided by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Portsnap: a Ports Collection Update Tool</title>

	<indexterm><primary>Updating and Upgrading</primary></indexterm>
	<indexterm>
	<primary>Portsnap</primary>
	<see>Updating and Upgrading</see>
	</indexterm>

	- <para>The base system of &os; includes a utility for updating
	- the Ports Collection too: the &man.portsnap.8; utility. Upon
	- execution, it will connect to a remote site, verify the secure
	- key, and download a new copy of the Ports Collection. The key
	- is used to verify the integrity of all downloaded files,
	- ensuring they have not been modified in-flight. To download the
	- latest Ports Collection files, issue the following
	- command:</para>
	+ <para>The base system of &os; includes &man.portsnap.8; for
	+ updating the Ports Collection. This utility connects to a
	+ &os; site, verifies the secure key, and downloads a new copy of
	+ the Ports Collection. The key is used to verify the integrity
	+ of all downloaded files. To download the latest Ports
	+ Collection files, issue the following command:</para>

	<screen>&prompt.root; <userinput>portsnap fetch</userinput>
	Looking up portsnap.FreeBSD.org mirrors... 9 mirrors found.
	Fetching snapshot tag from geodns-1.portsnap.freebsd.org... done.
	Fetching snapshot metadata... done.
	Updating from Tue May 22 02:12:15 CEST 2012 to Wed May 23 16:28:31 CEST 2012.
	Fetching 3 metadata patches.. done.
	Applying metadata patches... done.
	Fetching 3 metadata files... done.
	Fetching 90 patches.....10....20....30....40....50....60....70....80....90. done.
	Applying patches... done.
	Fetching 133 new ports or files... done.</screen>

	<para>What this example shows is that &man.portsnap.8; has found
	and verified several patches to the current ports data. This
	- also indicates that the utility was run previously, if it was a
	+ also indicates that the utility was run previously; if it was a
	first time run, the collection would have simply been
	downloaded.</para>

	<para>When &man.portsnap.8; successfully completes a
	<command>fetch</command> operation, the Ports Collection and
	- subsequent patches exist on the local system that have passed
	+ subsequent patches which exist on the local system have passed
	verification. The first time <command>portsnap</command> is
	- executed, you have to use <literal>extract</literal> to install
	- the downloaded files:</para>
	+ executed, use <literal>extract</literal> to install the
	+ downloaded files:</para>

	<screen>&prompt.root; <userinput>portsnap extract</userinput>
	/usr/ports/.cvsignore
	/usr/ports/CHANGES
	/usr/ports/COPYRIGHT
	/usr/ports/GIDs
	/usr/ports/KNOBS
	/usr/ports/LEGAL
	/usr/ports/MOVED
	/usr/ports/Makefile
	/usr/ports/Mk/bsd.apache.mk
	/usr/ports/Mk/bsd.autotools.mk
	/usr/ports/Mk/bsd.cmake.mk
	<replaceable>...</replaceable></screen>

	- <para>To update an already installed Ports Collection use the
	- command <command>portsnap update</command>:</para>
	+ <para>To update an already installed Ports Collection, use
	+ <command>portsnap update</command>:</para>

	<screen>&prompt.root; <userinput>portsnap update</userinput></screen>

	<para>The process is now complete, and applications may be
	installed or upgraded using the updated Ports Collection.</para>

	- <para>The <literal>fetch</literal> and <literal>extract</literal>
	- or <literal>update</literal> operations may be run
	- consecutively, as shown in the following example:</para>
	+ <para>When using <literal>fetch</literal>, the
	+ <literal>extract</literal> or the <literal>update</literal>
	+ operation may be run consecutively:</para>

	<screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>

	- <para>This command will download the latest version of the
	- Ports Collection and update your local version under
	+ <para>This command downloads the latest version of the Ports
	+ Collection and updates the local version under
	<filename class="directory">/usr/ports</filename>.</para>
	</sect1>

	<sect1 id="updating-upgrading-documentation">
	<title>Updating the Documentation Set</title>

	<indexterm><primary>Updating and Upgrading</primary></indexterm>

	<indexterm>
	<primary>Documentation</primary>
	<see>Updating and Upgrading</see>
	</indexterm>

	- <para>Besides the base system and the Ports Collection,
	- documentation is an integral part of the &os; operating system.
	- While an up-to-date version of the &os; Documentation Set is
	- always available on the
	- <ulink url="http://www.freebsd.org/doc/">&os; web site</ulink>,
	- some users might have slow or no permanent network connectivity
	- at all. Fortunately, there are several ways to update the
	- documentation shipped with each release by maintaining a local
	- copy of the latest &os; Documentation Set.</para>
	+ <para>Documentation is an integral part of the &os; operating
	+ system. While an up-to-date version of the &os; Documentation
	+ Set is always available on the <ulink
	+ url="http://www.freebsd.org/doc/">&os; web site</ulink>,
	+ some users might have slow or no permanent network connectivity.
	+ There are several ways to update the local copy of documentation
	+ with the latest &os; Documentation Set.</para>

	<sect2 id="dsvn-doc">
	<title>Using <application>Subversion</application> to Update the
	Documentation</title>

	<para>The &os; documentation sources can be obtained with
	- <application>Subversion</application>. This section
	- describes:</para>
	+ <application>svn</application>. This section
	+ describes how to:</para>

	<itemizedlist>
	<listitem>
	- <para>How to install the documentation toolchain, the tools
	- that are required to rebuild the &os; documentation from
	- its source.</para>
	+ <para>Install the documentation toolchain, the tools that
	+ are required to rebuild the &os; documentation from its
	+ source.</para>
	</listitem>

	<listitem>
	- <para>How to download a copy of the documentation source
	- at <filename class="directory">/usr/doc</filename>,
	- using <application>Subversion</application>.</para>
	+ <para>Download a copy of the documentation source at
	+ <filename class="directory">/usr/doc</filename>, using
	+ <application>svn</application>.</para>
	</listitem>

	<listitem>
	- <para>How to rebuild the &os; documentation from its source,
	- and install it under <filename
	+ <para>Rebuild the &os; documentation from its source, and
	+ install it under <filename
	class="directory">/usr/share/doc</filename>.</para>
	</listitem>

	<listitem>
	- <para>Some of the build options that are supported by the
	- build system of the documentation, i.e., the options that
	- build only some of the different language translations of
	- the documentation or the options that select a specific
	- output format.</para>
	+ <para>Recognize some of the build options that are
	+ supported by the build system of the documentation, such
	+ as the options that build only some of the different
	+ language translations of the documentation or the options
	+ that select a specific output format.</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2 id="installing-documentation-toolchain">
	- <title>Installing <application>Subversion</application> and the
	+ <title>Installing <application>svn</application> and the
	Documentation Toolchain</title>

	<para>Rebuilding the &os; documentation from source requires a
	- fairly large collection of tools. These tools are not part of
	- the &os; base system, because they need a large amount of disk
	- space and they are not useful to all &os; users; they are only
	- useful to those users that are actively writing new
	- documentation for &os; or are frequently updating their
	- documentation from source.</para>
	+ collection of tools which are not part of the &os; base system
	+ due to the amount of disk space these tools use. They are
	+ also not useful to all &os; users, only those users that are
	+ actively writing new documentation for &os; or are frequently
	+ updating their documentation from source.</para>

	- <para>All the required tools are available as part of the Ports
	- Collection. The
	- <filename role="package">textproc/docproj</filename> port is a
	- master port that has been developed by the &os; Documentation
	- Project, to ease the initial installation and future updates
	- of these tools.</para>
	+ <para>The required tools, including
	+ <application>svn</application>, are available in the
	+ <filename role="package">textproc/docproj</filename> meta-port
	+ developed by the &os; Documentation Project.</para>

	<note>
	<para>When no &postscript; or PDF documentation required, one
	might consider installing the <filename
	role="package">textproc/docproj-nojadetex</filename> port
	instead. This version of the documentation toolchain
	includes everything except the
	<application>teTeX</application> typesetting engine.
	<application>teTeX</application> is a very large collection
	of tools, so it may be quite sensible to omit its
	installation if PDF output is not really necessary.</para>
	</note>
	-
	- <para><application>Subversion</application> is installed with
	- the <filename role="package">textproc/docproj</filename>
	- port.</para>
	</sect2>

	<sect2 id="updating-documentation-sources">
	<title>Updating the Documentation Sources</title>

	- <para>The <application>Subversion</application> program can
	+ <para>In this example, <application>svn</application> is used to
	fetch a clean copy of the documentation sources from the
	- western US mirror using the HTTPS protocol with this
	- command:</para>
	+ western US mirror using the HTTPS protocol:</para>

	<screen>&prompt.root; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/doc/head /usr/doc</userinput></screen>

	- <para>Please use the closest mirror from the available <link
	+ <para>Select the closest mirror from the available <link
	linkend="svn-mirrors">Subversion mirror sites</link>.</para>

	<para>The initial download of the documentation sources may take
	a while. Let it run until it completes.</para>

	<para>Future updates of the documentation sources may be fetched
	by running:</para>

	<screen>&prompt.root; <userinput>svn update <filename class="directory">/usr/doc</filename></userinput></screen>

	<para>After checking out the sources, an alternative way of
	updating the documentation is supported by the
	- <filename>Makefile</filename> of the
	- <filename class="directory">/usr/doc</filename> directory by
	- running:</para>
	+ <filename>/usr/doc/Makefile</filename> by running the
	+ following commands:</para>

	<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
	&prompt.root; <userinput>make update</userinput></screen>
	</sect2>

	<sect2 id="updating-documentation-options">
	<title>Tunable Options of the Documentation Sources</title>

	<para>The updating and build system of the &os; documentation
	- supports a few options that ease the process of updating only
	- parts of the documentation, or the build of specific
	+ set supports a few options that ease the process of updating
	+ only parts of the documentation, or the build of specific
	translations. These options can be set either as system-wide
	- options in the <filename>/etc/make.conf</filename> file, or as
	- command-line options passed to the &man.make.1;
	- utility.</para>
	+ options in <filename>/etc/make.conf</filename>, or as
	+ command-line options passed to &man.make.1;.</para>

	- <para>The following options are some of these:</para>
	+ <para>The options include:</para>

	<variablelist>
	<varlistentry>
	<term><makevar>DOC_LANG</makevar></term>

	<listitem>
	<para>The list of languages and encodings to build and
	- install, e.g., <literal>en_US.ISO8859-1</literal> for
	- the English documentation only.</para>
	+ install, such as <literal>en_US.ISO8859-1</literal> for
	+ English documentation.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><makevar>FORMATS</makevar></term>

	<listitem>
	<para>A single format or a list of output formats to be
	built. Currently, <literal>html</literal>,
	<literal>html-split</literal>, <literal>txt</literal>,
	<literal>ps</literal>, <literal>pdf</literal>,
	and <literal>rtf</literal> are supported.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><makevar>DOCDIR</makevar></term>

	<listitem>
	<para>Where to install the documentation. It defaults to
	<filename
	class="directory">/usr/share/doc</filename>.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	- <para>For more make variables supported as system-wide options
	- in &os;, see &man.make.conf.5;.</para>
	+ <para>For more <command>make</command> variables supported as
	+ system-wide options in &os;, refer to
	+ &man.make.conf.5;.</para>

	- <para>For more make variables supported by the build system of
	- the &os; documentation, please refer to the
	+ <para>For more <command>make</command> variables supported by
	+ the build system of the &os; documentation, refer to the
	<ulink url="&url.doc.langbase;/books/fdp-primer">&os;
	Documentation Project Primer for New
	Contributors</ulink>.</para>
	</sect2>

	<sect2 id="updating-installed-documentation">
	<title>Installing the &os; Documentation from Source</title>

	- <para>When an up-to-date snapshot of the documentation sources
	- has been fetched in
	- <filename class="directory">/usr/doc</filename>, everything is
	+ <para>Once an up-to-date snapshot of the documentation sources
	+ has been fetched to <filename
	+ class="directory">/usr/doc</filename>, everything is
	ready for an update of the installed documentation.</para>

	<para>A full update of all the languages defined in
	- the <makevar>DOC_LANG</makevar> makefile option may be done by
	- typing:</para>
	+ <makevar>DOC_LANG</makevar> may be performed by typing:</para>

	<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>If an update of only a specific language is desired,
	&man.make.1; can be invoked in a language specific
	subdirectory of
	- <filename class="directory">/usr/doc</filename>, i.e.:</para>
	+ <filename class="directory">/usr/doc</filename>:</para>

	<screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput>
	&prompt.root; <userinput>make update install clean</userinput></screen>

	<para>The output formats that will be installed may be specified
	- by setting the <makevar>FORMATS</makevar> make variable,
	- i.e.:</para>
	+ by setting <makevar>FORMATS</makevar>:</para>

	<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
	&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen>

	<para>For information on editing and submitting corrections to
	- the documentation, please see the <ulink
	- url="&url.books.fdp-primer;">FreeBSD Documentation
	+ the documentation, refer to the <ulink
	+ url="&url.books.fdp-primer;">&os; Documentation
	Project Primer for New Contributors</ulink>.</para>
	</sect2>

	<sect2 id="doc-ports">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Marc</firstname>
	<surname>Fonvieille</surname>
	<contrib>Based on the work of </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>Using Documentation Ports</title>

	<indexterm><primary>Updating and Upgrading</primary></indexterm>

	<indexterm>
	<primary>documentation package</primary>
	<see>Updating and Upgrading</see>
	</indexterm>

	- <para>In the previous section, we have presented a method for
	- updating the &os; documentation from sources. Source based
	- updates may not be feasible or practical for all &os; systems
	- though. Building the documentation sources requires a fairly
	- large collection of tools and utilities, the
	- <emphasis>documentation toolchain</emphasis>, a certain level
	- of familiarity with <application>Subversion</application> and
	- source checkouts from a repository, and a few manual steps to
	- build the checked out sources. In this section, we describe
	- an alternative way of updating the installed copies of the
	- &os; documentation; one that uses the Ports Collection
	- and makes it possible to:</para>
	+ <para>The previous section presented a method for updating the
	+ &os; documentation from sources. Source based updates may not
	+ be feasible or practical for all &os; systems as building the
	+ documentation sources requires the <emphasis>documentation
	+ toolchain</emphasis>, a certain level of familiarity with
	+ <application>svn</application> and source checkouts from a
	+ repository, and a few manual steps to build the checked out
	+ sources. This section describes an alternative method which
	+ uses the Ports Collection and makes it possible to:</para>

	<itemizedlist>
	<listitem>
	- <para>Download and install pre-built snaphots of the
	+ <para>Download and install pre-built snapshots of the
	documentation, without having to locally build anything
	- (eliminating this way the need for an installation of the
	- entire documentation toolchain).</para>
	+ or install the documentation toolchain.</para>
	</listitem>

	<listitem>
	<para>Download the documentation sources and build them
	- through the ports framework (making the checkout and build
	- steps a bit eaiser).</para>
	+ through the ports framework, making the checkout and build
	+ steps a bit easier.</para>
	</listitem>
	</itemizedlist>

	<para>These two methods of updating the &os; documentation are
	- supported by a set of
	- <emphasis>documentation ports</emphasis>, updated by the
	- &a.doceng; on a monthly basis. These are listed in the &os;
	- Ports Collection, under the virtual category named <ulink
	- url="http://www.freshports.org/docs/">docs</ulink>.</para>
	+ supported by a set of <emphasis>documentation
	+ ports</emphasis>, updated by the &a.doceng; on a monthly
	+ basis. These are listed in the &os; Ports Collection,
	+ under the <ulink
	+ url="http://www.freshports.org/docs/">docs</ulink>
	+ category.</para>

	<sect3 id="doc-ports-install-make">
	<title>Building and Installing Documentation Ports</title>

	<para>The documentation ports use the ports building framework
	to make documentation builds easier. They automate the
	process of checking out the documentation source, running
	&man.make.1; with the appropriate environment settings and
	command-line options, and they make the installation or
	deinstallation of documentation as easy as the installation
	of any other &os; port or package.</para>

	<note>
	<para>As an extra feature, when the documentation ports are
	built locally, they record a dependency to the
	- <emphasis>documentation toolchain</emphasis> ports, so the
	- latter is automatically installed too.</para>
	+ <emphasis>documentation toolchain</emphasis> ports, so
	+ that they are also automatically installed.</para>
	</note>

	<para>Organization of the documentation ports is as
	follows:</para>

	<itemizedlist>
	<listitem>
	- <para>There is a <quote>master port</quote>,
	- <filename role="package">misc/freebsd-doc-en</filename>,
	- where the documentation port files can be found. It is
	- the base of all documentation ports. By default, it
	- builds the English documentation only.</para>
	+ <para>The <quote>master port</quote>, <filename
	+ role="package">misc/freebsd-doc-en</filename>,
	+ which installs all of the English documentation
	+ ports.</para>
	</listitem>

	<listitem>
	- <para>There is an <quote>all in one port</quote>,
	- <filename
	- role="package">misc/freebsd-doc-all</filename>, and it
	+ <para>The <quote>all in one port</quote>, <filename
	+ role="package">misc/freebsd-doc-all</filename>,
	builds and installs all documentation in all available
	languages.</para>
	</listitem>

	<listitem>
	- <para>Finally, there is a <quote>slave port</quote> for
	- each translation, e.g.: <filename
	+ <para>There is a <quote>slave port</quote> for each
	+ translation, such as <filename
	role="package">misc/freebsd-doc-hu</filename> for the
	- Hungarian-language documents. All of them depend on the
	- master port and install the translated documentation of
	- the respective language.</para>
	+ Hungarian-language documents.</para>
	</listitem>
	</itemizedlist>

	- <para>To install a documentation port from source, issue the
	- following commands (as <username>root</username>):</para>
	+ <para>For example, to build and install the English
	+ documentation in split <acronym>HTML</acronym> format,
	+ similar to the format used on <ulink
	+ url="http://www.FreeBSD.org"></ulink>, to
	+ <filename
	+ class="directory">/usr/local/share/doc/freebsd</filename>,
	+ install the following port</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	- <para>This will build and install the English documentation in
	- split <acronym>HTML</acronym> format (the same as used on
	- <ulink url="http://www.FreeBSD.org"></ulink>) in the
	- <filename
	- class="directory">/usr/local/share/doc/freebsd</filename>
	- directory.</para>
	-
	<sect4 id="doc-ports-options">
	<title>Common Knobs and Options</title>

	<para>There are many options for modifying the default
	- behavior of the documentation ports. The following is
	- just a short list:</para>
	+ behavior of the documentation ports, including:</para>

	<variablelist>
	<varlistentry>
	<term><makevar>WITH_HTML</makevar></term>

	<listitem>
	- <para>Allows the build of the HTML format: a single
	- HTML file per document. The formatted documentation
	- is saved to a file called
	- <filename>article.html</filename>, or
	- <filename>book.html</filename>, as appropriate, plus
	- images.</para>
	+ <para>Builds the HTML format with a single HTML file
	+ per document. The formatted documentation is saved
	+ to a file called <filename>article.html</filename>,
	+ or <filename>book.html</filename>, as appropriate,
	+ plus images.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><makevar>WITH_PDF</makevar></term>

	<listitem>
	- <para>Allows the build of the &adobe; Portable
	- Document Format, for use with &adobe;
	- &acrobat.reader;,
	- <application>Ghostscript</application> or other PDF
	- readers. The formatted documentation is saved to a
	+ <para>Builds the &adobe; Portable Document Format
	+ (PDF). The formatted documentation is saved to a
	file called <filename>article.pdf</filename> or
	<filename>book.pdf</filename>, as
	appropriate.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><makevar>DOCBASE</makevar></term>

	<listitem>
	- <para>Where to install the documentation. It defaults
	- to <filename
	+ <para>Specifies where to install the documentation.
	+ It defaults to <filename
	class="directory">/usr/local/share/doc/freebsd</filename>.</para>

	<note>
	- <para>Notice that the default target directory
	- differs from the directory used by the
	- <application>Subversion</application> method.
	- This is because we are installing a port, and
	- ports are usually installed under the <filename
	- class="directory">/usr/local</filename>
	- directory. This can be overridden by adding the
	- <makevar>PREFIX</makevar> variable.</para>
	+ <para>The default target directory differs from the
	+ directory used <application>svn</application>.
	+ This is because ports are usually installed within
	+ <filename class="directory">/usr/local</filename>.
	+ This can be overridden by using
	+ <makevar>PREFIX</makevar>.</para>
	</note>
	</listitem>
	</varlistentry>
	</variablelist>

	- <para>Here is a brief example on how to use the variables
	- mentioned above to install the Hungarian documentation in
	- Portable Document Format:</para>
	+ <para>This example uses variables to install the Hungarian
	+ documentation as a PDF:</para>

	<screen>&prompt.root; cd /usr/ports/misc/freebsd-doc-hu
	&prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean</screen>
	</sect4>
	</sect3>

	<sect3 id="doc-ports-install-package">
	<title>Using Documentation Packages</title>

	<para>Building the documentation ports from source, as
	described in the previous section, requires a local
	installation of the documentation toolchain and a bit of
	disk space for the build of the ports. When resources are
	not available to install the documentation toolchain, or
	because the build from sources would take too much disk
	space, it is still possible to install pre-built snapshots
	of the documentation ports.</para>

	<para>The &a.doceng; prepares monthly snapshots of the &os;
	documentation packages. These binary packages can be used
	with any of the bundled package tools, like &man.pkg.add.1;,
	&man.pkg.delete.1;, and so on.</para>

	<note>
	<para>When binary packages are used, the &os; documentation
	will be installed in <emphasis>all</emphasis> available
	formats for the given language.</para>
	</note>

	<para>For example, the following command will install the
	latest pre-built package of the Hungarian
	documentation:</para>

	<screen>&prompt.root; <userinput>pkg_add -r hu-freebsd-doc</userinput></screen>

	<note>
	- <para>Packages have the following name format that differs
	- from the corresponding port's name:
	- <literal><replaceable>lang</replaceable>-freebsd-doc</literal>.
	- Here <replaceable>lang</replaceable> is the short format
	- of the language code, i.e., <literal>hu</literal> for
	+ <para>Packages use a format that differs from the
	+ corresponding port's name:
	+ <literal><replaceable>lang</replaceable>-freebsd-doc</literal>,
	+ where <replaceable>lang</replaceable> is the short format
	+ of the language code, such as <literal>hu</literal> for
	Hungarian, or <literal>zh_cn</literal> for Simplified
	Chinese.</para>
	</note>
	</sect3>

	<sect3 id="doc-ports-update">
	<title>Updating Documentation Ports</title>

	- <para>To update a previously installed documentation port, any
	- tool suitable for updating ports is sufficient. For
	- example, the following command updates the installed
	- Hungarian documentation via the
	- <filename role="package">ports-mgmt/portupgrade</filename>
	- tool by using packages only:</para>
	+ <para>Documentation ports can be updated like any other port.
	+ For example, the following command updates the installed
	+ Hungarian documentation using
	+ <filename role="package">ports-mgmt/portmaster</filename>
	+ by using packages only:</para>

	- <screen>&prompt.root; <userinput>portupgrade -PP hu-freebsd-doc</userinput></screen>
	+ <screen>&prompt.root; <userinput>portmaster -PP hu-freebsd-doc</userinput></screen>
	</sect3>
	</sect2>

	<!-- FIXME: Waiting for a working docsnap server... -->
	<![ IGNORE [
	<sect2 id="docsnap">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Pav</firstname>
	<surname>Lucistnik</surname>
	<contrib>Based on information provided by </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>Using Docsnap</title>

	<indexterm><primary>Updating and Upgrading</primary></indexterm>

	<indexterm>
	<primary>Docsnap</primary>
	<see>Updating and Upgrading</see>
	</indexterm>

	<para><application>Docsnap</application> is an &man.rsync.1;
	- repository for updating installed &os; Documentation in a
	+ repository for updating installed &os; documentation in a
	relatively easy and fast way. A
	<quote><application>Docsnap</application> server</quote>
	tracks the documentation sources, and builds them in HTML
	- format every hour. The
	+ format every hour.
	<filename role="package">textproc/docproj</filename> is
	unneeded with <application>Docsnap</application> as only
	patches to the built documentation exist.</para>

	<para>The only requirement for using this technique is
	the <filename role="package">net/rsync</filename> port or
	- package. To add it, use the following command:</para>
	+ package. To install the package, use the following
	+ command:</para>

	<screen>&prompt.root; <userinput>pkg_add -r rsync</userinput></screen>

	<note>
	- <para><application>Docsnap</application> has been originally
	+ <para><application>Docsnap</application> was originally
	developed for updating documentation installed to
	<filename class="directory">/usr/share/doc</filename>, but
	the following examples could be adapted for other
	- directories as well. For user directories, it does not
	- require <username>root</username> privileges.</para>
	+ directories. Updating to user directories does not require
	+ <username>root</username> privileges.</para>
	</note>

	<para>To update the documentation set, issue the following
	command:</para>

	<screen>&prompt.root; <userinput>rsync -rltvz <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap <replaceable>/usr/share/doc</replaceable></userinput></screen>

	<note>
	<para>There is only one <application>Docsnap</application>
	- server at the moment;
	- the <hostid>docsnap.sk.FreeBSD.org</hostid> shown
	- above.</para>
	+ server at the moment; the
	+ <hostid>docsnap.sk.FreeBSD.org</hostid> shown above.</para>
	</note>

	- <para>Do not use the <option>--delete</option> flag here as
	- there are some items installed into
	- <filename class="directory">/usr/share/doc</filename> during
	- <command>make installworld</command>, which would accidentally
	+ <para>Do not use <option>--delete</option> as there are some
	+ items installed into <filename
	+ class="directory">/usr/share/doc</filename> during
	+ <command>make installworld</command> which would accidentally
	be removed. To clean up, use this command instead:</para>

	<screen>&prompt.root; <userinput>rsync -rltvz --delete <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap/??_??\.\* <replaceable>/usr/share/doc</replaceable></userinput></screen>

	<para>If a subset of documentation needs to be updated, for
	example, the English documentation only, the following command
	should be used:</para>

	<screen>&prompt.root; <userinput>rsync -rltvz <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap/en_US.ISO8859-1 <replaceable>/usr/share/doc</replaceable></userinput></screen>
	</sect2>
	]]>
	</sect1>

	<sect1 id="current-stable">
	<title>Tracking a Development Branch</title>

	<indexterm><primary>-CURRENT</primary></indexterm>
	<indexterm><primary>-STABLE</primary></indexterm>

	- <para>There are two development branches to FreeBSD: &os.current;
	- and &os.stable;. This section will explain a bit about each and
	- describe how to keep your system up-to-date with each respective
	- tree. &os.current; will be discussed first, then
	+ <para>There are two development branches to &os;: &os.current;
	+ and &os.stable;. This section provides an explanation of each
	+ and describes how to keep a system up-to-date with each
	+ respective tree. &os.current; will be discussed first, then
	&os.stable;.</para>

	<sect2 id="current">
	<title>Staying Current with &os;</title>

	- <para>As you read this, keep in mind that &os.current; is the
	- <quote>bleeding edge</quote> of &os; development.
	- &os.current; users are expected to have a high degree of
	- technical skill, and should be capable of solving difficult
	- system problems on their own. If you are new to &os;, think
	- twice before installing it.</para>
	+ <para>&os.current; is the <quote>bleeding edge</quote> of &os;
	+ development. &os.current; users are expected to have a high
	+ degree of technical skill and should be capable of solving
	+ difficult system problems on their own. If you are new to
	+ &os;, track &os.stable; instead.</para>

	<sect3>
	<title>What Is &os.current;?</title>

	<indexterm><primary>snapshot</primary></indexterm>

	<para>&os.current; is the latest working sources for &os;.
	This includes work in progress, experimental changes, and
	transitional mechanisms that might or might not be present
	in the next official release of the software. While many
	&os; developers compile the &os.current; source code daily,
	there are periods of time when the sources are not
	- buildable. These problems are resolved as expeditiously as
	+ buildable. These problems are resolved as quickly as
	possible, but whether or not &os.current; brings disaster or
	- greatly desired functionality can be a matter of which exact
	- moment you grabbed the source code in!</para>
	+ greatly desired functionality can be a matter of when the
	+ source code was synced</para>
	</sect3>

	<sect3>
	<title>Who Needs &os.current;?</title>

	- <para>&os.current; is made available for 3 primary
	+ <para>&os.current; is made available for three primary
	interest groups:</para>

	<orderedlist>
	<listitem>
	<para>Members of the &os; community who are actively
	working on some part of the source tree and for whom
	keeping <quote>current</quote> is an absolute
	requirement.</para>
	</listitem>

	<listitem>
	<para>Members of the &os; community who are active
	testers, willing to spend time solving problems in order
	to ensure that &os.current; remains as sane as possible.
	- These are also people who wish to make topical
	- suggestions on changes and the general direction of
	- &os;, and submit patches to implement them.</para>
	+ These testers wish to make topical suggestions on
	+ changes and the general direction of &os;, and submit
	+ patches to implement them.</para>
	</listitem>

	<listitem>
	<para>Those who merely wish to keep an eye on things, or
	- to use the current sources for reference purposes
	- (e.g., for <emphasis>reading</emphasis>, not running).
	+ to use the current sources for reference purposes.
	These people also make the occasional comment or
	contribute code.</para>
	</listitem>
	</orderedlist>
	</sect3>

	<sect3>
	<title>What Is &os.current; <emphasis>Not</emphasis>?</title>

	<orderedlist>
	<listitem>
	- <para>A fast-track to getting pre-release bits because you
	- heard there is some cool new feature in there and you
	- want to be the first on your block to have it. Being
	- the first on the block to get the new feature means that
	- you are the first on the block to get the new
	- bugs.</para>
	+ <para>A fast-track to getting new features before the next
	+ release. Pre-release features are not yet fully tested
	+ and most likely contain bugs.</para>
	</listitem>

	<listitem>
	- <para>A quick way of getting bug fixes. Any given version
	- of &os.current; is just as likely to introduce new bugs
	- as to fix existing ones.</para>
	+ <para>A quick way of getting bug fixes, though the fix is
	+ just as likely to introduce new bugs as to fix existing
	+ ones.</para>
	</listitem>

	<listitem>
	- <para>In any way <quote>officially supported</quote>. We
	- do our best to help people genuinely in one of the 3
	- <quote>legitimate</quote> &os.current; groups, but we
	- simply <emphasis>do not have the time</emphasis> to
	- provide tech support. This is not because we are mean
	- and nasty people who do not like helping people out (we
	- would not even be doing &os; if we were). We simply
	- cannot answer hundreds messages a day
	- <emphasis>and</emphasis> work on FreeBSD! Given the
	- choice between improving &os; and answering lots of
	- questions on experimental code, the developers opt for
	- the former.</para>
	+ <para>In no way <quote>officially
	+ supported</quote>.</para>
	</listitem>
	</orderedlist>
	</sect3>

	<sect3>
	<title>Using &os.current;</title>

	<indexterm>
	<primary>-CURRENT</primary>
	<secondary>using</secondary>
	</indexterm>
	<orderedlist>
	<listitem>
	<para>Join the &a.current.name; and the
	- &a.svn-src-head.name; lists. This is not just a good
	- idea, it is <emphasis>essential</emphasis>. If you are
	- not on the <emphasis>&a.current.name;</emphasis> list,
	- you will not see the comments that people are making
	- about the current state of the system and thus will
	- probably end up stumbling over a lot of problems that
	- others have already found and solved. Even more
	- importantly, you will miss out on important bulletins
	- which may be critical to your system's continued
	- health.</para>
	+ &a.svn-src-head.name; lists. This is
	+ <emphasis>essential</emphasis> in order to see the
	+ comments that people are making about the current state
	+ of the system and to receive important bulletins which
	+ may be critical to the system's continued health.</para>

	- <para>The &a.svn-src-head.name; list will allow you to see
	- the commit log entry for each change as it is made,
	- along with any pertinent information on possible
	- side-effects.</para>
	+ <para>The &a.svn-src-head.name; list records the commit
	+ log entry for each change as it is made, along with any
	+ pertinent information on possible side-effects.</para>

	- <para>To join these lists, or one of the others available
	- go to &a.mailman.lists.link; and click on the list that
	- you wish to subscribe to. Instructions on the rest of
	- the procedure are available there. If you are
	- interested in tracking changes for the whole source
	- tree, we would recommend subscribing to the
	- &a.svn-src-all.name; list.</para>
	+ <para>To join these lists, go to &a.mailman.lists.link;,
	+ click on the list to subscribe to, and follow the
	+ instructions. In order to track changes to the whole
	+ source tree, subscribe to the &a.svn-src-all.name;
	+ list.</para>
	</listitem>

	<listitem>
	<para>Grab the sources from a &os;
	- <link linkend="mirrors">mirror site</link>. You can do
	- this in one of several ways:</para>
	+ <link linkend="mirrors">mirror site</link> using
	+ one of the following methods:</para>

	<orderedlist>
	<indexterm>
	<primary>Subversion</primary>
	</indexterm>
	<indexterm>
	<primary><command>cron</command></primary>
	</indexterm>
	<indexterm>
	<primary>-CURRENT</primary>
	<secondary>Syncing with
	<application>Subversion</application>
	</secondary>
	</indexterm>
	<indexterm>
	<primary>-CURRENT</primary>
	<secondary>Syncing with
	<application>CTM</application>
	</secondary>
	</indexterm>

	<listitem>
	- <para>Use the <link linkend="svn">svn</link> program
	- to check out the desired development or release
	- branch. This is the recommended method, providing
	- access to &os; development as it occurs. Checkout
	- the -CURRENT code from the <literal>head</literal>
	- branch of one of the
	- <link linkend="svn-mirrors">Subversion mirror
	- sites</link>. Because of the size of the
	- repository, it is recommended that only desired
	- subtrees be checked out.</para>
	+ <para>Use <link linkend="svn">svn</link> to check out
	+ the desired development or release branch. This is
	+ the recommended method, providing access to &os;
	+ development as it occurs. Checkout the -CURRENT
	+ code from the <literal>head</literal> branch of one
	+ of the <link linkend="svn-mirrors">Subversion mirror
	+ sites</link>. Due to the size of the repository,
	+ it is recommended that only desired subtrees be
	+ checked out.</para>
	</listitem>

	<listitem>
	<indexterm>
	<primary>-CURRENT</primary>
	<secondary>Syncing with CTM</secondary>
	</indexterm>

	<para>Use the <application><link
	linkend="ctm">CTM</link></application> facility.
	- If you have very bad connectivity (high price
	- connections or only email access)
	- <application>CTM</application> is an option.
	- However, it is a lot of hassle and can give you
	- broken files. This leads to it being rarely used,
	- which again increases the chance of it not working
	- for fairly long periods of time. We recommend using
	- <application><link
	- linkend="svn">Subversion</link></application> for
	- any system with Internet connectivity.</para>
	+ If you have bad connectivity such as high price
	+ connections or only email access,
	+ <application>CTM</application> is an option, but it
	+ is not as reliable as <application><link
	+ linkend="svn">Subversion</link></application>.
	+ For this reason, <application><link
	+ linkend="svn">Subversion</link></application>
	+ is the recommended method for any system with
	+ Internet connectivity.</para>
	</listitem>
	</orderedlist>
	</listitem>

	<listitem>
	- <para>If you are grabbing the sources to run, and not just
	- look at, then grab <emphasis>all</emphasis> of
	- &os.current;, not just selected portions. The reason
	- for this is that various parts of the source depend on
	- updates elsewhere, and trying to compile just a subset
	- is almost guaranteed to get you into trouble.</para>
	+ <para>If you plan to run, and not just look at the
	+ sources, download <emphasis>all</emphasis> of
	+ &os.current;, not just selected portions. Various parts
	+ of the source depend on updates elsewhere, and trying to
	+ compile just a subset is almost guaranteed to cause
	+ problems.</para>

	<indexterm>
	<primary>-CURRENT</primary>
	<secondary>compiling</secondary>
	</indexterm>
	- <para>Before compiling &os.current;, read the
	- <filename>Makefile</filename> in
	- <filename>/usr/src</filename> carefully. You should at
	- least <link linkend="makeworld">install a new kernel and
	+ <para>Before compiling &os.current;, read
	+ <filename>/usr/src/Makefile</filename> very carefully.
	+ <link linkend="makeworld">Install a new kernel and
	rebuild the world</link> the first time through as part
	- of the upgrading process. Reading the &a.current; and
	- <filename>/usr/src/UPDATING</filename> will keep you
	+ of the upgrading process. Read the &a.current; and
	+ <filename>/usr/src/UPDATING</filename> to stay
	up-to-date on other bootstrapping procedures that
	- sometimes become necessary as we move toward the next
	+ sometimes become necessary on the road to the next
	release.</para>
	</listitem>

	<listitem>
	- <para>Be active! If you are running &os.current;, we want
	- to know what you have to say about it, especially if you
	- have suggestions for enhancements or bug fixes.
	+ <para>Be active! &os.current; users are encouraged to
	+ submit their suggestions for enhancements or bug fixes.
	Suggestions with accompanying code are received most
	enthusiastically!</para>
	</listitem>
	</orderedlist>
	</sect3>
	</sect2>

	<sect2 id="stable">
	<title>Staying Stable with &os;</title>

	<sect3>
	<title>What Is &os.stable;?</title>

	<indexterm><primary>-STABLE</primary></indexterm>

	- <para>&os.stable; is our development branch from which major
	+ <para>&os.stable; is the development branch from which major
	releases are made. Changes go into this branch at a
	different pace, and with the general assumption that they
	have first gone into &os.current; for testing. This is
	<emphasis>still</emphasis> a development branch, however,
	and this means that at any given time, the sources for
	&os.stable; may or may not be suitable for any particular
	purpose. It is simply another engineering development
	track, not a resource for end-users.</para>
	</sect3>

	<sect3>
	<title>Who Needs &os.stable;?</title>

	- <para>If you are interested in tracking or contributing to the
	+ <para>Those interested in tracking or contributing to the
	FreeBSD development process, especially as it relates to the
	- next <quote>point</quote> release of FreeBSD, then you
	- should consider following &os.stable;.</para>
	+ next <quote>point</quote> release of FreeBSD, should
	+ consider following &os.stable;.</para>

	- <para>While it is true that security fixes also go into the
	- &os.stable; branch, you do not <emphasis>need</emphasis> to
	- track &os.stable; to do this. Every security advisory for
	- FreeBSD explains how to fix the problem for the releases it
	- affects
	+ <para>While security fixes go into the &os.stable; branch, one
	+ does not <emphasis>need</emphasis> to track &os.stable; to
	+ receive security fixes. Every security advisory for &os;
	+ explains how to fix the problem for the releases it
	+ affects which are not yet EOL.

	<footnote>
	- <para>That is not quite true. We can not continue
	- to support old releases of FreeBSD forever, although we
	- do support them for many years. For a complete
	- description of the current security policy for old
	- releases of FreeBSD, please see <ulink
	- url="&url.base;/security/">http://www.FreeBSD.org/security/</ulink>.</para></footnote>,
	- and tracking an entire development branch just
	- for security reasons is likely to bring in a lot of unwanted
	- changes as well.</para>
	+ <para>For a complete description of the current security
	+ policy for old releases of FreeBSD, refer to <ulink
	+ url="&url.base;/security/">http://www.FreeBSD.org/security/</ulink>.</para></footnote>.</para>

	- <para>Although we endeavor to ensure that the &os.stable;
	- branch compiles and runs at all times, this cannot be
	- guaranteed. In addition, while code is developed in
	- &os.current; before including it in &os.stable;, more people
	- run &os.stable; than &os.current;, so it is inevitable that
	- bugs and corner cases will sometimes be found in &os.stable;
	- that were not apparent in &os.current;.</para>
	+ <para>While the &os.stable; branch should compile and run at
	+ all times, this cannot be guaranteed. While code is
	+ developed in &os.current; before including it in
	+ &os.stable;, more people run &os.stable; than &os.current;,
	+ so it is inevitable that bugs and corner cases will
	+ sometimes be found in &os.stable; that were not apparent in
	+ &os.current;.</para>

	- <para>For these reasons, we do <emphasis>not</emphasis>
	- recommend that you blindly track &os.stable;, and it is
	- particularly important that you do not update any production
	- servers to &os.stable; without first thoroughly testing the
	- code in your development environment.</para>
	+ <para>For these reasons, one should <emphasis>not</emphasis>
	+ blindly track &os.stable;. It is particularly important not
	+ to update any production servers to &os.stable; without
	+ first thoroughly testing the code in that development
	+ environment.</para>

	- <para>If you do not have the resources to do this then we
	- recommend that you run the most recent release of FreeBSD,
	- and use the binary update mechanism to move from release to
	- release.</para>
	+ <para>Except for those users who have the resources to perform
	+ testing, it is recommended that users instead run the most
	+ recent release of FreeBSD, and use the binary update
	+ mechanism to move from release to release.</para>
	</sect3>

	<sect3>
	<title>Using &os.stable;</title>

	<indexterm>
	<primary>-STABLE</primary>
	<secondary>using</secondary>
	</indexterm>
	<orderedlist>
	<listitem>
	- <para>Join the &a.stable.name; list. This will keep you
	+ <para>Join the &a.stable.name; list in order to stay
	informed of build-dependencies that may appear in
	&os.stable; or any other issues requiring special
	attention. Developers will also make announcements in
	this mailing list when they are contemplating some
	controversial fix or update, giving the users a chance
	to respond if they have any issues to raise concerning
	the proposed change.</para>

	<para>Join the relevant <application>SVN</application>
	- list for the branch you are tracking. For example, if
	- you are tracking the 9-STABLE branch, join the
	- &a.svn-src-stable-9.name; list. This will allow you to
	- view the commit log entry for each change as it is made,
	- along with any pertinent information on possible
	+ list for the branch being tracked. For example, users
	+ tracking the 9-STABLE branch should join the
	+ &a.svn-src-stable-9.name; list. This list records the
	+ commit log entry for each change as it is made, along
	+ with any pertinent information on possible
	side-effects.</para>

	- <para>To join these lists, or one of the others available
	- go to &a.mailman.lists.link; and click on the list that
	- you wish to subscribe to. Instructions on the rest of
	- the procedure are available there. If you are
	- interested in tracking changes for the whole source
	- tree, we would recommend subscribing to the
	- &a.svn-src-all.name; list.</para>
	+ <para>To join these lists,
	+ go to &a.mailman.lists.link;, click on the list to
	+ subscribe to, and follow the instructions. In order to
	+ track changes for the whole source tree, subscribe to
	+ &a.svn-src-all.name;.</para>
	</listitem>

	<listitem>
	- <para>If you are going to install a new system and want it
	- to run monthly snapshot built from &os.stable;, please
	- check the
	- <ulink url="&url.base;/snapshots/">Snapshots</ulink> web
	- page for more information. Alternatively, it is
	- possible to install the most recent &os.stable; release
	- from the <link linkend="mirrors">mirror sites</link> and
	- follow the instructions below to upgrade your system to
	- the most up to date &os.stable; source code.</para>
	+ <para>To install a new system in order to run monthly
	+ snapshots built from &os.stable;, refer to <ulink
	+ url="&url.base;/snapshots/">Snapshots</ulink>for more
	+ information. Alternatively, it is possible to install
	+ the most recent &os.stable; release from the <link
	+ linkend="mirrors">mirror sites</link> and follow the
	+ instructions below to upgrade the system to the most
	+ up-to-date &os.stable; source code.</para>

	- <para>If you are already running a previous release of
	- &os; and wish to upgrade via sources then you can easily
	- do so from a &os;
	- <link linkend="mirrors">mirror site</link>. This can be
	- done in one of several ways:</para>
	+ <para>Several methods are available to upgrade from a &os;
	+ <link linkend="mirrors">mirror site</link> on a system
	+ already running a previous release of &os;:</para>

	<orderedlist>
	<indexterm>
	<primary>Subversion</primary>
	</indexterm>
	<indexterm>
	<primary><command>cron</command></primary>
	</indexterm>
	<indexterm>
	<primary>-STABLE</primary>
	<secondary>syncing with
	<application>Subversion</application></secondary>
	</indexterm>

	<listitem>
	- <para>Use the <link linkend="svn">svn</link> program
	- to check out the desired development or release
	- branch. This is the recommended method, providing
	- access to &os; development as it occurs. Branch
	- names include <literal>head</literal> for the
	- current development head, and branches identified in
	- <ulink url="&url.base;/releng/">the release
	- engineering page</ulink>, such as
	- <literal>stable/9</literal> or
	- <literal>releng/9.0</literal>. URL
	- prefixes for <application>Subversion</application>
	- checkout of the base system are shown in <link
	+ <para>Use <link linkend="svn">svn</link> to check out
	+ the desired development or release branch. This is
	+ the recommended method, providing access to &os;
	+ development as it occurs. Branch names include
	+ <literal>head</literal> for the current development
	+ head, and branches identified in <ulink
	+ url="&url.base;/releng/">the release engineering
	+ page</ulink>, such as <literal>stable/9</literal>
	+ or <literal>releng/9.0</literal>. URL prefixes for
	+ <application>Subversion</application> checkout of
	+ the base system are shown in <link
	linkend="svn-mirrors">Subversion mirror
	sites</link>.
	Because of the size of the repository, it is
	recommended that only desired subtrees be checked
	out.</para>
	</listitem>

	<listitem>
	<indexterm>
	<primary>-STABLE</primary>
	<secondary>syncing with CTM</secondary>
	</indexterm>

	- <para>Use the <application><link
	- linkend="ctm">CTM</link></application> facility.
	- If you do not have a fast and inexpensive connection
	- to the Internet, this is the method you should
	- consider using.</para>
	+ <para>Consider using <application><link
	+ linkend="ctm">CTM</link></application> if you do
	+ not have a fast connection to the Internet.</para>
	</listitem>
	</orderedlist>
	</listitem>

	<listitem>
	- <para>Essentially, if you need rapid on-demand access to
	- the source and communications bandwidth is not a
	- consideration, use
	+ <para>If you need rapid on-demand access to the source and
	+ communications bandwidth is not a consideration, use
	<application>Subversion</application>. Otherwise, use
	<application>CTM</application>.</para>
	</listitem>

	<listitem>
	<indexterm>
	<primary>-STABLE</primary>
	<secondary>compiling</secondary>
	</indexterm>

	- <para>Before compiling &os.stable;, read the
	- <filename>Makefile</filename> in
	- <filename>/usr/src</filename> carefully. You should at
	- least <link linkend="makeworld">install a new kernel and
	- rebuild the world</link> the first time through as part
	- of the upgrading process. Reading the &a.stable; and
	- <filename>/usr/src/UPDATING</filename> will keep you
	+ <para>Before compiling &os.stable;, read
	+ <filename>/usr/src/Makefile</filename> carefully. <link
	+ linkend="makeworld">Install a new kernel and rebuild
	+ the world</link> the first time through as part of the
	+ upgrading process. Read &a.stable; and
	+ <filename>/usr/src/UPDATING</filename> to keep
	up-to-date on other bootstrapping procedures that
	- sometimes become necessary as we move toward the next
	+ sometimes become necessary on the road to the next
	release.</para>
	</listitem>
	</orderedlist>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="synching">
	- <title>Synchronizing Your Source</title>
	+ <title>Synchronizing Source</title>

	- <para>There are various ways of using an Internet (or email)
	- connection to stay up-to-date with any given area of the &os;
	- project sources, or all areas, depending on what interests you.
	- The primary services we offer are
	- <link linkend="svn">Subversion</link> and
	- <link linkend="ctm">CTM</link>.</para>
	+ <para>There are various ways of using an Internet or email
	+ connection to stay up-to-date with any given area, or all areas,
	+ of the &os; project sources. The primary services are <link
	+ linkend="svn">Subversion</link> and <link
	+ linkend="ctm">CTM</link>.</para>

	<warning>
	- <para>While it is possible to update only parts of your source
	+ <para>While it is possible to update only parts of the source
	tree, the only supported update procedure is to update the
	- entire tree and recompile both userland (i.e., all the
	- programs that run in user space, such as those in
	- <filename>/bin</filename> and <filename>/sbin</filename>) and
	- kernel sources. Updating only part of your source tree, only
	- the kernel, or only userland will often result in problems.
	- These problems may range from compile errors to kernel panics
	- or data corruption.</para>
	+ entire tree and recompile all the programs that run in user
	+ space, such as those in <filename>/bin</filename> and
	+ <filename>/sbin</filename>, and kernel sources. Updating only
	+ part of the source tree, only the kernel, or only the userland
	+ programs will often result in problems ranging from compile
	+ errors to kernel panics or data corruption.</para>
	</warning>

	<indexterm>
	<primary>Subversion</primary>
	</indexterm>

	<para><application>Subversion</application> uses the
	- <emphasis>pull</emphasis> model of updating sources. The user
	- (or a <command>cron</command> script) invokes the
	+ <emphasis>pull</emphasis> model of updating sources. The user,
	+ or a <command>cron</command> script, invokes the
	<command>svn</command> program, and it brings files up-to-date.
	<application>Subversion</application> is the preferred means of
	- updating local source trees. The updates you receive are
	- up-to-the-minute and you get them when, and only when, you want
	- them. You can easily restrict your updates to the specific
	- files or directories that are of interest to you. Updates are
	- generated on the fly by the server, according to what you have
	- and what you want to have.</para>
	+ updating local source trees. The updates are up-to-the-minute
	+ and the user controls when they are downloaded. It is easy to
	+ restrict updates to specific files or directories and the
	+ requested updates are generated on the fly by the server.</para>

	<indexterm>
	<primary><application>CTM</application></primary>
	</indexterm>
	- <para><application>CTM</application>, on the other hand, does not
	- interactively compare the sources you have with those on the
	- master archive or otherwise pull them across. Instead, a script
	- which identifies changes in files since its previous run is
	- executed several times a day on the master CTM machine, any
	- detected changes being compressed, stamped with a
	- sequence-number and encoded for transmission over email (in
	- printable ASCII only). Once received, these
	- <quote>CTM deltas</quote> can then be handed to the
	+ <para><application>CTM</application> does not interactively
	+ compare the local sources with those on the master archive or
	+ otherwise pull them across. Instead, a script which identifies
	+ changes in files since its previous run is executed several
	+ times a day on the master CTM machine. Any detected changes are
	+ compressed, stamped with a sequence-number, and encoded for
	+ transmission over email in printable ASCII only. Once received,
	+ these <quote>CTM deltas</quote> can then be handed to the
	&man.ctm.rmail.1; utility which will automatically decode,
	- verify and apply the changes to the user's copy of the sources.
	- This process is far more efficient than
	- <application>Subversion</application>, and places less strain on
	- our server resources since it is a <emphasis>push</emphasis>
	+ verify, and apply the changes to the user's copy of the sources.
	+ This process is more efficient than
	+ <application>Subversion</application> and places less strain on
	+ server resources since it is a <emphasis>push</emphasis>
	rather than a <emphasis>pull</emphasis> model.</para>

	- <para>There are other trade-offs, of course. If you inadvertently
	- wipe out portions of your archive,
	+ <para>There are other trade-offs. If a user inadvertently
	+ wipes out portions of the local archive,
	<application>Subversion</application> will detect and rebuild
	- the damaged portions for you. <application>CTM</application>
	- will not do this, and if you wipe some portion of your source
	- tree out (and do not have it backed up) then you will have to
	- start from scratch (from the most recent CTM
	- <quote>base delta</quote>) and rebuild it all with
	- <application>CTM</application>.</para>
	+ the damaged portions. <application>CTM</application> will not
	+ do this, and if a user deletes some portion of the source tree
	+ and does not have a backup, they will have to start from scratch
	+ from the most recent CTM <quote>base delta</quote> and rebuild
	+ it all with <application>CTM</application>.</para>
	</sect1>

	<sect1 id="makeworld">
	<title>Rebuilding <quote>world</quote></title>

	<indexterm>
	<primary>Rebuilding <quote>world</quote></primary>
	</indexterm>
	- <para>Once you have synchronized your local source tree against a
	- particular version of &os; (&os.stable;, &os.current;, and so
	- on) you can then use the source tree to rebuild the
	- system.</para>
	+ <para>Once the local source tree is synchronized against a
	+ particular version of &os; such as &os.stable; or &os.current;,
	+ the source tree can be used to rebuild the system.</para>

	<warning>
	<title>Make a Backup</title>

	<para>It cannot be stressed enough how important it is to make a
	- backup of your system <emphasis>before</emphasis> you do this.
	- While rebuilding the world is (as long as you follow these
	- instructions) an easy task to do, there will inevitably be
	- times when you make mistakes, or when mistakes made by others
	- in the source tree render your system unbootable.</para>
	+ backup of the system <emphasis>before</emphasis> rebuilding
	+ the system. While rebuilding the world is an easy task, there
	+ will inevitably be times when mistakes in the source tree
	+ render the system unbootable.</para>

	- <para>Make sure you have taken a backup. And have a fixit
	- floppy or bootable CD at hand. You will probably never have
	+ <para>Create and verify a backup and have a bootable
	+ installation media at hand. You will probably never have
	to use it, but it is better to be safe than sorry!</para>
	</warning>

	<warning>
	<title>Subscribe to the Right Mailing List</title>

	<indexterm><primary>mailing list</primary></indexterm>
	<para>The &os.stable; and &os.current; branches are, by their
	nature, <emphasis>in development</emphasis>. People that
	contribute to &os; are human, and mistakes occasionally
	happen.</para>

	<para>Sometimes these mistakes can be quite harmless, just
	- causing your system to print a new diagnostic warning. Or the
	- change may be catastrophic, and render your system unbootable
	- or destroy your file systems (or worse).</para>
	+ causing the system to print a new diagnostic warning. Or the
	+ change may be catastrophic, and render the system unbootable
	+ or destroy file systems.</para>

	- <para>If problems like these occur, a <quote>heads up</quote> is
	+ <para>When problems occur, a <quote>heads up</quote> is
	posted to the appropriate mailing list, explaining the nature
	- of the problem and which systems it affects. And an
	- <quote>all clear</quote> announcement is posted when the
	- problem has been solved.</para>
	+ of the problem and which systems it affects. An <quote>all
	+ clear</quote> announcement is posted when the problem has
	+ been solved.</para>

	- <para>If you try to track &os.stable; or &os.current; and do
	- not read the &a.stable; or the &a.current; respectively, then
	- you are asking for trouble.</para>
	+ <para>Users who track &os.stable; or &os.current; and do
	+ not read &a.stable; or &a.current; respectively, are asking
	+ for trouble.</para>
	</warning>

	<warning>
	<title>Do Not Use <command>make world</command></title>

	- <para>A lot of older documentation recommends using
	- <command>make world</command> for this. Doing that skips
	- some important steps and should only be used if you are
	- sure of what you are doing. For almost all circumstances
	- <command>make world</command> is the wrong thing to do, and
	- the procedure described here should be used instead.</para>
	+ <para>Some older documentation recommends using
	+ <command>make world</command>. However, that command skips
	+ some important steps and should only be used by experts. For
	+ almost all circumstances <command>make world</command> is the
	+ wrong thing to do, and the procedure described here should be
	+ used instead.</para>
	</warning>

	<sect2 id="canonical-build">
	<title>The Canonical Way to Update Your System</title>

	- <para>To update your system, you should check
	+ <para>Before updating the system, read
	<filename>/usr/src/UPDATING</filename> for any pre-buildworld
	- steps necessary for your version of the sources and then use
	+ steps necessary for that version of the sources. Then, use
	the procedure outlined here.</para>

	- <para>These upgrade steps assume that you are currently using an
	- old &os; version, consisting of an old compiler, old kernel,
	- old world and old configuration files. By
	- <quote>world</quote> here we mean the core system binaries,
	- libraries and programming files. The compiler is part of
	+ <para>These upgrade steps assume an upgrade from an older &os;
	+ version, consisting of an old compiler, old kernel,
	+ old world, and old configuration files.
	+ <quote>World</quote> includes the core system binaries,
	+ libraries, and programming files. The compiler is part of
	<quote>world</quote>, but has a few special concerns.</para>

	- <para>We also assume that you have already obtained the sources
	- to a newer system. If the sources available on the particular
	- system are old too, see <xref linkend="synching"/> for
	- detailed help about synchronizing them to a newer
	- version.</para>
	+ <para>These steps also assume that the sources to a newer
	+ version have already been obtained. If the sources are not
	+ up-to-date, refer to <xref linkend="synching"/> for detailed
	+ help about synchronizing to a newer version.</para>

	- <para>Updating the system from sources is a bit more subtle than
	- it might initially seem to be, and the &os; developers have
	+ <para>Updating the system from source is a more subtle process
	+ than it might initially seem to be, and the &os; developers have
	found it necessary over the years to change the recommended
	approach fairly dramatically as new kinds of unavoidable
	dependencies come to light. The rest of this section
	describes the rationale behind the currently recommended
	upgrade sequence.</para>

	<para>Any successful update sequence must deal with the
	following issues:</para>

	<itemizedlist>
	<listitem>
	- <para>The old compiler might not be able to compile the new
	- kernel. (Old compilers sometimes have bugs.) So, the new
	- kernel should be built with the new compiler. In
	- particular, the new compiler must be built before the new
	- kernel is built. This does not necessarily mean that the
	- new compiler must be <emphasis>installed</emphasis> before
	- building the new kernel.</para>
	+ <para>The old compiler might have a bug and not be able to
	+ compile the new kernel. So, the new kernel should be
	+ built with the new compiler, meaning that the new compiler
	+ must be built before the new kernel is built. This does
	+ not necessarily mean that the new compiler must be
	+ <emphasis>installed</emphasis> before building the new
	+ kernel.</para>
	</listitem>

	<listitem>
	<para>The new world might rely on new kernel features. So,
	the new kernel must be installed before the new world is
	installed.</para>
	</listitem>
	</itemizedlist>

	<para>These first two issues are the basis for the
	core <maketarget>buildworld</maketarget>,
	<maketarget>buildkernel</maketarget>,
	<maketarget>installkernel</maketarget>,
	- <maketarget>installworld</maketarget> sequence that we
	- describe in the following paragraphs. This is not an
	- exhaustive list of all the reasons why you should prefer the
	- currently recommended upgrade process. Some of the less
	- obvious ones are listed below:</para>
	+ <maketarget>installworld</maketarget> sequence described in
	+ the following paragraphs. Other reasons for using these
	+ steps are listed below:</para>

	<itemizedlist>
	<listitem>
	<para>The old world might not run correctly on the new
	- kernel, so you must install the new world immediately upon
	- installing the new kernel.</para>
	+ kernel, so the new world must be installed immediately
	+ upon installing the new kernel.</para>
	</listitem>

	<listitem>
	- <para>Some configuration changes must be done before the new
	+ <para>Some configuration changes must be made before the new
	world is installed, but others might break the old world.
	Hence, two different configuration upgrade steps are
	generally needed.</para>
	</listitem>

	<listitem>
	<para>For the most part, the update process only replaces or
	- adds files; existing old files are not deleted. In a few
	- cases, this can cause problems. As a result, the update
	- procedure will sometimes specify certain files that should
	- be manually deleted at certain steps. This may or may not
	- be automated in the future.</para>
	+ adds files and existing old files are not deleted. In a
	+ few cases, this can cause problems. As a result, the
	+ update procedure will sometimes specify certain files that
	+ should be manually deleted at certain steps. This may or
	+ may not be automated in the future.</para>
	</listitem>
	</itemizedlist>

	<para>These concerns have led to the following recommended
	sequence. Note that the detailed sequence for particular
	updates may require additional steps, but this core process
	should remain unchanged for some time:</para>

	<orderedlist>
	<listitem>
	<para><command>make
	<maketarget>buildworld</maketarget></command></para>

	<para>This first compiles the new compiler and a few related
	tools, then uses the new compiler to compile the rest of
	the new world. The result ends up in
	<filename class="directory">/usr/obj</filename>.</para>
	</listitem>

	<listitem>
	<para><command>make
	<maketarget>buildkernel</maketarget></command></para>

	- <para>Unlike the older approach, using &man.config.8; and
	- &man.make.1;, this uses the <emphasis>new</emphasis>
	- compiler residing in
	- <filename class="directory">/usr/obj</filename>. This
	- protects you against compiler-kernel mismatches.</para>
	+ <para>This uses the <emphasis>new</emphasis> compiler
	+ residing in <filename
	+ class="directory">/usr/obj</filename> in order to
	+ protect against compiler-kernel mismatches.</para>
	</listitem>

	<listitem>
	<para><command>make
	<maketarget>installkernel</maketarget></command></para>

	<para>Place the new kernel and kernel modules onto the disk,
	making it possible to boot with the newly updated
	kernel.</para>
	</listitem>

	<listitem>
	<para>Reboot into single user mode.</para>

	<para>Single user mode minimizes problems from updating
	software that is already running. It also minimizes any
	problems from running the old world on a new
	kernel.</para>
	</listitem>

	<listitem>
	<para><command>mergemaster
	<option>-p</option></command></para>

	<para>This does some initial configuration file updates in
	- preparation for the new world. For instance it may add
	+ preparation for the new world. For instance, it may add
	new user groups to the system, or new user names to the
	password database. This is often necessary when new
	groups or special system-user accounts have been added
	since the last update, so that the
	<maketarget>installworld</maketarget> step will be able to
	use the newly installed system user or system group names
	without problems.</para>
	</listitem>

	<listitem>
	<para><command>make
	<maketarget>installworld</maketarget></command></para>

	<para>Copies the world
	- from <filename class="directory">/usr/obj</filename>. You
	- now have a new kernel and new world on disk.</para>
	+ from <filename class="directory">/usr/obj</filename>. The
	+ new kernel and new world are now installed on disk.</para>
	</listitem>

	<listitem>
	<para><command>mergemaster</command></para>

	- <para>Now you can update the remaining configuration files,
	- since you have a new world on disk.</para>
	+ <para>Repeated to update the remaining configuration files,
	+ now that the new world is on disk.</para>
	</listitem>

	<listitem>
	<para>Reboot.</para>

	<para>A full machine reboot is needed now to load the new
	kernel and new world with new configuration files.</para>
	</listitem>
	</orderedlist>

	- <para>Note that if you are upgrading from one release of the
	- same &os; branch to a more recent release of the same branch,
	- i.e., from 7.0 to 7.1, then this procedure may not be
	- absolutely necessary, since you are unlikely to run into
	- serious mismatches between compiler, kernel, userland and
	- configuration files. The older approach of
	+ <para>Upgrades from one release of the same &os; branch to a
	+ more recent release of the same branch, such as from 9.0 to
	+ 9.1, may not need this procedure since it is less likely to
	+ run into serious mismatches between compiler, kernel,
	+ userland, and configuration files. The approach of
	<command>make <maketarget>world</maketarget></command>
	followed by building and installing a new kernel might work
	well enough for minor updates.</para>

	- <para>But, when upgrading across major releases, people who do
	- not follow this procedure should expect some problems.</para>
	+ <para>When upgrading across major releases, people who do not
	+ follow this procedure should expect some problems.</para>

	- <para>It is also worth noting that many upgrades
	- (i.e., 4.<replaceable>X</replaceable> to 5.0) may require
	- specific additional steps (renaming or deleting specific files
	- prior to installworld, for instance). Read the
	- <filename>/usr/src/UPDATING</filename> file carefully,
	- especially at the end, where the currently recommended upgrade
	- sequence is explicitly spelled out.</para>
	+ <para>It is also worth noting that many upgrades may require
	+ specific additional steps such as renaming or deleting
	+ specific files prior to installworld. Read
	+ <filename>/usr/src/UPDATING</filename> carefully, especially
	+ at the end, where the currently recommended upgrade sequence
	+ is explicitly spelled out.</para>

	<para>This procedure has evolved over time as the developers
	have found it impossible to completely prevent certain kinds
	of mismatch problems. Hopefully, the current procedure will
	remain stable for a long time.</para>

	<para>To summarize, the currently recommended way of upgrading
	&os; from sources is:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput>
	&prompt.root; <userinput>make buildworld</userinput>
	&prompt.root; <userinput>make buildkernel</userinput>
	&prompt.root; <userinput>make installkernel</userinput>
	&prompt.root; <userinput>shutdown -r now</userinput></screen>

	<note>
	<para>There are a few rare cases when an extra run of
	<command>mergemaster -p</command> is needed before the
	<maketarget>buildworld</maketarget> step. These are
	described in <filename>UPDATING</filename>. In general,
	- though, you can safely omit this step if you are not
	- updating across one or more major &os; versions.</para>
	+ though, this step can safely be omitted when not updating
	+ across one or more major &os; versions.</para>
	</note>

	<para>After <maketarget>installkernel</maketarget> finishes
	- successfully, you should boot in single user mode
	- (i.e., using <command>boot -s</command> from the loader
	- prompt). Then run:</para>
	+ successfully, boot into single user mode using <command>boot
	+ -s</command> from the loader prompt. Then run:</para>

	<screen>&prompt.root; <userinput>mount -u /</userinput>
	&prompt.root; <userinput>mount -a -t ufs</userinput>
	&prompt.root; <userinput>adjkerntz -i</userinput>
	&prompt.root; <userinput>mergemaster -p</userinput>
	&prompt.root; <userinput>cd /usr/src</userinput>
	&prompt.root; <userinput>make installworld</userinput>
	&prompt.root; <userinput>mergemaster</userinput>
	&prompt.root; <userinput>reboot</userinput></screen>

	<warning>
	<title>Read Further Explanations</title>

	- <para>The sequence described above is only a short resume to
	- help you getting started. You should however read the
	- following sections to clearly understand each step,
	- especially if you want to use a custom kernel
	- configuration.</para>
	+ <para>The following sections clearly describe each step,
	+ especially when using a custom kernel configuration.</para>
	</warning>
	</sect2>

	<sect2 id="src-updating">
	<title>Read <filename>/usr/src/UPDATING</filename></title>

	- <para>Before you do anything else, read
	- <filename>/usr/src/UPDATING</filename> (or the equivalent file
	- wherever you have a copy of the source code). This file
	- should contain important information about problems you might
	- encounter, or specify the order in which you might have to run
	- certain commands. If <filename>UPDATING</filename>
	- contradicts something you read here,
	- <filename>UPDATING</filename> takes precedence.</para>
	+ <para>Before updating, read
	+ <filename>/usr/src/UPDATING</filename>. This file contains
	+ important information about potential problems and may specify
	+ the order to run certain commands. If
	+ <filename>UPDATING</filename> contradicts the procedure in
	+ this section, <filename>UPDATING</filename> takes
	+ precedence.</para>

	<important>
	<para>Reading <filename>UPDATING</filename> is not an
	acceptable substitute for subscribing to the correct mailing
	- list, as described previously. The two requirements are
	- complementary, not exclusive.</para>
	+ list. The two requirements are complementary, not
	+ exclusive.</para>
	</important>
	</sect2>

	<sect2 id="make-conf">
	<title>Check <filename>/etc/make.conf</filename></title>

	<indexterm>
	<primary><filename>make.conf</filename></primary>
	</indexterm>

	- <para>&man.make.1; options are shown in &man.make.conf.5; and
	+ <para>Available &man.make.1; options are shown in
	+ &man.make.conf.5; and
	<filename>/usr/share/examples/etc/make.conf</filename>. These
	settings can be added to <filename>/etc/make.conf</filename>
	to control the way &man.make.1; runs and how it builds
	programs. Changes to some settings can have far-reaching and
	potentially surprising effects. Read the comments in both
	locations and keep in mind that the defaults have been chosen
	for a combination of performance and safety.</para>

	<para>Options set in <filename>/etc/make.conf</filename> take
	effect every time &man.make.1; is used, including compiling
	applications from the Ports Collection or user-written C
	- programs, or building the &os; operating system itself.</para>
	+ programs, or building the &os; operating system.</para>
	</sect2>

	<sect2 id="src-conf">
	<title>Check <filename>/etc/src.conf</filename></title>

	<indexterm>
	<primary><filename>src.conf</filename></primary>
	</indexterm>

	<para><filename>/etc/src.conf</filename> controls the building
	of the operating system from source code. Unlike
	<filename>/etc/make.conf</filename>, the contents of
	<filename>/etc/src.conf</filename> only take effect when the
	&os; operating system itself is being built. Descriptions of
	the many options available for this file are shown in
	&man.src.conf.5;. Be cautious about disabling seemingly
	unneeded kernel modules and build options. Sometimes there
	are unexpected or subtle interactions.</para>
	</sect2>

	<sect2 id="updating-etc">
	<title>Update the Files in <filename>/etc</filename></title>

	- <para>The <filename>/etc</filename> directory contains a large
	- part of your system's configuration information, as well as
	- scripts that are run at system startup. Some of these scripts
	- change from version to version of FreeBSD.</para>
	+ <para><filename class="directory">/etc</filename> contains a
	+ large part of the system's configuration information, as well
	+ as scripts that are run at system startup. Some of these
	+ scripts change between &os; versions.</para>

	- <para>Some of the configuration files are also used in the day
	- to day running of the system. In particular,
	+ <para>Some of the configuration files are used in the day to
	+ day running of the system, such as
	<filename>/etc/group</filename>.</para>

	<para>There have been occasions when the installation part of
	- <command>make installworld</command> has expected certain
	- usernames or groups to exist. When performing an upgrade it
	- is likely that these users or groups did not exist. This
	- caused problems when upgrading. In some cases
	- <command>make buildworld</command> will check to see if these
	- users or groups exist.</para>
	+ <command>make installworld</command> expected certain
	+ usernames or groups to exist. When performing an upgrade, it
	+ is likely that these users or groups do not yet exist. In
	+ some cases <command>make buildworld</command> will check to
	+ see if these users or groups exist.</para>

	- <para>An example of this is when the <username>smmsp</username>
	- user was added. Users had the installation process fail for
	- them when &man.mtree.8; was trying to create
	- <filename>/var/spool/clientmqueue</filename>.</para>
	-
	<para>The solution is to run &man.mergemaster.8; in
	- pre-buildworld mode by providing the <option>-p</option>
	- option. This will compare only those files that are essential
	- for the success of <maketarget>buildworld</maketarget> or
	+ pre-buildworld mode with <option>-p</option>. This compares
	+ only those files that are essential for the success of
	+ <maketarget>buildworld</maketarget> or
	<maketarget>installworld</maketarget>.</para>

	<tip>
	- <para>If you are feeling particularly paranoid, you can check
	- your system to see which files are owned by the group you
	- are renaming or deleting:</para>
	+ <para>To check which files are owned by the group being
	+ renamed or deleted:</para>

	<screen>&prompt.root; <userinput>find / -group <replaceable>GID</replaceable> -print</userinput></screen>

	- <para>will show all files owned by group
	- <replaceable>GID</replaceable> (which can be either a group
	- name or a numeric group ID).</para>
	+ <para>This command will show all files owned by group
	+ <replaceable>GID</replaceable>, which can be either a group
	+ name or a numeric group ID.</para>
	</tip>
	</sect2>

	<sect2 id="makeworld-singleuser">
	<title>Drop to Single User Mode</title>

	<indexterm><primary>single-user mode</primary></indexterm>

	- <para>You may want to compile the system in single user mode.
	- Apart from the obvious benefit of making things go slightly
	- faster, reinstalling the system will touch a lot of important
	- system files, all the standard system binaries, libraries,
	- include files and so on. Changing these on a running system
	- (particularly if you have active users on the system at the
	- time) is asking for trouble.</para>
	+ <para>Consider compiling the system in single user mode.
	+ Reinstalling the system touches a lot of important system
	+ files, all the standard system binaries, libraries, and
	+ include files. Changing these on a running system,
	+ particularly one with active users, is asking for
	+ trouble.</para>

	<indexterm><primary>multi-user mode</primary></indexterm>
	<para>Another method is to compile the system in multi-user
	mode, and then drop into single user mode for the
	- installation. If you would like to do it this way, simply
	- hold off on the following steps until the build has completed.
	- You can postpone dropping to single user mode until you have
	- to <maketarget>installkernel</maketarget> or
	+ installation. With this method, hold off on the following
	+ steps until the build has completed. Drop to single user mode
	+ in order to run <maketarget>installkernel</maketarget> or
	<maketarget>installworld</maketarget>.</para>

	- <para>As the superuser, you can execute:</para>
	+ <para>To enter single user mode from a running system:</para>

	<screen>&prompt.root; <userinput>shutdown now</userinput></screen>

	- <para>from a running system, which will drop it to single user
	- mode.</para>
	-
	<para>Alternatively, reboot the system, and at the boot prompt,
	- select the <quote>single user</quote> option. The system will
	- then boot single user. At the shell prompt you should then
	- run:</para>
	+ select the <quote>single user</quote> option. Once at the
	+ single user mode shell prompt, run:</para>

	<screen>&prompt.root; <userinput>fsck -p</userinput>
	&prompt.root; <userinput>mount -u /</userinput>
	&prompt.root; <userinput>mount -a -t ufs</userinput>
	&prompt.root; <userinput>swapon -a</userinput></screen>

	<para>This checks the file systems, remounts
	<filename>/</filename> read/write, mounts all the other UFS
	- file systems referenced in <filename>/etc/fstab</filename> and
	- then turns swapping on.</para>
	+ file systems referenced in <filename>/etc/fstab</filename>,
	+ and turns swapping on.</para>

	<note>
	- <para>If your CMOS clock is set to local time and not to GMT
	- (this is true if the output of the &man.date.1; command
	- does not show the correct time and zone),
	- you may also need to run the following command:</para>
	+ <para>If the CMOS clock is set to local time and not to GMT
	+ (this is true if the output of &man.date.1; does not show
	+ the correct time and zone), run the following
	+ command:</para>

	<screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>

	- <para>This will make sure that your local time-zone settings
	- get set up correctly — without this, you may later run
	- into some problems.</para>
	+ <para>This ensures that the local time-zone settings get set
	+ up correctly.</para>
	</note>
	</sect2>

	<sect2 id="cleaning-usr-obj">
	<title>Remove <filename>/usr/obj</filename></title>

	- <para>As parts of the system are rebuilt they are placed in
	- directories which (by default) go under
	- <filename>/usr/obj</filename>. The directories shadow those
	- under <filename>/usr/src</filename>.</para>
	+ <para>As parts of the system are rebuilt, they are, by default,
	+ placed in subdirectories of <filename>/usr/obj</filename>.
	+ The directories shadow those under
	+ <filename>/usr/src</filename>.</para>

	- <para>You can speed up the <command>make buildworld</command>
	- process, and possibly save yourself some dependency headaches
	- by removing this directory as well.</para>
	+ <para>To speed up the <command>make buildworld</command>
	+ process, and possibly save some dependency headaches,
	+ remove this directory if it already exists.</para>

	<para>Some files below <filename>/usr/obj</filename> may have
	- the immutable flag set (see &man.chflags.1; for more
	- information) which must be removed first.</para>
	+ the immutable flag set which must be removed first using
	+ &man.chflags.1;.</para>

	<screen>&prompt.root; <userinput>cd /usr/obj</userinput>
	&prompt.root; <userinput>chflags -R noschg *</userinput>
	&prompt.root; <userinput>rm -rf *</userinput></screen>
	</sect2>

	<sect2 id="updating-upgrading-compilebase">
	<title>Recompile the Base System</title>

	<sect3>
	<title>Saving the Output</title>

	- <para>It is a good idea to save the output you get from
	- running &man.make.1; to another file. If something goes
	- wrong you will have a copy of the error message. While this
	- might not help you in diagnosing what has gone wrong, it can
	- help others if you post your problem to one of the &os;
	- mailing lists.</para>
	+ <para>It is a good idea to save the output from running
	+ &man.make.1; to a file. If something goes wrong, a copy of
	+ the error message can be posted to one of the &os; mailing
	+ lists.</para>

	- <para>The easiest way to do this is to use the &man.script.1;
	- command, with a parameter that specifies the name of the
	- file to save all output to. You would do this immediately
	- before rebuilding the world, and then type
	+ <para>The easiest way to do this is to use &man.script.1;
	+ with a parameter that specifies the name of the file to save
	+ all output to. Run this command immediately before
	+ rebuilding the world, and then type
	<userinput>exit</userinput> when the process has
	- finished.</para>
	+ finished:</para>

	<screen>&prompt.root; <userinput>script /var/tmp/mw.out</userinput>
	Script started, output file is /var/tmp/mw.out
	&prompt.root; <userinput>make TARGET</userinput>
	<emphasis>… compile, compile, compile …</emphasis>
	&prompt.root; <userinput>exit</userinput>
	Script done, …</screen>

	- <para>If you do this, <emphasis>do not</emphasis> save the
	- output in <filename>/tmp</filename>. This directory may be
	- cleared next time you reboot. A better place to store it is
	- in <filename>/var/tmp</filename> (as in the previous
	- example) or in <username>root</username>'s home
	- directory.</para>
	+ <para><emphasis>Do not</emphasis> save the output in <filename
	+ class="directory">/tmp</filename> as this directory may be
	+ cleared at next reboot. A better place to save the file is
	+ <filename class="directory">/var/tmp</filename> or in
	+ <username>root</username>'s home directory.</para>
	</sect3>

	<sect3 id="make-buildworld">
	<title>Compile the Base System</title>

	- <para>You must be in the <filename>/usr/src</filename>
	- directory:</para>
	+ <para>While in <filename class="directory">/usr/src</filename>
	+ type:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>

	- <para>(unless, of course, your source code is elsewhere, in
	- which case change to that directory instead).</para>
	-
	<indexterm><primary><command>make</command></primary></indexterm>

	- <para>To rebuild the world you use the &man.make.1; command.
	- This command reads instructions from the
	- <filename>Makefile</filename>, which describes how the
	- programs that comprise &os; should be rebuilt, the order in
	- which they should be built, and so on.</para>
	+ <para>To rebuild the world, use &man.make.1;. This command
	+ reads instructions from the <filename>Makefile</filename>,
	+ which describes how the programs that comprise &os; should
	+ be built and the order in which they should be built.</para>

	- <para>The general format of the command line you will type is
	- as follows:</para>
	+ <para>The general format of the command is as follows:</para>

	<screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen>

	<para>In this example,
	<option>-<replaceable>x</replaceable></option> is an option
	- that you would pass to &man.make.1;. See the &man.make.1;
	- manual page for an example of the options you can
	- pass.</para>
	+ passed to &man.make.1;. Refer to &man.make.1; for an
	+ examples of available options.</para>

	<para><option>-D<replaceable>VARIABLE</replaceable></option>
	passes a variable to the <filename>Makefile</filename>. The
	behavior of the <filename>Makefile</filename> is controlled
	by these variables. These are the same variables as are set
	in <filename>/etc/make.conf</filename>, and this provides
	- another way of setting them.</para>
	+ another way of setting them. For example:</para>

	<screen>&prompt.root; <userinput>make -DNO_PROFILE <replaceable>target</replaceable></userinput></screen>

	<para>is another way of specifying that profiled libraries
	should not be built, and corresponds with the</para>

	<programlisting>NO_PROFILE= true # Avoid compiling profiled libraries</programlisting>

	<para>line in <filename>/etc/make.conf</filename>.</para>

	<para><replaceable>target</replaceable> tells &man.make.1;
	- what you want to do. Each <filename>Makefile</filename>
	- defines a number of different <quote>targets</quote>, and
	- your choice of target determines what happens.</para>
	+ what to do. Each <filename>Makefile</filename> defines a
	+ number of different <quote>targets</quote>, and the choice
	+ of target determines what happens.</para>

	- <para>Some targets are listed in the
	- <filename>Makefile</filename>, but are not meant for you to
	- run. Instead, they are used by the build process to break
	- out the steps necessary to rebuild the system into a number
	- of sub-steps.</para>
	+ <para>Some targets listed in the
	+ <filename>Makefile</filename> are used by the build process
	+ to break out the steps necessary to rebuild the system into
	+ a number of sub-steps.</para>

	- <para>Most of the time you will not need to pass any
	- parameters to &man.make.1;, and so your command like will
	- look like this:</para>
	+ <para>Most of the time, no parameters need to be passed to
	+ &man.make.1; and the command looks like this:</para>

	<screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen>

	- <para>Where <replaceable>target</replaceable> will be one of
	- many build options. The first target should always be
	+ <para>Where <replaceable>target</replaceable> is one of many
	+ build options. The first target should always be
	<makevar>buildworld</makevar>.</para>

	<para>As the names imply, <maketarget>buildworld</maketarget>
	builds a complete new tree under
	- <filename>/usr/obj</filename>, and
	- <maketarget>installworld</maketarget>, another target,
	- installs this tree on the current machine.</para>
	+ <filename>/usr/obj</filename> and
	+ <maketarget>installworld</maketarget> installs this tree on
	+ the current machine.</para>

	- <para>Having separate options is very useful for two reasons.
	- First, it allows you to do the build safe in the knowledge
	- that no components of your running system will be affected.
	- The build is <quote>self hosted</quote>. Because of this,
	- you can safely run <maketarget>buildworld</maketarget> on a
	+ <para>Having separate options is useful for two reasons.
	+ First, it allows for a <quote>self hosted</quote> build that
	+ does not affect any components of a running system. Because
	+ of this, <maketarget>buildworld</maketarget> can be run on a
	machine running in multi-user mode with no fear of
	- ill-effects. It is still recommended that you run the
	- <maketarget>installworld</maketarget> part in single user
	- mode, though.</para>
	+ ill-effects. It is still recommended that
	+ <maketarget>installworld</maketarget> be run in part in
	+ single user mode, though.</para>

	- <para>Secondly, it allows you to use NFS mounts to upgrade
	- multiple machines on your network. If you have three
	+ <para>Secondly, it allows NFS mounts to be used to upgrade
	+ multiple machines on a network. If order to upgrade three
	machines, <hostid>A</hostid>, <hostid>B</hostid> and
	- <hostid>C</hostid> that you want to upgrade, run
	- <command>make buildworld</command> and
	- <command>make installworld</command> on <hostid>A</hostid>.
	- <hostid>B</hostid> and <hostid>C</hostid> should then NFS
	- mount <filename>/usr/src</filename> and
	+ <hostid>C</hostid>, run <command>make buildworld</command>
	+ and <command>make installworld</command> on
	+ <hostid>A</hostid>. <hostid>B</hostid> and
	+ <hostid>C</hostid> should then NFS mount
	+ <filename>/usr/src</filename> and
	<filename>/usr/obj</filename> from <hostid>A</hostid>, and
	- you can then run <command>make installworld</command> to
	- install the results of the build on <hostid>B</hostid> and
	+ run <command>make installworld</command> to install the
	+ results of the build on <hostid>B</hostid> and
	<hostid>C</hostid>.</para>

	<para>Although the <maketarget>world</maketarget> target still
	- exists, you are strongly encouraged not to use it.</para>
	+ exists, users are strongly encouraged not to use it.</para>

	- <para>Run</para>
	+ <para>Instead, run:</para>

	<screen>&prompt.root; <userinput>make buildworld</userinput></screen>

	- <para>It is possible to specify a <option>-j</option> option
	- to <command>make</command> which will cause it to spawn
	- several simultaneous processes. This is most useful on
	- multi-CPU machines. However, since much of the compiling
	- process is IO bound rather than CPU bound it is also useful
	- on single CPU machines.</para>
	+ <para>It is possible to specify <option>-j</option> which
	+ will cause <command>make</command> to spawn several
	+ simultaneous processes. This is most useful on multi-CPU
	+ machines. However, since much of the compiling process is
	+ I/O bound rather than CPU bound, it is also useful on single
	+ CPU machines.</para>

	- <para>On a typical single-CPU machine you would run:</para>
	+ <para>On a typical single-CPU machine, run:</para>

	<screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>

	<para>&man.make.1; will then have up to 4 processes running at
	any one time. Empirical evidence posted to the mailing
	lists shows this generally gives the best performance
	benefit.</para>

	- <para>If you have a multi-CPU machine and you are using an SMP
	- configured kernel try values between 6 and 10 and see how
	- they speed things up.</para>
	+ <para>On a multi-CPU machine using an SMP configured kernel,
	+ try values between 6 and 10 and see how they speed things
	+ up.</para>
	</sect3>

	<sect3>
	<title>Timings</title>

	<indexterm>
	<primary>rebuilding <quote>world</quote></primary>
	<secondary>timings</secondary>
	</indexterm>

	<para>Many factors influence the build time, but fairly recent
	machines may only take a one or two hours to build the
	&os.stable; tree, with no tricks or shortcuts used during
	the process. A &os.current; tree will take somewhat
	longer.</para>
	</sect3>
	</sect2>

	<sect2 id="new-kernel">
	<title>Compile and Install a New Kernel</title>

	<indexterm>
	<primary>kernel</primary>
	<secondary>compiling</secondary>
	</indexterm>

	- <para>To take full advantage of your new system you should
	- recompile the kernel. This is practically a necessity, as
	- certain memory structures may have changed, and programs like
	- &man.ps.1; and &man.top.1; will fail to work until the kernel
	- and source code versions are the same.</para>
	+ <para>To take full advantage of the new system, recompile the
	+ kernel. This is practically a necessity, as certain memory
	+ structures may have changed, and programs like &man.ps.1; and
	+ &man.top.1; will fail to work until the kernel and source code
	+ versions are the same.</para>

	<para>The simplest, safest way to do this is to build and
	install a kernel based on <filename>GENERIC</filename>. While
	<filename>GENERIC</filename> may not have all the necessary
	- devices for your system, it should contain everything
	- necessary to boot your system back to single user mode. This
	- is a good test that the new system works properly. After
	- booting from <filename>GENERIC</filename> and verifying that
	- your system works you can then build a new kernel based on
	- your normal kernel configuration file.</para>
	+ devices for the system, it should contain everything necessary
	+ to boot the system back to single user mode. This is a good
	+ test that the new system works properly. After booting from
	+ <filename>GENERIC</filename> and verifying that the system
	+ works, a new kernel can be built based on a custom kernel
	+ configuration file.</para>

	<para>On &os; it is important to
	<link linkend="make-buildworld">build world</link> before
	building a new kernel.</para>

	<note>
	- <para>If you want to build a custom kernel, and already have a
	- configuration file, just use
	- <literal>KERNCONF=<replaceable>MYKERNEL</replaceable></literal>
	- like this:</para>
	+ <para>To build a custom kernel with an existing customized
	+ configuration file, use
	+ <literal>KERNCONF=<replaceable>MYKERNEL</replaceable></literal>:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput>
	&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput>
	&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
	+
	</note>

	- <para>Note that if you have raised
	- <literal>kern.securelevel</literal> above 1
	- <emphasis>and</emphasis> you have set either the
	- <literal>noschg</literal> or similar flags to your kernel
	- binary, you might find it necessary to drop into single user
	- mode to use <maketarget>installkernel</maketarget>. Otherwise
	- you should be able to run both these commands from multi user
	- mode without problems. See &man.init.8; for details about
	- <literal>kern.securelevel</literal> and &man.chflags.1; for
	+ <para>If <varname>kern.securelevel</varname> has been raised
	+ above 1 <emphasis>and</emphasis> <literal>noschg</literal> or
	+ similar flags have been set on the kernel binary, drop into
	+ single user mode to use
	+ <maketarget>installkernel</maketarget>. Otherwise, both these
	+ commands can be run from multi user mode without problems.
	+ See &man.init.8; for details about
	+ <varname>kern.securelevel</varname> and &man.chflags.1; for
	details about the various file flags.</para>
	</sect2>

	<sect2 id="new-kernel-singleuser">
	<title>Reboot into Single User Mode</title>

	<indexterm><primary>single-user mode</primary></indexterm>

	- <para>You should reboot into single user mode to test the new
	- kernel works. Do this by following the instructions in
	- <xref linkend="makeworld-singleuser"/>.</para>
	+ <para>Reboot into single user mode to test that the new kernel
	+ works using the instructions in <xref
	+ linkend="makeworld-singleuser"/>.</para>
	</sect2>

	<sect2 id="make-installworld">
	<title>Install the New System Binaries</title>

	- <para>You should now use <maketarget>installworld</maketarget>
	- to install the new system binaries.</para>
	+ <para>Next, use <maketarget>installworld</maketarget> to install
	+ the new system binaries:</para>

	- <para>Run</para>
	-
	<screen>&prompt.root; <userinput>cd /usr/src</userinput>
	&prompt.root; <userinput>make installworld</userinput></screen>

	<note>
	- <para>If you specified variables on the
	- <command>make buildworld</command> command line, you must
	- specify the same variables in the
	- <command>make installworld</command> command line. This
	- does not necessarily hold true for other options; for
	- example, <option>-j</option> must never be used with
	+ <para>If variables were specified to
	+ <command>make buildworld</command>, specify the same
	+ variables to <command>make installworld</command>. However,
	+ <option>-j</option> must never be used with
	<maketarget>installworld</maketarget>.</para>

	<para>For example, if you ran:</para>

	<screen>&prompt.root; <userinput>make -DNO_PROFILE buildworld</userinput></screen>

	- <para>you must install the results with:</para>
	+ <para>install the results with:</para>

	<screen>&prompt.root; <userinput>make -DNO_PROFILE installworld</userinput></screen>

	- <para>otherwise it would try to install profiled libraries
	- that had not been built during the
	+ <para>otherwise, the command will try to install profiled
	+ libraries that were not built during the
	<command>make buildworld</command> phase.</para>
	</note>
	</sect2>

	<sect2 id="post-installworld-updates">
	<title>Update Files Not Updated by
	<command>make installworld</command></title>

	- <para>Remaking the world will not update certain directories (in
	- particular, <filename>/etc</filename>,
	- <filename>/var</filename> and <filename>/usr</filename>) with
	+ <para>Remaking the world will not update certain directories,
	+ such as <filename class="directory">/etc</filename>,
	+ <filename class="directory">/var</filename> and
	+ <filename class="directory">/usr</filename>, with
	new or changed configuration files.</para>

	- <para>The simplest way to update these files is to use
	- &man.mergemaster.8;, though it is possible to do it manually
	- if you would prefer to do that. Regardless of which way you
	- choose, be sure to make a backup of <filename>/etc</filename>
	- in case anything goes wrong.</para>
	+ <para>The simplest way to update the files in these directories
	+ is to use &man.mergemaster.8;. Be sure to first make a backup
	+ of <filename>/etc</filename> in case anything goes
	+ wrong.</para>

	<sect3 id="mergemaster">
	<sect3info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect3info>
	<title><command>mergemaster</command></title>

	<indexterm>
	<primary>
	<command>mergemaster</command>
	</primary>
	</indexterm>

	- <para>The &man.mergemaster.8; utility is a Bourne script that
	- will aid you in determining the differences between your
	- configuration files in <filename>/etc</filename>, and the
	+ <para>&man.mergemaster.8; is a Bourne script to aid in
	+ determining the differences between the configuration files
	+ in <filename class="directory">/etc</filename>, and the
	configuration files in the source tree
	- <filename>/usr/src/etc</filename>. This is the recommended
	- solution for keeping the system configuration files up to
	- date with those located in the source tree.</para>
	+ <filename class="directory">/usr/src/etc</filename>. This
	+ is the recommended solution for keeping the system
	+ configuration files up to date with those located in the
	+ source tree.</para>

	- <para>To begin simply type <command>mergemaster</command> at
	- your prompt, and watch it start going.
	- <command>mergemaster</command> will then build a temporary
	- root environment, from <filename>/</filename> down, and
	- populate it with various system configuration files. Those
	- files are then compared to the ones currently installed in
	- your system. At this point, files that differ will be shown
	- in &man.diff.1; format, with the <option>+</option> sign
	- representing added or modified lines, and <option>-</option>
	- representing lines that will be either removed completely,
	- or replaced with a new line. See the &man.diff.1; manual
	- page for more information about the &man.diff.1; syntax and
	- how file differences are shown.</para>
	+ <para>To begin, type <command>mergemaster</command> and it
	+ will build a temporary root environment, from
	+ <filename>/</filename> down, and populate it with various
	+ system configuration files. Those files are then compared
	+ to the ones currently installed in the system. Files that
	+ differ will be shown in &man.diff.1; format, with the
	+ <option>+</option> sign representing added or modified
	+ lines, and <option>-</option> representing lines that will
	+ be either removed completely, or replaced with a new file.
	+ Refer to &man.diff.1; for more information about the
	+ &man.diff.1; syntax and how file differences are
	+ shown.</para>

	- <para>&man.mergemaster.8; will then show you each file that
	- displays variances, and at this point you will have the
	- option of either deleting the new file (referred to as the
	- temporary file), installing the temporary file in its
	- unmodified state, merging the temporary file with the
	- currently installed file, or viewing the &man.diff.1;
	- results again.</para>
	+ <para>&man.mergemaster.8; will then display each file that
	+ differs, and present the options of either deleting the new
	+ file, referred to as the temporary file, installing the
	+ temporary file in its unmodified state, merging the
	+ temporary file with the currently installed file, or viewing
	+ the &man.diff.1; results again.</para>

	<para>Choosing to delete the temporary file will tell
	- &man.mergemaster.8; that we wish to keep our current file
	- unchanged, and to delete the new version. This option is
	- not recommended, unless you see no reason to change the
	- current file. You can get help at any time by typing
	- <keycap>?</keycap> at the &man.mergemaster.8; prompt. If
	- the user chooses to skip a file, it will be presented again
	- after all other files have been dealt with.</para>
	+ &man.mergemaster.8; to keep the current file unchanged and
	+ to delete the new version. This option is not recommended,
	+ unless there is no reason to change the current file. To
	+ get help at any time, type <keycap>?</keycap> at the
	+ &man.mergemaster.8; prompt. If the user chooses to skip a
	+ file, it will be presented again after all other files have
	+ been dealt with.</para>

	<para>Choosing to install the unmodified temporary file will
	replace the current file with the new one. For most
	unmodified files, this is the best option.</para>

	- <para>Choosing to merge the file will present you with a text
	- editor, and the contents of both files. You can now merge
	- them by reviewing both files side by side on the screen, and
	+ <para>Choosing to merge the file will present a text editor,
	+ and the contents of both files. The files can be merged
	+ by reviewing both files side by side on the screen, and
	choosing parts from both to create a finished product. When
	- the files are compared side by side, the <keycap>l</keycap>
	- key will select the left contents and the <keycap>r</keycap>
	- key will select contents from your right. The final output
	- will be a file consisting of both parts, which can then be
	- installed. This option is customarily used for files where
	- settings have been modified by the user.</para>
	+ the files are compared side by side, <keycap>l</keycap>
	+ selects the left contents and <keycap>r</keycap> selects
	+ contents from the right. The final output will be a file
	+ consisting of both parts, which can then be installed. This
	+ option is customarily used for files where settings have
	+ been modified by the user.</para>

	<para>Choosing to view the &man.diff.1; results again will
	- show you the file differences just like &man.mergemaster.8;
	- did before prompting you for an option.</para>
	+ display the file differences just like &man.mergemaster.8;
	+ did before prompting an option.</para>

	- <para>After &man.mergemaster.8; is done with the system files
	- you will be prompted for other options. &man.mergemaster.8;
	- may ask if you want to rebuild the password file and will
	- finish up with an option to remove left-over temporary
	- files.</para>
	+ <para>After &man.mergemaster.8; is done with the system files,
	+ it will prompt for other options. &man.mergemaster.8; may
	+ prompt to rebuild the password file and will finish up with
	+ an option to remove left-over temporary files.</para>
	</sect3>

	<sect3>
	<title>Manual Update</title>

	- <para>If you wish to do the update manually, however, you
	- cannot just copy over the files from
	- <filename>/usr/src/etc</filename> to
	- <filename>/etc</filename> and have it work. Some of these
	- files must be <quote>installed</quote> first. This is
	- because the <filename>/usr/src/etc</filename> directory
	- <emphasis>is not</emphasis> a copy of what your
	- <filename>/etc</filename> directory should look like. In
	- addition, there are files that should be in
	- <filename>/etc</filename> that are not in
	+ <para>To perform the update manually instead, do not just copy
	+ over the files from
	+ <filename class="directory">/usr/src/etc</filename> to
	+ <filename class="directory">/etc</filename> and expect it to
	+ work. Some files must be <quote>installed</quote> first as
	+ <filename class="directory">/usr/src/etc</filename>
	+ <emphasis>is not</emphasis> a copy of what
	+ <filename class="directory">/etc</filename> should look
	+ like. In addition, some files that should be in
	+ <filename>/etc</filename> are not in
	<filename>/usr/src/etc</filename>.</para>

	<para>If you are using &man.mergemaster.8; (as recommended),
	you can skip forward to the
	<link linkend="updating-upgrading-rebooting">next
	section</link>.</para>

	- <para>The simplest way to do this by hand is to install the
	- files into a new directory, and then work through them
	+ <para>The simplest way to merge files by hand is to install
	+ the files into a new directory, and then work through them
	looking for differences.</para>

	<warning>
	<title>Backup Your Existing
	<filename>/etc</filename></title>

	- <para>Although, in theory, nothing is going to touch this
	- directory automatically, it is always better to be sure.
	- So copy your existing <filename>/etc</filename> directory
	- somewhere safe. Something like:</para>
	+ <para>It is recommended to first copy the existing
	+ <filename class="directory">/etc</filename> somewhere
	+ safe, like so:</para>

	<screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>

	- <para><option>-R</option> does a recursive copy,
	- <option>-p</option> preserves times, ownerships on files
	- and suchlike.</para>
	+ <para>where <option>-R</option> does a recursive copy and
	+ <option>-p</option> preserves times and the ownerships on
	+ files.</para>
	</warning>

	- <para>You need to build a dummy set of directories to install
	- the new <filename>/etc</filename> and other files into.
	- <filename>/var/tmp/root</filename> is a reasonable choice,
	- and there are a number of subdirectories required under this
	- as well.</para>
	+ <para>Build a temporary set of directories into which the new
	+ <filename class="directory">/etc</filename> and other files
	+ can be installed:</para>

	<screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput>
	&prompt.root; <userinput>cd /usr/src/etc</userinput>
	&prompt.root; <userinput>make DESTDIR=/var/tmp/root distrib-dirs distribution</userinput></screen>

	<para>This will build the necessary directory structure and
	install the files. A lot of the subdirectories that have
	- been created under <filename>/var/tmp/root</filename> are
	- empty and should be deleted. The simplest way to do this is
	+ been created under <filename
	+ class="directory">/var/tmp/root</filename> are empty and
	+ should be deleted. The simplest way to do this is
	to:</para>

	<screen>&prompt.root; <userinput>cd /var/tmp/root</userinput>
	&prompt.root; <userinput>find -d . -type d \| xargs rmdir 2>/dev/null</userinput></screen>

	- <para>This will remove all empty directories. (Standard error
	- is redirected to <filename>/dev/null</filename> to prevent
	+ <para>This will remove all empty directories while redirecting
	+ standard error to <filename>/dev/null</filename> to prevent
	the warnings about the directories that are not
	- empty.)</para>
	+ empty.</para>

	- <para><filename>/var/tmp/root</filename> now contains all the
	- files that should be placed in appropriate locations below
	- <filename>/</filename>. You now have to go through each of
	- these files, determining how they differ with your existing
	- files.</para>
	+ <para><filename class="directory">/var/tmp/root</filename> now
	+ contains all the files that should be placed in appropriate
	+ locations below <filename class="directory">/</filename>.
	+ Go through each of these files, determining how they differ
	+ from the system's existing files.</para>

	- <para>Note that some of the files that will have been
	- installed in <filename>/var/tmp/root</filename> have a
	- leading <quote>.</quote>. At the time of writing the only
	- files like this are shell startup files in
	- <filename>/var/tmp/root/</filename> and
	- <filename>/var/tmp/root/root/</filename>, although there may
	- be others (depending on when you are reading this). Make
	- sure you use <command>ls -a</command> to catch them.</para>
	+ <para>Some of the files installed into <filename
	+ class="directory">/var/tmp/root</filename> have a
	+ leading <quote>.</quote>. Make sure to use <command>ls
	+ -a</command> in order to catch them.</para>

	- <para>The simplest way to do this is to use &man.diff.1; to
	- compare the two files:</para>
	+ <para>The simplest way to compare files is to use
	+ &man.diff.1;:</para>

	<screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen>

	- <para>This will show you the differences between your
	- <filename>/etc/shells</filename> file and the new
	- <filename>/var/tmp/root/etc/shells</filename> file. Use
	- these to decide whether to merge in changes that you have
	- made or whether to copy over your old file.</para>
	+ <para>This command will show the differences between the
	+ existing <filename>/etc/shells</filename> and the new
	+ <filename>/var/tmp/root/etc/shells</filename>. Review the
	+ differences to decide whether to merge in custom changes
	+ or to replace the existing file with the new one.</para>

	<tip>
	<title>Name the New Root Directory
	- (<filename>/var/tmp/root</filename>) with a Time Stamp, so
	- You Can Easily Compare Differences Between
	- Versions</title>
	+ (<filename class="directory">/var/tmp/root</filename>)
	+ with a Time Stamp, so You Can Easily Compare Differences
	+ Between Versions</title>

	- <para>Frequently rebuilding the world means that you have to
	- update <filename>/etc</filename> frequently as well, which
	- can be a bit of a chore.</para>
	+ <para>Frequently rebuilding world entails frequently
	+ updating <filename class="directory">/etc</filename>
	+ as well, which can be a bit of a chore.</para>

	- <para>You can speed this process up by keeping a copy of the
	- last set of changed files that you merged into
	- <filename>/etc</filename>. The following procedure gives
	- one idea of how to do this.</para>
	+ <para>To speed up this process, use the following
	+ procedure to keep a copy of the last set of changed files
	+ that were merged into <filename
	+ class="directory">/etc</filename>.</para>

	<procedure>
	<step>
	- <para>Make the world as normal. When you want to update
	- <filename>/etc</filename> and the other directories,
	- give the target directory a name based on the current
	- date. If you were doing this on the 14th of February
	- 1998 you could do the following:</para>
	+ <para>Make the world as normal. When updating
	+ <filename class="directory">/etc</filename> and the
	+ other directories, give the target directory a name
	+ based on the current date:</para>

	- <screen>&prompt.root; <userinput>mkdir /var/tmp/root-19980214</userinput>
	+ <screen>&prompt.root; <userinput>mkdir /var/tmp/root-20130214</userinput>
	&prompt.root; <userinput>cd /usr/src/etc</userinput>
	-&prompt.root; <userinput>make DESTDIR=/var/tmp/root-19980214 \
	+&prompt.root; <userinput>make DESTDIR=/var/tmp/root-20130214 \
	distrib-dirs distribution</userinput></screen>
	</step>

	<step>
	<para>Merge in the changes from this directory as
	- outlined above.</para>
	-
	- <para><emphasis>Do not</emphasis> remove the
	- <filename>/var/tmp/root-19980214</filename> directory
	- when you have finished.</para>
	+ outlined above. <emphasis>Do not</emphasis> remove
	+ the <filename>/var/tmp/root-20130214</filename>
	+ directory when you have finished.</para>
	</step>

	<step>
	- <para>When you have downloaded the latest version of the
	- source and remade it, follow step 1. This will give
	- you a new directory, which might be called
	- <filename>/var/tmp/root-19980221</filename> (if you
	- wait a week between doing updates).</para>
	+ <para>After downloading the latest version of the
	+ source and remaking it, follow step 1. Create a new
	+ directory, which reflects the new date. This example
	+ uses
	+ <filename>/var/tmp/root-20130221</filename>.</para>
	</step>

	<step>
	- <para>You can now see the differences that have been
	- made in the intervening week using &man.diff.1; to
	- create a recursive diff between the two
	- directories:</para>
	+ <para>Use &man.diff.1; to see the differences that have
	+ been made in the intervening week by creating a
	+ recursive diff between the two directories:</para>

	<screen>&prompt.root; <userinput>cd /var/tmp</userinput>
	-&prompt.root; <userinput>diff -r root-19980214 root-19980221</userinput></screen>
	+&prompt.root; <userinput>diff -r root-20130214 root-20130221</userinput></screen>

	<para>Typically, this will be a much smaller set of
	- differences than those between
	- <filename>/var/tmp/root-19980221/etc</filename> and
	- <filename>/etc</filename>. Because the set of
	- differences is smaller, it is easier to migrate those
	- changes across into your <filename>/etc</filename>
	- directory.</para>
	+ differences than those between <filename
	+ class="directory">/var/tmp/root-20130221/etc</filename>
	+ and <filename class="directory">/etc</filename>.
	+ Because the set of differences is smaller, it is
	+ easier to migrate those changes across into
	+ <filename class="directory">/etc</filename>.</para>
	</step>

	<step>
	- <para>You can now remove the older of the two
	- <filename>/var/tmp/root-*</filename>
	+ <para>When finished, remove the older of the two
	+ <filename class="directory">/var/tmp/root-*</filename>
	directories:</para>

	- <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-19980214</userinput></screen>
	+ <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-20130214</userinput></screen>
	</step>

	<step>
	- <para>Repeat this process every time you need to merge
	- in changes to <filename>/etc</filename>.</para>
	+ <para>Repeat this process whenever merging
	+ in changes to <filename
	+ class="directory">/etc</filename>.</para>
	</step>
	</procedure>

	- <para>You can use &man.date.1; to automate the generation of
	- the directory names:</para>
	+ <para>Use &man.date.1; to automate the generation of the
	+ directory names:</para>

	<screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen>
	</tip>
	</sect3>
	</sect2>

	<sect2 id="updating-upgrading-rebooting">
	<title>Rebooting</title>

	- <para>You are now done. After you have verified that everything
	- appears to be in the right place you can reboot the system. A
	- simple &man.shutdown.8; should do it:</para>
	+ <para>Verify that everything appears to be in the right place,
	+ then reboot the system using &man.shutdown.8;:</para>

	<screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
	- </sect2>

	- <sect2>
	- <title>Finished</title>
	-
	- <para>You should now have successfully upgraded your &os;
	+ <para>You should now have successfully upgraded the &os;
	system. Congratulations.</para>

	<para>If things went slightly wrong, it is easy to rebuild a
	- particular piece of the system. For example, if you
	- accidentally deleted <filename>/etc/magic</filename> as part
	- of the upgrade or merge of <filename>/etc</filename>, the
	- &man.file.1; command will stop working. In this case, the fix
	- would be to run:</para>
	+ particular piece of the system. For example, if
	+ <filename>/etc/magic</filename> was accidentally deleted as
	+ part of the upgrade or merge of <filename
	+ class="directory">/etc</filename>, &man.file.1; will stop
	+ working. To fix this, run:</para>

	<screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
	&prompt.root; <userinput>make all install</userinput></screen>
	</sect2>

	<sect2 id="updating-questions">
	<title>Questions</title>

	<qandaset>
	<qandaentry>
	<question>
	<para>Do I need to re-make the world for every
	change?</para>
	</question>

	<answer>
	- <para>There is no easy answer to this one, as it depends
	- on the nature of the change. For example, if you just
	- ran <application>Subversion</application>, and it has
	- shown the following files as being updated:</para>
	+ <para>There is no easy answer, as it depends on the nature
	+ of the change. For example, if running
	+ <application>svn</application> only shows the following
	+ files as being updated:</para>

	<screen><filename>src/games/cribbage/instr.c</filename>
	<filename>src/games/sail/pl_main.c</filename>
	<filename>src/release/sysinstall/config.c</filename>
	<filename>src/release/sysinstall/media.c</filename>
	<filename>src/share/mk/bsd.port.mk</filename></screen>

	<para>it probably is not worth rebuilding the entire
	- world. You could just go to the appropriate
	- sub-directories and <command>make all install</command>,
	- and that is about it. But if something major changed,
	- for example <filename>src/lib/libc/stdlib</filename>
	- then you should either re-make the world, or at least
	- those parts of it that are statically linked (as well as
	- anything else you might have added that is statically
	- linked).</para>
	+ world. Instead, go into the appropriate sub-directories
	+ and run <command>make all install</command>. But if
	+ something major changed, such as
	+ <filename>src/lib/libc/stdlib</filename>, either
	+ re-make world, or at least those parts of it that are
	+ statically linked.</para>

	- <para>At the end of the day, it is your call. You might
	- be happy re-making the world every fortnight say, and
	- let changes accumulate over that fortnight. Or you
	- might want to re-make just those things that have
	- changed, and be confident you can spot all the
	- dependencies.</para>
	+ <para>At the end of the day, it is your call. Some users
	+ re-make the world every fortnight and let changes
	+ accumulate over that fortnight. Others only re-make
	+ those things that have changed and are careful to spot
	+ all the dependencies.</para>

	- <para>And, of course, this all depends on how often you
	- want to upgrade, and whether you are tracking
	- &os.stable; or &os.current;.</para>
	+ <para>It all depends on how often a user wants to upgrade
	+ and whether they are tracking &os.stable; or
	+ &os.current;.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>My compile failed with lots of signal 11 (or other
	- signal number) errors. What has happened?</para>
	+ signal number) errors. What happened?</para>
	</question>

	<answer>
	<indexterm><primary>signal 11</primary></indexterm>

	- <para>This is normally indicative of hardware problems.
	- (Re)making the world is an effective way to stress test
	- your hardware, and will frequently throw up memory
	- problems. These normally manifest themselves as the
	- compiler mysteriously dying on receipt of strange
	- signals.</para>
	+ <para>This normally indicates hardware problems.
	+ (Re)making world is an effective way to stress test
	+ hardware, and will frequently throw up memory
	+ problems which normally manifest themselves as the
	+ compiler mysteriously aborts.</para>

	- <para>A sure indicator of this is if you can restart the
	- make and it dies at a different point in the
	- process.</para>
	+ <para>A sure indicator of this occurs when
	+ <application>make</application> is restarted and it
	+ dies at a different point in the process.</para>

	- <para>In this instance there is little you can do except
	- start swapping around the components in your machine to
	- determine which one is failing.</para>
	+ <para>To resolve this error, start swapping around the
	+ components in the machine to determine which one is
	+ failing.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	- <para>Can I remove <filename>/usr/obj</filename> when I
	- have finished?</para>
	+ <para>Can <filename class="directory">/usr/obj</filename>
	+ be removed when finished?</para>
	</question>

	<answer>
	<para>The short answer is yes.</para>

	- <para><filename>/usr/obj</filename> contains all the
	- object files that were produced during the compilation
	- phase. Normally, one of the first steps in the
	- <command>make buildworld</command> process is to remove
	- this directory and start afresh. In this case, keeping
	- <filename>/usr/obj</filename> around after you have
	- finished makes little sense, and will free up a large
	- chunk of disk space (currently about 2 GB).</para>
	+ <para><filename class="directory">/usr/obj</filename>
	+ contains all the object files that were produced during
	+ the compilation phase. Normally, one of the first steps
	+ in the <command>make buildworld</command> process is to
	+ remove this directory and start afresh. Keeping
	+ <filename class="directory">/usr/obj</filename> around
	+ when finished makes little sense, and its removal frees
	+ up a approximately 2 GB of disk space.</para>

	- <para>However, if you know what you are doing you can have
	- <command>make buildworld</command> skip this step. This
	- will make subsequent builds run much faster, since most
	- of the sources will not need to be recompiled. The flip
	- side of this is that subtle dependency problems can
	- creep in, causing your build to fail in odd ways. This
	- frequently generates noise on the &os; mailing lists,
	- when one person complains that their build has failed,
	- not realizing that it is because they have tried to cut
	+ <para>Advances users can instruct
	+ <command>make buildworld</command> to skip this step.
	+ This speeds up subsequent builds, since most of the
	+ sources will not need to be recompiled. The flip side
	+ is that subtle dependency problems can creep in, causing
	+ the build to fail in odd ways. This frequently
	+ generates noise on the &os; mailing lists, when one
	+ person complains that their build has failed, not
	+ realizing that it is because they have tried to cut
	corners.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>Can interrupted builds be resumed?</para>
	</question>

	<answer>
	- <para>This depends on how far through the process you got
	- before you found a problem.</para>
	+ <para>This depends on how far into the process the
	+ problem occurs.</para>

	- <para><emphasis>In general</emphasis> (and this is not a
	- hard and fast rule) the
	- <command>make buildworld</command> process builds new
	- copies of essential tools (such as &man.gcc.1;, and
	- &man.make.1;) and the system libraries. These tools and
	- libraries are then installed. The new tools and
	- libraries are then used to rebuild themselves, and are
	- installed again. The entire system (now including
	- regular user programs, such as &man.ls.1; or
	- &man.grep.1;) is then rebuilt with the new system
	- files.</para>
	+ <para>In general, <command>make buildworld</command>
	+ builds new copies of essential tools, such as
	+ &man.gcc.1; and &man.make.1;, and the system libraries.
	+ These tools and libraries are then installed, used to
	+ rebuild themselves, and are installed again. The entire
	+ system, including regular user programs such as
	+ &man.ls.1; or &man.grep.1;, is then rebuilt with the new
	+ system files.</para>

	- <para>If you are at the last stage, and you know it
	- (because you have looked through the output that you
	- were storing) then you can (fairly safely) do:</para>
	+ <para>During the last stage, it is fairly safe to:</para>

	<screen><emphasis>… fix the problem …</emphasis>
	&prompt.root; <userinput>cd /usr/src</userinput>
	&prompt.root; <userinput>make -DNO_CLEAN all</userinput></screen>

	<para>This will not undo the work of the previous
	<command>make buildworld</command>.</para>

	<para>If you see the message:</para>

	<screen>--------------------------------------------------------------
	Building everything..
	--------------------------------------------------------------</screen>

	- <para>in the <command>make buildworld</command> output
	- then it is probably fairly safe to do so.</para>
	+ <para>in the <command>make buildworld</command> output,
	+ it is probably fairly safe to do so.</para>

	- <para>If you do not see that message, or you are not sure,
	- then it is always better to be safe than sorry, and
	+ <para>If that message is not displayed, or you are not
	+ sure, it is always better to be safe than sorry, and
	restart the build from scratch.</para>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>How can I speed up making the world?</para>
	</question>

	<answer>
	<itemizedlist>
	<listitem>
	- <para>Run in single user mode.</para>
	+ <para>Run it in single user mode.</para>
	</listitem>

	<listitem>
	- <para>Put the <filename>/usr/src</filename> and
	- <filename>/usr/obj</filename> directories on
	- separate file systems held on separate disks. If
	+ <para>Put <filename
	+ class="directory">/usr/src</filename> and
	+ <filename class="directory">/usr/obj</filename>
	+ on separate file systems held on separate disks. If
	possible, put these disks on separate disk
	controllers.</para>
	</listitem>

	<listitem>
	- <para>Better still, put these file systems across
	- multiple disks using the &man.ccd.4; (concatenated
	- disk driver) device.</para>
	+ <para>Alternately, put these file systems across
	+ multiple disks using &man.ccd.4;.</para>
	</listitem>

	<listitem>
	- <para>Turn off profiling (set
	+ <para>Turn off profiling by setting
	<quote>NO_PROFILE=true</quote> in
	- <filename>/etc/make.conf</filename>). You almost
	- certainly do not need it.</para>
	+ <filename>/etc/make.conf</filename>.</para>
	</listitem>

	<listitem>
	- <para>Pass the
	+ <para>Pass
	<option>-j<replaceable>n</replaceable></option>
	- option to &man.make.1; to run multiple processes in
	- parallel. This usually helps regardless of whether
	- you have a single or a multi processor
	- machine.</para>
	+ to &man.make.1; to run multiple processes in
	+ parallel. This usually helps on both single and
	+ multi processor machines.</para>
	</listitem>

	<listitem>
	<para>The file system holding
	- <filename>/usr/src</filename> can be mounted (or
	- remounted) with the <option>noatime</option> option.
	+ <filename class="directory">/usr/src</filename> can
	+ be mounted or remounted with
	+ <option>noatime</option>.
	This prevents the file system from recording the
	- file access time. You probably do not need this
	- information anyway.</para>
	+ file access time which is probably not
	+ needed.</para>

	<screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen>

	<warning>
	- <para>The example assumes
	- <filename>/usr/src</filename> is on its own file
	- system. If it is not (if it is a part of
	- <filename>/usr</filename> for example) then you
	- will need to use that file system mount point, and
	- not <filename>/usr/src</filename>.</para>
	+ <para>This example assumes <filename
	+ class="directory">/usr/src</filename> is on its
	+ own file system. If it is part of
	+ <filename class="directory">/usr</filename>, then
	+ use that file system mount point instead.</para>
	</warning>
	</listitem>

	<listitem>
	- <para>The file system holding
	- <filename>/usr/obj</filename> can be mounted (or
	- remounted) with the <option>async</option> option.
	- This causes disk writes to happen asynchronously.
	- In other words, the write completes immediately, and
	- the data is written to the disk a few seconds later.
	- This allows writes to be clustered together, and can
	- be a dramatic performance boost.</para>
	+ <para>The file system holding <filename
	+ class="directory">/usr/obj</filename> can be
	+ mounted or remounted with <option>async</option>
	+ so that disk writes happen asynchronously. The
	+ write completes immediately, and the data is written
	+ to the disk a few seconds later. This allows writes
	+ to be clustered together, and can provide a dramatic
	+ performance boost.</para>

	<warning>
	- <para>Keep in mind that this option makes your file
	- system more fragile. With this option there is an
	- increased chance that, should power fail, the file
	- system will be in an unrecoverable state when the
	- machine restarts.</para>
	+ <para>Keep in mind that this option makes the file
	+ system more fragile. With this option, there is
	+ an increased chance that, should power fail, the
	+ file system will be in an unrecoverable state when
	+ the machine restarts.</para>

	- <para>If <filename>/usr/obj</filename> is the only
	- thing on this file system then it is not a
	+ <para>If <filename
	+ class="directory">/usr/obj</filename> is the
	+ only directory on this file system, this is not a
	problem. If you have other, valuable data on the
	- same file system then ensure your backups are
	- fresh before you enable this option.</para>
	+ same file system, ensure that there are verified
	+ backups before enabling this option.</para>
	</warning>

	<screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen>

	<warning>
	- <para>As above, if <filename>/usr/obj</filename> is
	+ <para>If <filename
	+ class="directory">/usr/obj</filename> is
	not on its own file system, replace it in the
	example with the name of the appropriate mount
	point.</para>
	</warning>
	</listitem>
	</itemizedlist>
	</answer>
	</qandaentry>

	<qandaentry>
	<question>
	<para>What do I do if something goes wrong?</para>
	</question>

	<answer>
	- <para>Make absolutely sure your environment has no
	- extraneous cruft from earlier builds. This is simple
	- enough.</para>
	+ <para>Make absolutely sure that the environment has no
	+ extraneous cruft from earlier builds:</para>

	<screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput>
	&prompt.root; <userinput>rm -rf /usr/obj/usr</userinput>
	&prompt.root; <userinput>cd /usr/src</userinput>
	&prompt.root; <userinput>make cleandir</userinput>
	&prompt.root; <userinput>make cleandir</userinput></screen>

	<para>Yes, <command>make cleandir</command> really should
	be run twice.</para>

	- <para>Then restart the whole process, starting
	+ <para>Then, restart the whole process, starting
	with <command>make buildworld</command>.</para>

	- <para>If you still have problems, send the error and the
	+ <para>If problems persist, send the error and the
	output of <command>uname -a</command> to &a.questions;.
	- Be prepared to answer other questions about your
	+ Be prepared to answer other questions about the
	setup!</para>
	</answer>
	</qandaentry>
	</qandaset>
	</sect2>
	</sect1>

	<sect1 id="make-delete-old">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Anton</firstname>
	<surname>Shterenlikht</surname>
	<contrib>Based on notes provided by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Deleting Obsolete Files, Directories and Libraries</title>

	<indexterm>
	<primary>Deleting obsolete files, directories and
	libraries</primary>
	</indexterm>

	- <para>As a part of the &os; development lifecycle, it happens from
	- time to time that files and their contents become obsolete.
	- This may be because their functionality is implemented
	- elsewhere, the version number of the library has changed or it
	- was removed from the system entirely. This includes old files,
	- libraries and directories, which should be removed when updating
	- the system. The benefit for the user is that the system is not
	- cluttered with old files which take up unnecessary space on the
	- storage (and backup) medium. Additionally, if the old library
	- had a security or stability issue, you should update to the
	- newer library to keep your system safe and prevent crashes
	- caused by the old library implementation. The files,
	- directories, and libraries that are considered obsolete are
	- listed in <filename>/usr/src/ObsoleteFiles.inc</filename>. The
	- following instructions will help you removing these obsolete
	+ <para>As a part of the &os; development lifecycle, files and their
	+ contents occasionally become obsolete. This may be because
	+ functionality is implemented elsewhere, the version number of
	+ the library has changed, or it was removed from the system
	+ entirely. This includes old files, libraries, and directories,
	+ which should be removed when updating the system. The benefit
	+ is that the system is not cluttered with old files which take up
	+ unnecessary space on the storage and backup media.
	+ Additionally, if the old library has a security or stability
	+ issue, the system should be updated to the newer library to keep
	+ it safe and to prevent crashes caused by the old library.
	+ Files, directories, and libraries which are considered obsolete
	+ are listed in <filename>/usr/src/ObsoleteFiles.inc</filename>.
	+ The following instructions should be used to remove obsolete
	files during the system upgrade process.</para>

	- <para>We assume you are following the steps outlined in
	- <xref linkend="canonical-build"/>. After the
	+ <para>Follow the steps outlined in <xref
	+ linkend="canonical-build"/>. After the
	<command>make <maketarget>installworld</maketarget></command>
	- and the subsequent <command>mergemaster</command> commands have
	- finished successfully, you should check for obsolete files and
	- libraries as follows:</para>
	+ and the subsequent <command>mergemaster</command> have finished
	+ successfully, check for obsolete files and libraries as
	+ follows:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput>
	&prompt.root; <userinput>make check-old</userinput></screen>

	<para>If any obsolete files are found, they can be deleted using
	- the following commands:</para>
	+ the following command:</para>

	<screen>&prompt.root; <userinput>make delete-old</userinput></screen>

	<tip>
	- <para>See <filename>/usr/src/Makefile</filename>
	+ <para>Refer to <filename>/usr/src/Makefile</filename>
	for more targets of interest.</para>
	</tip>

	<para>A prompt is displayed before deleting each obsolete file.
	- You can skip the prompt and let the system remove these files
	- automatically by using the
	- <makevar>BATCH_DELETE_OLD_FILES</makevar> make-variable as
	- follows:</para>
	+ To skip the prompt and let the system remove these files
	+ automatically, use
	+ <makevar>BATCH_DELETE_OLD_FILES</makevar>:</para>

	<screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen>

	- <para>You can also achieve the same goal by piping these commands
	- through <command>yes</command> like this:</para>
	+ <para>The same goal can be achieved by piping these commands
	+ through <command>yes</command>:</para>

	<screen>&prompt.root; <userinput>yes\|make delete-old</userinput></screen>

	<warning>
	<title>Warning</title>

	<para>Deleting obsolete files will break applications that
	still depend on those obsolete files. This is especially true
	- for old libraries. In most cases, you need to recompile the
	- programs, ports, or libraries that used the old library before
	- <command>make
	+ for old libraries. In most cases, the programs, ports, or
	+ libraries that used the old library need to be recompiled
	+ before <command>make
	<maketarget>delete-old-libs</maketarget></command> is
	executed.</para>
	</warning>

	<para>Utilities for checking shared library dependencies are
	available from the Ports Collection in
	<filename role="package">sysutils/libchk</filename> or <filename
	role="package">sysutils/bsdadminscripts</filename>.</para>

	<para>Obsolete shared libraries can conflict with newer libraries,
	causing messages like these:</para>

	<screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5
	/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>

	<para>To solve these problems, determine which port installed the
	library:</para>

	<screen>&prompt.root; <userinput>pkg_info -W /usr/local/lib/libtiff.so</userinput>
	/usr/local/lib/libtiff.so was installed by package tiff-3.9.4
	&prompt.root; <userinput>pkg_info -W /usr/local/lib/libXext.so</userinput>
	/usr/local/lib/libXext.so was installed by package libXext-1.1.1,1</screen>

	- <para>Then deinstall, rebuild and reinstall the port. The
	- <filename role="package">ports-mgmt/portmaster</filename> and
	- <filename role="package">ports-mgmt/portupgrade</filename>
	- utilities can be used to automate this process. After you have
	- made sure that all ports are rebuilt and do not use the old
	- libraries any more, you can delete them using the following
	- command:</para>
	+ <para>Then deinstall, rebuild and reinstall the port. <filename
	+ role="package">ports-mgmt/portmaster</filename> can be used to
	+ automate this process. After all ports are rebuilt and no
	+ longer use the old libraries, delete the old libraries using the
	+ following command:</para>

	<screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
	</sect1>

	<sect1 id="small-lan">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Mike</firstname>
	<surname>Meyer</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>Tracking for Multiple Machines</title>

	<indexterm>
	<primary>NFS</primary>
	<secondary>installing multiple machines</secondary>
	</indexterm>

	- <para>If you have multiple machines that you want to track the
	- same source tree, then having all of them download sources and
	- rebuild everything seems like a waste of resources: disk space,
	- network bandwidth, and CPU cycles. It is, and the solution is
	- to have one machine do most of the work, while the rest of the
	- machines mount that work via NFS. This section outlines a
	- method of doing so.</para>
	+ <para>When multiple machines need to track the same source tree,
	+ it is a waste of disk space, network bandwidth, and CPU cycles
	+ to have each system download the sources and rebuild everything.
	+ The solution is to have one machine do most of the work, while
	+ the rest of the machines mount that work via NFS. This section
	+ outlines a method of doing so.</para>

	<sect2 id="small-lan-preliminaries">
	<title>Preliminaries</title>

	- <para>First, identify a set of machines that is going to run
	- the same set of binaries, which we will call a
	- <emphasis>build set</emphasis>. Each machine can have a
	- custom kernel, but they will be running the same userland
	- binaries. From that set, choose a machine to be the
	- <emphasis>build machine</emphasis>. It is going to be the
	- machine that the world and kernel are built on. Ideally, it
	- should be a fast machine that has sufficient spare CPU to run
	+ <para>First, identify a set of machines which will run the
	+ same set of binaries, known as a <emphasis>build
	+ set</emphasis>. Each machine can have a custom kernel, but
	+ will run the same userland binaries. From that set, choose a
	+ machine to be the <emphasis>build machine</emphasis> that the
	+ world and kernel are built on. Ideally, this is a fast
	+ machine that has sufficient spare CPU to run
	<command>make buildworld</command> and
	- <command>make buildkernel</command>. You will also want to
	- choose a machine to be the <emphasis>test machine</emphasis>,
	- which will test software updates before they are put into
	- production. This <emphasis>must</emphasis> be a machine that
	- you can afford to have down for an extended period of time.
	- It can be the build machine, but need not be.</para>
	+ <command>make buildkernel</command>. Select a machine to be
	+ the <emphasis>test machine</emphasis>, which will test
	+ software updates before they are put into production. This
	+ <emphasis>must</emphasis> be a machine that can afford to be
	+ down for an extended period of time. It can be the build
	+ machine, but need not be.</para>

	<para>All the machines in this build set need to mount
	- <filename>/usr/obj</filename> and
	- <filename>/usr/src</filename> from the same machine, and at
	- the same point. Ideally, those are on two different drives on
	- the build machine, but they can be NFS mounted on that machine
	- as well. If you have multiple build sets,
	- <filename>/usr/src</filename> should be on one build machine,
	- and NFS mounted on the rest.</para>
	+ <filename class="directory">/usr/obj</filename> and
	+ <filename class="directory">/usr/src</filename> from the same
	+ machine, and at the same point. Ideally, those directories
	+ are on two different drives on the build machine, but they can
	+ be NFS mounted on that machine as well. For multiple
	+ build sets, <filename class="directory">/usr/src</filename>
	+ should be on one build machine, and NFS mounted on the
	+ rest.</para>

	- <para>Finally make sure that
	- <filename>/etc/make.conf</filename> and
	- <filename>/etc/src.conf</filename> on all the machines in the
	- build set agrees with the build machine. That means that the
	- build machine must build all the parts of the base system that
	- any machine in the build set is going to install. Also, each
	- build machine should have its kernel name set with
	+ <para>Finally, ensure that <filename>/etc/make.conf</filename>
	+ and <filename>/etc/src.conf</filename> on all the machines in
	+ the build set agree with the build machine. That means that
	+ the build machine must build all the parts of the base system
	+ that any machine in the build set is going to install. Also,
	+ each build machine should have its kernel name set with
	<makevar>KERNCONF</makevar> in
	<filename>/etc/make.conf</filename>, and the build machine
	should list them all in <makevar>KERNCONF</makevar>, listing
	its own kernel first. The build machine must have the kernel
	configuration files for each machine in
	- <filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>
	+ <filename
	+ class="directory">/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>
	if it is going to build their kernels.</para>
	</sect2>

	<sect2 id="small-lan-base-system">
	<title>The Base System</title>

	- <para>Now that all that is done, you are ready to build
	- everything. Build the kernel and world as described in
	- <xref linkend="make-buildworld"/> on the build machine, but do
	+ <para>On the build machine, build the kernel and world as
	+ described in <xref linkend="make-buildworld"/>, but do
	not install anything. After the build has finished, go to the
	- test machine, and install the kernel you just built. If this
	- machine mounts <filename>/usr/src</filename> and
	- <filename>/usr/obj</filename> via NFS, when you reboot to
	- single user you will need to enable the network and mount
	- them. The easiest way to do this is to boot to multi-user,
	- then run <command>shutdown now</command> to go to single user
	- mode. Once there, you can install the new kernel and world
	- and run <command>mergemaster</command> just as you normally
	- would. When done, reboot to return to normal multi-user
	- operations for this machine.</para>
	+ test machine, and install the built kernel. If this machine
	+ mounts <filename class="directory">/usr/src</filename> and
	+ <filename class="directory">/usr/obj</filename> via NFS,
	+ enable the network and mount these directories after rebooting
	+ to single user mode. The easiest way to do this is to boot to
	+ multi-user, then run <command>shutdown now</command> to go to
	+ single user mode. Once there, install the new kernel and
	+ world and run <command>mergemaster</command> as usual. When
	+ done, reboot to return to normal multi-user operations for
	+ this machine.</para>

	- <para>After you are certain that everything on the test
	- machine is working properly, use the same procedure to
	- install the new software on each of the other machines in
	- the build set.</para>
	+ <para>After verifying that everything on the test machine is
	+ working properly, use the same procedure to install the new
	+ software on each of the other machines in the build
	+ set.</para>
	</sect2>

	<sect2 id="small-lan-ports">
	<title>Ports</title>

	<para>The same ideas can be used for the ports tree. The first
	- critical step is mounting <filename>/usr/ports</filename> from
	- the same machine to all the machines in the build set. You
	- can then set up <filename>/etc/make.conf</filename> properly
	- to share distfiles. You should set <makevar>DISTDIR</makevar>
	- to a common shared directory that is writable by whichever
	- user <username>root</username> is mapped to by your NFS
	- mounts. Each machine should set
	- <makevar>WRKDIRPREFIX</makevar> to a local build directory.
	- Finally, if you are going to be building and distributing
	- packages, you should set <makevar>PACKAGES</makevar> to a
	+ critical step is to mount <filename
	+ class="directory">/usr/ports</filename> from the same
	+ machine to all the machines in the build set. Then, configure
	+ <filename>/etc/make.conf</filename> properly to share
	+ distfiles. Set <makevar>DISTDIR</makevar> to a common shared
	+ directory that is writable by whichever user
	+ <username>root</username> is mapped to by the NFS mounts.
	+ Each machine should set <makevar>WRKDIRPREFIX</makevar> to a
	+ local build directory. Finally, if the system is to build and
	+ distribute packages, set <makevar>PACKAGES</makevar> to a
	directory similar to <makevar>DISTDIR</makevar>.</para>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/desktop/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/desktop/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/desktop/chapter.xml (revision 41355)
	@@ -1,1309 +1,1298 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project
	$FreeBSD$
	-->

	<chapter id="desktop">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Christophe</firstname>
	<surname>Juniet</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</chapterinfo>

	<title>Desktop Applications</title>

	<sect1 id="desktop-synopsis">
	<title>Synopsis</title>

	<para>While &os; is popular as a server for its performance and
	stability, it is also suited for day-to-day use as a desktop.
	- With over 24,000 applications available as <link
	+ With over &os.numports; applications available as <link
	linkend="packages-using">packages</link> or <link
	linkend="ports-using">ports</link>, it is easy to build a
	customized desktop that runs a wide variety of desktop
	applications. This chapter demonstrates how to install some
	popular desktop applications effortlessly using packages or the
	&os; Ports Collection.</para>

	<para>As &os; features <link linkend="linuxemu">&linux; binary
	compatibility</link>, many applications developed for &linux;
	can be installed on a &os; desktop. Many of the ports using
	&linux; binary compatibility start with <quote>linux-</quote>.
	This chapter assumes that &linux; binary compatibility has been
	enabled before any &linux; applications are installed.</para>

	<para>This chapter demonstrates how to install the following
	desktop applications:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="3">
	<thead>
	<row>
	<entry>Type of Application</entry>
	<entry>Application Name</entry>
	<entry>Package Name</entry>
	<entry>Ports Name</entry>
	</row>
	</thead>

	<tbody>

	<row>
	<entry>Browser</entry>
	<entry><application>Firefox</application></entry>
	<entry><literal>firefox</literal></entry>
	<entry><filename
	role="package">www/firefox</filename></entry>
	</row>

	<row>
	<entry>Browser</entry>
	<entry><application>Opera</application></entry>
	<entry><literal>opera</literal></entry>
	<entry><filename
	role="package">www/opera</filename></entry>
	</row>

	<row>
	<entry>Browser</entry>
	<entry><application>Konqueror</application></entry>
	<entry><literal>kde4-baseapps</literal></entry>
	<entry><filename
	role="package">x11/kde4-baseapps</filename></entry>
	</row>

	<row>
	<entry>Browser</entry>
	<entry><application>Chromium</application></entry>
	<entry><literal>chromium</literal></entry>
	<entry><filename
	role="package">www/chromium</filename></entry>
	</row>

	<row>
	<entry>Productivity</entry>
	<entry><application>Calligra</application></entry>
	<entry><literal>calligra</literal></entry>
	<entry><filename
	role="package">editors/calligra</filename></entry>
	</row>

	<row>
	<entry>Productivity</entry>
	<entry><application>AbiWord</application></entry>
	<entry><literal>abiword</literal></entry>
	<entry><filename
	role="package">editors/abiword</filename></entry>
	</row>

	<row>
	<entry>Productivity</entry>
	<entry><application>The GIMP</application></entry>
	<entry><literal>gimp</literal></entry>
	<entry><filename
	role="package">graphics/gimp</filename></entry>
	</row>

	<row>
	<entry>Productivity</entry>
	<entry><application>Apache
	OpenOffice</application></entry>
	<entry><literal>openoffice</literal></entry>
	<entry><filename
	role="package">editors/openoffice-3</filename></entry>
	</row>

	<row>
	<entry>Productivity</entry>
	<entry><application>LibreOffice</application></entry>
	<entry><literal>libreoffice</literal></entry>
	<entry><filename
	role="package">editors/libreoffice</filename></entry>
	</row>

	<row>
	<entry>Document Viewer</entry>
	<entry><application>&acrobat.reader;</application></entry>
	<entry><literal>no package due to
	license restriction</literal></entry>
	<entry><filename
	role="package">print/acroread9</filename></entry>
	</row>

	<row>
	<entry>Document Viewer</entry>
	<entry><application>gv</application></entry>
	<entry><literal>gv</literal></entry>
	<entry><filename
	role="package">print/gv</filename></entry>
	</row>

	<row>
	<entry>Document Viewer</entry>
	<entry><application>Xpdf</application></entry>
	<entry><literal>xpdf</literal></entry>
	<entry><filename
	role="package">graphics/xpdf</filename></entry>
	</row>

	<row>
	<entry>Document Viewer</entry>
	<entry><application>GQview</application></entry>
	<entry><literal>gqview</literal></entry>
	<entry><filename
	role="package">graphics/gqview</filename></entry>
	</row>

	<row>
	<entry>Finance</entry>
	<entry><application>GnuCash</application></entry>
	<entry><literal>gnucash</literal></entry>
	<entry><filename
	role="package">finance/gnucash</filename></entry>
	</row>

	<row>
	<entry>Finance</entry>
	<entry><application>Gnumeric</application></entry>
	<entry><literal>gnumeric</literal></entry>
	<entry><filename
	role="package">math/gnumeric</filename></entry>
	</row>

	<row>
	+ <entry>Finance</entry>
	<entry><application>KMyMoney</application></entry>
	<entry><literal>kmymoney-kde4</literal></entry>
	<entry><filename
	role="package">finance/kmymoney-kde4</filename></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>Before reading this chapter, you should know how to:</para>

	<itemizedlist>
	<listitem>
	<para>Install additional software using packages or
	ports.</para>
	</listitem>

	<listitem>
	<para>Enable &linux; binary compatibility.</para>
	</listitem>
	</itemizedlist>

	<para>For information on how to configure a multimedia
	- environment, refer to <link linkend="multimedia"></link>. For
	+ environment, refer to <xref linkend="multimedia"/>. For
	information on how to set up and use electronic mail, refer to
	- <link linkend="mail"></link>.</para>
	+ <xref linkend="mail"/>.</para>
	</sect1>

	<sect1 id="desktop-browsers">
	<title>Browsers</title>

	<indexterm>
	<primary>browsers</primary>
	<secondary>web</secondary>
	</indexterm>

	<para>&os; does not come with a pre-installed web browser.
	Instead, the <ulink
	url="http://www.FreeBSD.org/ports/www.html">www</ulink>
	category of the Ports Collection contains many browsers which
	can be installed as a package or compiled from the Ports
	Collection.</para>

	<para>The <application>KDE</application> and
	<application>GNOME</application> desktop environments include
	- their own HTML browser. Refer to <link linkend="x11-wm"></link>
	+ their own HTML browser. Refer to <xref linkend="x11-wm"/>
	for more information on how to set up these complete
	desktops.</para>

	<para>Some light-weight browsers include
	<filename role="package">www/dillo2</filename>,
	<filename role="package">www/links</filename>, and
	<filename role="package">www/w3m</filename>.</para>

	<para>This section demonstrates how to install the following
	popular web browsers and indicates if the application is
	resource-heavy, takes time to compile from ports, or has any
	major dependencies.</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="4">
	<thead>
	<row>
	<entry>Application Name</entry>
	<entry>Resources Needed</entry>
	<entry>Installation from Ports</entry>
	<entry>Notes</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><application>Firefox</application></entry>
	<entry>medium</entry>
	<entry>heavy</entry>
	- <entry><application>&os; and &linux; versions are
	- available</application></entry>
	+ <entry>&os; and &linux; versions are available</entry>
	</row>

	<row>
	<entry><application>Opera</application></entry>
	<entry>light</entry>
	<entry>light</entry>
	<entry>&os; and &linux; versions are available</entry>
	</row>

	<row>
	<entry><application>Konqueror</application></entry>
	<entry>medium</entry>
	<entry>heavy</entry>
	- <entry><application>Requires KDE</application>
	+ <entry>Requires <application>KDE</application>
	libraries</entry>
	</row>

	<row>
	<entry><application>Chromium</application></entry>
	<entry>medium</entry>
	<entry>heavy</entry>
	- <entry><application>Requires Gtk+</application></entry>
	+ <entry>Requires <application>Gtk+</application></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<sect2>
	<title>Firefox</title>

	<indexterm>
	<primary><application>Firefox</application></primary>
	</indexterm>

	<para><application>Firefox</application> is a modern, free,
	open source browser that is fully ported to &os;. It
	features a standards-compliant HTML display engine, tabbed
	browsing, popup blocking, extensions, improved security, and
	more. <application>Firefox</application> is based on the
	<application>Mozilla</application> codebase.</para>

	<para>Install the package of the latest release version of
	<application>Firefox</application> by typing:</para>

	<screen>&prompt.root; <userinput>pkg_add -r firefox</userinput></screen>

	<para>To instead install <application>Firefox</application>
	Extended Support Release (ESR) version, use:</para>

	<screen>&prompt.root; <userinput>pkg_add -r firefox-esr</userinput></screen>

	<para>Localized versions are available in <filename
	role="package">www/firefox-i18n</filename> and <filename
	role="package">www/firefox-esr-i18n</filename>.</para>

	<para>The Ports Collection can instead be used to compile
	the desired version of <application>firefox</application> from
	source code. This example builds <filename
	role="package">www/firefox</filename>, where
	<literal>firefox</literal> can be replaced with the ESR or
	localized version to install.</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/www/firefox</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<sect3 id="moz-java-plugin">
	<title>Firefox and &java; Plugin</title>

	<note>
	<para>The following sections assume that
	<application>Firefox</application> is already
	installed.</para>
	</note>

	<para><filename role="package">java/icedtea-web</filename>
	provides a free software web browser plugin for running
	Java applets. It can be installed as a package. To
	alternately compile the port:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/java/icedtea-web</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>Keep the default configuration options when compiling the
	port.</para>

	<para>Once installed, start <application>firefox</application>,
	enter <literal>about:plugins</literal> in the location bar and
	press <keycap>Enter</keycap>. A page listing the installed
	plugins will be displayed. The
	<application>&java;</application> plugin should be
	listed.</para>

	<para>If the browser is unable to find the plugin, each user
	will have to run the following command and relaunch the
	browser:</para>

	<screen>&prompt.user; <userinput>ln -s /usr/local/lib/IcedTeaPlugin.so \
	$HOME/.mozilla/plugins/</userinput></screen>
	</sect3>

	<sect3 id="moz-flash-plugin">

	<title>Firefox and &adobe; &flash; Plugin</title>

	<indexterm>
	<primary>Flash</primary>
	</indexterm>

	<para>A native &adobe; &flash; plugin is not available for &os;.
	However, a software layer (wrapper) for running the &linux;
	version of the plugin exists. This wrapper also provides
	support for other browser plugins such as &realplayer;.</para>

	- <para>The steps required to install and enable this plugin vary
	- by the &os; version:</para>
	+ <para>To install and enable this plugin:</para>

	<procedure>
	<step>
	- <title>Under &os; 7.X</title>
	-
	- <para>Install the <filename
	- role="package">www/nspluginwrapper</filename> package
	- or port. This application requires <filename
	- role="package">emulators/linux_base-fc4</filename> which
	- is a large port.</para>
	-
	- <para>Next, install <filename
	- role="package">www/linux-flashplugin9</filename>. This
	- will install &flash; 9.X which is the version known to
	- run correctly under &os; 7.X.</para>
	- </step>
	-
	- <step>
	- <title>Under &os; 8.X or Newer</title>
	-
	<para>Compile the <filename
	role="package">www/nspluginwrapper</filename> port.
	Due to licensing restrictions, a package is not available.
	This port requires <filename
	role="package">emulators/linux_base-f10</filename> which
	is a large port.</para>
	+ </step>

	- <para>Next, compile the <filename
	+ <step>
	+ <para>Compile the <filename
	role="package">www/linux-f10-flashplugin11</filename>
	port. Due to licensing restrictions, a package is not
	available.</para>
	+ </step>

	- <para>This version of &flash; requires the following link to
	- be created:</para>
	-
	+ <step>
	<screen>&prompt.root; <userinput>ln -s /usr/local/lib/npapi/linux-f10-flashplugin/libflashplayer.so \
	/usr/local/lib/browser_plugins/</userinput></screen>

	- <para>Manually create <filename
	+ <para>Create <filename
	class="directory">/usr/local/lib/browser_plugins</filename>
	if it does not already exist on the system.</para>
	</step>
	- </procedure>

	- <para>Once the right &flash; port, according to the &os;
	- version, is installed, the plugin must be installed by each
	- user with <command>nspluginwrapper</command>:</para>
	+ <step>
	+ <para>Before flash is first used each user must run:</para>

	- <screen>&prompt.user; <userinput>nspluginwrapper -v -a -i</userinput></screen>
	+ <screen>&prompt.user; <userinput>nspluginwrapper -v -a -i</userinput></screen>

	- <para>Start the browser, enter <literal>about:plugins</literal>
	- in the location bar and press <keycap>Enter</keycap>. A list
	- should appear with all the currently available plugins.</para>
	+ <para>When flash is updated each user must run:</para>
	+
	+ <screen>&prompt.user; <userinput>nspluginwrapper -v -a -u</userinput></screen>
	+
	+ <para>Start the browser, enter
	+ <literal>about:plugins</literal> in the location bar and
	+ press <keycap>Enter</keycap>. A list should appear with
	+ all the currently available plugins.</para>
	+ </step>
	+
	+ </procedure>
	</sect3>

	<sect3 id="moz-swfdec-flash-plugin">
	<title>Firefox and Swfdec &flash; Plugin</title>

	<para>Swfdec is the library for decoding and rendering &flash;
	animations. Swfdec-Mozilla is a plugin for
	<application>Firefox</application> browsers that uses the
	Swfdec library for playing SWF files. It is still in heavy
	development.</para>

	<para>To install the package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r swfdec-plugin</userinput></screen>

	<para>If the package is not available, compile and install it
	from the Ports Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/www/swfdec-plugin</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>Restart the browser for this plugin to take
	effect.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Opera</title>

	<indexterm>
	<primary><application>Opera</application></primary>
	</indexterm>

	<para><application>Opera</application> is a full-featured and
	standards-compliant browser which is still lightweight and
	fast. It comes with a built-in mail and news reader, an IRC
	client, an RSS/Atom feeds reader, and more. It is available
	as a native &os; version and as a version that runs under
	&linux; emulation.</para>

	<para>This command installs the package of the &os; version of
	<application>Opera</application>. Replace
	<literal>opera</literal> with <literal>linux-opera</literal>
	to instead install the &linux; version.</para>

	<screen>&prompt.root; <userinput>pkg_add -r opera</userinput></screen>

	<para>Alternately, install either version through the Ports
	Collection. This example compiles the native version:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/www/opera</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>To install the &linux; version, substitute
	<literal>linux-opera</literal> in place of
	<literal>opera</literal>.</para>

	<para>To install &adobe; &flash; plugin support, first compile
	the <filename
	role="package">www/linux-f10-flashplugin11</filename> port,
	as a package is not available due to licensing restrictions.
	Then install either the <filename
	role="package">www/opera-linuxplugins</filename> port
	or package. This example compiles both from ports:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/www/linux-f10-flashplugin11</userinput>
	&prompt.root; <userinput>make install clean</userinput>
	&prompt.root; <userinput>cd /usr/ports/www/opera-linuxplugins</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>Once installed, check the presence of the plugin by
	starting the browser, entering
	<literal>opera:plugins</literal> in the location bar and
	pressing <keycap>Enter</keycap>. A list should appear with
	all the currently available plugins.</para>

	<para>To add the <application>&java;</application> plugin,
	follow the <link linkend="moz-java-plugin">instructions for
	Firefox</link>.</para>
	</sect2>

	<sect2>
	<title>Konqueror</title>

	<indexterm>
	<primary><application>Konqueror</application></primary>
	</indexterm>

	<para><application>Konqueror</application> is part of <filename
	role="package">x11/kde4-baseapps</filename>.
	<application>Konqueror</application> is more than a web
	browser as it is also a file manager and a multimedia
	viewer.</para>

	<para><application>Konqueror</application> supports WebKit as
	well as its own KHTML. WebKit is a rendering engine used by
	many modern browsers including Chromium. To use WebKit with
	<application>Konqueror</application> on &os;, install
	the <filename
	role="package">www/kwebkitpart</filename> package or
	port. This example compiles the port:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/www/kwebkitpart</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>To enable WebKit within
	<application>Konqueror</application>, click
	<quote>Settings</quote>, <quote>Configure Konqueror</quote>.
	In the <quote>General</quote> settings page, click the
	drop-down menu next to <quote>Default web browser
	engine</quote> and change <quote>KHTML</quote> to
	<quote>WebKit</quote>.</para>

	<para><application>Konqueror</application> also supports
	<application>&flash;</application>. A <quote>How To</quote>
	guide for getting <application>&flash;</application> support
	on <application>Konqueror</application> is available at <ulink
	url="http://freebsd.kde.org/howtos/konqueror-flash.php"></ulink>.</para>
	</sect2>

	<sect2>
	<title>Chromium</title>

	<indexterm>
	<primary><application>Chromium</application></primary>
	</indexterm>

	<para><application>Chromium</application> is an open source
	browser project that aims to build a safer, faster, and more
	stable web browsing experience.
	<application>Chromium</application> features tabbed browsing,
	popup blocking, extensions, and much more.
	<application>Chromium</application> is the open source project
	upon which the Google Chrome web browser is based.</para>

	<para><application>Chromium</application> can be installed as a
	package by typing:</para>

	<screen>&prompt.root; <userinput>pkg_add -r chromium</userinput></screen>

	<para>Alternatively, <application>Chromium</application> can be
	compiled from source using the Ports Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/www/chromium</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<note>
	<para>The executable for <application>Chromium</application>
	is <filename>/usr/local/bin/chrome</filename>, not
	<filename>/usr/local/bin/chromium</filename>.</para>
	</note>

	<sect3 id="chromium-java-plugin">
	<title>Chromium and &java; Plugin</title>

	<note>
	<para>The following sections assume that
	<application>Chromium</application> is already
	installed.</para>
	</note>

	<para>To install &java; plugin support, follow the instructions
	- in <link linkend="moz-java-plugin"></link>.</para>
	+ in <xref linkend="moz-java-plugin"/>.</para>

	<para>Once &java; support is installed, start
	<application>Chromium</application>, and enter
	<literal>about:plugins</literal> in the address bar.
	IcedTea-Web should be listed as one of the installed
	plugins.</para>

	<para>If <application>Chromium</application> does not display
	the IcedTea-Web plugin, run the following commands, and
	restart the web browser:</para>

	<screen>&prompt.root; <userinput>mkdir -p /usr/local/share/chromium/plugins
	&prompt.root; ln -s /usr/local/lib/IcedTeaPlugin.so \
	/usr/local/share/chromium/plugins/</userinput></screen>
	</sect3>

	<sect3 id="chromium-flash-plugin">
	<title>Chromium and &adobe; &flash; Plugin</title>

	<para>Configuring <application>Chromium</application> and
	&adobe; &flash; is similar to the
	<link linkend="moz-flash-plugin">instructions for
	Firefox</link>. No additional configuration should be
	necessary, since <application>Chromium</application> is able
	to use some plugins from other browsers.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="desktop-productivity">
	<title>Productivity</title>

	<para>When it comes to productivity, new users often look for a
	good office suite or a friendly word processor. While some
	<link linkend="x11-wm">desktop environments</link> like
	<application>KDE</application> already provide an office suite,
	there is no default productivity package. Several office
	suites and word processors are available for &os;, regardless
	of the installed desktop environment.</para>

	<para>This section demonstrates how to install the following
	- popular web browsers and indicates if the application is
	- resource-heavy, takes time to compile from ports, or has any
	+ popular productivity software and indicates if the application
	+ is resource-heavy, takes time to compile from ports, or has any
	major dependencies.</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="4">
	<thead>
	<row>
	<entry>Application Name</entry>
	<entry>Resources Needed</entry>
	<entry>Installation from Ports</entry>
	<entry>Major Dependencies</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><application>Calligra</application></entry>
	<entry>light</entry>
	<entry>heavy</entry>
	<entry><application>KDE</application></entry>
	</row>

	<row>
	<entry><application>AbiWord</application></entry>
	<entry>light</entry>
	<entry>light</entry>
	<entry><application>Gtk+</application> or
	<application>GNOME</application></entry>
	</row>

	<row>
	<entry><application>The Gimp</application></entry>
	<entry>light</entry>
	<entry>heavy</entry>
	<entry><application>Gtk+</application></entry>
	</row>

	<row>
	<entry><application>Apache
	OpenOffice</application></entry>
	<entry>heavy</entry>
	<entry>huge</entry>
	<entry><application>&jdk;</application> and
	<application>Mozilla</application></entry>
	</row>

	<row>
	<entry><application>LibreOffice</application></entry>
	<entry>somewhat heavy</entry>
	<entry>huge</entry>
	<entry><application>Gtk+</application>, or
	<application>KDE</application>/
	<application>GNOME</application>, or
	<application>&jdk;</application></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<sect2>
	<title>Calligra</title>

	<indexterm>
	<primary><application>Calligra</application></primary>
	</indexterm>
	<indexterm>
	<primary>office suite</primary>
	<secondary><application>Calligra</application></secondary>
	</indexterm>

	<para>The KDE community provides its desktop environment with
	an office suite which can be used outside of
	<application>KDE</application>.
	<application>Calligra</application> includes standard
	components that can be found in other office suites.
	<application>Words</application> is the word processor,
	<application>Sheets</application> is the spreadsheet program,
	<application>Stage</application> manages slide presentations,
	and <application>Karbon</application> is used to draw
	graphical documents.</para>

	<para><filename
	role="package">editors/calligra</filename> can be installed
	as a package or a port. To install the package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r calligra</userinput></screen>

	<para>If the package is not available, use the Ports Collection
	instead:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/editors/calligra</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>
	</sect2>

	<sect2>
	<title>AbiWord</title>

	<indexterm>
	<primary><application>AbiWord</application></primary>
	</indexterm>

	<para><application>AbiWord</application> is a free word
	processing program similar in look and feel to
	<application>&microsoft; Word</application>. It is suitable
	for typing papers, letters, reports, memos, and so forth. It
	is fast, contains many features, and is user-friendly.</para>

	<para><application>AbiWord</application> can import or export
	many file formats, including some proprietary ones like
	&microsoft; <filename>.doc</filename>.</para>

	<para>To install the <application>AbiWord</application>
	package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r abiword</userinput></screen>

	<para>If the package is not available, it can be compiled from
	the Ports Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/editors/abiword</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>
	</sect2>

	<sect2>
	<title>The GIMP</title>

	<indexterm>
	<primary><application>The GIMP</application></primary>
	</indexterm>

	<para>For image authoring or picture retouching,
	<application>The GIMP</application> provides a sophisticated
	image manipulation program. It can be used as a simple paint
	program or as a quality photo retouching suite. It supports a
	large number of plugins and features a scripting interface.
	<application>The GIMP</application> can read and write a wide
	range of file formats and supports interfaces with scanners
	and tablets.</para>

	<para>To install the package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r gimp</userinput></screen>

	<para>Alternately, use the Ports Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/graphics/gimp</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>The <ulink
	url="http://www.FreeBSD.org/ports/graphics.html">graphics</ulink>
	category of the Ports Collection contains several
	<application>GIMP</application>-related plugins, help
	files, and user manuals.</para>

	</sect2>

	<sect2>
	<title>Apache OpenOffice</title>

	<indexterm>
	<primary>
	<application>Apache OpenOffice</application>
	</primary>
	</indexterm>
	<indexterm>
	<primary>office suite</primary>
	<secondary>
	<application>Apache OpenOffice</application>
	</secondary>
	</indexterm>

	<para>On 1 June 2011, &oracle; donated the
	<application>OpenOffice.org</application> code base to the
	Apache Software Foundation.
	<application>OpenOffice.org</application> is now known as
	<application>Apache OpenOffice</application> and is developed
	under the wing of the Apache Software Foundation's
	Incubator.</para>

	<para><application>Apache OpenOffice</application> includes all
	of the mandatory applications in a complete office
	productivity suite: a word processor, spreadsheet,
	presentation manager, and drawing program. Its user
	interface is very similar to other office suites, and it can
	import and export in various popular file formats. It is
	available in a number of different languages and
	internationalization has been extended to interfaces, spell
	checkers, and dictionaries.</para>

	<para>The word processor of
	<application>Apache OpenOffice</application> uses a native XML
	file format for increased portability and flexibility. The
	spreadsheet program features a macro language which can be
	interfaced with external databases.
	<application>Apache OpenOffice</application> is stable and
	runs natively on &windows;, &solaris;, &linux;, &os;, and
	&macos; X. More information about <application>Apache
	OpenOffice</application> can be found on the <ulink
	url="http://incubator.apache.org/openofficeorg/">Apache
	OpenOffice web site</ulink>. For &os; specific
	information, and to directly download packages, refer to the
	web site of the <ulink
	url="http://porting.openoffice.org/freebsd/">&os; Apache
	OpenOffice Porting Team</ulink>.</para>

	<para>To install the <application>Apache
	OpenOffice</application> package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r apache-openoffice</userinput></screen>

	<note>
	<para>When running a -RELEASE version of &os;, this should
	work. Otherwise, download the latest package from the
	website of the &os;
	<application>Apache OpenOffice</application> Porting Team
	and install it using &man.pkg.add.1;. Both the current
	release and development versions are available for download
	at this web site.</para>
	</note>

	<para>Once the package is installed, type the following command
	to launch <application>Apache OpenOffice</application>:</para>

	<screen>&prompt.user; <userinput>openoffice-<replaceable>X.Y.Z</replaceable></userinput></screen>

	<para>where <replaceable>X.Y.Z</replaceable> is the version
	number of the installed version of
	<application>Apache OpenOffice</application>.</para>

	<note>
	<para>During the first launch, some questions will be asked
	and a <filename>.openoffice.org</filename> folder
	will be created in the user's home directory.</para>
	</note>

	<para>If the desired <application>Apache
	OpenOffice</application> package is not available, compiling
	the port is still an opton. However, this requires a lot of
	disk space and a fairly long time to compile:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/editors/openoffice-3</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<note>
	<para>To build a localized version, replace the previous
	command with:</para>

	<screen>&prompt.root; <userinput>make LOCALIZED_LANG=<replaceable>your_language</replaceable> install clean</userinput></screen>

	<para>Replace
	<replaceable>your_language</replaceable> with the correct
	language ISO-code. A list of supported language codes is
	available in
	<filename>files/Makefile.localized</filename>, located in
	the port's directory.</para>
	</note>
	</sect2>

	<sect2>
	<title>LibreOffice</title>

	<indexterm>
	<primary><application>LibreOffice</application></primary>
	</indexterm>
	<indexterm>
	<primary>office suite</primary>
	<secondary><application>LibreOffice</application></secondary>
	</indexterm>

	<para><application>LibreOffice</application> is a free software
	office suite developed by <ulink
	url="http://www.documentfoundation.org/">The Document
	Foundation</ulink>. It is compatible with other major
	office suites and available on a variety of platforms. It is
	a rebranded fork of <application>OpenOffice.org</application>
	which includes all of the mandatory applications in a complete
	office productivity suite: a word processor, spreadsheet,
	presentation manager, drawing program, database management
	program, and a tool for creating and editing mathematical
	formula. It is available in a number of different languages
	and internationalization has been extended to interfaces,
	spell checkers, and dictionaries.</para>

	<para>The word processor of
	<application>LibreOffice</application> uses a native XML file
	format for increased portability and flexibility. The
	spreadsheet program features a macro language which can be
	interfaced with external databases.
	<application>LibreOffice</application> is stable and runs
	natively on &windows;, &linux;, &os;, and &macos; X.
	More information about
	<application>LibreOffice </application> can be found on the
	<ulink url="http://www.libreoffice.org/">LibreOffice web
	site</ulink>.</para>

	<para>To install the English version of the
	<application>LibreOffice</application> package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r libreoffice</userinput></screen>

	<para>The <ulink
	url="http://www.FreeBSD.org/ports/editors.html">editors</ulink>
	category of the Ports Collection contains several
	localizations for <application>LibreOffice</application>.
	When installing a localized package, replace
	<literal>libreoffice</literal> with the name of the
	localized package.</para>

	<para>Once the package is installed, type the following command
	to run <application>LibreOffice</application>:</para>

	<screen>&prompt.user; <userinput>libreoffice</userinput></screen>

	<note>
	<para>During the first launch, some questions will be asked
	and a <filename class="directory">.libreoffice</filename>
	folder will be created in the user's home directory.</para>
	</note>

	<para>If the desired <application>LibreOffice</application>
	package is not available, compiling the port is still an
	option. However, this requires a lot of disk space and a
	fairly long time to compile. This example compiles the
	English version:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/editors/libreoffice</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<note>
	<para>To build a localized version,
	<application>cd</application> into the port directory
	of the desired language. Supported languages can be found
	in the <ulink
	url="http://www.FreeBSD.org/ports/editors.html">editors</ulink>
	category of the Ports Collection.</para>
	</note>
	</sect2>
	</sect1>

	<sect1 id="desktop-viewers">
	<title>Document Viewers</title>

	<para>Some new document formats have gained popularity since
	the advent of &unix; and the viewers they require may not be
	available in the base system. This section demonstrates how to
	install the following viewers:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="4">
	<thead>
	<row>
	<entry>Application Name</entry>
	<entry>Resources Needed</entry>
	<entry>Installation from Ports</entry>
	<entry>Major Dependencies</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><application>&acrobat.reader;</application></entry>
	<entry>light</entry>
	<entry>light</entry>
	<entry>&linux; binary compatibility</entry>
	</row>

	<row>
	<entry><application>gv</application></entry>
	<entry>light</entry>
	<entry>light</entry>
	<entry><application>Xaw3d</application></entry>
	</row>

	<row>
	<entry><application>Xpdf</application></entry>
	<entry>light</entry>
	<entry>light</entry>
	<entry><application>FreeType</application></entry>
	</row>

	<row>
	<entry><application>GQview</application></entry>
	<entry>light</entry>
	<entry>light</entry>
	<entry><application>Gtk+</application> or
	<application>GNOME</application></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<sect2>
	<title>&acrobat.reader;</title>

	<indexterm>
	<primary><application>Acrobat Reader</application></primary>
	</indexterm>
	<indexterm>
	<primary>PDF</primary>
	<secondary>viewing</secondary>
	</indexterm>

	<para>Many documents are now distributed as Portable Document
	Format (PDF) files. One popular viewer for PDFs is
	<application>&acrobat.reader;</application>,
	released by &adobe; for &linux;. As &os; can run &linux;
	binaries, it is also available for &os;. Due to
	licensing restrictions, a package is not available so it must
	be compiled from ports. Several localizations are
	available from the <ulink
	url="http://www.FreeBSD.org/ports/print.html">print</ulink>
	category of the Ports Collection.</para>

	<para>This command installs the English version of
	<application>&acrobat.reader; 9</application> from the Ports
	Collection. To instead install a localized version,
	<application>cd</application> into the desired port's
	directory.</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/print/acroread9</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	</sect2>

	<sect2>
	<title><application>gv</application></title>

	<indexterm>
	<primary><application>gv</application></primary>
	</indexterm>
	<indexterm>
	<primary>PDF</primary>
	<secondary>viewing</secondary>
	</indexterm>
	<indexterm>
	<primary>PostScript</primary>
	<secondary>viewing</secondary>
	</indexterm>

	<para><ulink
	url="http://www.gnu.org/software/gv/">gv</ulink> is a
	&postscript; and PDF viewer. It is based on
	<application>ghostview</application>, but has a nicer look
	due to the <application>Xaw3d</application> library. It is
	fast with a clean interface. <application>gv</application>
	has many configurable features, such as orientation, paper
	size, scale, and anti-aliasing. Almost any operation can be
	performed with either the keyboard or the mouse.</para>

	<para>To install <application>gv</application> as a
	package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r gv</userinput></screen>

	<para>If a package is unavailable, use the Ports
	Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/print/gv</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>
	</sect2>

	<sect2>
	<title>Xpdf</title>

	<indexterm>
	<primary><application>Xpdf</application></primary>
	</indexterm>
	<indexterm>
	<primary>PDF</primary>
	<secondary>viewing</secondary>
	</indexterm>

	<para>For users that prefer a small &os; PDF viewer,
	<ulink
	url="http://www.foolabs.com/xpdf/">xpdf</ulink> provides a
	light-weight and efficient viewer which requires few
	resources. It uses the standard X fonts and does not require
	<application>&motif;</application> or any other X
	toolkit.</para>

	<para>To install the <application>Xpdf</application>
	package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r xpdf</userinput></screen>

	<para>If the package is not available, use the Ports
	Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/graphics/xpdf</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>Once the installation is complete, launch
	<command>xpdf</command> and use the right mouse button to
	activate the menu.</para>
	</sect2>

	<sect2>
	<title>GQview</title>

	<indexterm>
	<primary><application>GQview</application></primary>
	</indexterm>

	<para><ulink
	url="http://gqview.sourceforge.net/">GQview</ulink> is
	an image manager which supports viewing a file with a single
	click, launching an external editor, and thumbnail previews.
	It also features a slideshow mode and some basic file
	operations, making it easy to manage image collections and to
	find duplicate files. <application>GQview</application>
	supports full screen viewing and internationalization.</para>

	<para>To install the
	<application>GQview</application> package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r gqview</userinput></screen>

	<para>If the package is not available, use the Ports
	Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/graphics/gqview</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>
	</sect2>
	</sect1>

	<sect1 id="desktop-finance">
	<title>Finance</title>

	<para>For managing personal finances on a &os; desktop, some
	powerful and easy-to-use applications can be installed. Some
	are compatible with widespread file formats, such as the formats
	used by <application><trademark
	class="registered">Quicken</trademark></application> and
	<application>Excel</application>.</para>

	<para>This section covers these programs:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="4">
	<thead>
	<row>
	<entry>Application Name</entry>
	<entry>Resources Needed</entry>
	<entry>Installation from Ports</entry>
	<entry>Major Dependencies</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><application>GnuCash</application></entry>
	<entry>light</entry>
	<entry>heavy</entry>
	<entry><application>GNOME</application></entry>
	</row>

	<row>
	<entry><application>Gnumeric</application></entry>
	<entry>light</entry>
	<entry>heavy</entry>
	<entry><application>GNOME</application></entry>
	</row>

	<row>
	<entry><application>KMyMoney</application></entry>
	<entry>light</entry>
	<entry>heavy</entry>
	<entry><application>KDE</application></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<sect2>
	<title>GnuCash</title>

	<indexterm>
	<primary><application>GnuCash</application></primary>
	</indexterm>

	<para><ulink
	url="http://www.gnucash.org/">GnuCash</ulink> is part of the
	<application>GNOME</application> effort to provide
	user-friendly, yet powerful, applications to end-users.
	<application>GnuCash</application> can be used to keep track
	of income and expenses, bank accounts, and stocks. It
	features an intuitive interface while remaining
	professional.</para>

	<para><application>GnuCash</application> provides a smart
	register, a hierarchical system of accounts, and many keyboard
	accelerators and auto-completion methods. It can split a
	single transaction into several more detailed pieces.
	<application>GnuCash</application> can import and merge
	<application>Quicken</application> QIF files. It also handles
	most international date and currency formats.</para>

	<para>To install the <application>GnuCash</application>
	package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r gnucash</userinput></screen>

	<para>If the package is not available, use the Ports
	Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/finance/gnucash</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>
	</sect2>

	<sect2>
	<title>Gnumeric</title>

	<indexterm>
	<primary><application>Gnumeric</application></primary>
	</indexterm>
	<indexterm>
	<primary>spreadsheet</primary>
	<secondary><application>Gnumeric</application></secondary>
	</indexterm>

	<para><ulink
	url="http://projects.gnome.org/gnumeric/index.shtml">Gnumeric</ulink>
	is a spreadsheet program developed by the
	<application>GNOME</application> community. It features
	convenient automatic <quote>guessing</quote> of user input
	according to the cell format with an autofill system for many
	sequences. It can import files in a number of popular
	formats, including <application>Excel</application>,
	<application>Lotus 1-2-3</application>, and
	<application>Quattro Pro</application>. It has a large number
	of built-in functions and allows all of the usual cell formats
	such as number, currency, date, time, and much more.</para>

	<para>To install <application>Gnumeric</application> as a
	package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r gnumeric</userinput></screen>

	<para>If the package is not available, use the Ports
	Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/math/gnumeric</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>
	</sect2>

	<sect2>
	<title>KMyMoney</title>

	<indexterm><primary><application>KMyMoney</application></primary></indexterm>

	<indexterm>
	<primary>spreadsheet</primary>
	<secondary><application>KMyMoney</application></secondary>
	</indexterm>

	<para><ulink
	url="http://kmymoney2.sourceforge.net">KMyMoney</ulink>
	is a personal finance created by the
	<application>KDE</application> community.
	<application>KMyMoney</application> intends to provide and
	incorporate all the important features found in commercial
	personal finance manager applications. It also highlights
	ease-of-use and proper double-entry accounting among its
	features. <application>KMyMoney</application> imports from
	standard Quicken Interchange Format (QIF) files, tracks
	investments, handles multiple currencies, and provides a
	wealth of reports.</para>

	<para>To install <application>KMyMoney</application> as a
	package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r kmymoney-kde4</userinput></screen>

	<para>If the package is not available, use the Ports
	Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/finance/kmymoney-kde4</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/disks/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/disks/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/disks/chapter.xml (revision 41355)
	@@ -1,4611 +1,4592 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="disks">
	<title>Storage</title>

	<sect1 id="disks-synopsis">
	<title>Synopsis</title>

	<para>This chapter covers the use of disks in &os;. This
	includes memory-backed disks, network-attached disks,
	standard SCSI/IDE storage devices, and devices using the USB
	interface.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>The terminology &os; uses to describe the organization
	of data on a physical disk.</para>
	</listitem>

	<listitem>
	<para>How to add additional hard disks to a &os;
	system.</para>
	</listitem>

	<listitem>
	<para>How to configure &os; to use USB storage devices.</para>
	</listitem>

	<listitem>
	<para>How to set up virtual file systems, such as memory
	disks.</para>
	</listitem>

	<listitem>
	<para>How to use quotas to limit disk space usage.</para>
	</listitem>

	<listitem>
	<para>How to encrypt disks to secure them against
	attackers.</para>
	</listitem>

	<listitem>
	<para>How to create and burn CDs and DVDs on &os;.</para>
	</listitem>

	<listitem>
	<para>The various storage media options for backups.</para>
	</listitem>

	<listitem>
	<para>How to use the backup programs available under
	&os;.</para>
	</listitem>

	<listitem>
	<para>How to backup to floppy disks.</para>
	</listitem>

	<listitem>
	<para>What file system snapshots are and how to use them
	efficiently.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	<para>Know how to <link linkend="kernelconfig">configure and
	install a new &os; kernel</link>.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="disks-naming">
	<title>Device Names</title>

	<para>The following is a list of physical storage devices
	supported in &os;, and their associated device names.</para>

	<table id="disk-naming-physical-table" frame="none">
	<title>Physical Disk Naming Conventions</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Drive type</entry>
	<entry>Drive device name</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>IDE hard drives</entry>
	<entry><literal>ad</literal></entry>
	</row>

	<row>
	<entry>IDE CDROM drives</entry>
	<entry><literal>acd</literal></entry>
	</row>

	<row>
	<entry>SCSI hard drives and USB Mass storage
	devices</entry>
	<entry><literal>da</literal></entry>
	</row>

	<row>
	<entry>SCSI CDROM drives</entry>
	<entry><literal>cd</literal></entry>
	</row>

	<row>
	<entry>Assorted non-standard CDROM drives</entry>
	<entry><literal>mcd</literal> for Mitsumi CD-ROM and
	<literal>scd</literal> for Sony CD-ROM devices</entry>
	</row>

	<row>
	<entry>Floppy drives</entry>
	<entry><literal>fd</literal></entry>
	</row>

	<row>
	<entry>SCSI tape drives</entry>
	<entry><literal>sa</literal></entry>
	</row>

	<row>
	<entry>IDE tape drives</entry>
	<entry><literal>ast</literal></entry>
	</row>

	<row>
	<entry>Flash drives</entry>
	<entry><literal>fla</literal> for &diskonchip; Flash
	device</entry>
	</row>

	<row>
	<entry>RAID drives</entry>
	<entry><literal>aacd</literal> for &adaptec; AdvancedRAID,
	<literal>mlxd</literal> and <literal>mlyd</literal>
	for &mylex;,
	<literal>amrd</literal> for AMI &megaraid;,
	<literal>idad</literal> for Compaq Smart RAID,
	<literal>twed</literal> for &tm.3ware; RAID.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect1>

	<sect1 id="disks-adding">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>David</firstname>
	<surname>O'Brien</surname>
	<contrib>Originally contributed by </contrib>
	</author>
	</authorgroup>
	<!-- 26 Apr 1998 -->
	</sect1info>

	<title>Adding Disks</title>

	<indexterm>
	<primary>disks</primary>
	<secondary>adding</secondary>
	</indexterm>

	<para>This section describes how to add a new
	<acronym>SCSI</acronym> disk to a machine that currently only
	has a single drive. First, turn off the computer and install
	the drive in the computer following the instructions of the
	computer, controller, and drive manufacturers. Reboot
	the system and become <username>root</username>.</para>

	<para>Inspect <filename>/var/run/dmesg.boot</filename> to ensure
	the new disk was found. In this example, the newly added SCSI
	drive should appear as <devicename>da1</devicename>.</para>

	<indexterm><primary>partitions</primary></indexterm>
	<indexterm><primary>slices</primary></indexterm>
	<indexterm>
	<primary><command>fdisk</command></primary>
	</indexterm>

	<para>&os; runs on IBM-PC compatible computers, therefore it
	must take into account the PC BIOS partitions which are
	different from the traditional BSD partitions. A PC disk has up
	to four BIOS partition entries. If the disk is going to be
	truly dedicated to &os;, use <emphasis>dedicated</emphasis>
	mode. Otherwise, &os; will have to live within one of the PC
	BIOS partitions. &os; calls the PC BIOS partitions
	<emphasis>slices</emphasis> so as not to confuse them with
	traditional BSD partitions. Slices may also be used on a disk
	that is dedicated to &os;, but used in a computer that also has
	another operating system installed. This is a good way to avoid
	confusing the <command>fdisk</command> utility of non-&os;
	operating systems.</para>

	<para>In the slice case, the drive will be added as
	<filename>/dev/da1s1e</filename>. This is read as: SCSI disk,
	unit number 1 (second SCSI disk), slice 1 (PC BIOS partition 1),
	and <filename>e</filename> BSD partition. In the dedicated
	case, the drive will be added as
	<filename>/dev/da1e</filename>.</para>

	<para>Due to the use of 32-bit integers to store the number of
	sectors, &man.bsdlabel.8; is limited to 2^32-1 sectors per disk,
	or 2TB in most cases. The &man.fdisk.8; format allows a
	starting sector of no more than 2^32-1 and a length of no more
	than 2^32-1, limiting partitions to 2TB and disks to 4TB, in
	most cases. The &man.sunlabel.8; format is limited to 2^32-1
	sectors per partition and 8 partitions for a total of 16TB. For
	larger disks, &man.gpart.8; may be used to create
	<acronym>GPT</acronym> partitions. <acronym>GPT</acronym> has
	the added benefit of not being limited to 4 slices.</para>

	<sect2>
	<title>Using &man.sysinstall.8;</title>

	<indexterm>
	<primary><application>sysinstall</application></primary>
	<secondary>adding disks</secondary>
	</indexterm>
	<indexterm>
	<primary>su</primary>
	</indexterm>

	<procedure>
	<step>
	<title>Navigating
	<application>sysinstall</application></title>

	<para><command>sysinstall</command> can be used to partition
	and label a new disk using its easy-to-use menus. As
	<username>root</username>, run
	<command>sysinstall</command> and enter the
	<literal>Configure</literal> menu. Within the
	<literal>&os; Configuration Menu</literal>, scroll down
	and select the <literal>Fdisk</literal> option.</para>
	</step>

	<step>
	<title><application>fdisk</application> Partition
	Editor</title>

	<para>Once inside <application>fdisk</application>, pressing
	<keycap>A</keycap> will use the entire disk for &os;.
	When asked whether to <quote>remain cooperative with
	any future possible operating systems</quote>, answer
	<literal>YES</literal>. Write the changes to the disk
	using <keycap>W</keycap>. Exit the fdisk editor by
	pressing <keycap>Q</keycap> which will prompt about
	the <quote>Master Boot Record</quote>. Since the disk is
	being added to an already running system, choose
	<literal>None</literal>.</para>
	</step>

	<step>
	<title>Disk Label Editor</title>

	<indexterm><primary>BSD partitions</primary></indexterm>

	<para>Next, exit <application>sysinstall</application> and
	start it again. Follow the directions above, except this
	time choose the <literal>Label</literal> option. This
	will enter the <literal>Disk Label Editor</literal>. This
	editor is used to create traditional BSD partitions. A
	disk can have up to eight partitions, labeled
	<literal>a-h</literal>. A few of the partition labels
	have special uses. The <literal>a</literal> partition is
	used for the root partition (<filename
	class="directory">/</filename>). Only the disk the
	system boots from should have an <literal>a</literal>
	partition. The <literal>b</literal> partition is used for
	swap partitions, and there can be many disks with swap
	partitions. The <literal>c</literal> partition addresses
	the entire disk in dedicated mode, or the entire &os;
	slice in slice mode. The other partitions are for general
	use.</para>

	<para>The label editor in
	<application>sysinstall</application> favors the
	<literal>e</literal> partition for non-root, non-swap
	partitions. Within the label editor, create a single file
	system by pressing <keycap>C</keycap>. When prompted if
	this will be a FS (file system) or swap, choose
	<literal>FS</literal> and type in a mount point such as
	<filename class="directory">/mnt</filename>). When adding
	a disk in post-install mode,
	<application>sysinstall</application> will not create
	entries in <filename>/etc/fstab</filename>, so the mount
	point you specify is not important.</para>

	<para>Press <keycap>W</keycap> to write the new label to the
	disk and create a file system on it. Ignore any errors
	from <application>sysinstall</application> indicating that
	it could not mount the new partition. Exit the label
	editor then <application>sysinstall</application>
	completely.</para>
	</step>

	<step>
	<title>Finish</title>

	<para>The last step is to edit
	<filename>/etc/fstab</filename> to add an entry for your
	new disk.</para>
	</step>
	</procedure>
	</sect2>

	<sect2>
	<title>Using Command Line Utilities</title>

	<sect3>
	<title>Using Slices</title>

	<para>The setup in the following example allows the new disk
	to work correctly with other operating systems that might be
	installed on the computer without confusing other operating
	systems' <command>fdisk</command> utilities. This method is
	recommended for new disk installs. Only use
	<literal>dedicated</literal> mode if there is a good reason
	to do so!</para>

	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 bs=1k count=1</userinput>
	&prompt.root; <userinput>fdisk -BI da1</userinput> #Initialize your new disk
	&prompt.root; <userinput>bsdlabel -B -w da1s1 auto</userinput> #Label it.
	&prompt.root; <userinput>bsdlabel -e da1s1</userinput> # Edit the bsdlabel just created and add any partitions.
	&prompt.root; <userinput>mkdir -p /1</userinput>
	&prompt.root; <userinput>newfs /dev/da1s1e</userinput> # Repeat this for every partition you created.
	&prompt.root; <userinput>mount /dev/da1s1e /1</userinput> # Mount the partition(s)
	&prompt.root; <userinput>vi /etc/fstab</userinput> # Add the appropriate entry/entries to your <filename>/etc/fstab</filename>.</screen>

	<para>For an IDE disk, substitute
	<filename>ad</filename> for <filename>da</filename>.</para>
	</sect3>

	<sect3>
	<title>Dedicated</title>

	<indexterm><primary>OS/2</primary></indexterm>

	<para>If the new drive will not be shared with another
	operating system, <literal>dedicated</literal> mode can be
	used. This mode can confuse Microsoft operating systems;
	however, no damage will be done by them. To configure a
	disk in dedicated mode:</para>

	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 bs=1k count=1</userinput>
	&prompt.root; <userinput>bsdlabel -Bw da1 auto</userinput>
	&prompt.root; <userinput>bsdlabel -e da1</userinput> # create the `e' partition
	&prompt.root; <userinput>newfs /dev/da1e</userinput>
	&prompt.root; <userinput>mkdir -p /1</userinput>
	&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/da1e
	&prompt.root; <userinput>mount /1</userinput></screen>

	<para>An alternate method is:</para>

	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 count=2</userinput>
	&prompt.root; <userinput>bsdlabel /dev/da1 \| bsdlabel -BR da1 /dev/stdin</userinput>
	&prompt.root; <userinput>newfs /dev/da1e</userinput>
	&prompt.root; <userinput>mkdir -p /1</userinput>
	&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/da1e
	&prompt.root; <userinput>mount /1</userinput></screen>

	</sect3>
	</sect2>
	</sect1>

	<sect1 id="raid">
	<title>RAID</title>

	<sect2 id="raid-soft">
	<title>Software RAID</title>

	<sect3 id="ccd">
	<sect3info>
	<authorgroup>
	<author>
	<firstname>Christopher</firstname>
	<surname>Shumway</surname>
	<contrib>Original work by </contrib>
	</author>
	</authorgroup>

	<authorgroup>
	<author>
	<firstname>Jim</firstname>
	<surname>Brown</surname>
	<contrib>Revised by </contrib>
	</author>
	</authorgroup>
	</sect3info>

	<title>Concatenated Disk Driver (CCD) Configuration</title>

	<indexterm><primary>RAID</primary><secondary>software</secondary></indexterm>
	<indexterm><primary>RAID</primary><secondary>CCD</secondary></indexterm>

	<para>When choosing a mass storage solution, the most
	important factors to consider are speed, reliability, and
	cost. It is rare to have all three in balance. Normally a
	fast, reliable mass storage device is expensive, and to cut
	back on cost either speed or reliability must be
	sacrificed.</para>

	<para>In designing the system described below, cost was
	chosen as the most important factor, followed by speed,
	then reliability. Data transfer speed for this system is
	ultimately constrained by the network. While reliability is
	very important, the CCD drive described below serves online
	data that is already fully backed up and which can easily be
	replaced.</para>

	<para>Defining the requirements is the first step in choosing
	a mass storage solution. If the requirements prefer speed
	or reliability over cost, the solution will differ from the
	system described in this section.</para>

	<sect4 id="ccd-installhw">
	<title>Installing the Hardware</title>

	<para>In addition to the IDE system disk, three Western
	Digital 30GB, 5400 RPM IDE disks form the core of the CCD
	disk described below, providing approximately 90GB of
	online storage. Ideally, each IDE disk would have its own
	IDE controller and cable, but to minimize cost, additional
	IDE controllers were not used. Instead, the disks were
	configured with jumpers so that each IDE controller has
	one master, and one slave.</para>

	<para>Upon reboot, the system BIOS was configured to
	automatically detect the disks attached. More
	importantly, &os; detected them on reboot:</para>

	<programlisting>ad0: 19574MB <WDC WD205BA> [39770/16/63] at ata0-master UDMA33
	ad1: 29333MB <WDC WD307AA> [59598/16/63] at ata0-slave UDMA33
	ad2: 29333MB <WDC WD307AA> [59598/16/63] at ata1-master UDMA33
	ad3: 29333MB <WDC WD307AA> [59598/16/63] at ata1-slave UDMA33</programlisting>

	<note><para>If &os; does not detect all the disks, consult
	the drive documentation for proper setup and verify
	that the controller is supported by &os;.</para></note>
	</sect4>

	<sect4 id="ccd-setup">
	<title>Setting Up the CCD</title>

	<para>The &man.ccd.4; driver takes several identical disks
	and concatenates them into one logical file system. In
	order to use &man.ccd.4;, its kernel module must be
	loaded using &man.ccd.4;. When using a custom kernel,
	ensure that this line is compiled in:</para>

	<programlisting>device ccd</programlisting>

	<para>Before configuring &man.ccd.4;, use &man.bsdlabel.8;
	to label the disks:</para>

	<programlisting>bsdlabel -w ad1 auto
	bsdlabel -w ad2 auto
	bsdlabel -w ad3 auto</programlisting>

	<para>This example creates a bsdlabel for
	<devicename>ad1c</devicename>,
	<devicename>ad2c</devicename> and
	<devicename>ad3c</devicename> that spans the entire
	disk.</para>

	<para>The next step is to change the disk label type. Use
	&man.bsdlabel.8; to edit the disks:</para>

	<programlisting>bsdlabel -e ad1
	bsdlabel -e ad2
	bsdlabel -e ad3</programlisting>

	<para>This opens up the current disk label on each disk with
	the editor specified by the <envar>EDITOR</envar>
	environment variable, typically &man.vi.1;.</para>

	<para>An unmodified disk label will look something like
	this:</para>

	<programlisting>8 partitions:
	# size offset fstype [fsize bsize bps/cpg]
	c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597)</programlisting>

	<para>Add a new <literal>e</literal> partition for
	&man.ccd.4; to use. This can usually be copied from the
	<literal>c</literal> partition, but the
	<option>fstype</option> <emphasis>must</emphasis> be
	<userinput>4.2BSD</userinput>. The disk label should now
	look something like this:</para>

	<programlisting>8 partitions:
	# size offset fstype [fsize bsize bps/cpg]
	c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597)
	e: 60074784 0 4.2BSD 0 0 0 # (Cyl. 0 - 59597)</programlisting>
	</sect4>

	<sect4 id="ccd-buildingfs">
	<title>Building the File System</title>

	<para>Now that all the disks are labeled, build the
	&man.ccd.4; using &man.ccdconfig.8;, with options similar
	to the following:</para>

	<programlisting>ccdconfig ccd0<co id="co-ccd-dev"/> 32<co id="co-ccd-interleave"/> 0<co id="co-ccd-flags"/> /dev/ad1e<co id="co-ccd-devs"/> /dev/ad2e /dev/ad3e</programlisting>

	<para>The use and meaning of each option is described
	below:</para>

	<calloutlist>
	<callout arearefs="co-ccd-dev">
	<para>The first argument is the device to configure, in
	this case, <filename>/dev/ccd0c</filename>. The
	<literal>/dev/</literal> portion is optional.</para>
	</callout>

	<callout arearefs="co-ccd-interleave">
	<para>The interleave for the file system, which defines
	the size of a stripe in disk blocks, each normally 512
	bytes. So, an interleave of 32 would be 16,384
	bytes.</para>
	</callout>

	<callout arearefs="co-ccd-flags">
	<para>Flags for &man.ccdconfig.8;. For example, to
	enable drive mirroring, specify a flag. This
	configuration does not provide mirroring for
	&man.ccd.4;, so it is set at 0 (zero).</para>
	</callout>

	<callout arearefs="co-ccd-devs">
	<para>The final arguments to &man.ccdconfig.8; are the
	devices to place into the array. Use the complete
	path name for each device.</para>
	</callout>
	</calloutlist>

	<para>After running &man.ccdconfig.8; the &man.ccd.4; is
	configured and a file system can be installed. Refer to
	&man.newfs.8; for options, or run: </para>

	<programlisting>newfs /dev/ccd0c</programlisting>
	</sect4>

	<sect4 id="ccd-auto">
	<title>Making it All Automatic</title>

	<para>Generally, &man.ccd.4; should be configured to
	automount upon each reboot. To do this, write out the
	current configuration to
	<filename>/etc/ccd.conf</filename> using the following
	command:</para>

	<programlisting>ccdconfig -g > /etc/ccd.conf</programlisting>

	<para>During reboot, the script <command>/etc/rc</command>
	runs <command>ccdconfig -C</command> if
	<filename>/etc/ccd.conf</filename> exists. This
	automatically configures the &man.ccd.4; so it can be
	mounted.</para>

	<note>
	<para>When booting into single user mode, the following
	command must be issued to configure the array before
	the &man.ccd.4; can be mounted:</para>

	<programlisting>ccdconfig -C</programlisting>
	</note>

	<para>To automatically mount the &man.ccd.4;, place an entry
	for the &man.ccd.4; in <filename>/etc/fstab</filename> so
	it will be mounted at boot time:</para>

	<programlisting>/dev/ccd0c /media ufs rw 2 2</programlisting>
	</sect4>
	</sect3>

	<sect3 id="vinum">
	<title>The Vinum Volume Manager</title>

	<indexterm>
	<primary>RAID</primary>
	<secondary>software</secondary>
	</indexterm>
	<indexterm>
	<primary>RAID</primary>
	<secondary>Vinum</secondary>
	</indexterm>

	<para>The Vinum Volume Manager is a block device driver which
	implements virtual disk drives. It isolates disk hardware
	from the block device interface and maps data in ways which
	result in an increase in flexibility, performance and
	reliability compared to the traditional slice view of disk
	storage. &man.vinum.4; implements the RAID-0, RAID-1 and
	RAID-5 models, both individually and in combination.</para>

	<para>Refer to <link linkend="vinum-vinum"></link> for more
	information about &man.vinum.4;.</para>
	</sect3>
	</sect2>

	<sect2 id="raid-hard">
	<title>Hardware RAID</title>

	<indexterm>
	<primary>RAID</primary>
	<secondary>hardware</secondary>
	</indexterm>

	<para>&os; also supports a variety of hardware
	<acronym>RAID</acronym> controllers. These devices control a
	<acronym>RAID</acronym> subsystem without the need for &os;
	specific software to manage the array.</para>

	<para>Using an on-card <acronym>BIOS</acronym>, the card
	controls most of the disk operations. The following is a
	brief setup description using a Promise
	<acronym>IDE</acronym> <acronym>RAID</acronym> controller.
	When this card is installed and the system is started up, it
	displays a prompt requesting information. Follow the
	instructions to enter the card's setup screen and to combine
	all the attached drives. After doing so, the disks will
	look like a single drive to &os;. Other
	<acronym>RAID</acronym> levels can be set up
	accordingly.</para>
	</sect2>

	<sect2>
	<title>Rebuilding ATA RAID1 Arrays</title>

	<para>&os; supports the ability to hot-replace a failed disk in
	an array.</para>

	<para>An error indicating a failed disk will appear in
	<filename>/var/log/messages</filename> or in the &man.dmesg.8;
	output:</para>

	<programlisting>ad6 on monster1 suffered a hard error.
	ad6: READ command timeout tag=0 serv=0 - resetting
	ad6: trying fallback to PIO mode
	ata3: resetting devices .. done
	ad6: hard error reading fsbn 1116119 of 0-7 (ad6 bn 1116119; cn 1107 tn 4 sn 11)\\
	status=59 error=40
	ar0: WARNING - mirror lost</programlisting>

	<para>Use &man.atacontrol.8; to check for further
	information:</para>

	<screen>&prompt.root; <userinput>atacontrol list</userinput>
	ATA channel 0:
	Master: no device present
	Slave: acd0 <HL-DT-ST CD-ROM GCR-8520B/1.00> ATA/ATAPI rev 0

	ATA channel 1:
	Master: no device present
	Slave: no device present

	ATA channel 2:
	Master: ad4 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5
	Slave: no device present

	ATA channel 3:
	Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5
	Slave: no device present

	&prompt.root; <userinput>atacontrol status ar0</userinput>
	ar0: ATA RAID1 subdisks: ad4 ad6 status: DEGRADED</screen>

	<procedure>
	<step>
	<para>First, detach the ata channel with the failed disk
	so that it can be safely removed:</para>

	<screen>&prompt.root; <userinput>atacontrol detach ata3</userinput></screen>
	</step>

	<step>
	<para>Replace the disk.</para>
	</step>

	<step>
	<para>Reattach the ata channel:</para>

	<screen>&prompt.root; <userinput>atacontrol attach ata3</userinput>
	Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5
	Slave: no device present</screen>
	</step>

	<step>
	<para>Add the new disk to the array as a spare:</para>

	<screen>&prompt.root; <userinput>atacontrol addspare ar0 ad6</userinput></screen>
	</step>

	<step>
	<para>Rebuild the array:</para>

	<screen>&prompt.root; <userinput>atacontrol rebuild ar0</userinput></screen>
	</step>

	<step>
	<para>It is possible to check on the progress by issuing the
	following command:</para>

	<screen>&prompt.root; <userinput>dmesg \| tail -10</userinput>
	[output removed]
	ad6: removed from configuration
	ad6: deleted from ar0 disk1
	ad6: inserted into ar0 disk1 as spare

	&prompt.root; <userinput>atacontrol status ar0</userinput>
	ar0: ATA RAID1 subdisks: ad4 ad6 status: REBUILDING 0% completed</screen>
	</step>

	<step>
	<para>Wait until this operation completes.</para>
	</step>
	</procedure>
	</sect2>
	</sect1>

	<sect1 id="usb-disks">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Marc</firstname>
	<surname>Fonvieille</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<!-- Jul 2004 -->
	</sect1info>

	<title>USB Storage Devices</title>

	<indexterm>
	<primary>USB</primary>
	<secondary>disks</secondary>
	</indexterm>

	<para>Many external storage solutions, such as hard drives, USB
	thumbdrives, and CD/DVD burners, use the Universal Serial Bus
	(USB). &os; provides support for these devices.</para>

	<sect2>
	<title>Configuration</title>

	<para>The USB mass storage devices driver, &man.umass.4;,
	is built into the <filename>GENERIC</filename> kernel
	and provides support for USB storage devices. For a custom
	kernel, be sure that the following lines are present in the
	kernel configuration file:</para>

	<programlisting>device scbus
	device da
	device pass
	device uhci
	device ohci
	device ehci
	device usb
	device umass</programlisting>

	<para>Since the &man.umass.4; driver uses the SCSI subsystem to
	access the USB storage devices, any USB device will be seen as
	a SCSI device by the system. Depending on the USB chipset on
	the motherboard, <literal>device uhci</literal> or
	<literal>device ohci</literal> is used to provide USB 1.X
	support. Support for USB 2.0 controllers is provided by
	<literal>device ehci</literal>.</para>

	<note>
	<para>If the USB device is a CD or DVD burner, &man.cd.4;,
	must be added to the kernel via the line:</para>

	<programlisting>device cd</programlisting>

	<para>Since the burner is seen as a SCSI drive, the driver
	&man.atapicam.4; should not be used in the kernel
	configuration.</para>
	</note>
	</sect2>

	<sect2>
	<title>Testing the Configuration</title>

	<para>To test the USB configuration, plug in the USB device. In
	the system message buffer, &man.dmesg.8;, the drive should
	appear as something like:</para>

	<screen>umass0: USB Solid state disk, rev 1.10/1.00, addr 2
	GEOM: create disk da0 dp=0xc2d74850
	da0 at umass-sim0 bus 0 target 0 lun 0
	da0: <Generic Traveling Disk 1.11> Removable Direct Access SCSI-2 device
	da0: 1.000MB/s transfers
	da0: 126MB (258048 512 byte sectors: 64H 32S/T 126C)</screen>

	<para>The brand, device node (<devicename>da0</devicename>), and
	other details will differ according to the device.</para>

	<para>Since the USB device is seen as a SCSI one,
	<command>camcontrol</command> can be used to list the USB
	storage devices attached to the system:</para>

	<screen>&prompt.root; <userinput>camcontrol devlist</userinput>
	<Generic Traveling Disk 1.11> at scbus0 target 0 lun 0 (da0,pass0)</screen>

	<para>If the drive comes with a file system, it can be mounted.
	Refer to <link linkend="disks-adding"></link> for
	instructions on how to format and create partitions on the USB
	drive.</para>

	<warning>
	<para>Allowing untrusted users to mount arbitrary media, by
	enabling <varname>vfs.usermount</varname> as
	described below, should not be considered safe from a
	security point of view. Most file systems in &os; were not
	built to safeguard against malicious devices.</para>
	</warning>

	<para>To make the device mountable as a normal user, one
	solution is to make all users of the device a member of the
	<groupname>operator</groupname> group using &man.pw.8;.
	Next, ensure that the <groupname>operator</groupname> group is
	able to read and write the device by adding these lines to
	<filename>/etc/devfs.rules</filename>:</para>

	<programlisting>[localrules=5]
	add path 'da*' mode 0660 group operator</programlisting>

	<note>
	<para>If SCSI disks are installed in the system, change
	the second line as follows:</para>

	<programlisting>add path 'da[3-9]*' mode 0660 group operator</programlisting>

	<para>This will exclude the first three SCSI disks
	(<devicename>da0</devicename> to
	<devicename>da2</devicename>)from belonging to the
	<groupname>operator</groupname> group.</para>
	</note>

	<para>Next, enable the &man.devfs.rules.5; ruleset in
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>devfs_system_ruleset="localrules"</programlisting>

	<para>Next, instruct the running kernel to allow regular users
	to mount file systems. The easiest way is to add the
	following line to
	<filename>/etc/sysctl.conf</filename>:</para>

	<programlisting>vfs.usermount=1</programlisting>

	<para>Since this only takes effect after the next reboot use
	&man.sysctl.8; to set this variable now.</para>

	<para>The final step is to create a directory where the file
	system is to be mounted. This directory needs to be owned by
	the user that is to mount the file system. One way to do that
	is for <username>root</username> to create a subdirectory
	owned by that user as <filename
	class="directory">/mnt/<replaceable>username</replaceable></filename>.
	In the following example, replace
	<replaceable>username</replaceable> with the login name of the
	user and <replaceable>usergroup</replaceable> with the user's
	primary group:</para>

	<screen>&prompt.root; <userinput>mkdir /mnt/<replaceable>username</replaceable></userinput>
	&prompt.root; <userinput>chown <replaceable>username</replaceable>:<replaceable>usergroup</replaceable> /mnt/<replaceable>username</replaceable></userinput></screen>

	<para>Suppose a USB thumbdrive is plugged in, and a device
	<filename>/dev/da0s1</filename> appears. If the device is
	preformatted with a FAT file system, it can be mounted
	using:</para>

	<screen>&prompt.user; <userinput>mount -t msdosfs -o -m=644,-M=755 /dev/da0s1 /mnt/<replaceable>username</replaceable></userinput></screen>

	<para>Before the device can be unplugged, it
	<emphasis>must</emphasis> be unmounted first. After device
	removal, the system message buffer will show messages similar
	to the following:</para>

	<screen>umass0: at uhub0 port 1 (addr 2) disconnected
	(da0:umass-sim0:0:0:0): lost device
	(da0:umass-sim0:0:0:0): removing device entry
	GEOM: destroy disk da0 dp=0xc2d74850
	umass0: detached</screen>
	</sect2>

	<sect2>
	<title>Further Reading</title>

	<para>Beside the <link linkend="disks-adding">Adding
	Disks</link> and <link linkend="mount-unmount">Mounting and
	Unmounting File Systems</link> sections, reading various
	manual pages may be also useful: &man.umass.4;,
	&man.camcontrol.8;, and &man.usbconfig.8; under &os;  8.X
	or &man.usbdevs.8; under earlier versions of &os;.</para>
	</sect2>
	</sect1>

	<sect1 id="creating-cds">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Mike</firstname>
	<surname>Meyer</surname>
	<contrib>Contributed by </contrib>
	<!-- mwm@mired.org -->
	</author>
	</authorgroup>
	<!-- Apr 2001 -->
	</sect1info>

	<title>Creating and Using CD Media</title>

	<indexterm>
	<primary>CDROMs</primary>
	<secondary>creating</secondary>
	</indexterm>

	<sect2>
	<title>Introduction</title>

	<para>CD media provide a number of features that differentiate
	them from conventional disks. Initially, they were not
	writable by the user. They are designed so that they can be
	read continuously without delays to move the head between
	tracks. They are also much easier to transport between
	systems.</para>

	<para>CD media do have tracks, but this refers to a section of
	data to be read continuously and not a physical property of
	the disk. For example, to produce a CD on &os;, prepare the
	data files that are going to make up the tracks on the CD,
	then write the tracks to the CD.</para>

	<indexterm><primary>ISO 9660</primary></indexterm>
	<indexterm>
	<primary>file systems</primary>
	<secondary>ISO 9660</secondary>
	</indexterm>

	<para>The ISO 9660 file system was designed to deal with these
	differences. To overcome the original file system limits, it
	provides an extension mechanism that allows properly written
	CDs to exceed those limits while still working with systems
	that do not support those extensions.</para>

	<indexterm>
	<primary><filename
	role="package">sysutils/cdrtools</filename></primary>
	</indexterm>

	<para>The <filename role="package">sysutils/cdrtools</filename>
	port includes &man.mkisofs.8;, a program that can be used to
	produce a data file containing an ISO 9660 file system. It
	has options that support various extensions, and is described
	below.</para>

	<indexterm>
	<primary>CD burner</primary>
	<secondary>ATAPI</secondary>
	</indexterm>

	<para>Which tool to use to burn the CD depends on whether the
	CD burner is ATAPI or something else. ATAPI CD burners use
	<command><link linkend="burncd">burncd</link></command>
	which is part of the base system. SCSI and USB CD burners
	should use <command><link
	linkend="cdrecord">cdrecord</link></command> from the
	<filename role="package">sysutils/cdrtools</filename> port.
	It is also possible to use <command><link
	linkend="cdrecord">cdrecord</link></command> and other tools
	for SCSI drives on ATAPI hardware with the <link
	linkend="atapicam">ATAPI/CAM module</link>.</para>

	<para>For CD burning software with a graphical user
	interface, consider <application>X-CD-Roast</application> or
	<application>K3b</application>. These tools are available as
	packages or from the
	<filename role="package">sysutils/xcdroast</filename> and
	<filename role="package">sysutils/k3b</filename> ports.
	<application>X-CD-Roast</application> and
	<application>K3b</application> require the
	<link linkend="atapicam">ATAPI/CAM module</link> with ATAPI
	hardware.</para>
	</sect2>

	<sect2 id="mkisofs">
	<title><application>mkisofs</application></title>

	<para>The <filename role="package">sysutils/cdrtools</filename>
	port also installs &man.mkisofs.8;, which produces an ISO 9660
	file system that is an image of a directory tree in the &unix;
	file system name space. The simplest usage is:</para>

	<screen>&prompt.root; <userinput>mkisofs -o <replaceable>imagefile.iso</replaceable> <replaceable>/path/to/tree</replaceable></userinput></screen>

	<indexterm>
	<primary>file systems</primary>
	<secondary>ISO 9660</secondary>
	</indexterm>

	<para>This command creates an
	<replaceable>imagefile.iso</replaceable> containing an ISO
	9660 file system that is a copy of the tree at
	<replaceable>/path/to/tree</replaceable>. In the process, it
	maps the file names to names that fit the limitations of
	the standard ISO 9660 file system, and will exclude files that
	have names uncharacteristic of ISO file systems.</para>

	<indexterm>
	<primary>file systems</primary>
	<secondary>HFS</secondary>
	</indexterm>
	<indexterm>
	<primary>file systems</primary>
	<secondary>Joliet</secondary>
	</indexterm>
	<para>A number of options are available to overcome these
	restrictions. In particular, <option>-R</option> enables the
	Rock Ridge extensions common to &unix; systems,
	<option>-J</option> enables Joliet extensions used by
	Microsoft systems, and <option>-hfs</option> can be used to
	create HFS file systems used by &macos;.</para>

	<para>For CDs that are going to be used only on &os; systems,
	<option>-U</option> can be used to disable all filename
	restrictions. When used with <option>-R</option>, it produces
	a file system image that is identical to the specified &os;
	tree, though it may violate the ISO 9660 standard in a number
	of ways.</para>

	<indexterm>
	<primary>CDROMs</primary>
	<secondary>creating bootable</secondary>
	</indexterm>
	<para>The last option of general use is <option>-b</option>.
	This is used to specify the location of the boot image for use
	in producing an <quote>El Torito</quote> bootable CD. This
	option takes an argument which is the path to a boot image
	from the top of the tree being written to the CD. By default,
	&man.mkisofs.8; creates an ISO image in <quote>floppy disk
	emulation</quote> mode, and thus expects the boot image to
	be exactly 1200, 1440 or 2880 KB in size. Some boot
	loaders, like the one used by the &os; distribution disks, do
	not use emulation mode. In this case,
	<option>-no-emul-boot</option> should be used. So, if
	<filename class="directory">/tmp/myboot</filename> holds a
	bootable &os; system with the boot image in <filename
	class="directory">/tmp/myboot/boot/cdboot</filename>, this
	command would produce the image of an ISO 9660 file system as
	<filename>/tmp/bootable.iso</filename>:</para>

	<screen>&prompt.root; <userinput>mkisofs -R -no-emul-boot -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot</userinput></screen>

	<para>If <devicename>md</devicename> is configured in the
	kernel, the file system can be mounted as a memory disk
	with:</para>

	<screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /tmp/bootable.iso -u 0</userinput>
	&prompt.root; <userinput>mount -t cd9660 /dev/md0 /mnt</userinput></screen>

	<para>One can then verify that <filename
	class="directory">/mnt</filename> and <filename
	class="directory">/tmp/myboot</filename> are
	identical.</para>

	<para>There are many other options available for
	&man.mkisofs.8; to fine-tune its behavior. Refer to
	&man.mkisofs.8; for details.</para>
	</sect2>

	<sect2 id="burncd">
	<title><application>burncd</application></title>

	<indexterm>
	<primary>CDROMs</primary>
	<secondary>burning</secondary>
	</indexterm>
	<para>For an ATAPI CD burner, <command>burncd</command> can be
	used to burn an ISO image onto a CD.
	<command>burncd</command> is part of the base system,
	installed as <filename>/usr/sbin/burncd</filename>. Usage is
	very simple, as it has few options:</para>

	<screen>&prompt.root; <userinput>burncd -f <replaceable>cddevice</replaceable> data <replaceable>imagefile.iso</replaceable> fixate</userinput></screen>

	<para>This command will burn a copy of
	<replaceable>imagefile.iso</replaceable> on
	<replaceable>cddevice</replaceable>. The default device is
	<filename>/dev/acd0</filename>. See &man.burncd.8; for
	options to set the write speed, eject the CD after burning,
	and write audio data.</para>
	</sect2>

	<sect2 id="cdrecord">
	<title><application>cdrecord</application></title>

	<para>For systems without an ATAPI CD burner,
	<command>cdrecord</command> can be used to burn CDs.
	<command>cdrecord</command> is not part of the base system and
	must be installed from either the <filename
	role="package">sysutils/cdrtools</filename> package or port.
	Changes to the base system can cause binary versions of this
	program to fail, possibly resulting in a
	<quote>coaster</quote>. It is recommended to either upgrade
	the port when the system is upgraded, or for users
	<link linkend="stable">tracking -STABLE</link>, to upgrade the
	port when a new version becomes available.</para>

	<para>While <command>cdrecord</command> has many options, basic
	usage is simple. Burning an ISO 9660 image is done
	with:</para>

	<screen>&prompt.root; <userinput>cdrecord dev=<replaceable>device</replaceable> <replaceable>imagefile.iso</replaceable></userinput></screen>

	<para>The tricky part of using <command>cdrecord</command> is
	finding the <option>dev</option> to use. To find the proper
	setting, use <option>-scanbus</option> which might produce
	results like this:</para>

	<indexterm>
	<primary>CDROMs</primary>
	<secondary>burning</secondary>
	</indexterm>
	<screen>&prompt.root; <userinput>cdrecord -scanbus</userinput>
	Cdrecord-Clone 2.01 (i386-unknown-freebsd7.0) Copyright (C) 1995-2004 Jörg Schilling
	Using libscg version 'schily-0.1'
	scsibus0:
	0,0,0 0) 'SEAGATE ' 'ST39236LW ' '0004' Disk
	0,1,0 1) 'SEAGATE ' 'ST39173W ' '5958' Disk
	0,2,0 2) *
	0,3,0 3) 'iomega ' 'jaz 1GB ' 'J.86' Removable Disk
	0,4,0 4) 'NEC ' 'CD-ROM DRIVE:466' '1.26' Removable CD-ROM
	0,5,0 5) *
	0,6,0 6) *
	0,7,0 7) *
	scsibus1:
	1,0,0 100) *
	1,1,0 101) *
	1,2,0 102) *
	1,3,0 103) *
	1,4,0 104) *
	1,5,0 105) 'YAMAHA ' 'CRW4260 ' '1.0q' Removable CD-ROM
	1,6,0 106) 'ARTEC ' 'AM12S ' '1.06' Scanner
	1,7,0 107) *</screen>

	<para>This lists the appropriate <option>dev</option> value for
	the devices on the list. Locate the CD burner, and use the
	three numbers separated by commas as the value for
	<option>dev</option>. In this case, the CRW device is 1,5,0,
	so the appropriate input is <option>dev=1,5,0</option>.
	Refer to &man.cdrecord.1; for easier ways to specify this
	value and for information on writing audio tracks and
	controlling the write speed.</para>
	</sect2>

	<sect2 id="duplicating-audiocds">
	<title>Duplicating Audio CDs</title>

	<para>To duplicate an audio CD, extract the audio data from the
	CD to a series of files, then write these files to a blank CD.
	The process is slightly different for ATAPI and SCSI
	drives.</para>

	<procedure>
	<title>SCSI Drives</title>

	<step>
	<para>Use <command>cdda2wav</command> to extract the
	audio:</para>

	<screen>&prompt.user; <userinput>cdda2wav -vall -D2,0 -B -Owav</userinput></screen>
	</step>

	<step>
	<para>Use <command>cdrecord</command> to write the
	<filename>.wav</filename> files:</para>

	<screen>&prompt.user; <userinput>cdrecord -v dev=<replaceable>2,0</replaceable> -dao -useinfo *.wav</userinput></screen>

	<para>Make sure that <replaceable>2,0</replaceable> is set
	appropriately, as described in <link
	linkend="cdrecord"></link>.</para>
	</step>
	</procedure>

	<procedure>
	<title>ATAPI Drives</title>

	<note>
	<para>With the help of the
	<link linkend="atapicam">ATAPI/CAM module</link>,
	<command>cdda2wav</command> can also be used on ATAPI
	drives. This tool is usually a better choice for most of
	users, as it supports jitter correction and endianness,
	than the method proposed below.</para>
	</note>

	<step>
	<para>The ATAPI CD driver makes each track available as
	<filename>/dev/acd<replaceable>d</replaceable>t<replaceable>nn</replaceable></filename>,
	where <replaceable>d</replaceable> is the drive number,
	and <replaceable>nn</replaceable> is the track number
	written with two decimal digits, prefixed with zero as
	needed. So the first track on the first disk is
	<filename>/dev/acd0t01</filename>, the second is
	<filename>/dev/acd0t02</filename>, the third is
	<filename>/dev/acd0t03</filename>, and so on.</para>

	<para>Make sure the appropriate files exist in
	<filename>/dev</filename>. If the entries are missing,
	force the system to retaste the media:</para>

	<screen>&prompt.root; <userinput>dd if=/dev/acd0 of=/dev/null count=1</userinput></screen>
	</step>

	<step>
	<para>Extract each track using &man.dd.1;, making sure to
	specify a block size when extracting the files:</para>

	<screen>&prompt.root; <userinput>dd if=/dev/acd0t01 of=track1.cdr bs=2352</userinput>
	&prompt.root; <userinput>dd if=/dev/acd0t02 of=track2.cdr bs=2352</userinput>
	...</screen>
	</step>

	<step>
	<para>Burn the extracted files to disk using
	<command>burncd</command>. Specify that these are audio
	files, and that <command>burncd</command> should fixate
	the disk when finished:</para>

	<screen>&prompt.root; <userinput>burncd -f <replaceable>/dev/acd0</replaceable> audio track1.cdr track2.cdr <replaceable>...</replaceable> fixate</userinput></screen>
	</step>
	</procedure>
	</sect2>

	<sect2 id="imaging-cd">
	<title>Duplicating Data CDs</title>

	<para>It is possible to copy a data CD to an image file that is
	functionally equivalent to the image file created with
	&man.mkisofs.8;, and then use it to duplicate any data CD.
	The example given here assumes that the CDROM device is
	<devicename>acd0</devicename>. Substitute the correct CDROM
	device.</para>

	<screen>&prompt.root; <userinput>dd if=/dev/acd0 of=file.iso bs=2048</userinput></screen>

	<para>Now that there is an image, it can be burned to CD as
	described above.</para>
	</sect2>

	<sect2 id="mounting-cd">
	<title>Using Data CDs</title>

	<para>It is possible to mount and read the data on a standard
	data CD. By default, &man.mount.8; assumes that a file system
	is of type <literal>ufs</literal>. Running this
	command:</para>

	<screen>&prompt.root; <userinput>mount /dev/cd0 /mnt</userinput></screen>

	<para>will generate an error about <errorname>Incorrect super
	block</errorname>, and will fail to mount the CD. The CD
	does not use the <literal>UFS</literal> file system, so
	attempts to mount it as such will fail. Instead, tell
	&man.mount.8; that the file system is of type
	<literal>ISO9660</literal> by specifying
	<option>-t cd9660</option> to &man.mount.8;. For example,
	to mount the CDROM device, <filename>/dev/cd0</filename>,
	under <filename class="directory">/mnt</filename>,
	use:</para>

	<screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0 /mnt</userinput></screen>

	<para>Replace <filename>/dev/cd0</filename> with the device
	name for the CD device. Also, <option>-t cd9660</option>
	executes &man.mount.cd9660.8;, meaning the above command is
	equivalent to:</para>

	<screen>&prompt.root; <userinput>mount_cd9660 /dev/cd0 /mnt</userinput></screen>

	<para>While data CDROMs from any vendor can be mounted this way,
	disks with certain ISO 9660 extensions might behave oddly.
	For example, Joliet disks store all filenames in two-byte
	Unicode characters. The &os; kernel does not speak Unicode,
	but the &os; CD9660 driver is able to convert Unicode
	characters on the fly. If some non-English characters show up
	as question marks, specify the local charset with
	<option>-C</option>. For more information, refer to
	&man.mount.cd9660.8;.</para>

	<note>
	<para>In order to do this character conversion with the help
	of <option>-C</option>, the kernel requires the
	<filename>cd9660_iconv.ko</filename> module to be loaded.
	This can be done either by adding this line to
	<filename>loader.conf</filename>:</para>

	<programlisting>cd9660_iconv_load="YES"</programlisting>

	<para>and then rebooting the machine, or by directly loading
	the module with &man.kldload.8;.</para>
	</note>

	<para>Occasionally, <errorname>Device not configured</errorname>
	will be displayed when trying to mount a CDROM. This
	usually means that the CDROM drive thinks that there is no
	disk in the tray, or that the drive is not visible on the bus.
	It can take a couple of seconds for a CDROM drive to realize
	that a media is present, so be patient.</para>

	<para>Sometimes, a SCSI CDROM may be missed because it did not
	have enough time to answer the bus reset. To resolve this,add
	the following option to the kernel configuration and <link
	linkend="kernelconfig-building">rebuild the
	kernel</link>.</para>

	<programlisting>options SCSI_DELAY=15000</programlisting>

	<para>This tells the SCSI bus to pause 15 seconds during boot,
	to give the CDROM drive every possible chance to answer the
	bus reset.</para>
	</sect2>

	<sect2 id="rawdata-cd">
	<title>Burning Raw Data CDs</title>

	<para>It is possible to burn a file directly to CD, without
	creating an ISO 9660 file system. Some people do this for
	backup purposes. This command runs more quickly than burning
	a standard CD:</para>

	<screen>&prompt.root; <userinput>burncd -f /dev/acd1 -s 12 data archive.tar.gz fixate</userinput></screen>

	<para>In order to retrieve the data burned to such a CD, the
	data must be read from the raw device node:</para>

	<screen>&prompt.root; <userinput>tar xzvf /dev/acd1</userinput></screen>

	<para>This type of disk can not be mounted as a normal CDROM and
	the data cannot be read under any operating system except
	&os;. In order to mount the CD, or to share the data with
	another operating system, &man.mkisofs.8; must be used as
	described above.</para>
	</sect2>

	<sect2 id="atapicam">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Marc</firstname>
	<surname>Fonvieille</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>Using the ATAPI/CAM Driver</title>

	<indexterm>
	<primary>CD burner</primary>
	<secondary>ATAPI/CAM driver</secondary>
	</indexterm>

	<para>This driver allows ATAPI devices, such as CD/DVD drives,
	to be accessed through the SCSI subsystem, and so allows the
	use of applications like <filename
	role="package">sysutils/cdrdao</filename> or
	&man.cdrecord.1;.</para>

	<para>To use this driver, add the following line to
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>atapicam_load="YES"</programlisting>

	<para>then, reboot the system.</para>

	<note>
	<para>Users who prefer to statically compile &man.atapicam.4;
	support into the kernel, should add this line to the
	kernel configuration file:</para>

	<programlisting>device atapicam</programlisting>

	<para>Ensure the following lines are still in the kernel
	configuration file:</para>

	<programlisting>device ata
	device scbus
	device cd
	device pass</programlisting>

	<para>Then rebuild, install the new kernel, and reboot the
	machine.</para>
	</note>

	<para>During the boot process, the burner should show up, like
	so:</para>

	<screen>acd0: CD-RW <MATSHITA CD-RW/DVD-ROM UJDA740> at ata1-master PIO4
	cd0 at ata1 bus 0 target 0 lun 0
	cd0: <MATSHITA CDRW/DVD UJDA740 1.00> Removable CD-ROM SCSI-0 device
	cd0: 16.000MB/s transfers
	cd0: Attempt to query device size failed: NOT READY, Medium not present - tray closed</screen>

	<para>The drive can now be accessed via the
	<filename>/dev/cd0</filename> device name. For example, to
	mount a CD-ROM on <filename class="directory">/mnt</filename>,
	type the following:</para>

	<screen>&prompt.root; <userinput>mount -t cd9660 <replaceable>/dev/cd0</replaceable> /mnt</userinput></screen>

	<para>As <username>root</username>, run the following command
	to get the SCSI address of the burner:</para>

	<screen>&prompt.root; <userinput>camcontrol devlist</userinput>
	<MATSHITA CDRW/DVD UJDA740 1.00> at scbus1 target 0 lun 0 (pass0,cd0)</screen>

	<para>In this example, <literal>1,0,0</literal> is the SCSI
	address to use with &man.cdrecord.1; and other SCSI
	applications.</para>

	<para>For more information about ATAPI/CAM and SCSI system,
	refer to &man.atapicam.4; and &man.cam.4;.</para>
	</sect2>
	</sect1>

	<sect1 id="creating-dvds">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Marc</firstname>
	<surname>Fonvieille</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Andy</firstname>
	<surname>Polyakov</surname>
	<contrib>With inputs from </contrib>
	</author>
	</authorgroup>
	<!-- Feb 2004 -->
	</sect1info>

	<title>Creating and Using DVD Media</title>

	<indexterm>
	<primary>DVD</primary>
	<secondary>burning</secondary>
	</indexterm>

	<sect2>
	<title>Introduction</title>

	<para>Compared to the CD, the DVD is the next generation of
	optical media storage technology. The DVD can hold more data
	than any CD and is the standard for video publishing.</para>

	<para>Five physical recordable formats can be defined for a
	recordable DVD:</para>

	<itemizedlist>
	<listitem>
	<para>DVD-R: This was the first DVD recordable format
	available. The DVD-R standard is defined by the
	<ulink url="http://www.dvdforum.com/forum.shtml">DVD
	Forum</ulink>. This format is write once.</para>
	</listitem>

	<listitem>
	<para>DVD-RW: This is the rewritable version of the
	DVD-R standard. A DVD-RW can be rewritten about 1000
	times.</para>
	</listitem>

	<listitem>
	<para>DVD-RAM: This is a rewritable format which can be seen
	as a removable hard drive. However, this media is not
	compatible with most DVD-ROM drives and DVD-Video players
	as only a few DVD writers support the DVD-RAM format.
	Refer to <link linkend="creating-dvd-ram"></link> for more
	information on DVD-RAM use.</para>
	</listitem>

	<listitem>
	<para>DVD+RW: This is a rewritable format defined by
	the <ulink url="http://www.dvdrw.com/">DVD+RW
	Alliance</ulink>. A DVD+RW can be rewritten about 1000
	times.</para>
	</listitem>

	<listitem>
	<para>DVD+R: This format is the write once variation
	of the DVD+RW format.</para>
	</listitem>
	</itemizedlist>

	<para>A single layer recordable DVD can hold up to
	4,700,000,000 bytes which is actually 4.38 GB or
	4485 MB as 1 kilobyte is 1024 bytes.</para>

	<note>
	<para>A distinction must be made between the physical media
	and the application. For example, a DVD-Video is a specific
	file layout that can be written on any recordable DVD
	physical media such as DVD-R, DVD+R, or DVD-RW. Before
	choosing the type of media, ensure that both the burner and
	the DVD-Video player are compatible with the media under
	consideration.</para>
	</note>
	</sect2>

	<sect2>
	<title>Configuration</title>

	<para>To perform DVD recording, use &man.growisofs.1;. This
	command is part of the <filename
	role="package">sysutils/dvd+rw-tools</filename> utilities
	which support all DVD media types.</para>

	<para>These tools use the SCSI subsystem to access the devices,
	therefore <link linkend="atapicam">ATAPI/CAM support</link>
	must be loaded or statically compiled into the kernel. This
	support is not needed if the burner uses the USB interface.
	Refer to <link linkend="usb-disks"></link> for more details
	on USB device configuration.</para>

	<para>DMA access must also be enabled for ATAPI devices, by
	adding the following line to
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>hw.ata.atapi_dma="1"</programlisting>

	<para>Before attempting to use
	<application>dvd+rw-tools</application>, consult the
	<ulink
	url="http://fy.chalmers.se/~appro/linux/DVD+RW/hcn.html">Hardware
	Compatibility Notes</ulink>.</para>

	<note>
	<para>For a graphical user interface, consider using <filename
	role="package">sysutils/k3b</filename> which provides a
	user friendly interface to &man.growisofs.1; and many other
	burning tools.</para>
	</note>
	</sect2>

	<sect2>
	<title>Burning Data DVDs</title>

	<para>Since &man.growisofs.1; is a front-end to <link
	linkend="mkisofs">mkisofs</link>, it will invoke
	&man.mkisofs.8; to create the file system layout and perform
	the write on the DVD. This means that an image of the data
	does not need to be created before the burning process.</para>

	<para>To burn to a DVD+R or a DVD-R the data in
	<filename class="directory">/path/to/data</filename>,
	use the following command:</para>

	<screen>&prompt.root; <userinput>growisofs -dvd-compat -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen>

	<para>In this example, <option>-J -R</option> is passed to
	&man.mkisofs.8; to create an ISO 9660 file system with Joliet
	and Rock Ridge extensions. Refer to &man.mkisofs.8; for more
	details.</para>

	<para>For the initial session recording, <option>-Z</option> is
	used for both single and multiple sessions. Replace
	<replaceable>/dev/cd0</replaceable>, with the name of the DVD
	device. Using <option>-dvd-compat</option> indicates that the
	disk will be closed and that the recording will be
	unappendable. This should also provide better media
	compatibility with DVD-ROM drives.</para>

	<para>To burn a pre-mastered image, such as
	<replaceable>imagefile.iso</replaceable>, use:</para>

	<screen>&prompt.root; <userinput>growisofs -dvd-compat -Z <replaceable>/dev/cd0</replaceable>=<replaceable>imagefile.iso</replaceable></userinput></screen>

	<para>The write speed should be detected and automatically set
	according to the media and the drive being used. To force the
	write speed, use <option>-speed=</option>. Refer to
	&man.growisofs.1; for example usage.</para>

	<note>
	<para>In order to support working files larger than 4.38GB, an
	UDF/ISO-9660 hybrid filesystem must be created by passing
	<option>-udf -iso-level 3</option> to &man.mkisofs.8; and
	all related programs, such as &man.growisofs.1;. This is
	required only when creating an ISO image file or when
	writing files directly to a disk. Since a disk created this
	way must be mounted as an UDF filesystem with
	&man.mount.udf.8;, it will be usable only on an UDF aware
	operating system. Otherwise it will look as if it contains
	corrupted files.</para>

	<para>To create this type of ISO file:</para>

	<screen>&prompt.user; <userinput>mkisofs -R -J -udf -iso-level 3 -o <replaceable>imagefile.iso</replaceable> <replaceable>/path/to/data</replaceable></userinput></screen>

	<para>To burn files directly to a disk:</para>

	<screen>&prompt.root; <userinput>growisofs -dvd-compat -udf -iso-level 3 -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen>

	<para>When an ISO image already contains large files, no
	additional options are required for &man.growisofs.1; to
	burn that image on a disk.</para>

	<para>Be sure to use an up-to-date version of <filename
	role="package">sysutils/cdrtools</filename>, which
	contains &man.mkisofs.8;, as an older version may not
	contain large files support. If the latest version does
	not work, install <filename
	role="package">sysutils/cdrtools-devel</filename> and read
	its &man.mkisofs.8;.</para>
	</note>
	</sect2>

	<sect2>
	<title>Burning a DVD-Video</title>

	<indexterm>
	<primary>DVD</primary>
	<secondary>DVD-Video</secondary>
	</indexterm>

	<para>A DVD-Video is a specific file layout based on the ISO
	9660 and micro-UDF (M-UDF) specifications. Since DVD-Video
	presents a specific data structure hierarchy, a particular
	program such as <filename
	role="package">multimedia/dvdauthor</filename> is needed to
	author the DVD.</para>

	<para>If an image of the DVD-Video file system already exists,
	it can be burned in the same way as any other image. If
	<command>dvdauthor</command> was used to make the DVD and the
	result is in <filename
	class="directory">/path/to/video</filename>, the following
	command should be used to burn the DVD-Video:</para>

	<screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -dvd-video <replaceable>/path/to/video</replaceable></userinput></screen>

	<para><option>-dvd-video</option> is passed to &man.mkisofs.8;
	to instruct it to create a DVD-Video file system layout.
	This option implies the <option>-dvd-compat</option>
	&man.growisofs.1; option.</para>
	</sect2>

	<sect2>
	<title>Using a DVD+RW</title>

	<indexterm>
	<primary>DVD</primary>
	<secondary>DVD+RW</secondary>
	</indexterm>

	<para>Unlike CD-RW, a virgin DVD+RW needs to be formatted before
	first use. It is <emphasis>recommended</emphasis> to let
	&man.growisofs.1; take care of this automatically whenever
	appropriate. However, it is possible to use
	<command>dvd+rw-format</command> to format the DVD+RW:</para>

	<screen>&prompt.root; <userinput>dvd+rw-format <replaceable>/dev/cd0</replaceable></userinput></screen>

	<para>Only perform this operation once and keep in mind that
	only virgin DVD+RW medias need to be formatted. Once
	formatted, the DVD+RW can be burned as usual.</para>

	<para>To burn a totally new file system and not just append some
	data onto a DVD+RW, the media does not need to be blanked
	first. Instead, write over the previous recording like
	this:</para>

	<screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/newdata</replaceable></userinput></screen>

	<para>The DVD+RW format supports appending data to a previous
	recording. This operation consists of merging a new session
	to the existing one as it is not considered to be
	multi-session writing. &man.growisofs.1; will
	<emphasis>grow</emphasis> the ISO 9660 file system present on
	the media.</para>

	<para>For example, to append data to a DVD+RW, use the
	following:</para>

	<screen>&prompt.root; <userinput>growisofs -M <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/nextdata</replaceable></userinput></screen>

	<para>The same &man.mkisofs.8; options used to burn the
	initial session should be used during next writes.</para>

	<note>
	<para>Use <option>-dvd-compat</option> for better media
	compatibility with DVD-ROM drives. When using DVD+RW, this
	option will not prevent the addition of data.</para>
	</note>

	<para>To blank the media, use:</para>

	<screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable>=<replaceable>/dev/zero</replaceable></userinput></screen>
	</sect2>

	<sect2>
	<title>Using a DVD-RW</title>

	<indexterm>
	<primary>DVD</primary>
	<secondary>DVD-RW</secondary>
	</indexterm>

	<para>A DVD-RW accepts two disc formats: incremental sequential
	and restricted overwrite. By default, DVD-RW discs are in
	sequential format.</para>

	<para>A virgin DVD-RW can be directly written without being
	formatted. However, a non-virgin DVD-RW in sequential format
	needs to be blanked before writing a new initial
	session.</para>

	<para>To blank a DVD-RW in sequential mode:</para>

	<screen>&prompt.root; <userinput>dvd+rw-format -blank=full <replaceable>/dev/cd0</replaceable></userinput></screen>

	<note>
	<para>A full blanking using <option>-blank=full</option> will
	take about one hour on a 1x media. A fast blanking can be
	performed using <option>-blank</option>, if the DVD-RW will
	be recorded in Disk-At-Once (DAO) mode. To burn the DVD-RW
	in DAO mode, use the command:</para>

	<screen>&prompt.root; <userinput>growisofs -use-the-force-luke=dao -Z <replaceable>/dev/cd0</replaceable>=<replaceable>imagefile.iso</replaceable></userinput></screen>

	<para>Since &man.growisofs.1; automatically attempts to detect
	fast blanked media and engage DAO write,
	<option>-use-the-force-luke=dao</option> should not be
	required.</para>

	<para>One should instead use restricted overwrite mode with
	any DVD-RW as this format is more flexible than the default
	of incremental sequential.</para>
	</note>

	<para>To write data on a sequential DVD-RW, use the same
	instructions as for the other DVD formats:</para>

	<screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen>

	<para>To append some data to a previous recording, use
	<option>-M</option> with &man.growisofs.1;. However, if data
	is appended on a DVD-RW in incremental sequential mode, a new
	session will be created on the disc and the result will be a
	multi-session disc.</para>

	<para>A DVD-RW in restricted overwrite format does not need to
	be blanked before a new initial session. Instead, overwrite
	the disc with <option>-Z</option>. It is also possible to
	grow an existing ISO 9660 file system written on the disc with
	<option>-M</option>. The result will be a one-session
	DVD.</para>

	<para>To put a DVD-RW in restricted overwrite format, the
	following command must be used:</para>

	<screen>&prompt.root; <userinput>dvd+rw-format <replaceable>/dev/cd0</replaceable></userinput></screen>

	<para>To change back to sequential format, use:</para>

	<screen>&prompt.root; <userinput>dvd+rw-format -blank=full <replaceable>/dev/cd0</replaceable></userinput></screen>
	</sect2>

	<sect2>
	<title>Multi-Session</title>

	<para>Few DVD-ROM drives support multi-session DVDs and most of
	the time only read the first session. DVD+R, DVD-R and DVD-RW
	in sequential format can accept multiple sessions. The notion
	of multiple sessions does not exist for the DVD+RW and the
	DVD-RW restricted overwrite formats.</para>

	<para>Using the following command after an initial non-closed
	session on a DVD+R, DVD-R, or DVD-RW in sequential format,
	will add a new session to the disc:</para>

	<screen>&prompt.root; <userinput>growisofs -M <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/nextdata</replaceable></userinput></screen>

	<para>Using this command with a DVD+RW or a DVD-RW in restricted
	overwrite mode will append data while merging the new session
	to the existing one. The result will be a single-session
	disc. Use this method to add data after an initial write on
	these types of media.</para>

	<note>
	<para>Since some space on the media is used between each
	session to mark the end and start of sessions, one should
	add sessions with a large amount of data to optimize media
	space. The number of sessions is limited to 154 for a
	DVD+R, about 2000 for a DVD-R, and 127 for a DVD+R Double
	Layer.</para>
	</note>
	</sect2>

	<sect2>
	<title>For More Information</title>

	<para>To obtain more information about a DVD, use
	<command>dvd+rw-mediainfo
	<replaceable>/dev/cd0</replaceable></command> while the disc
	in the specified drive.</para>

	<para>More information about
	<application>dvd+rw-tools</application> can be found in
	&man.growisofs.1;, on the <ulink
	url="http://fy.chalmers.se/~appro/linux/DVD+RW/">dvd+rw-tools
	web site</ulink>, and in the <ulink
	url="http://lists.debian.org/cdwrite/">cdwrite mailing
	list</ulink> archives.</para>

	<note>
	<para>When creating a problem report related to the use of
	<application>dvd+rw-tools</application>, always include the
	output of <command>dvd+rw-mediainfo</command>.</para>
	</note>
	</sect2>

	<sect2 id="creating-dvd-ram">
	<title>Using a DVD-RAM</title>

	<indexterm>
	<primary>DVD</primary>
	<secondary>DVD-RAM</secondary>
	</indexterm>

	<sect3>
	<title>Configuration</title>

	<para>DVD-RAM writers can use either a SCSI or ATAPI
	interface. For ATAPI devices, DMA access has to be
	enabled by adding the following line to
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>hw.ata.atapi_dma="1"</programlisting>
	</sect3>

	<sect3>
	<title>Preparing the Media</title>

	<para>A DVD-RAM can be seen as a removable hard drive. Like
	any other hard drive, the DVD-RAM must be formatted before
	it can be used. In this example, the whole disk space will
	be formatted with a standard UFS2 file system:</para>

	<screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/dev/acd0</replaceable> bs=2k count=1</userinput>
	&prompt.root; <userinput>bsdlabel -Bw <replaceable>acd0</replaceable></userinput>
	&prompt.root; <userinput>newfs <replaceable>/dev/acd0</replaceable></userinput></screen>

	<para>The DVD device, <devicename>acd0</devicename>, must be
	changed according to the configuration.</para>
	</sect3>

	<sect3>
	<title>Using the Media</title>

	<para>Once the DVD-RAM has been formatted, it can be mounted
	as a normal hard drive:</para>

	<screen>&prompt.root; <userinput>mount <replaceable>/dev/acd0</replaceable> <replaceable>/mnt</replaceable></userinput></screen>

	<para>Once mounted, the DVD-RAM will be both readable and
	writeable.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="floppies">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Julio</firstname>
	<surname>Merino</surname>
	<contrib>Original work by </contrib>
	</author>
	</authorgroup>
	<!-- 24 Dec 2001 -->
	<authorgroup>
	<author>
	<firstname>Martin</firstname>
	<surname>Karlsson</surname>
	<contrib>Rewritten by </contrib>
	</author>
	</authorgroup>
	<!-- 27 Apr 2003 -->
	</sect1info>

	<title>Creating and Using Floppy Disks</title>

	<para>Storing data on floppy disks is sometimes useful, for
	example when one does not have any other removable storage media
	or when one needs to transfer small amounts of data to another
	computer.</para>

	<para>This section explains how to use floppy disks in &os;. It
	covers formatting and usage of 3.5inch DOS floppies, but the
	concepts are similar for other floppy disk formats.</para>

	<sect2>
	<title>Formatting Floppies</title>

	<sect3>
	<title>The Device</title>

	<para>Floppy disks are accessed through entries in
	<filename class="directory">/dev</filename>, just like other
	devices. To access the raw floppy disk, simply use
	<filename>/dev/fd<replaceable>N</replaceable></filename>.</para>
	</sect3>

	<sect3>
	<title>Formatting</title>

	<para>A floppy disk needs to be low-level formatted before it
	can be used. This is usually done by the vendor, but
	formatting is a good way to check media integrity. Although
	it is possible to force other disk sizes, 1440kB is what
	most floppy disks are designed for.</para>

	<para>To low-level format the floppy disk, use
	&man.fdformat.1;. This utility expects the device name as
	an argument.</para>

	<para>Make note of any error messages, as these can help
	determine if the disk is good or bad.</para>

	<sect4>
	<title>Formatting Floppy Disks</title>

	<para>To format the floppy, insert a new 3.5inch floppy
	disk into the first floppy drive and issue:</para>

	<screen>&prompt.root; <userinput>/usr/sbin/fdformat -f 1440 /dev/fd0</userinput></screen>
	</sect4>
	</sect3>
	</sect2>

	<sect2>
	<title>The Disk Label</title>

	<para>After low-level formatting the disk, a disk label needs to
	placed on it. This disk label will be destroyed later, but
	it is needed by the system to determine the size of the disk
	and its geometry.</para>

	<para>The new disk label will take over the whole disk and will
	contain all the proper information about the geometry of the
	floppy. The geometry values for the disk label are listed in
	<filename>/etc/disktab</filename>.</para>

	<para>To write the disk label, use &man.bsdlabel.8;:</para>

	<screen>&prompt.root; <userinput>/sbin/bsdlabel -B -w /dev/fd0 fd1440</userinput></screen>
	</sect2>

	<sect2>
	<title>The File System</title>

	<para>The floppy is now ready to be high-level formatted. This
	will place a new file system on it so that &os; can read and
	write to the disk. Since creating the new file system
	destroys the disk label, the disk label needs to be recreated
	whenever the disk is reformatted.</para>

	<para>The floppy's file system can be either UFS or FAT.
	FAT is generally a better choice for floppies.</para>

	<para>To put a new file system on the floppy, issue:</para>

	<screen>&prompt.root; <userinput>/sbin/newfs_msdos /dev/fd0</userinput></screen>

	<para>The disk is now ready for use.</para>
	</sect2>

	<sect2>
	<title>Using the Floppy</title>

	<para>To use the floppy, mount it with &man.mount.msdosfs.8;.
	One can also use
	<filename role="package">emulators/mtools</filename> from the
	Ports Collection.</para>
	</sect2>
	</sect1>

	<sect1 id="backups-tapebackups">
	<title>Creating and Using Data Tapes</title>

	<indexterm><primary>tape media</primary></indexterm>

	<para>Tape technology has continued to evolve but is less likely
	to be used in a modern system. Modern backup systems tend to
	use off site combined with local removable disk drive
	technologies. Still, &os; will support any tape drive that
	uses SCSI, such as LTO and older devices such as DAT. There is
	limited support for SATA and USB tape drives.</para>

	<sect2 id="tapes-sa0">
	<title>Serial Access with &man.sa.4;</title>

	<indexterm>
	<primary>tape drives</primary>
	</indexterm>

	<para>&os; uses the &man.sa.4; driver, providing
	<devicename>/dev/sa0</devicename>,
	<devicename>/dev/nsa0</devicename>, and
	<devicename>/dev/esa0</devicename>. In normal use, only
	<devicename>/dev/sa0</devicename> is needed.
	<devicename>/dev/nsa0</devicename> is the same physical drive
	as <devicename>/dev/sa0</devicename> but does not rewind the
	tape after writing a file. This allows writing more than one
	file to a tape. Using <devicename>/dev/esa0</devicename>
	ejects the tape after the device is closed, if
	applicable.</para>
	</sect2>

	<sect2>
	<title id="tapes-mt">Controlling the Tape Drive with
	&man.mt.1;</title>

	<indexterm>
	<primary>tape media</primary>
	<secondary>mt</secondary>
	</indexterm>

	<para>&man.mt.1; is the &os; utility for controlling other
	operations of the tape drive, such as seeking through files on
	a tape or writing tape control marks to the tape.</para>

	<para>For example, the first three files on a tape can be
	preserved by skipping past them before writing a new
	file:</para>

	<screen>&prompt.root; <userinput>mt -f /dev/nsa0 fsf 3</userinput></screen>
	</sect2>

	<sect2>
	<title id="tapes-tar">Using &man.tar.1; to Read and
	Write Tape Backups</title>

	<para>An example of writing a single file to tape using
	&man.tar.1;:</para>

	<screen>&prompt.root; <userinput>tar cvf /dev/sa0 <replaceable>file</replaceable></userinput></screen>

	<para>Recovering files from a &man.tar.1; archive on tape into
	the current directory:</para>

	<screen>&prompt.root; <userinput>tar xvf /dev/sa0</userinput></screen>
	</sect2>

	<sect2>
	<title id="tapes-dumprestore">Using &man.dump.8; and
	&man.restore.8; to Create and Restore Backups</title>

	<para>A simple backup of <filename
	class="directory">/usr</filename> with &man.dump.8;:</para>

	<screen>&prompt.root; <userinput>dump -0aL -b64 -f /dev/nsa0 /usr</userinput></screen>

	<para>Interactively restoring files from a &man.dump.8; file on
	tape into the current directory:</para>

	<screen>&prompt.root; <userinput>restore -i -f /dev/nsa0</userinput></screen>
	</sect2>

	<sect2>
	<title id="tapes-othersofware">Other Tape Software</title>

	<para>Higher-level programs are available to simplify tape
	backup. The most popular are
	<application>Amanda</application> and
	<application>Bacula</application>. These programs aim to make
	backups easier and more convenient, or to automate complex
	backups of multiple machines. The Ports Collection contains
	both these and other tape utility applications.</para>
	</sect2>
	</sect1>

	<sect1 id="backups-floppybackups">
	<title>Backups to Floppies</title>

	<sect2 id="floppies-using">
	<title>Can I Use Floppies for Backing Up My Data?</title>

	<indexterm><primary>backup floppies</primary></indexterm>
	<indexterm><primary>floppy disks</primary></indexterm>

	<para>Floppy disks are not a suitable media for making backups
	as:</para>

	<itemizedlist>
	<listitem>
	<para>The media is unreliable, especially over long periods
	of time.</para>
	</listitem>

	<listitem>
	<para>Backing up and restoring is very slow.</para>
	</listitem>

	<listitem>
	<para>They have a very limited capacity.</para>
	</listitem>
	</itemizedlist>

	<para>However, if no other method of backing up data is
	available, floppy disks are better than no backup at
	all.</para>

	<para>When backing up to floppy disks, ensure the floppies are
	of good quality. Floppies that have been lying around the
	office for a couple of years are a bad choice. Ideally,
	use new ones from a reputable manufacturer.</para>
	</sect2>

	<sect2 id="floppies-creating">
	<title>So How Do I Backup My Data to Floppies?</title>

	<para>The best way to backup to floppy disk is to use
	&man.tar.1; with <option>-M</option> (multi-volume), which
	allows backups to span multiple floppies.</para>

	<para>To backup all the files in the current directory and
	sub-directory, use this as <username>root</username>:</para>

	<screen>&prompt.root; <userinput>tar Mcvf /dev/fd0 *</userinput></screen>

	<para>When the first floppy is full, &man.tar.1; will prompt
	to insert the next volume, which in this case is the next
	floppy disk:</para>

	<screen>Prepare volume #2 for /dev/fd0 and hit return:</screen>

	<para>This is repeated, with the volume number incrementing,
	until all the specified files have been archived.</para>
	</sect2>

	<sect2 id="floppies-compress">
	<title>Can I Compress My Backups?</title>

	<indexterm>
	<primary><command>tar</command></primary>
	</indexterm>
	<indexterm>
	<primary><command>gzip</command></primary>
	</indexterm>
	<indexterm><primary>compression</primary></indexterm>

	<para>Unfortunately, &man.tar.1; does not support
	<option>-z</option> for multi-volume archives. Instead,
	&man.gzip.1; all the files, &man.tar.1; them to the floppies,
	then &man.gunzip.1; the files.</para>
	</sect2>

	<sect2 id="floppies-restoring">
	<title>How Do I Restore My Backups?</title>

	<para>To restore the entire archive use:</para>

	<screen>&prompt.root; <userinput>tar Mxvf /dev/fd0</userinput></screen>

	<para>There are two methods to restore only specific files. The
	first is to insert the first floppy and use:</para>

	<screen>&prompt.root; <userinput>tar Mxvf /dev/fd0 <replaceable>filename</replaceable></userinput></screen>

	<para>&man.tar.1; will prompt to insert subsequent floppies
	until it finds the required file.</para>

	<para>Alternatively, if the floppy containing the file is known,
	insert that floppy and use the same command. If the first
	file on the floppy is a continuation from the previous one,
	&man.tar.1; will warn that it cannot restore it, even if you
	have not asked it to.</para>
	</sect2>
	</sect1>

	<sect1 id="backup-strategies">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Lowell</firstname>
	<surname>Gilbert</surname>
	<contrib>Original work by </contrib>
	</author>
	</authorgroup>
	<!-- 3 Dec 2005 -->
	</sect1info>

	<title>Backup Strategies</title>

	<para>The first requirement in devising a backup plan is to make
	sure that all of the following problems are covered:</para>

	<itemizedlist>
	<listitem>
	<para>Disk failure.</para>
	</listitem>

	<listitem>
	<para>Accidental file deletion.</para>
	</listitem>

	<listitem>
	<para>Random file corruption.</para>
	</listitem>

	<listitem>
	<para>Complete machine destruction, say by fire, including
	destruction of any on-site backups.</para>
	</listitem>
	</itemizedlist>

	<para>Some systems will be best served by having each of these
	problems covered by a completely different technique. Except
	for strictly personal systems with low-value data, it is
	unlikely that one technique will cover all of them.</para>

	<para>Some possible techniques include:</para>

	<itemizedlist>
	<listitem>
	<para>Archives of the whole system, backed up onto permanent,
	off-site media. This provides protection against all of the
	problems listed above, but is slow and inconvenient to
	restore from. Copies of the backups can be stored on site
	or online, but there will still be inconveniences in
	restoring files, especially for non-privileged users.</para>
	</listitem>

	<listitem>
	<para>Filesystem snapshots, which are really only helpful in
	the accidental file deletion scenario, but can be
	<emphasis>very</emphasis> helpful in that case, as well as
	quick and easy to deal with.</para>
	</listitem>

	<listitem>
	<para>Copies of whole file systems or disks which can be
	created with a periodic <filename
	role="package">net/rsync</filename> of the whole machine.
	This is generally most useful in networks with unique
	requirements. For general protection against disk failure,
	this is usually inferior to <acronym>RAID</acronym>. For
	restoring accidentally deleted files, it can be comparable
	to <acronym>UFS</acronym> snapshots.</para>
	</listitem>

	<listitem>
	<para><acronym>RAID</acronym>, which minimizes or avoids
	downtime when a disk fails at the expense of having to deal
	with disk failures more often, because there are more disks,
	albeit at a much lower urgency.</para>
	</listitem>

	<listitem>
	<para>Checking fingerprints of files using &man.mtree.8;.
	Although this is not a backup, this technique indicates
	when one needs to resort to backups. This is particularly
	important for offline backups, and should be checked
	periodically.</para>
	</listitem>
	</itemizedlist>

	<para>It is quite easy to come up with more techniques, many
	of them variations on the ones listed above. Specialized
	requirements usually lead to specialized techniques. For
	example, backing up a live database usually requires a method
	particular to the database software as an intermediate step.
	The important thing is to know which dangers should be protected
	against, and how each will be handled.</para>
	</sect1>

	<sect1 id="backup-basics">
	<title>Backup Basics</title>

	<para>The major backup programs built into &os; are
	&man.dump.8;, &man.tar.1;, &man.cpio.1;, and
	&man.pax.1;.</para>

	<sect2>
	<title>Dump and Restore</title>

	<indexterm>
	<primary>backup software</primary>
	<secondary>dump / restore</secondary>
	</indexterm>
	<indexterm>
	<primary><command>dump</command></primary>
	</indexterm>
	<indexterm>
	<primary><command>restore</command></primary>
	</indexterm>

	<para>The traditional &unix; backup programs are
	<command>dump</command> and <command>restore</command>. They
	operate on the drive as a collection of disk blocks, below the
	abstractions of files, links and directories that are created
	by the file systems. Unlike other backup software,
	<command>dump</command> backs up an entire file system on a
	device. It is unable to backup only part of a file system or
	a directory tree that spans more than one file system.
	<command>dump</command> does not write files and directories,
	but rather writes the raw data blocks that comprise files and
	directories. When used to extract data,
	<command>restore</command> stores temporary
	files in <filename class="directory">/tmp/</filename> by
	default. When using a recovery disk with a small <filename
	class="directory">/tmp</filename>, set
	<envar>TMPDIR</envar> to a directory with more free space in
	order for the restore to succeed.</para>

	<note>
	<para>If <command>dump</command> is used on the root
	directory, it will not back up <filename
	class="directory">/home</filename>,
	<filename class="directory">/usr</filename> or many other
	directories since these are typically mount points for other
	file systems or symbolic links into those file
	systems.</para>
	</note>

	<para><command>dump</command> has quirks that remain from its
	early days in Version 6 of AT&T &unix;,circa 1975. The
	default parameters are suitable for 9-track tapes (6250 bpi),
	not the high-density media available today (up to 62,182
	ftpi). These defaults must be overridden on the command line
	to utilize the capacity of current tape drives.</para>

	<indexterm>
	<primary><filename>.rhosts</filename></primary>
	</indexterm>
	<para>It is also possible to backup data across the network to a
	tape drive attached to another computer with
	<command>rdump</command> and <command>rrestore</command>.
	Both programs rely upon &man.rcmd.3; and &man.ruserok.3; to
	access the remote tape drive. Therefore, the user performing
	the backup must be listed in <filename>.rhosts</filename> on
	the remote computer. The arguments to
	<command>rdump</command> and <command>rrestore</command> must
	be suitable to use on the remote computer. For example, to
	<command>rdump</command> from a &os; computer to an Exabyte
	tape drive connected to a host called
	<hostid>komodo</hostid>, use:</para>

	<screen>&prompt.root; <userinput>/sbin/rdump 0dsbfu 54000 13000 126 komodo:/dev/nsa8 /dev/da0a 2>&1</userinput></screen>

	<para>There are security implications to allowing
	<filename>.rhosts</filename> authentication, so use
	with caution.</para>

	<para>It is also possible to use <command>dump</command> and
	<command>restore</command> in a more secure fashion over
	<command>ssh</command>.</para>

	<example>
	<title>Using <command>dump</command> over
	<application>ssh</application></title>

	<screen>&prompt.root; <userinput>/sbin/dump -0uan -f - /usr \| gzip -2 \| ssh -c blowfish \
	targetuser@targetmachine.example.com dd of=/mybigfiles/dump-usr-l0.gz</userinput></screen>
	</example>

	<para>Or, use the built-in <envar>RSH</envar>:</para>

	<example>
	<title>Using <command>dump</command> over
	<application>ssh</application> with <envar>RSH</envar>
	Set</title>

	<screen>&prompt.root; <userinput>env RSH=/usr/bin/ssh /sbin/dump -0uan -f targetuser@targetmachine.example.com:/dev/sa0 /usr</userinput></screen>
	</example>
	</sect2>

	<sect2>
	<title><command>tar</command></title>

	<indexterm>
	<primary>backup software</primary>
	<secondary><command>tar</command></secondary>
	</indexterm>

	<para>&man.tar.1; also dates back to Version 6 of AT&T
	&unix;, circa 1975. <command>tar</command> operates in
	cooperation with the file system and writes files and
	directories to tape. <command>tar</command> does not support
	the full range of options that are available from
	&man.cpio.1;, but it does not require the unusual command
	pipeline that <command>cpio</command> uses.</para>

	<indexterm><primary><command>tar</command></primary></indexterm>

	<para>To <command>tar</command> to an Exabyte tape drive
	connected to a host called <hostid>komodo</hostid>:</para>

	<screen>&prompt.root; <userinput>tar cf - . \| rsh komodo dd of=<replaceable>tape-device</replaceable> obs=20b</userinput></screen>

	<para>When backing up over an insecure network, instead use
	<command>ssh</command>.</para>
	</sect2>

	<sect2>
	<title><command>cpio</command></title>

	<indexterm>
	<primary>backup software</primary>
	<secondary><command>cpio</command></secondary>
	</indexterm>

	<para>&man.cpio.1; is the original &unix; file interchange tape
	program for magnetic media. <command>cpio</command> includes
	options to perform byte-swapping, write a number of different
	archive formats, and pipe the data to other programs. This
	last feature makes <command>cpio</command> an excellent choice
	for installation media. <command>cpio</command> does not know
	how to walk the directory tree and a list of files must be
	provided through <filename>stdin</filename>.</para>

	<indexterm>
	<primary><command>cpio</command></primary>
	</indexterm>

	<para>Since <command>cpio</command> does not support backups
	across the network, use a pipeline and <command>ssh</command>
	to send the data to a remote tape drive.</para>

	<screen>&prompt.root; <userinput>for f in <replaceable>directory_list; do</replaceable></userinput>
	<userinput>find $f >> backup.list</userinput>
	<userinput>done</userinput>
	&prompt.root; <userinput>cpio -v -o --format=newc < backup.list \| ssh <replaceable>user</replaceable>@<replaceable>host</replaceable> "cat > <replaceable>backup_device</replaceable>"</userinput></screen>

	<para>Where <replaceable>directory_list</replaceable> is the
	list of directories to back up,
	<replaceable>user</replaceable>@<replaceable>host</replaceable>
	is the user/hostname combination that will be performing the
	backups, and <replaceable>backup_device</replaceable> is where
	the backups should be written to, such as
	<filename>/dev/nsa0</filename>).</para>
	</sect2>

	<sect2>
	<title><command>pax</command></title>

	<indexterm>
	<primary>backup software</primary>
	<secondary><command>pax</command></secondary>
	</indexterm>
	<indexterm><primary><command>pax</command></primary></indexterm>
	<indexterm><primary>POSIX</primary></indexterm>
	<indexterm><primary>IEEE</primary></indexterm>

	<para>&man.pax.1; is the IEEE/&posix; answer to
	<command>tar</command> and <command>cpio</command>. Over the
	years the various versions of <command>tar</command> and
	<command>cpio</command> have become slightly incompatible. So
	rather than fight it out to fully standardize them, &posix;
	created a new archive utility. <command>pax</command>
	attempts to read and write many of the various
	<command>cpio</command> and <command>tar</command> formats,
	plus new formats of its own. Its command set more resembles
	<command>cpio</command> than <command>tar</command>.</para>
	</sect2>

	<sect2 id="backups-programs-amanda">
	<title><application>Amanda</application></title>

	<indexterm>
	<primary>backup software</primary>
	<secondary><application>Amanda</application></secondary>
	</indexterm>
	<indexterm>
	<primary><application>Amanda</application></primary>
	</indexterm>

	<!-- Remove link until <port> tag is available -->
	<para><application>Amanda</application> (Advanced Maryland
	Network Disk Archiver) is a client/server backup system,
	rather than a single program. An
	<application>Amanda</application> server will backup to a
	single tape drive any number of computers that have
	<application>Amanda</application> clients and a network
	connection to the <application>Amanda</application> server. A
	common problem at sites with a number of large disks is that
	the length of time required to backup to data directly to tape
	exceeds the amount of time available for the task.
	<application>Amanda</application> solves this problem by using
	a <quote>holding disk</quote> to backup several file systems
	at the same time. <application>Amanda</application> creates
	<quote>archive sets</quote>: a group of tapes used over a
	period of time to create full backups of all the file systems
	listed in <application>Amanda</application>'s configuration
	file. The <quote>archive set</quote> also contains nightly
	incremental, or differential, backups of all the file systems.
	Restoring a damaged file system requires the most recent full
	backup and the incremental backups.</para>

	<para>The configuration file provides fine grained control of
	backups and the network traffic that
	<application>Amanda</application> generates.
	<application>Amanda</application> will use any of the above
	backup programs to write the data to tape.
	<application>Amanda</application> is not installed by
	but is available as either a port or package.</para>
	</sect2>

	<sect2>
	<title>Do Nothing</title>

	<para><quote>Do nothing</quote> is not a computer program, but
	it is the most widely used backup strategy. There are no
	initial costs. There is no backup schedule to follow. Just
	say no. If something happens to your data, grin and bear
	it!</para>

	<para>If your time and data is worth little to nothing, then
	<quote>Do nothing</quote> is the most suitable backup program
	for the computer. But beware, &os; is a useful tool and
	over time it can be used to create a valuable collection of
	files.</para>

	<para><quote>Do nothing</quote> is the correct backup method for
	<filename class="directory">/usr/obj</filename> and other
	directory trees that can be exactly recreated by the computer.
	An example is the files that comprise the HTML or &postscript;
	version of this Handbook. These document formats have been
	created from XML input files. Creating backups of the HTML or
	&postscript; files is not necessary if the XML files are
	backed up regularly.</para>
	</sect2>

	<sect2>
	<title>Which Backup Program Is Best?</title>

	<indexterm>
	<primary>LISA</primary>
	</indexterm>

	<para>&man.dump.8; <emphasis>Period.</emphasis> Elizabeth D.
	Zwicky torture tested all the backup programs discussed here.
	The clear choice for preserving all your data and all the
	peculiarities of &unix; file systems is
	<command>dump</command>. Elizabeth created file systems
	containing a large variety of unusual conditions (and some not
	so unusual ones) and tested each program by doing a backup and
	restore of those file systems. The peculiarities included:
	files with holes, files with holes and a block of nulls, files
	with funny characters in their names, unreadable and
	unwritable files, devices, files that change size during the
	backup, files that are created/deleted during the backup and
	more. She presented the results at LISA V in Oct. 1991. See
	<ulink
	url="http://www.coredumps.de/doc/dump/zwicky/testdump.doc.html">torture-testing
	Backup and Archive Programs</ulink>.</para>
	</sect2>

	<sect2>
	<title>Emergency Restore Procedure</title>

	<sect3>
	<title>Before the Disaster</title>

	<para>There are four steps which should be performed in
	preparation for any disaster that may occur.</para>
	<indexterm>
	<primary><command>bsdlabel</command></primary>
	</indexterm>

	<para>First, print the bsdlabel of each disk using a command
	such as <command>bsdlabel da0 \| lpr</command>. Also print a
	copy of <filename>/etc/fstab</filename> and all boot
	messages.</para>

	<indexterm><primary>livefs CD</primary></indexterm>
	<para>Second, burn a <quote>livefs</quote> CD. This CD
	contains support for booting into a &os;
	<quote>livefs</quote> rescue mode, allowing the user to
	perform many tasks like running &man.dump.8;,
	&man.restore.8;, &man.fdisk.8;, &man.bsdlabel.8;,
	&man.newfs.8;, &man.mount.8;, and more. The livefs CD image
	for &os;/&arch.i386; &rel2.current;-RELEASE is
	available from <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/ISO-IMAGES/&rel2.current;/&os;-&rel2.current;-RELEASE-&arch.i386;-livefs.iso"></ulink>.</para>

	<note>
	<para>Livefs CD images are not available for
	&os; &rel.current;-RELEASE and later. In addition to
	the CDROM installation images, flash drive installation
	images may be used to recover a system. The
	<quote>memstick</quote> image for
	&os;/&arch.i386; &rel.current;-RELEASE is available
	from <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/&arch.i386;/ISO-IMAGES/&rel.current;/&os;-&rel.current;-RELEASE-&arch.i386;-memstick.img"></ulink>.</para>
	</note>

	<para>Third, create backup tapes regularly. Any changes that
	made after the last backup may be irretrievably lost.
	Write-protect the backup media.</para>

	<para>Fourth, test the <quote>livefs</quote> CD and the
	backups. Make notes of the procedure. Store these notes
	with the CD, the printouts, and the backups. These notes
	may prevent the inadvertent destruction of the backups while
	under the stress of performing an emergency
	recovery.</para>

	<para>For an added measure of security, store an extra
	<quote>livefs</quote> CD and the latest backup at a
	remote location, where a remote location is
	<emphasis>not</emphasis> the basement of the same building.
	A remote location should be physically separated from the
	computers and disk drives by a significant distance.</para>
	</sect3>

	<sect3>
	<title>After the Disaster</title>

	<para>First, determine if the hardware survived. Thanks
	to regular, off-site backups, there is no need to worry
	about the software.</para>

	<para>If the hardware has been damaged, the parts should be
	replaced before attempting to use the computer.</para>

	<para>If the hardware is okay, insert the
	<quote>livefs</quote> CD and boot the computer. The
	original install menu will be displayed on the screen.
	Select the correct country, then choose
	<guimenuitem>Fixit -- Repair mode with CDROM/DVD/floppy or
	start a shell.</guimenuitem> then select
	<guimenuitem>CDROM/DVD -- Use the live filesystem
	CDROM/DVD</guimenuitem>.
	<command>restore</command> and the other needed programs
	are located in <filename
	class="directory">/mnt2/rescue</filename>.</para>

	<para>Recover each file system separately.</para>

	<indexterm>
	<primary><command>mount</command></primary>
	</indexterm>
	<indexterm><primary>root partition</primary></indexterm>
	<indexterm>
	<primary><command>bsdlabel</command></primary>
	</indexterm>
	<indexterm>
	<primary><command>newfs</command></primary>
	</indexterm>

	<para>Try to <command>mount</command> the root partition
	of the first disk using <command>mount /dev/da0a
	/mnt</command>. If the bsdlabel was damaged, use
	<command>bsdlabel</command> to re-partition and label the
	disk to match the label that was printed and saved. Use
	<command>newfs</command> to re-create the file systems.
	Re-mount the root partition of the disk read-write using
	<command>mount -u -o rw /mnt</command>. Use the backups
	to recover the data for this file system. Unmount the file
	system with <command>umount /mnt</command>. Repeat for each
	file system that was damaged.</para>

	<para>Once the system is running, backup the data onto new
	media as whatever caused the crash or data loss may strike
	again. Another hour spent now may save further distress
	later.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="disks-virtual">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Marc</firstname>
	<surname>Fonvieille</surname>
	<contrib>Reorganized and enhanced by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Network, Memory, and File-Backed File Systems</title>

	<indexterm><primary>virtual disks</primary></indexterm>
	<indexterm>
	<primary>disks</primary>
	<secondary>virtual</secondary>
	</indexterm>

	<para>In addition to physical disks such as floppies, CDs, and
	hard drives, &os; also supports <firstterm>virtual
	disks</firstterm>.</para>

	<indexterm><primary>NFS</primary></indexterm>
	<indexterm><primary>Coda</primary></indexterm>
	<indexterm>
	<primary>disks</primary>
	<secondary>memory</secondary>
	</indexterm>
	<para>These include network file systems such as the
	<link linkend="network-nfs">Network File System</link> and Coda,
	memory-based file systems, and file-backed file systems.</para>

	<para>According to the &os; version, the tools used for the
	creation and use of file-backed and memory-based file systems
	differ.</para>

	<note>
	<para>Use &man.devfs.5; to allocate device nodes transparently
	for the user.</para>
	</note>

	<sect2 id="disks-mdconfig">
	<title>File-Backed File System</title>

	<indexterm>
	<primary>disks</primary>
	<secondary>file-backed</secondary>
	</indexterm>

	<para>&man.mdconfig.8; is used to configure and enable memory
	disks, &man.md.4;, under &os;. To use &man.mdconfig.8;,
	&man.md.4; must be first loaded. When using a custom kernel
	configuration file, ensure it includes this line:</para>

	<programlisting>device md</programlisting>

	<para>&man.mdconfig.8; supports several types of memory backed
	virtual disks: memory disks allocated with &man.malloc.9; and
	memory disks using a file or swap space as backing. One
	possible use is the mounting of CD images.</para>

	<para>To mount an existing file system image:</para>

	<example>
	<title>Using <command>mdconfig</command> to Mount an Existing
	File System Image</title>

	<screen>&prompt.root; <userinput>mdconfig -a -t vnode -f <replaceable>diskimage</replaceable> -u <replaceable>0</replaceable></userinput>
	&prompt.root; <userinput>mount /dev/md<replaceable>0</replaceable> <replaceable>/mnt</replaceable></userinput></screen>
	</example>

	<para>To create a new file system image with
	&man.mdconfig.8;:</para>

	<example>
	<title>Creating a New File-Backed Disk with
	<command>mdconfig</command></title>

	<screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>newimage</replaceable> bs=1k count=<replaceable>5</replaceable>k</userinput>
	5120+0 records in
	5120+0 records out
	&prompt.root; <userinput>mdconfig -a -t vnode -f <replaceable>newimage</replaceable> -u <replaceable>0</replaceable></userinput>
	&prompt.root; <userinput>bsdlabel -w md<replaceable>0</replaceable> auto</userinput>
	&prompt.root; <userinput>newfs md<replaceable>0</replaceable>a</userinput>
	/dev/md0a: 5.0MB (10224 sectors) block size 16384, fragment size 2048
	using 4 cylinder groups of 1.25MB, 80 blks, 192 inodes.
	super-block backups (for fsck -b #) at:
	160, 2720, 5280, 7840
	&prompt.root; <userinput>mount /dev/md<replaceable>0</replaceable>a <replaceable>/mnt</replaceable></userinput>
	&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput>
	Filesystem 1K-blocks Used Avail Capacity Mounted on
	/dev/md0a 4710 4 4330 0% /mnt</screen>
	</example>

	<para>If unit number is not specified with
	<option>-u</option>, &man.mdconfig.8; uses the
	&man.md.4; automatic allocation to select an unused device.
	The name of the allocated unit will be output to stdout, such
	as <devicename>md4</devicename>. Refer to &man.mdconfig.8;
	for more details about.</para>

	<para>While &man.mdconfig.8; is useful, it takes several
	command lines to create a file-backed file system. &os; also
	comes with &man.mdmfs.8; which automatically configures a
	&man.md.4; disk using &man.mdconfig.8;, puts a UFS file system
	on it using &man.newfs.8;, and mounts it using &man.mount.8;.
	For example, to create and mount the same file system image as
	above, type the following:</para>

	<example>
	<title>Configure and Mount a File-Backed Disk with
	<command>mdmfs</command></title>

	<screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>newimage</replaceable> bs=1k count=<replaceable>5</replaceable>k</userinput>
	5120+0 records in
	5120+0 records out
	&prompt.root; <userinput>mdmfs -F <replaceable>newimage</replaceable> -s <replaceable>5</replaceable>m md<replaceable>0</replaceable> <replaceable>/mnt</replaceable></userinput>
	&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput>
	Filesystem 1K-blocks Used Avail Capacity Mounted on
	/dev/md0 4718 4 4338 0% /mnt</screen>
	</example>

	<para>When <option>md</option> is used without a unit number,
	&man.mdmfs.8; uses the &man.md.4; auto-unit feature to
	automatically select an unused device. For more details
	about &man.mdmfs.8;, refer to its manual page.</para>
	</sect2>

	<sect2 id="disks-md-freebsd5">
	<title>Memory-Based File System</title>

	<indexterm>
	<primary>disks</primary>
	<secondary>memory file system</secondary>
	</indexterm>

	<para>For a memory-based file system, <quote>swap
	backing</quote> should normally be used. This does not mean
	that the memory disk will be swapped out to disk by default,
	but rather that the memory disk will be allocated from a
	memory pool which can be swapped out to disk if needed. It is
	also possible to create memory-based disks which are
	&man.malloc.9; backed, but using large malloc backed memory
	disks can result in a system panic if the kernel runs out of
	memory.</para>

	<example>
	<title>Creating a New Memory-Based Disk with
	<command>mdconfig</command></title>

	<screen>&prompt.root; <userinput>mdconfig -a -t swap -s <replaceable>5</replaceable>m -u <replaceable>1</replaceable></userinput>
	&prompt.root; <userinput>newfs -U md<replaceable>1</replaceable></userinput>
	/dev/md1: 5.0MB (10240 sectors) block size 16384, fragment size 2048
	using 4 cylinder groups of 1.27MB, 81 blks, 192 inodes.
	with soft updates
	super-block backups (for fsck -b #) at:
	160, 2752, 5344, 7936
	&prompt.root; <userinput>mount /dev/md<replaceable>1</replaceable> <replaceable>/mnt</replaceable></userinput>
	&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput>
	Filesystem 1K-blocks Used Avail Capacity Mounted on
	/dev/md1 4718 4 4338 0% /mnt</screen>
	</example>

	<example>
	<title>Creating a New Memory-Based Disk with
	<command>mdmfs</command></title>

	<screen>&prompt.root; <userinput>mdmfs -s <replaceable>5</replaceable>m md<replaceable>2</replaceable> <replaceable>/mnt</replaceable></userinput>
	&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput>
	Filesystem 1K-blocks Used Avail Capacity Mounted on
	/dev/md2 4846 2 4458 0% /mnt</screen>
	</example>
	</sect2>

	<sect2>
	<title>Detaching a Memory Disk from the System</title>

	<indexterm>
	<primary>disks</primary>
	<secondary>detaching a memory disk</secondary>
	</indexterm>

	<para>When a memory-based or file-based file system is no
	longer in use, its resources should be released back to
	the system. First, unmount the file system, then use
	&man.mdconfig.8; to detach the disk from the system and
	release the resources.</para>

	<para>For example, to detach and free all resources used by
	<filename>/dev/md4</filename>:</para>

	<screen>&prompt.root; <userinput>mdconfig -d -u <replaceable>4</replaceable></userinput></screen>

	<para>It is possible to list information about configured
	&man.md.4; devices by running
	<command>mdconfig -l</command>.</para>
	</sect2>
	</sect1>

	<sect1 id="snapshots">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<!-- 15 JUL 2002 -->
	</sect1info>

	<title>File System Snapshots</title>

	<indexterm>
	<primary>file systems</primary>
	<secondary>snapshots</secondary>
	</indexterm>

	<para>&os; offers a feature in conjunction with
	<link linkend="soft-updates">Soft Updates</link>: file system
	snapshots.</para>

	<para>UFS snapshots allow a user to create images of specified
	file systems, and treat them as a file. Snapshot files must be
	created in the file system that the action is performed on, and
	a user may create no more than 20 snapshots per file system.
	Active snapshots are recorded in the superblock so they are
	persistent across unmount and remount operations along with
	system reboots. When a snapshot is no longer required, it can
	be removed using &man.rm.1;. While snapshots may be removed in
	any order, all the used space may not be acquired because
	another snapshot will possibly claim some of the released
	blocks.</para>

	<para>The un-alterable <option>snapshot</option> file flag is set
	by &man.mksnap.ffs.8; after initial creation of a snapshot file.
	&man.unlink.1; makes an exception for snapshot files since it
	allows them to be removed.</para>

	<para>Snapshots are created using &man.mount.8;. To place a
	snapshot of <filename class="directory">/var</filename> in the
	file <filename>/var/snapshot/snap</filename>, use the following
	command:</para>

	<screen>&prompt.root; <userinput>mount -u -o snapshot /var/snapshot/snap /var</userinput></screen>

	<para>Alternatively, use &man.mksnap.ffs.8; to create the
	snapshot:</para>

	<screen>&prompt.root; <userinput>mksnap_ffs /var /var/snapshot/snap</userinput></screen>

	<para>One can find snapshot files on a file system, such as
	<filename class="directory">/var</filename>, using
	&man.find.1;:</para>

	<screen>&prompt.root; <userinput>find /var -flags snapshot</userinput></screen>

	<para>Once a snapshot has been created, it has several
	uses:</para>

	<itemizedlist>
	<listitem>
	<para>Some administrators will use a snapshot file for backup
	purposes, because the snapshot can be transferred to CDs or
	tape.</para>
	</listitem>

	<listitem>
	<para>The file system integrity checker, &man.fsck.8;, may be
	run on the snapshot. Assuming that the file system was
	clean when it was mounted, this should always provide a
	clean and unchanging result.</para>
	</listitem>

	<listitem>
	<para>Running &man.dump.8; on the snapshot will produce a dump
	file that is consistent with the file system and the
	timestamp of the snapshot. &man.dump.8; can also take a
	snapshot, create a dump image, and then remove the snapshot
	in one command by using <option>-L</option>.</para>
	</listitem>

	<listitem>
	<para>The snapshot can be mounted as a frozen image of the
	file system. To &man.mount.8; the snapshot
	<filename>/var/snapshot/snap</filename> run:</para>

	<screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /var/snapshot/snap -u 4</userinput>
	&prompt.root; <userinput>mount -r /dev/md4 /mnt</userinput></screen>
	</listitem>
	</itemizedlist>

	<para>The frozen <filename class="directory">/var</filename> is
	now available through <filename
	class="directory">/mnt</filename>. Everything will initially
	be in the same state it was during the snapshot creation time.
	The only exception is that any earlier snapshots will appear as
	zero length files. To unmount the snapshot, use:</para>

	<screen>&prompt.root; <userinput>umount /mnt</userinput>
	&prompt.root; <userinput>mdconfig -d -u 4</userinput></screen>

	<para>For more information about <option>softupdates</option> and
	file system snapshots, including technical papers, visit
	Marshall Kirk McKusick's website at
	<ulink url="http://www.mckusick.com/"></ulink>.</para>
	</sect1>

	<sect1 id="quotas">
	<title>File System Quotas</title>

	<indexterm>
	<primary>accounting</primary>
	<secondary>disk space</secondary>
	</indexterm>
	<indexterm><primary>disk quotas</primary></indexterm>

	<para>Quotas are an optional feature of the operating system that
	can be used to limit the amount of disk space or the number of
	files a user or members of a group may allocate on a per-file
	system basis. This is used most often on timesharing systems
	where it is desirable to limit the amount of resources any one
	user or group of users may allocate. This prevents one user or
	group of users from consuming all of the available disk
	space.</para>

	<sect2>
	<title>Configuring the System to Enable Disk Quotas</title>

	<para>Before using disk quotas, quota support must be added to
	the kernel by adding the following line to the kernel
	configuration file:</para>

	<programlisting>options QUOTA</programlisting>

	<para>The <filename>GENERIC</filename> kernel does not
	have this enabled by default, so a custom kernel must be
	compiled in order to use disk quotas. Refer to <link
	linkend="kernelconfig"></link> for more information on
	kernel configuration.</para>

	<para>Next, enable disk quotas in
	- <filename>/etc/rc.conf</filename>. On &os; 7.X and
	- earlier, this is done by adding the line:</para>
	+ <filename>/etc/rc.conf</filename>:</para>

	- <programlisting>enable_quotas="YES"</programlisting>
	-
	- <para>On &os; 8.0-RELEASE and later, add the following
	- line instead:</para>
	-
	<programlisting>quota_enable="YES"</programlisting>

	<indexterm>
	<primary>disk quotas</primary>
	<secondary>checking</secondary>
	</indexterm>
	<para>For finer control over quota startup, an additional
	configuration variable is available. Normally on bootup, the
	quota integrity of each file system is checked by
	&man.quotacheck.8;. This program insures that the data in the
	quota database properly reflects the data on the file system.
	This is a time consuming process that will significantly
	affect the time the system takes to boot. To skip this step,
	add this variable to <filename>/etc/rc.conf</filename>:</para>

	<programlisting>check_quotas="NO"</programlisting>

	<para>Finally, edit <filename>/etc/fstab</filename> to enable
	disk quotas on a per-file system basis. This is when user or
	group quotas can be enabled on the file systems.</para>

	<para>To enable per-user quotas on a file system, add
	<option>userquota</option> to the options field in the
	<filename>/etc/fstab</filename> entry for the file system to
	enable quotas on. For example:</para>

	<programlisting>/dev/da1s2g /home ufs rw,userquota 1 2</programlisting>

	<para>To enable group quotas, instead use
	<option>groupquota</option>. To enable both user and group
	quotas, change the entry as follows:</para>

	<programlisting>/dev/da1s2g /home ufs rw,userquota,groupquota 1 2</programlisting>

	<para>By default, the quota files are stored in the root
	directory of the file system as
	<filename>quota.user</filename> and
	<filename>quota.group</filename>. Refer to &man.fstab.5; for
	more information. Even though an alternate location for the
	quota files can be specified, this is not recommended because
	the various quota utilities do not seem to handle this
	properly.</para>

	<para>Once the configuration is complete, reboot the system
	with the new kernel. <filename>/etc/rc</filename> will
	automatically run the appropriate commands to create the
	initial quota files for all of the quotas enabled in
	<filename>/etc/fstab</filename>. There is no need to
	manually create any zero length quota files.</para>

	<para>In the normal course of operations, there should be no
	need to manually run &man.quotacheck.8;, &man.quotaon.8;, or
	&man.quotaoff.8;. However, one should read their manual pages
	to be familiar with their operation.</para>
	</sect2>

	<sect2>
	<title>Setting Quota Limits</title>

	<indexterm>
	<primary>disk quotas</primary>
	<secondary>limits</secondary>
	</indexterm>

	<para>Once the system has been configured to enable quotas,
	verify they really are enabled by running:</para>

	<screen>&prompt.root; <userinput>quota -v</userinput></screen>

	<para>There should be a one line summary of disk usage and
	current quota limits for each file system that quotas are
	enabled on.</para>

	<para>The system is now ready to be assigned quota limits with
	&man.edquota.8;.</para>

	<para>Several options are available to enforce limits on the
	amount of disk space a user or group may allocate, and how
	many files they may create. Allocations can be limited based
	on disk space (block quotas), number of files (inode quotas),
	or a combination of both. Each limits is further broken down
	into two categories: hard and soft limits.</para>

	<indexterm><primary>hard limit</primary></indexterm>
	<para>A hard limit may not be exceeded. Once a user reaches a
	hard limit, no further allocations can be made on that file
	system by that user. For example, if the user has a hard
	limit of 500 kbytes on a file system and is currently using
	490 kbytes, the user can only allocate an additional 10
	kbytes. Attempting to allocate an additional 11 kbytes will
	fail.</para>

	<indexterm><primary>soft limit</primary></indexterm>
	<para>Soft limits can be exceeded for a limited amount of time,
	known as the grace period, which is one week by default. If a
	user stays over their limit longer than the grace period, the
	soft limit turns into a hard limit and no further allocations
	are allowed. When the user drops back below the soft limit,
	the grace period is reset.</para>

	<para>The following is an example output from &man.edquota.8;.
	When &man.edquota.8; is invoked, the editor specified by
	<envar>EDITOR</envar> is opened in order to edit the quota
	limits. The default editor is set to
	<application>vi</application>.</para>

	<screen>&prompt.root; <userinput>edquota -u test</userinput></screen>

	<programlisting>Quotas for user test:
	/usr: kbytes in use: 65, limits (soft = 50, hard = 75)
	inodes in use: 7, limits (soft = 50, hard = 60)
	/usr/var: kbytes in use: 0, limits (soft = 50, hard = 75)
	inodes in use: 0, limits (soft = 50, hard = 60)</programlisting>

	<para>There are normally two lines for each file system that
	has quotas enabled. One line represents the block limits and
	the other represents the inode limits. Change the value to
	modify the quota limit. For example, to raise this
	user's block limit from a soft limit of 50 and a hard limit of
	75 to a soft limit of 500 and a hard limit of 600,
	change:</para>

	<programlisting>/usr: kbytes in use: 65, limits (soft = 50, hard = 75)</programlisting>

	<para>to:</para>

	<programlisting>/usr: kbytes in use: 65, limits (soft = 500, hard = 600)</programlisting>

	<para>The new quota limits take affect upon exiting the
	editor.</para>

	<para>Sometimes it is desirable to set quota limits on a range
	of UIDs. This can be done by passing <option>-p</option> to
	&man.edquota.8;. First, assign the desired quota limit to a
	user, then run <command>edquota -p protouser
	startuid-enduid</command>. For example, if
	<username>test</username> has the desired quota limits, the
	following command will duplicate those quota limits for UIDs
	10,000 through 19,999:</para>

	<screen>&prompt.root; <userinput>edquota -p test 10000-19999</userinput></screen>

	<para>For more information, refer to &man.edquota.8;.</para>
	</sect2>

	<sect2>
	<title>Checking Quota Limits and Disk Usage</title>

	<indexterm>
	<primary>disk quotas</primary>
	<secondary>checking</secondary>
	</indexterm>

	<para>Either &man.quota.1; or &man.repquota.8; can be used to
	check quota limits and disk usage. To check individual user
	or group quotas and disk usage, use &man.quota.1;. A user
	may only examine their own quota and the quota of a group they
	are a member of. Only the superuser may view all user and
	group quotas. To get a summary of all quotas and disk usage
	for file systems with quotas enabled, use
	&man.repquota.8;.</para>

	<para>The following is sample output from
	<command>quota -v</command> for a user that has quota limits
	on two file systems.</para>

	<programlisting>Disk quotas for user test (uid 1002):
	Filesystem usage quota limit grace files quota limit grace
	/usr 65* 50 75 5days 7 50 60
	/usr/var 0 50 75 0 50 60</programlisting>

	<indexterm><primary>grace period</primary></indexterm>
	<para>In this example, the user is currently 15 kbytes over the
	soft limit of 50 kbytes on <filename
	class="directory">/usr</filename> and has 5 days of grace
	period left. The asterisk <literal>*</literal> indicates that
	the user is currently over the quota limit.</para>

	<para>Normally, file systems that the user is not using any disk
	space on will not show in the output of &man.quota.1;, even if
	the user has a quota limit assigned for that file system. Use
	<option>-v</option> to display those file systems, such as
	<filename class="directory">/usr/var</filename> in the above
	example.</para>
	</sect2>

	<sect2>
	<title>Quotas over NFS</title>

	<indexterm><primary>NFS</primary></indexterm>

	<para>Quotas are enforced by the quota subsystem on the NFS
	server. The &man.rpc.rquotad.8; daemon makes quota
	information available to &man.quota.1; on NFS clients,
	allowing users on those machines to see their quota
	statistics.</para>

	<para>Enable <command>rpc.rquotad</command> in
	<filename>/etc/inetd.conf</filename> like so:</para>

	<programlisting>rquotad/1 dgram rpc/udp wait root /usr/libexec/rpc.rquotad rpc.rquotad</programlisting>

	<para>Now restart <command>inetd</command>:</para>

	<screen>&prompt.root; <userinput>service inetd restart</userinput></screen>
	</sect2>
	</sect1>

	<sect1 id="disks-encrypting">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Lucky</firstname>
	<surname>Green</surname>
	<contrib>Contributed by </contrib>
	<affiliation>
	<address><email>shamrock@cypherpunks.to</email></address>
	</affiliation>
	</author>
	</authorgroup>
	<!-- 11 MARCH 2003 -->
	</sect1info>

	<title>Encrypting Disk Partitions</title>

	<indexterm>
	<primary>disks</primary>
	<secondary>encrypting</secondary>
	</indexterm>

	<para>&os; offers excellent online protections against
	unauthorized data access. File permissions and <link
	linkend="mac">Mandatory Access Control</link> (MAC) help
	prevent unauthorized users from accessing data while the
	operating system is active and the computer is powered up.
	However, the permissions enforced by the operating system are
	irrelevant if an attacker has physical access to a computer and
	can move the computer's hard drive to another system to copy and
	analyze the data.</para>

	<para>Regardless of how an attacker may have come into possession
	of a hard drive or powered-down computer, both the GEOM Based
	Disk Encryption (<command>gbde</command>) and
	<command>geli</command> cryptographic subsystems in &os; are
	able to protect the data on the computer's file systems against
	even highly-motivated attackers with significant resources.
	Unlike cumbersome encryption methods that encrypt only
	individual files, <command>gbde</command> and
	<command>geli</command> transparently encrypt entire file
	systems. No cleartext ever touches the hard drive's
	platter.</para>

	<sect2>
	<title>Disk Encryption with
	<application>gbde</application></title>

	<procedure>
	<step>
	<para>Configuring <application>gbde</application> requires
	superuser privileges.</para>

	<screen>&prompt.user; <userinput>su -</userinput>
	Password:</screen>
	</step>

	<step>
	<para>If using a custom kernel configuration file, ensure it
	contains this line:</para>

	<para><literal>options GEOM_BDE</literal></para>

	<para>If the kernel already contains this support, use
	<command>kldload</command> to load &man.gbde.4;:</para>

	<screen>&prompt.root; <userinput>kldload geom_bde</userinput></screen>
	</step>
	</procedure>

	<sect3>
	<title>Preparing the Encrypted Hard Drive</title>

	<para>The following example demonstrates adding a new hard
	drive to a system that will hold a single encrypted
	partition. This partition will be mounted as
	<filename class="directory">/private</filename>.
	<application>gbde</application> can also be used to encrypt
	<filename class="directory">/home</filename> and
	<filename class="directory">/var/mail</filename>, but this
	requires more complex instructions which exceed the scope of
	this introduction.</para>

	<procedure>
	<step>
	<title>Add the New Hard Drive</title>

	<para>Install the new drive to the system as explained in
	<link linkend="disks-adding"></link>. For the purposes
	of this example, a new hard drive partition has been
	added as <devicename>/dev/ad4s1c</devicename> and
	<devicename>/dev/ad0s1<replaceable>*</replaceable></devicename>
	represents the existing standard &os; partitions.</para>

	<screen>&prompt.root; <userinput>ls /dev/ad*</userinput>
	/dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1
	/dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c
	/dev/ad0s1a /dev/ad0s1d /dev/ad4</screen>
	</step>

	<step>
	<title>Create a Directory to Hold <command>gbde</command>
	Lock Files</title>

	<screen>&prompt.root; <userinput>mkdir /etc/gbde</userinput></screen>

	<para>The <application>gbde</application> lock file
	contains information that
	<application>gbde</application> requires to access
	encrypted partitions. Without access to the lock file,
	<application>gbde</application> will not be able to
	decrypt the data contained in the encrypted partition
	without significant manual intervention which is not
	supported by the software. Each encrypted partition
	uses a separate lock file.</para>
	</step>

	<step>
	<title>Initialize the <command>gbde</command>
	Partition</title>

	<para>A <application>gbde</application> partition must be
	initialized before it can be used. This initialization
	needs to be performed only once:</para>

	<screen>&prompt.root; <userinput>gbde init /dev/ad4s1c -i -L /etc/gbde/ad4s1c.lock</userinput></screen>

	<para>&man.gbde.8; will open the default editor, in order
	to set various configuration options in a template. For
	use with UFS1 or UFS2, set the sector_size to
	2048:</para>

	<programlisting># &dollar;FreeBSD: src/sbin/gbde/template.txt,v 1.1.36.1 2009/08/03 08:13:06 kensmith Exp $
	#
	# Sector size is the smallest unit of data which can be read or written.
	# Making it too small decreases performance and decreases available space.
	# Making it too large may prevent filesystems from working. 512 is the
	# minimum and always safe. For UFS, use the fragment size
	#
	sector_size = 2048
	[...]</programlisting>

	<para>&man.gbde.8; will ask the user twice to type the
	passphrase used to secure the data. The passphrase must
	be the same both times. The ability of
	<application>gbde</application> to protect data depends
	entirely on the quality of the passphrase. For tips on
	how to select a secure passphrase that is easy to
	remember, see the <ulink
	url="http://world.std.com/~reinhold/diceware.html">Diceware
	Passphrase</ulink> website.</para>

	<para><command>gbde init</command>creates a lock file for
	the <application>gbde</application> partition. In this
	example, it is stored as
	<filename>/etc/gbde/ad4s1c.lock</filename>.
	<application>gbde</application> lock files must end in
	<quote>.lock</quote> in order to be correctly detected
	by the <filename>/etc/rc.d/gbde</filename> start up
	script.</para>

	<caution>
	<para><application>gbde</application> lock files
	<emphasis>must</emphasis> be backed up together with
	the contents of any encrypted partitions. While
	deleting a lock file alone cannot prevent a determined
	attacker from decrypting a
	<application>gbde</application> partition, without the
	lock file, the legitimate owner will be unable to
	access the data on the encrypted partition without a
	significant amount of work that is totally unsupported
	by &man.gbde.8;.</para>
	</caution>
	</step>

	<step>
	<title>Attach the Encrypted Partition to the
	Kernel</title>

	<screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c.lock</userinput></screen>

	<para>This command will prompt to input the passphrase
	that was selected during the initialization of the
	encrypted partition. The new encrypted device will
	appear in
	<filename class="directory">/dev</filename> as
	<devicename>/dev/device_name.bde</devicename>:</para>

	<screen>&prompt.root; <userinput>ls /dev/ad*</userinput>
	/dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1
	/dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c
	/dev/ad0s1a /dev/ad0s1d /dev/ad4 /dev/ad4s1c.bde</screen>
	</step>

	<step>
	<title>Create a File System on the Encrypted
	Device</title>

	<para>Once the encrypted device has been attached to the
	kernel, a file system can be created on the device using
	&man.newfs.8;. This example creates a UFS2 file
	system with soft updates enabled.</para>

	<screen>&prompt.root; <userinput>newfs -U /dev/ad4s1c.bde</userinput></screen>

	<note>
	<para>&man.newfs.8; must be performed on an attached
	<application>gbde</application> partition which is
	identified by a
	<filename><replaceable>*</replaceable>.bde</filename>
	extension to the device name.</para>
	</note>
	</step>

	<step>
	<title>Mount the Encrypted Partition</title>

	<para>Create a mount point for the encrypted file
	system:</para>

	<screen>&prompt.root; <userinput>mkdir /private</userinput></screen>

	<para>Mount the encrypted file system:</para>

	<screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen>
	</step>

	<step>
	<title>Verify That the Encrypted File System is
	Available</title>

	<para>The encrypted file system should now be visible to
	&man.df.1; and be available for use.</para>

	<screen>&prompt.user; <userinput>df -H</userinput>
	Filesystem Size Used Avail Capacity Mounted on
	/dev/ad0s1a 1037M 72M 883M 8% /
	/devfs 1.0K 1.0K 0B 100% /dev
	/dev/ad0s1f 8.1G 55K 7.5G 0% /home
	/dev/ad0s1e 1037M 1.1M 953M 0% /tmp
	/dev/ad0s1d 6.1G 1.9G 3.7G 35% /usr
	/dev/ad4s1c.bde 150G 4.1K 138G 0% /private</screen>
	</step>
	</procedure>
	</sect3>

	<sect3>
	<title>Mounting Existing Encrypted File Systems</title>

	<para>After each boot, any encrypted file systems must be
	re-attached to the kernel, checked for errors, and mounted,
	before the file systems can be used. The required commands
	must be executed as <username>root</username>.</para>

	<procedure>
	<step>
	<title>Attach the <command>gbde</command> Partition to the
	Kernel</title>

	<screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c.lock</userinput></screen>

	<para>This command will prompt for the passphrase that was
	selected during initialization of the encrypted
	<application>gbde</application> partition.</para>
	</step>

	<step>
	<title>Check the File System for Errors</title>

	<para>Since encrypted file systems cannot yet be listed in
	<filename>/etc/fstab</filename> for automatic mounting,
	the file systems must be checked for errors by running
	&man.fsck.8; manually before mounting:</para>

	<screen>&prompt.root; <userinput>fsck -p -t ffs /dev/ad4s1c.bde</userinput></screen>
	</step>

	<step>
	<title>Mount the Encrypted File System</title>

	<screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen>

	<para>The encrypted file system is now available for
	use.</para>
	</step>
	</procedure>

	<sect4>
	<title>Automatically Mounting Encrypted Partitions</title>

	<para>It is possible to create a script to automatically
	attach, check, and mount an encrypted partition, but for
	security reasons the script should not contain the
	&man.gbde.8; password. Instead, it is recommended that
	such scripts be run manually while providing the password
	via the console or &man.ssh.1;.</para>

	<para>As an alternative, an <filename>rc.d</filename> script
	is provided. Arguments for this script can be passed via
	&man.rc.conf.5;:</para>

	<programlisting>gbde_autoattach_all="YES"
	gbde_devices="ad4s1c"
	gbde_lockdir="/etc/gbde"</programlisting>

	<para>This requires that the
	<application>gbde</application> passphrase be entered at
	boot time. After typing the correct passphrase, the
	<application>gbde</application> encrypted partition will
	be mounted automatically. This can be useful when using
	<application>gbde</application> on laptops.</para>
	</sect4>
	</sect3>

	<sect3>
	<title>Cryptographic Protections Employed by
	<command>gbde</command></title>

	<para>&man.gbde.8; encrypts the sector payload using 128-bit
	AES in CBC mode. Each sector on the disk is encrypted with
	a different AES key. For more information on the
	cryptographic design, including how the sector keys are
	derived from the user-supplied passphrase, refer to
	&man.gbde.4;.</para>
	</sect3>

	<sect3>
	<title>Compatibility Issues</title>

	<para>&man.sysinstall.8; is incompatible with
	<application>gbde</application>-encrypted devices. All
	<devicename><replaceable>*</replaceable>.bde</devicename>
	devices must be detached from the kernel before starting
	&man.sysinstall.8; or it will crash during its initial
	probing for devices. To detach the encrypted device used in
	the example, use the following command:</para>

	<screen>&prompt.root; <userinput>gbde detach /dev/ad4s1c</userinput></screen>

	<para>Also, since &man.vinum.4; does not use the
	&man.geom.4; subsystem,
	<application>gbde</application> can not be used with
	<application>vinum</application> volumes.</para>
	</sect3>
	</sect2>

	<sect2>
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Daniel</firstname>
	<surname>Gerzo</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<!-- Date of writing: 28 November 2005 -->
	</sect2info>

	<title>Disk Encryption with <command>geli</command></title>

	<para>An alternative cryptographic GEOM class is available
	through &man.geli.8;. <command>geli</command> differs from
	<command>gbde</command>; offers different features, and uses
	a different scheme for doing cryptographic work.</para>

	<para>&man.geli.8; provides the following features:</para>

	<itemizedlist>
	<listitem>
	<para>Utilizes the &man.crypto.9; framework and, when
	cryptographic hardware is available,
	<command>geli</command> uses it automatically.</para>
	</listitem>

	<listitem>
	<para>Supports multiple cryptographic algorithms such as
	AES, Blowfish, and 3DES.</para>
	</listitem>

	<listitem>
	<para>Allows the root partition to be encrypted. The
	passphrase used to access the encrypted root partition
	will be requested during system boot.</para>
	</listitem>

	<listitem>
	<para>Allows the use of two independent keys such as a
	<quote>key</quote> and a
	<quote>company key</quote>.</para>
	</listitem>

	<listitem>
	<para><command>geli</command> is fast as it performs simple
	sector-to-sector encryption.</para>
	</listitem>

	<listitem>
	<para>Allows backup and restore of master keys. If a user
	destroys their keys, it is still possible to get access
	to the data by restoring keys from the backup.</para>
	</listitem>

	<listitem>
	<para>Allows a disk to attach with a random, one-time key
	which is useful for swap partitions and temporary file
	systems.</para>
	</listitem>
	</itemizedlist>

	<para>More <command>geli</command> features can be found in
	&man.geli.8;.</para>

	<para>This section describes how to enable support for
	<command>geli</command> in the &os; kernel and explains how
	to create and use a <command>geli</command> encryption
	provider.</para>

	<para>Superuser privileges are required since modifications
	to the kernel are necessary.</para>

	<procedure>
	<step>
	<title>Adding <command>geli</command> Support to the
	Kernel</title>

	<para>For a custom kernel, ensure the kernel configuration
	file contains these lines:</para>

	<programlisting>options GEOM_ELI
	device crypto</programlisting>

	<para>Alternatively, the <command>geli</command> module can
	be loaded at boot time by adding the following line to
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>geom_eli_load="YES"</programlisting>

	<para>&man.geli.8; should now be supported by the
	kernel.</para>
	</step>

	<step>
	<title>Generating the Master Key</title>

	<para>The following example describes how to generate a
	key file which will be used as part of the master key for
	the encrypted provider mounted under
	<filename class="directory">/private</filename>. The key
	file will provide some random data used to encrypt the
	master key. The master key will also be protected by a
	passphrase. The provider's sector size will be 4kB.
	The example will describe how to attach to the
	<command>geli</command> provider, create a file system on
	it, mount it, work with it, and finally, how to detach
	it.</para>

	<para>It is recommended to use a bigger sector size, such as
	4kB, for better performance.</para>

	<para>The master key will be protected with a passphrase and
	the data source for the key file will be
	<devicename>/dev/random</devicename>. The sector size of
	the provider <devicename>/dev/da2.eli</devicename> will be
	4kB.</para>

	<screen>&prompt.root; <userinput>dd if=/dev/random of=/root/da2.key bs=64 count=1</userinput>
	&prompt.root; <userinput>geli init -s 4096 -K /root/da2.key /dev/da2</userinput>
	Enter new passphrase:
	Reenter new passphrase:</screen>

	<para>It is not mandatory to use both a passphrase and a key
	file as either method of securing the master key can be
	used in isolation.</para>

	<para>If the key file is given as <quote>-</quote>, standard
	input will be used. This example shows how more than one
	key file can be used:</para>

	<screen>&prompt.root; <userinput>cat keyfile1 keyfile2 keyfile3 \| geli init -K - /dev/da2</userinput></screen>
	</step>

	<step>
	<title>Attaching the Provider with the Generated Key</title>

	<screen>&prompt.root; <userinput>geli attach -k /root/da2.key /dev/da2</userinput>
	Enter passphrase:</screen>

	<para>The new plaintext device will be named
	<filename>/dev/<replaceable>da2</replaceable>.eli</filename>.</para>

	<screen>&prompt.root; <userinput>ls /dev/da2*</userinput>
	/dev/da2 /dev/da2.eli</screen>
	</step>

	<step>
	<title>Creating the New File System</title>

	<screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/da2.eli bs=1m</userinput>
	&prompt.root; <userinput>newfs /dev/da2.eli</userinput>
	&prompt.root; <userinput>mount /dev/da2.eli /private</userinput></screen>

	<para>The encrypted file system should now be visible to
	&man.df.1; and be available for use:</para>

	<screen>&prompt.root; <userinput>df -H</userinput>
	Filesystem Size Used Avail Capacity Mounted on
	/dev/ad0s1a 248M 89M 139M 38% /
	/devfs 1.0K 1.0K 0B 100% /dev
	/dev/ad0s1f 7.7G 2.3G 4.9G 32% /usr
	/dev/ad0s1d 989M 1.5M 909M 0% /tmp
	/dev/ad0s1e 3.9G 1.3G 2.3G 35% /var
	/dev/da2.eli 150G 4.1K 138G 0% /private</screen>
	</step>

	<step>
	<title>Unmounting and Detaching the Provider</title>

	<para>Once the work on the encrypted partition is done, and
	the <filename class="directory">/private</filename>
	partition is no longer needed, it is prudent to consider
	unmounting and detaching the <command>geli</command>
	encrypted partition from the kernel:</para>

	<screen>&prompt.root; <userinput>umount /private</userinput>
	&prompt.root; <userinput>geli detach da2.eli</userinput></screen>
	</step>
	</procedure>

	<para>More information about the use of &man.geli.8; can be
	found in its manual page.</para>

	<sect3>
	<title>Using the <filename>geli</filename>
	<filename>rc.d</filename> Script</title>

	<para><command>geli</command> comes with a
	<filename>rc.d</filename> script which can be used to
	simplify the usage of <command>geli</command>. An example
	of configuring <command>geli</command> through
	&man.rc.conf.5; follows:</para>

	<programlisting>geli_devices="da2"
	geli_da2_flags="-p -k /root/da2.key"</programlisting>

	<para>This configures <devicename>/dev/da2</devicename> as a
	<command>geli</command> provider of which the master key
	file is located in <filename>/root/da2.key</filename>.
	<command>geli</command> will not use a passphrase when
	attaching to the provider if
	<option>-P</option> was given during the
	<literal>geli init</literal> phase. The system will detach
	the <command>geli</command> provider from the kernel before
	the system shuts down.</para>

	<para>More information about configuring
	<filename>rc.d</filename> is provided in the
	<link linkend="configtuning-rcd">rc.d</link> section of the
	Handbook.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="swap-encrypting">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Christian</firstname>
	<surname>Brüffer</surname>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>Encrypting Swap Space</title>

	<indexterm>
	<primary>swap</primary>
	<secondary>encrypting</secondary>
	</indexterm>

	<para>Swap encryption in &os; is easy to configure. Depending on
	which version of &os; is being used, different options are
	available and configuration can vary slightly. The &man.gbde.8;
	or &man.geli.8; encryption systems can be used for swap
	encryption. Both systems use the <filename>encswap</filename>
	<link linkend="configtuning-rcd">rc.d</link> script.</para>

	<sect2>
	<title>Why Should Swap be Encrypted?</title>

	<para>Like the encryption of disk partitions, encryption of swap
	space is used to protect sensitive information. Consider an
	application that deals with passwords. As long as these
	passwords stay in physical memory, all is well. However, if
	the operating system starts swapping out memory pages to free
	space for other applications, the passwords may be written to
	the disk platters unencrypted. Encrypting swap space can be a
	solution for this scenario.</para>
	</sect2>

	<sect2>
	<title>Preparation</title>

	<note>
	<para>For the remainder of this section,
	<devicename>ad0s1b</devicename> will be the swap
	partition.</para>
	</note>

	<para>By default, swap is unencrypted. It is possible that it
	contains passwords or other sensitive data in cleartext. To
	rectify this, the data on the swap partition should be
	overwritten with random garbage:</para>

	<screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/ad0s1b bs=1m</userinput></screen>
	</sect2>

	<sect2>
	<title>Swap Encryption with &man.gbde.8;</title>

	<para>The <literal>.bde</literal> suffix should be added to the
	device in the respective <filename>/etc/fstab</filename> swap
	line:</para>

	<programlisting># Device Mountpoint FStype Options Dump Pass#
	/dev/ad0s1b.bde none swap sw 0 0</programlisting>
	</sect2>

	<sect2>
	<title>Swap Encryption with &man.geli.8;</title>

	<para>The procedure for instead using &man.geli.8; for swap
	encryption is similar to that of using &man.gbde.8;. The
	<literal>.eli</literal> suffix should be added to the device
	in the respective <filename>/etc/fstab</filename> swap
	line:</para>

	<programlisting># Device Mountpoint FStype Options Dump Pass#
	/dev/ad0s1b.eli none swap sw 0 0</programlisting>

	<para>&man.geli.8; uses the <acronym>AES</acronym> algorithm
	with a key length of 128 bit by default. These defaults can
	be altered by using <literal>geli_swap_flags</literal> in
	<filename>/etc/rc.conf</filename>. The following line tells
	the <filename>encswap</filename> rc.d script to create
	&man.geli.8; swap partitions using the Blowfish algorithm with
	a key length of 128 bits and a sectorsize of 4 kilobytes, and
	sets <quote>detach on last close</quote>:</para>

	<programlisting>geli_swap_flags="-e blowfish -l 128 -s 4096 -d"</programlisting>

	<para>Refer to the description of
	<command>onetime</command> in &man.geli.8; for a list of
	possible options.</para>
	</sect2>

	<sect2>
	<title>Verifying That it Works</title>

	<para>Once the system has rebooted, proper operation of the
	encrypted swap can be verified using
	<command>swapinfo</command>.</para>

	<para>If &man.gbde.8; is being used:</para>

	<screen>&prompt.user; <userinput>swapinfo</userinput>
	Device 1K-blocks Used Avail Capacity
	/dev/ad0s1b.bde 542720 0 542720 0%</screen>

	<para>If &man.geli.8; is being used:</para>

	<screen>&prompt.user; <userinput>swapinfo</userinput>
	Device 1K-blocks Used Avail Capacity
	/dev/ad0s1b.eli 542720 0 542720 0%</screen>
	</sect2>
	</sect1>

	<sect1 id="disks-hast">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Daniel</firstname>
	<surname>Gerzo</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Freddie</firstname>
	<surname>Cash</surname>
	<contrib>With inputs from </contrib>
	</author>
	<author>
	<firstname>Pawel Jakub</firstname>
	<surname>Dawidek</surname>
	</author>
	<author>
	<firstname>Michael W.</firstname>
	<surname>Lucas</surname>
	</author>
	<author>
	<firstname>Viktor</firstname>
	<surname>Petersson</surname>
	</author>
	</authorgroup>
	<!-- Date of writing: 26 February 2011 -->
	</sect1info>

	<title>Highly Available Storage (HAST)</title>

	<indexterm>
	<primary>HAST</primary>
	<secondary>high availability</secondary>
	</indexterm>

	<sect2>
	<title>Synopsis</title>

	<para>High availability is one of the main requirements in
	serious business applications and highly-available storage is
	a key component in such environments. Highly Available
	STorage, or <acronym>HAST<remark role="acronym">Highly
	Available STorage</remark></acronym>, was developed by
	&a.pjd.email; as a framework which allows transparent storage of the
	same data across several physically separated machines
	connected by a TCP/IP network. <acronym>HAST</acronym> can be
	understood as a network-based RAID1 (mirror), and is similar
	to the DRBD® storage system known from the GNU/&linux;
	platform. In combination with other high-availability
	features of &os; like <acronym>CARP</acronym>,
	<acronym>HAST</acronym> makes it possible to build a
	highly-available storage cluster that is resistant to hardware
	failures.</para>

	<para>After reading this section, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>What <acronym>HAST</acronym> is, how it works and
	which features it provides.</para>
	</listitem>

	<listitem>
	<para>How to set up and use <acronym>HAST</acronym> on
	&os;.</para>
	</listitem>

	<listitem>
	<para>How to integrate <acronym>CARP</acronym> and
	&man.devd.8; to build a robust storage system.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this section, you should:</para>

	<itemizedlist>
	<listitem>
	<para>Understand &unix; and <link
	linkend="basics">&os; basics</link>.</para>
	</listitem>

	<listitem>
	<para>Know how to <link
	linkend="config-tuning">configure</link> network
	interfaces and other core &os; subsystems.</para>
	</listitem>

	<listitem>
	<para>Have a good understanding of <link
	linkend="network-communication">&os;
	networking</link>.</para>
	</listitem>
	-
	- <listitem>
	- <para>Use &os; 8.1-RELEASE or newer.</para>
	- </listitem>
	</itemizedlist>

	<para>The <acronym>HAST</acronym> project was sponsored by The
	&os; Foundation with support from <ulink
	url="http://www.omc.net/">OMCnet Internet Service
	GmbH</ulink> and <ulink url="http://www.transip.nl/">TransIP
	BV</ulink>.</para>
	</sect2>

	<sect2>
	<title>HAST Features</title>

	<para>The main features of the <acronym>HAST</acronym> system
	are:</para>

	<itemizedlist>
	<listitem>
	<para>Can be used to mask I/O errors on local hard
	drives.</para>
	</listitem>

	<listitem>
	<para>File system agnostic as it works with any file
	system supported by &os;.</para>
	</listitem>

	<listitem>
	<para>Efficient and quick resynchronization, synchronizing
	only blocks that were modified during the downtime of a
	node.</para>
	</listitem>

	<!--
	<listitem>
	<para>Has several synchronization modes to allow for fast
	failover.</para>
	</listitem>
	-->

	<listitem>
	<para>Can be used in an already deployed environment to add
	additional redundancy.</para>
	</listitem>

	<listitem>
	<para>Together with <acronym>CARP</acronym>,
	<application>Heartbeat</application>, or other tools, it
	can be used to build a robust and durable storage
	system.</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2>
	<title>HAST Operation</title>

	<para>As <acronym>HAST</acronym> provides a synchronous
	block-level replication of any storage media to several
	machines, it requires at least two physical machines:
	the <literal>primary</literal>, also known as the
	<literal>master</literal> node, and the
	<literal>secondary</literal> or <literal>slave</literal>
	node. These two machines together are referred to as a
	cluster.</para>

	<note>
	<para>HAST is currently limited to two cluster nodes in
	total.</para>
	</note>

	<para>Since <acronym>HAST</acronym> works in a
	primary-secondary configuration, it allows only one of the
	cluster nodes to be active at any given time. The
	<literal>primary</literal> node, also called
	<literal>active</literal>, is the one which will handle all
	the I/O requests to <acronym>HAST</acronym>-managed
	devices. The <literal>secondary</literal> node is
	automatically synchronized from the <literal>primary</literal>
	node.</para>

	<para>The physical components of the <acronym>HAST</acronym>
	system are:</para>

	<itemizedlist>
	<listitem>
	<para>local disk on primary node, and</para>
	</listitem>

	<listitem>
	<para>disk on remote, secondary node.</para>
	</listitem>
	</itemizedlist>

	<para><acronym>HAST</acronym> operates synchronously on a block
	level, making it transparent to file systems and applications.
	<acronym>HAST</acronym> provides regular GEOM providers in
	<filename class="directory">/dev/hast/</filename> for use by
	other tools or applications, thus there is no difference
	between using <acronym>HAST</acronym>-provided devices and
	raw disks or partitions.</para>

	<para>Each write, delete, or flush operation is sent to the
	local disk and to the remote disk over TCP/IP. Each read
	operation is served from the local disk, unless the local disk
	is not up-to-date or an I/O error occurs. In such case, the
	read operation is sent to the secondary node.</para>

	<sect3>
	<title>Synchronization and Replication Modes</title>

	<para><acronym>HAST</acronym> tries to provide fast failure
	recovery. For this reason, it is very important to reduce
	synchronization time after a node's outage. To provide fast
	synchronization, <acronym>HAST</acronym> manages an on-disk
	bitmap of dirty extents and only synchronizes those during a
	regular synchronization, with an exception of the initial
	sync.</para>

	<para>There are many ways to handle synchronization.
	<acronym>HAST</acronym> implements several replication modes
	to handle different synchronization methods:</para>

	<itemizedlist>
	<listitem>
	<para><emphasis>memsync</emphasis>: report write operation
	as completed when the local write operation is finished
	and when the remote node acknowledges data arrival, but
	before actually storing the data. The data on the
	remote node will be stored directly after sending the
	acknowledgement. This mode is intended to reduce
	- latency, but still provides very good reliability. The
	- <emphasis>memsync</emphasis> replication mode is
	- currently not implemented.</para>
	+ latency, but still provides very good reliability.</para>
	</listitem>

	<listitem>
	<para><emphasis>fullsync</emphasis>: report write
	operation as completed when local write completes and
	when remote write completes. This is the safest and the
	slowest replication mode. This mode is the
	default.</para>
	</listitem>

	<listitem>
	<para><emphasis>async</emphasis>: report write operation
	as completed when local write completes. This is the
	fastest and the most dangerous replication mode. It
	should be used when replicating to a distant node where
	- latency is too high for other modes. The
	- <emphasis>async</emphasis> replication mode is currently
	- not implemented.</para>
	+ latency is too high for other modes.</para>
	</listitem>
	</itemizedlist>
	-
	- <warning>
	- <para>Only the <emphasis>fullsync</emphasis> replication
	- mode is currently supported.</para>
	- </warning>
	</sect3>
	</sect2>

	<sect2>
	<title>HAST Configuration</title>

	<para><acronym>HAST</acronym> requires
	<literal>GEOM_GATE</literal> support which is not present in
	the default <literal>GENERIC</literal> kernel. However, the
	<varname>geom_gate.ko</varname> loadable module is available
	in the default &os; installation. Alternatively, to build
	<literal>GEOM_GATE</literal> support into the kernel
	statically, add this line to the custom kernel configuration
	file:</para>

	<programlisting>options GEOM_GATE</programlisting>

	<para>The <acronym>HAST</acronym> framework consists of several
	parts from the operating system's point of view:</para>

	<itemizedlist>
	<listitem>
	<para>the &man.hastd.8; daemon responsible for data
	synchronization,</para>
	</listitem>

	<listitem>
	<para>the &man.hastctl.8; userland management
	utility,</para>
	</listitem>

	<listitem>
	<para>and the &man.hast.conf.5; configuration file.</para>
	</listitem>
	</itemizedlist>

	<para>The following example describes how to configure two nodes
	in <literal>master</literal>-<literal>slave</literal> /
	<literal>primary</literal>-<literal>secondary</literal>
	operation using <acronym>HAST</acronym> to replicate the data
	between the two. The nodes will be called
	<literal><replaceable>hasta</replaceable></literal> with an IP
	address of <replaceable>172.16.0.1</replaceable> and
	<literal><replaceable>hastb</replaceable></literal> with an IP
	of address <replaceable>172.16.0.2</replaceable>. Both nodes
	will have a dedicated hard drive
	<devicename>/dev/<replaceable>ad6</replaceable></devicename>
	of the same size for <acronym>HAST</acronym> operation. The
	<acronym>HAST</acronym> pool, sometimes also referred to as a
	resource or the GEOM provider in <filename
	class="directory">/dev/hast/</filename>, will be
	called
	<filename><replaceable>test</replaceable></filename>.</para>

	<para>Configuration of <acronym>HAST</acronym> is done using
	<filename>/etc/hast.conf</filename>. This file should be the
	same on both nodes. The simplest configuration possible
	is:</para>

	<programlisting>resource test {
	on hasta {
	local /dev/ad6
	remote 172.16.0.2
	}
	on hastb {
	local /dev/ad6
	remote 172.16.0.1
	}
	}</programlisting>

	<para>For more advanced configuration, refer to
	&man.hast.conf.5;.</para>

	<tip>
	<para>It is also possible to use host names in the
	<literal>remote</literal> statements. In such a case, make
	sure that these hosts are resolvable and are defined in
	<filename>/etc/hosts</filename> or in the local
	<acronym>DNS</acronym>.</para>
	</tip>

	<para>Now that the configuration exists on both nodes,
	the <acronym>HAST</acronym> pool can be created. Run these
	commands on both nodes to place the initial metadata onto the
	local disk and to start &man.hastd.8;:</para>

	<screen>&prompt.root; <userinput>hastctl create test</userinput>
	&prompt.root; <userinput>service hastd onestart</userinput></screen>

	<note>
	<para>It is <emphasis>not</emphasis> possible to use GEOM
	providers with an existing file system or to convert an
	existing storage to a <acronym>HAST</acronym>-managed pool.
	This procedure needs to store some metadata on the provider
	and there will not be enough required space
	available on an existing provider.</para>
	</note>

	<para>A HAST node's <literal>primary</literal> or
	<literal>secondary</literal> role is selected by an
	administrator, or software like
	<application>Heartbeat</application>, using &man.hastctl.8;.
	On the primary node,
	<literal><replaceable>hasta</replaceable></literal>, issue
	this command:</para>

	<screen>&prompt.root; <userinput>hastctl role primary test</userinput></screen>

	<para>Similarly, run this command on the secondary node,
	<literal><replaceable>hastb</replaceable></literal>:</para>

	<screen>&prompt.root; <userinput>hastctl role secondary test</userinput></screen>

	<caution>
	<para>When the nodes are unable to communicate with each
	other, and both are configured as primary nodes, the
	condition is called <literal>split-brain</literal>. To
	troubleshoot this situation, follow the steps described in
	<link linkend="disks-hast-sb"></link>.</para>
	</caution>

	<para>Verify the result by running &man.hastctl.8; on each
	node:</para>

	<screen>&prompt.root; <userinput>hastctl status test</userinput></screen>

	<para>The important text is the <literal>status</literal> line,
	which should say <literal>complete</literal>
	on each of the nodes. If it says <literal>degraded</literal>,
	something went wrong. At this point, the synchronization
	between the nodes has already started. The synchronization
	completes when <command>hastctl status</command>
	reports 0 bytes of <literal>dirty</literal> extents.</para>


	<para>The next step is to create a filesystem on the
	<devicename>/dev/hast/<replaceable>test</replaceable></devicename>
	GEOM provider and mount it. This must be done on the
	<literal>primary</literal> node, as
	<filename>/dev/hast/<replaceable>test</replaceable></filename>
	appears only on the <literal>primary</literal> node. Creating
	the filesystem can take a few minutes, depending on the size
	of the hard drive:</para>

	<screen>&prompt.root; <userinput>newfs -U /dev/hast/test</userinput>
	&prompt.root; <userinput>mkdir /hast/test</userinput>
	&prompt.root; <userinput>mount /dev/hast/test /hast/test</userinput></screen>

	<para>Once the <acronym>HAST</acronym> framework is configured
	properly, the final step is to make sure that
	<acronym>HAST</acronym> is started automatically during
	system boot. Add this line to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>hastd_enable="YES"</programlisting>

	<sect3>
	<title>Failover Configuration</title>

	<para>The goal of this example is to build a robust storage
	system which is resistant to the failure of any given node.
	The scenario is that a <literal>primary</literal> node of
	the cluster fails. If this happens, the
	<literal>secondary</literal> node is there to take over
	seamlessly, check and mount the file system, and continue to
	work without missing a single bit of data.</para>

	<para>To accomplish this task, another &os; feature,
	<acronym>CARP</acronym>, provides for automatic failover on
	the IP layer. <acronym>CARP</acronym> (Common
	Address Redundancy Protocol) allows multiple hosts on the
	same network segment to share an IP address. Set up
	<acronym>CARP</acronym> on both nodes of the cluster
	according to the documentation available in
	<link linkend="carp"></link>. After setup, each node will
	have its own <devicename>carp0</devicename> interface with a
	shared IP address of
	<replaceable>172.16.0.254</replaceable>. The primary
	<acronym>HAST</acronym> node of the cluster must be the
	master <acronym>CARP</acronym> node.</para>

	<para>The <acronym>HAST</acronym> pool created in the previous
	section is now ready to be exported to the other hosts on
	the network. This can be accomplished by exporting it
	through <acronym>NFS</acronym> or
	<application>Samba</application>, using the shared IP
	address <replaceable>172.16.0.254</replaceable>. The only
	problem which remains unresolved is an automatic failover
	should the primary node fail.</para>

	<para>In the event of <acronym>CARP</acronym> interfaces going
	up or down, the &os; operating system generates a
	&man.devd.8; event, making it possible to watch for state
	changes on the <acronym>CARP</acronym> interfaces. A state
	change on the <acronym>CARP</acronym> interface is an
	indication that one of the nodes failed or came back online.
	These state change events make it possible to run a script
	which will automatically handle the HAST failover.</para>

	<para>To be able to catch state changes on the
	<acronym>CARP</acronym> interfaces, add this
	configuration to
	<filename>/etc/devd.conf</filename> on each node:</para>

	<programlisting>notify 30 {
	match "system" "IFNET";
	match "subsystem" "carp0";
	match "type" "LINK_UP";
	action "/usr/local/sbin/carp-hast-switch master";
	};

	notify 30 {
	match "system" "IFNET";
	match "subsystem" "carp0";
	match "type" "LINK_DOWN";
	action "/usr/local/sbin/carp-hast-switch slave";
	};</programlisting>

	<para>Restart &man.devd.8; on both nodes to put the new
	configuration into effect:</para>

	<screen>&prompt.root; <userinput>service devd restart</userinput></screen>

	<para>When the <devicename>carp0</devicename> interface state
	changes by going up or down , the system generates a
	notification, allowing the &man.devd.8; subsystem to run an
	arbitrary script, in this case
	<filename>/usr/local/sbin/carp-hast-switch</filename>. This
	script handles the automatic failover. For further
	clarification about the above &man.devd.8; configuration,
	refer to &man.devd.conf.5;.</para>

	<para>An example of such a script could be:</para>

	<programlisting>#!/bin/sh

	# Original script by Freddie Cash <fjwcash@gmail.com>
	# Modified by Michael W. Lucas <mwlucas@BlackHelicopters.org>
	# and Viktor Petersson <vpetersson@wireload.net>

	# The names of the HAST resources, as listed in /etc/hast.conf
	resources="test"

	# delay in mounting HAST resource after becoming master
	# make your best guess
	delay=3

	# logging
	log="local0.debug"
	name="carp-hast"

	# end of user configurable stuff

	case "$1" in
	master)
	logger -p $log -t $name "Switching to primary provider for ${resources}."
	sleep ${delay}

	# Wait for any "hastd secondary" processes to stop
	for disk in ${resources}; do
	while $( pgrep -lf "hastd: ${disk} $secondary$" > /dev/null 2>&1 ); do
	sleep 1
	done

	# Switch role for each disk
	hastctl role primary ${disk}
	if [ $? -ne 0 ]; then
	logger -p $log -t $name "Unable to change role to primary for resource ${disk}."
	exit 1
	fi
	done

	# Wait for the /dev/hast/* devices to appear
	for disk in ${resources}; do
	for I in $( jot 60 ); do
	[ -c "/dev/hast/${disk}" ] && break
	sleep 0.5
	done

	if [ ! -c "/dev/hast/${disk}" ]; then
	logger -p $log -t $name "GEOM provider /dev/hast/${disk} did not appear."
	exit 1
	fi
	done

	logger -p $log -t $name "Role for HAST resources ${resources} switched to primary."


	logger -p $log -t $name "Mounting disks."
	for disk in ${resources}; do
	mkdir -p /hast/${disk}
	fsck -p -y -t ufs /dev/hast/${disk}
	mount /dev/hast/${disk} /hast/${disk}
	done

	;;

	slave)
	logger -p $log -t $name "Switching to secondary provider for ${resources}."

	# Switch roles for the HAST resources
	for disk in ${resources}; do
	if ! mount \| grep -q "^/dev/hast/${disk} on "
	then
	else
	umount -f /hast/${disk}
	fi
	sleep $delay
	hastctl role secondary ${disk} 2>&1
	if [ $? -ne 0 ]; then
	logger -p $log -t $name "Unable to switch role to secondary for resource ${disk}."
	exit 1
	fi
	logger -p $log -t $name "Role switched to secondary for resource ${disk}."
	done
	;;
	esac</programlisting>

	<para>In a nutshell, the script takes these actions when a
	node becomes <literal>master</literal> /
	<literal>primary</literal>:</para>

	<itemizedlist>
	<listitem>
	<para>Promotes the <acronym>HAST</acronym> pools to
	primary on a given node.</para>
	</listitem>

	<listitem>
	<para>Checks the file system under the
	<acronym>HAST</acronym> pool.</para>
	</listitem>

	<listitem>
	<para>Mounts the pools at an appropriate place.</para>
	</listitem>
	</itemizedlist>

	<para>When a node becomes <literal>backup</literal> /
	<literal>secondary</literal>:</para>

	<itemizedlist>
	<listitem>
	<para>Unmounts the <acronym>HAST</acronym> pools.</para>
	</listitem>

	<listitem>
	<para>Degrades the <acronym>HAST</acronym> pools to
	secondary.</para>
	</listitem>
	</itemizedlist>

	<caution>
	<para>Keep in mind that this is just an example script which
	serves as a proof of concept. It does not handle all the
	possible scenarios and can be extended or altered in any
	way, for example, to start/stop required services.</para>
	</caution>

	<tip>
	<para>For this example, a standard UFS file system was used.
	To reduce the time needed for recovery, a journal-enabled
	UFS or ZFS file system can be used instead.</para>
	</tip>

	<para>More detailed information with additional examples can
	be found in the
	<ulink url="http://wiki.FreeBSD.org/HAST">HAST Wiki</ulink>
	page.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Troubleshooting</title>

	<sect3>
	<title>General Troubleshooting Tips</title>

	<para><acronym>HAST</acronym> should generally work without
	issues. However, as with any other software product, there
	may be times when it does not work as supposed. The sources
	of the problems may be different, but the rule of thumb is
	to ensure that the time is synchronized between all nodes of
	the cluster.</para>

	<para>When troubleshooting <acronym>HAST</acronym> problems,
	the debugging level of &man.hastd.8; should be increased by
	starting &man.hastd.8; with <literal>-d</literal>. This
	argument may be specified multiple times to further increase
	the debugging level. A lot of useful information may be
	obtained this way. Consider also using
	<literal>-F</literal>, which starts &man.hastd.8; in the
	foreground.</para>
	</sect3>

	<sect3 id="disks-hast-sb">
	<title>Recovering from the Split-brain Condition</title>

	<para><literal>Split-brain</literal> is when the nodes of the
	cluster are unable to communicate with each other, and both
	are configured as primary. This is a dangerous condition
	because it allows both nodes to make incompatible changes to
	the data. This problem must be corrected manually by the
	system administrator.</para>

	<para>The administrator must decide which node has more
	important changes (or merge them manually) and let
	<acronym>HAST</acronym> perform full synchronization of the
	node which has the broken data. To do this, issue these
	commands on the node which needs to be
	resynchronized:</para>

	<screen>&prompt.root; <userinput>hastctl role init <resource></userinput>
	&prompt.root; <userinput>hastctl create <resource></userinput>
	&prompt.root; <userinput>hastctl role secondary <resource></userinput></screen>
	</sect3>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/eresources/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/eresources/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/eresources/chapter.xml (revision 41355)
	@@ -1,2271 +1,2247 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<appendix id="eresources">
	<title>Resources on the Internet</title>

	<para>The rapid pace of FreeBSD progress makes print media
	impractical as a means of following the latest developments.
	Electronic resources are the best, if not often the only, way
	to stay informed of the latest advances. Since FreeBSD is a
	volunteer effort, the user community itself also generally serves
	as a <quote>technical support department</quote> of sorts, with
	electronic mail, web forums, and USENET news being the most
	effective way of reaching that community.</para>

	<para>The most important points of contact with the FreeBSD user
	community are outlined below. If you are aware of other resources
	not mentioned here, please send them to the &a.doc; so that they
	may also be included.</para>

	<sect1 id="eresources-mail">
	<title>Mailing Lists</title>

	<para>The mailing lists are the most direct way of addressing
	questions or opening a technical discussion to a concentrated
	FreeBSD audience. There are a wide variety of lists on a number
	of different FreeBSD topics. Addressing your questions to the
	most appropriate mailing list will invariably assure a faster
	and more accurate response.</para>

	<para>The charters for the various lists are given at the bottom
	of this document. <emphasis>Please read the charter before
	joining or sending mail to any list</emphasis>. Most of our
	list subscribers now receive many hundreds of FreeBSD related
	messages every day, and by setting down charters and rules for
	proper use we are striving to keep the signal-to-noise ratio
	of the lists high. To do less would see the mailing lists
	ultimately fail as an effective communications medium for the
	project.</para>

	<note>
	<para><emphasis>If you wish to test your ability to send to
	&os; lists, send a test message to &a.test.name;.</emphasis>
	Please do not send test messages to any other list.</para>
	</note>

	<para>When in doubt about what list to post a question to, see
	<ulink url="&url.articles.freebsd-questions;">How to get best
	results from the FreeBSD-questions mailing
	list</ulink>.</para>

	<para>Before posting to any list, please learn about how to
	best use the mailing lists, such as how to help avoid
	frequently-repeated discussions, by reading the <ulink
	url="&url.articles.mailing-list-faq;"> Mailing List Frequently
	Asked Questions</ulink> (FAQ) document.</para>

	<para>Archives are kept for all of the mailing lists and can be
	searched using the <ulink
	url="&url.base;/search/index.html">FreeBSD World Wide Web
	server</ulink>. The keyword searchable archive offers an
	excellent way of finding answers to frequently asked questions
	and should be consulted before posting a question. Note that
	this also means that messages sent to FreeBSD mailing lists
	are archived in perpetuity. When protecting privacy is a
	concern, consider using a disposable secondary email address
	and posting only public information.</para>

	<sect2 id="eresources-summary">
	<title>List Summary</title>

	<para><emphasis>General lists:</emphasis> The following are
	general lists which anyone is free (and encouraged) to
	join:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>List</entry>
	<entry>Purpose</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>&a.advocacy.name;</entry>
	<entry>FreeBSD Evangelism</entry>
	</row>

	<row>
	<entry>&a.announce.name;</entry>
	- <entry>Important events and project milestones</entry>
	+ <entry>Important events and project milestones (moderated)</entry>
	</row>

	<row>
	<entry>&a.arch.name;</entry>
	<entry>Architecture and design discussions</entry>
	</row>

	<row>
	<entry>&a.bugbusters.name;</entry>
	<entry>Discussions pertaining to the maintenance of
	the FreeBSD problem report database and related
	tools</entry>
	</row>

	<row>
	<entry>&a.bugs.name;</entry>
	<entry>Bug reports</entry>
	</row>

	<row>
	<entry>&a.chat.name;</entry>
	<entry>Non-technical items related to the FreeBSD
	community</entry>
	</row>

	<row>
	<entry>&a.chromium.name;</entry>
	<entry>FreeBSD-specific Chromium issues</entry>
	</row>

	<row>
	<entry>&a.current.name;</entry>
	<entry>Discussion concerning the use of
	&os.current;</entry>
	</row>

	<row>
	<entry>&a.isp.name;</entry>
	<entry>Issues for Internet Service Providers using
	FreeBSD</entry>
	</row>

	<row>
	<entry>&a.jobs.name;</entry>
	<entry>FreeBSD employment and consulting
	opportunities</entry>
	</row>

	<row>
	<entry>&a.questions.name;</entry>
	<entry>User questions and technical support</entry>
	</row>

	<row>
	<entry>&a.security-notifications.name;</entry>
	- <entry>Security notifications</entry>
	+ <entry>Security notifications (moderated)</entry>
	</row>

	<row>
	<entry>&a.stable.name;</entry>
	<entry>Discussion concerning the use of
	&os.stable;</entry>
	</row>

	<row>
	<entry>&a.test.name;</entry>
	<entry>Where to send your test messages instead of
	one of the actual lists</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para><emphasis>Technical lists:</emphasis> The following
	lists are for technical discussion. You should read the
	charter for each list carefully before joining or sending
	mail to one as there are firm guidelines for their use and
	content.</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>List</entry>
	<entry>Purpose</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>&a.acpi.name;</entry>
	<entry>ACPI and power management development</entry>
	</row>

	<row>
	<entry>&a.afs.name;</entry>
	<entry>Porting AFS to FreeBSD</entry>
	</row>

	<row>
	<entry>&a.aic7xxx.name;</entry>
	<entry>Developing drivers for the &adaptec;
	AIC 7xxx</entry>
	</row>

	<row>
	<entry>&a.amd64.name;</entry>
	- <entry>Porting FreeBSD to AMD64 systems</entry>
	+ <entry>Porting FreeBSD to AMD64 systems (moderated)</entry>
	</row>

	<row>
	<entry>&a.apache.name;</entry>
	<entry>Discussion about
	<application>Apache</application> related
	ports</entry>
	</row>

	<row>
	<entry>&a.arm.name;</entry>
	<entry>Porting FreeBSD to &arm; processors</entry>
	</row>

	<row>
	<entry>&a.atm.name;</entry>
	<entry>Using ATM networking with FreeBSD</entry>
	</row>

	<row>
	<entry>&a.bluetooth.name;</entry>
	<entry>Using &bluetooth; technology in FreeBSD</entry>
	</row>

	<row>
	<entry>&a.cluster.name;</entry>
	<entry>Using FreeBSD in a clustered environment</entry>
	</row>

	<row>
	<entry>&a.cvsweb.name;</entry>
	<entry>CVSweb maintenance</entry>
	</row>

	<row>
	<entry>&a.database.name;</entry>
	<entry>Discussing database use and development under
	FreeBSD</entry>
	</row>

	<row>
	<entry>&a.desktop.name;</entry>
	<entry>Using and improving &os; on the desktop</entry>
	</row>

	<row>
	<entry>&a.doc.name;</entry>
	<entry>Creating FreeBSD related documents</entry>
	</row>

	<row>
	<entry>&a.drivers.name;</entry>
	<entry>Writing device drivers for &os;</entry>
	</row>

	<row>
	<entry>&a.eclipse.name;</entry>
	<entry>FreeBSD users of Eclipse IDE, tools, rich client
	applications and ports.</entry>
	</row>

	<row>
	<entry>&a.embedded.name;</entry>
	<entry>Using FreeBSD in embedded applications</entry>
	</row>

	<row>
	<entry>&a.eol.name;</entry>
	<entry>Peer support of FreeBSD-related software that
	is no longer supported by the FreeBSD project.</entry>
	</row>

	<row>
	<entry>&a.emulation.name;</entry>
	<entry>Emulation of other systems such as
	Linux/&ms-dos;/&windows;</entry>
	</row>

	<row>
	<entry>&a.firewire.name;</entry>
	<entry>FreeBSD &firewire; (iLink, IEEE 1394) technical
	discussion</entry>
	</row>

	<row>
	<entry>&a.fs.name;</entry>
	<entry>File systems</entry>
	</row>

	<row>
	<entry>&a.gecko.name;</entry>
	<entry><application>Gecko Rendering
	Engine</application> issues</entry>
	</row>

	<row>
	<entry>&a.geom.name;</entry>
	<entry>GEOM-specific discussions and
	implementations</entry>
	</row>

	<row>
	<entry>&a.gnome.name;</entry>
	<entry>Porting <application>GNOME</application> and
	<application>GNOME</application> applications</entry>
	</row>

	<row>
	<entry>&a.hackers.name;</entry>
	<entry>General technical discussion</entry>
	</row>

	<row>
	<entry>&a.hardware.name;</entry>
	<entry>General discussion of hardware for running
	FreeBSD</entry>
	</row>

	<row>
	<entry>&a.i18n.name;</entry>
	<entry>FreeBSD Internationalization</entry>
	</row>

	<row>
	<entry>&a.ia32.name;</entry>
	<entry>FreeBSD on the IA-32 (&intel; x86)
	platform</entry>
	</row>

	<row>
	<entry>&a.ia64.name;</entry>
	<entry>Porting FreeBSD to &intel;'s upcoming IA64
	systems</entry>
	</row>

	<row>
	<entry>&a.infiniband.name;</entry>
	<entry>Infiniband on FreeBSD</entry>
	</row>

	<row>
	<entry>&a.ipfw.name;</entry>
	<entry>Technical discussion concerning the redesign
	of the IP firewall code</entry>
	</row>

	<row>
	<entry>&a.isdn.name;</entry>
	<entry>ISDN developers</entry>
	</row>

	<row>
	<entry>&a.jail.name;</entry>
	<entry>Discussion about the &man.jail.8;
	facility</entry>
	</row>

	<row>
	<entry>&a.java.name;</entry>
	<entry>&java; developers and people porting &jdk;s to
	FreeBSD</entry>
	</row>

	<row>
	<entry>&a.kde.name;</entry>
	<entry>Porting <application>KDE</application> and
	<application>KDE</application> applications</entry>
	</row>

	<row>
	<entry>&a.lfs.name;</entry>
	<entry>Porting LFS to FreeBSD</entry>
	</row>

	<row>
	<entry>&a.mips.name;</entry>
	<entry>Porting FreeBSD to &mips;</entry>
	</row>

	<row>
	<entry>&a.mobile.name;</entry>
	<entry>Discussions about mobile computing</entry>
	</row>

	<row>
	<entry>&a.mono.name;</entry>
	<entry>Mono and C# applications on FreeBSD</entry>
	</row>

	<row>
	<entry>&a.mozilla.name;</entry>
	<entry>Porting <application>Mozilla</application> to
	FreeBSD</entry>
	</row>

	<row>
	<entry>&a.multimedia.name;</entry>
	<entry>Multimedia applications</entry>
	</row>

	<row>
	<entry>&a.newbus.name;</entry>
	<entry>Technical discussions about bus
	architecture</entry>
	</row>

	<row>
	<entry>&a.net.name;</entry>
	<entry>Networking discussion and TCP/IP source
	code</entry>
	</row>

	<row>
	<entry>&a.numerics.name;</entry>
	<entry>Discussions of high quality implementation of
	libm functions</entry>
	</row>

	<row>
	<entry>&a.office.name;</entry>
	<entry>Office applications on &os;</entry>
	</row>

	<row>
	<entry>&a.performance.name;</entry>
	<entry>Performance tuning questions for high
	performance/load installations</entry>
	</row>

	<row>
	<entry>&a.perl.name;</entry>
	<entry>Maintenance of a number of
	Perl-related ports</entry>
	</row>

	<row>
	<entry>&a.pf.name;</entry>
	<entry>Discussion and questions about the packet filter
	firewall system</entry>
	</row>

	<row>
	<entry>&a.platforms.name;</entry>
	<entry>Concerning ports to non &intel; architecture
	platforms</entry>
	</row>

	<row>
	<entry>&a.ports.name;</entry>
	<entry>Discussion of the Ports Collection</entry>
	</row>

	<row>
	<entry>&a.ports-announce.name;</entry>
	<entry>Important news and instructions about the Ports
	- Collection</entry>
	+ Collection (moderated)</entry>
	</row>

	<row>
	<entry>&a.ports-bugs.name;</entry>
	<entry>Discussion of the ports bugs/PRs</entry>
	</row>

	<row>
	<entry>&a.ppc.name;</entry>
	<entry>Porting FreeBSD to the &powerpc;</entry>
	</row>

	<row>
	<entry>&a.proliant.name;</entry>
	<entry>Technical discussion of FreeBSD on HP ProLiant
	server platforms</entry>
	</row>

	<row>
	<entry>&a.python.name;</entry>
	<entry>FreeBSD-specific Python issues</entry>
	</row>

	<row>
	<entry>&a.rc.name;</entry>
	<entry>Discussion related to the
	<filename>rc.d</filename> system and its
	development</entry>
	</row>

	<row>
	<entry>&a.realtime.name;</entry>
	<entry>Development of realtime extensions to
	FreeBSD</entry>
	</row>

	<row>
	<entry>&a.ruby.name;</entry>
	<entry>FreeBSD-specific Ruby discussions</entry>
	</row>

	<row>
	<entry>&a.scsi.name;</entry>
	<entry>The SCSI subsystem</entry>
	</row>

	<row>
	<entry>&a.security.name;</entry>
	<entry>Security issues affecting FreeBSD</entry>
	</row>

	<row>
	<entry>&a.small.name;</entry>
	<entry>Using FreeBSD in embedded applications
	(obsolete; use &a.embedded.name; instead)</entry>
	</row>

	<row>
	<entry>&a.snapshots.name;</entry>
	<entry>&os; Development Snapshot Announcements</entry>
	</row>

	<row>
	<entry>&a.sparc.name;</entry>
	<entry>Porting FreeBSD to &sparc; based systems</entry>
	</row>

	<row>
	<entry>&a.standards.name;</entry>
	<entry>FreeBSD's conformance to the C99 and the &posix;
	standards</entry>
	</row>

	<row>
	<entry>&a.sysinstall.name;</entry>
	<entry>&man.sysinstall.8; development</entry>
	</row>

	<row>
	<entry>&a.tcltk.name;</entry>
	<entry>FreeBSD-specific Tcl/Tk discussions</entry>
	</row>

	<row>
	<entry>&a.threads.name;</entry>
	<entry>Threading in FreeBSD</entry>
	</row>

	<row>
	<entry>&a.tilera.name;</entry>
	<entry>Porting FreeBSD to the Tilera family of
	CPUs</entry>
	</row>

	<row>
	<entry>&a.tokenring.name;</entry>
	<entry>Support Token Ring in FreeBSD</entry>
	</row>

	<row>
	<entry>&a.toolchain.name;</entry>
	<entry>Maintenance of &os;'s integrated
	toolchain</entry>
	</row>

	<row>
	<entry>&a.usb.name;</entry>
	<entry>Discussing &os; support for USB</entry>
	</row>

	<row>
	<entry>&a.virtualization.name;</entry>
	<entry>Discussion of various virtualization techniques
	supported by &os;</entry>
	</row>

	<row>
	<entry>&a.vuxml.name;</entry>
	<entry>Discussion on VuXML infrastructure</entry>
	</row>

	<row>
	<entry>&a.x11.name;</entry>
	<entry>Maintenance and support of X11 on FreeBSD</entry>
	</row>

	<row>
	<entry>&a.xen.name;</entry>
	<entry>Discussion of the &os; port to &xen; —
	implementation and usage</entry>
	</row>

	<row>
	<entry>&a.xfce.name;</entry>
	<entry><application>XFCE</application> for &os; —
	porting and maintaining</entry>
	</row>

	<row>
	<entry>&a.zope.name;</entry>
	<entry><application>Zope</application> for &os; —
	porting and maintaining</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para><emphasis>Limited lists:</emphasis> The following lists
	are for more specialized (and demanding) audiences and are
	probably not of interest to the general public. It is also
	a good idea to establish a presence in the technical lists
	before joining one of these limited lists so that you will
	understand the communications etiquette involved.</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>List</entry>
	<entry>Purpose</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>&a.hubs.name;</entry>
	<entry>People running mirror sites (infrastructural
	support)</entry>
	</row>

	<row>
	<entry>&a.usergroups.name;</entry>
	<entry>User group coordination</entry>
	</row>

	<row>
	- <entry>&a.vendors.name;</entry>
	- <entry>Vendors pre-release coordination</entry>
	- </row>
	-
	- <row>
	<entry>&a.wip-status.name;</entry>
	<entry>FreeBSD Work-In-Progress Status</entry>
	</row>

	<row>
	<entry>&a.wireless.name;</entry>
	<entry>Discussions of 802.11 stack, tools, device driver
	development</entry>
	</row>
	-
	- <row>
	- <entry>&a.www.name;</entry>
	- <entry>Maintainers of
	- <ulink
	- url="&url.base;/index.html">www.FreeBSD.org</ulink></entry>
	- </row>
	</tbody>
	</tgroup>
	</informaltable>

	<para><emphasis>Digest lists:</emphasis> All of the above lists
	are available in a digest format. Once subscribed to a list,
	you can change your digest options in your account options
	section.</para>

	<para><emphasis>SVN lists:</emphasis> The following lists
	are for people interested in seeing the log messages for
	changes to various areas of the source tree. They are
	<emphasis>Read-Only</emphasis> lists and should not have
	mail sent to them.</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="3">
	<thead>
	<row>
	<entry>List</entry>
	<entry>Source area</entry>
	<entry>Area Description (source for)</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>&a.svn-doc-all.name;</entry>
	<entry><filename>/usr/doc</filename></entry>
	<entry>All changes to the doc Subversion repository
	(except for <filename>user</filename>,
	<filename>projects</filename>
	and <filename>translations</filename>)</entry>
	</row>

	<row>
	<entry>&a.svn-doc-head.name;</entry>
	<entry><filename>/usr/doc</filename></entry>
	<entry>All changes to the <quote>head</quote> branch of
	the doc Subversion repository</entry>
	</row>

	<row>
	<entry>&a.svn-doc-projects.name;</entry>
	<entry><filename>/usr/doc/projects</filename></entry>
	<entry>All changes to the <filename>projects</filename>
	area of the doc Subversion repository</entry>
	</row>

	<row>
	<entry>&a.svn-doc-svnadmin.name;</entry>
	<entry><filename>/usr/doc</filename></entry>
	<entry>All changes to the administrative scripts, hooks,
	and other configuration data of the doc Subversion
	repository</entry>
	</row>

	<row>
	<entry>&a.svn-ports-all.name;</entry>
	<entry><filename>/usr/ports</filename></entry>
	<entry>All changes to the ports Subversion
	repository</entry>
	</row>

	<row>
	<entry>&a.svn-ports-head.name;</entry>
	<entry><filename>/usr/ports</filename></entry>
	<entry>All changes to the <quote>head</quote> branch
	of the ports Subversion repository</entry>
	</row>

	<row>
	<entry>&a.svn-ports-svnadmin.name;</entry>
	<entry><filename>/usr/ports</filename></entry>
	<entry>All changes to the administrative scripts, hooks,
	and other configuration data of the ports Subversion
	repository</entry>
	</row>

	<row>
	<entry>&a.svn-src-all.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the src Subversion repository
	(except for <filename>user</filename>
	and <filename>projects</filename>)</entry>
	</row>

	<row>
	<entry>&a.svn-src-head.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the <quote>head</quote> branch
	of the src Subversion repository (the &os;-CURRENT
	branch)</entry>
	</row>

	<row>
	<entry>&a.svn-src-projects.name;</entry>
	<entry><filename>/usr/projects</filename></entry>
	<entry>All changes to the <filename>projects</filename>
	area of the src Subversion repository</entry>
	</row>

	<row>
	<entry>&a.svn-src-release.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the <filename>releases</filename>
	area of the src Subversion repository</entry>
	</row>

	<row>
	<entry>&a.svn-src-releng.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the <filename>releng</filename>
	branches of the src Subversion repository (the
	security / release engineering branches)</entry>
	</row>

	<row>
	<entry>&a.svn-src-stable.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the all stable branches of the src
	Subversion repository</entry>
	</row>

	<row>
	<entry>&a.svn-src-stable-6.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the <filename>stable/6</filename>
	branch of the src Subversion repository</entry>
	</row>

	<row>
	<entry>&a.svn-src-stable-7.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the <filename>stable/7</filename>
	branch of the src Subversion repository</entry>
	</row>

	<row>
	<entry>&a.svn-src-stable-8.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the <filename>stable/8</filename>
	branch of the src Subversion repository</entry>
	</row>

	<row>
	<entry>&a.svn-src-stable-9.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the <filename>stable/9</filename>
	branch of the src Subversion repository</entry>
	</row>

	<row>
	<entry>&a.svn-src-stable-other.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the
	older <filename>stable</filename> branches of the src
	Subversion repository</entry>
	</row>

	<row>
	<entry>&a.svn-src-svnadmin.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the administrative scripts, hooks,
	and other configuration data of the src Subversion
	repository</entry>
	</row>

	<row>
	<entry>&a.svn-src-user.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the
	experimental <filename>user</filename> area of the src
	Subversion repository</entry>
	</row>

	<row>
	<entry>&a.svn-src-vendor.name;</entry>
	<entry><filename>/usr/src</filename></entry>
	<entry>All changes to the vendor work area of the src
	Subversion repository</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</sect2>

	<sect2 id="eresources-subscribe">
	<title>How to Subscribe</title>

	<para>To subscribe to a list, click on the list name above or
	go to &a.mailman.lists.link; and click on the list that you
	are interested in. The list page should contain all of the
	necessary subscription instructions.</para>

	<para>To actually post to a given list, send mail to
	<email><replaceable>listname</replaceable>@FreeBSD.org</email>.
	It will then be redistributed to mailing list members
	world-wide.</para>

	<para>To unsubscribe yourself from a list, click on the URL
	found at the bottom of every email received from the list.
	It is also possible to send an email to
	<email><replaceable>listname</replaceable>-unsubscribe@FreeBSD.org</email>
	to unsubscribe yourself.</para>

	<para>Again, we would like to request that you keep discussion
	in the technical mailing lists on a technical track. If you
	are only interested in important announcements then it is
	suggested that you join the &a.announce;, which is intended
	only for infrequent traffic.</para>
	</sect2>

	<sect2 id="eresources-charters">
	<title>List Charters</title>

	<para><emphasis>All</emphasis> FreeBSD mailing lists have
	certain basic rules which must be adhered to by anyone using
	them. Failure to comply with these guidelines will result
	in two (2) written warnings from the FreeBSD Postmaster
	<email>postmaster@FreeBSD.org</email>, after which, on a
	third offense, the poster will removed from all FreeBSD
	mailing lists and filtered from further posting to them. We
	regret that such rules and measures are necessary at all,
	but today's Internet is a pretty harsh environment, it would
	seem, and many fail to appreciate just how fragile some of
	its mechanisms are.</para>

	<para>Rules of the road:</para>

	<itemizedlist>
	<listitem>
	<para>The topic of any posting should adhere to the basic
	charter of the list it is posted to, e.g., if the list
	is about technical issues then your posting should contain
	technical discussion. Ongoing irrelevant chatter or
	flaming only detracts from the value of the mailing list
	for everyone on it and will not be tolerated. For
	free-form discussion on no particular topic, the &a.chat;
	is freely available and should be used instead.</para>
	</listitem>

	<listitem>
	<para>No posting should be made to more than 2 mailing
	lists, and only to 2 when a clear and obvious need to post
	to both lists exists. For most lists, there is already
	a great deal of subscriber overlap and except for the most
	esoteric mixes (say <quote>-stable & -scsi</quote>),
	there really is no reason to post to more than one list at
	a time. If a message is sent to you in such a way that
	multiple mailing lists appear on the <literal>Cc</literal>
	line then the <literal>Cc</literal> line should also be
	trimmed before sending it out again. <emphasis>You are
	still responsible for your own cross-postings, no matter
	who the originator might have been.</emphasis></para>
	</listitem>

	<listitem>
	<para>Personal attacks and profanity (in the context of
	an argument) are not allowed, and that includes users
	and developers alike. Gross breaches of netiquette,
	like excerpting or reposting private mail when permission
	to do so was not and would not be forthcoming, are frowned
	upon but not specifically enforced.
	<emphasis>However</emphasis>, there are also very few
	cases where such content would fit within the charter
	of a list and it would therefore probably rate a warning
	(or ban) on that basis alone.</para>
	</listitem>

	<listitem>
	<para>Advertising of non-FreeBSD related products or
	services is strictly prohibited and will result in an
	immediate ban if it is clear that the offender is
	advertising by spam.</para>
	</listitem>
	</itemizedlist>

	<para><emphasis>Individual list charters:</emphasis></para>

	<variablelist>

	<varlistentry>
	<term>&a.acpi.name;</term>

	<listitem>
	<para><emphasis>ACPI and power management
	development</emphasis></para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.afs.name;</term>

	<listitem>
	<para><emphasis>Andrew File System</emphasis></para>

	<para>This list is for discussion on porting and using
	AFS from CMU/Transarc</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.announce.name;</term>

	<listitem>
	<para><emphasis>Important events /
	milestones</emphasis></para>

	<para>This is the mailing list for people interested
	only in occasional announcements of significant FreeBSD
	events. This includes announcements about snapshots
	and other releases. It contains announcements of new
	FreeBSD capabilities. It may contain calls for
	volunteers etc. This is a low volume, strictly
	moderated mailing list.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.arch.name;</term>

	<listitem>
	<para><emphasis>Architecture and design
	discussions</emphasis></para>

	<para>This list is for discussion of the FreeBSD
	architecture. Messages will mostly be kept strictly
	technical in nature. Examples of suitable topics
	are:</para>

	<itemizedlist>
	<listitem>
	<para>How to re-vamp the build system to have several
	customized builds running at the same time.</para>
	</listitem>

	<listitem>
	<para>What needs to be fixed with VFS to make
	Heidemann layers work.</para>
	</listitem>

	<listitem>
	<para>How do we change the device driver interface
	to be able to use the same drivers cleanly on many
	buses and architectures.</para>
	</listitem>

	<listitem>
	<para>How to write a network driver.</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.bluetooth.name;</term>

	<listitem>
	<para><emphasis>&bluetooth; in FreeBSD</emphasis></para>

	<para>This is the forum where FreeBSD's &bluetooth; users
	congregate. Design issues, implementation details,
	patches, bug reports, status reports, feature requests,
	and all matters related to &bluetooth; are fair
	game.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.bugbusters.name;</term>

	<listitem>
	<para><emphasis>Coordination of the Problem Report
	handling effort</emphasis></para>

	<para>The purpose of this list is to serve as a
	coordination and discussion forum for the Bugmeister,
	his Bugbusters, and any other parties who have a genuine
	interest in the PR database. This list is not for
	discussions about specific bugs, patches or PRs.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.bugs.name;</term>

	<listitem>
	<para><emphasis>Bug reports</emphasis></para>

	<para>This is the mailing list for reporting bugs in
	FreeBSD. Whenever possible, bugs should be submitted
	using the &man.send-pr.1; command or the <ulink
	url="&url.base;/send-pr.html">WEB
	interface</ulink> to it.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.chat.name;</term>

	<listitem>
	<para><emphasis>Non technical items related to the FreeBSD
	community</emphasis></para>

	<para>This list contains the overflow from the other
	lists about non-technical, social information. It
	includes discussion about whether Jordan looks like a
	toon ferret or not, whether or not to type in capitals,
	who is drinking too much coffee, where the best beer
	is brewed, who is brewing beer in their basement, and
	so on. Occasional announcements of important events
	(such as upcoming parties, weddings, births, new jobs,
	etc) can be made to the technical lists, but the follow
	ups should be directed to this -chat list.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.chromium.name;</term>

	<listitem>
	<para><emphasis>FreeBSD-specific Chromium
	issues</emphasis></para>

	<para>This is a list for the discussion of Chromium
	support for FreeBSD. This is a technical list to
	discuss development and installation of Chromium.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.core.name;</term>

	<listitem>
	<para><emphasis>FreeBSD core team</emphasis></para>

	<para>This is an internal mailing list for use by the core
	members. Messages can be sent to it when a serious
	FreeBSD-related matter requires arbitration or
	high-level scrutiny.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.current.name;</term>

	<listitem>
	<para><emphasis>Discussions about the use of
	&os.current;</emphasis></para>

	<para>This is the mailing list for users of &os.current;.
	It includes warnings about new features coming out in
	-CURRENT that will affect the users, and instructions
	on steps that must be taken to remain -CURRENT. Anyone
	running <quote>CURRENT</quote> must subscribe to this
	list. This is a technical mailing list for which
	strictly technical content is expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.cvsweb.name;</term>

	<listitem>
	<para><emphasis>FreeBSD CVSweb Project</emphasis></para>

	<para>Technical discussions about use, development and
	maintenance of FreeBSD-CVSweb.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.desktop.name;</term>

	<listitem>
	<para><emphasis>Using and improving &os; on the
	desktop</emphasis></para>

	<para>This is a forum for discussion of &os; on the
	desktop. It is primarily a place for desktop porters
	and users to discuss issues and improve &os;'s desktop
	support.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.doc.name;</term>

	<listitem>
	<para><emphasis>Documentation project</emphasis></para>

	<para>This mailing list is for the discussion of issues
	and projects related to the creation of documentation
	for FreeBSD. The members of this mailing list are
	collectively referred to as <quote>The FreeBSD
	Documentation Project</quote>. It is an open list;
	feel free to join and contribute!</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.drivers.name;</term>

	<listitem>
	<para><emphasis>Writing device drivers for
	&os;</emphasis></para>

	<para>This is a forum for technical discussions related
	to device drivers on &os;. It is primarily a place
	for device driver writers to ask questions about how
	to write device drivers using the APIs in the &os;
	kernel.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.eclipse.name;</term>

	<listitem>
	<para><emphasis>&os; users of Eclipse IDE, tools, rich
	client applications and ports.</emphasis></para>

	<para>The intention of this list is to provide mutual
	support for everything to do with choosing, installing,
	using, developing and maintaining the Eclipse IDE,
	tools, rich client applications on the &os; platform and
	assisting with the porting of Eclipse IDE and plugins to
	the &os; environment.</para>

	<para>The intention is also to facilitate exchange of
	information between the Eclipse community and the &os;
	community to the mutual benefit of both.</para>

	<para>Although this list is focused primarily on the needs
	of Eclipse users it will also provide a forum for those
	who would like to develop &os; specific applications
	using the Eclipse framework.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.embedded.name;</term>

	<listitem>
	<para><emphasis>Using FreeBSD in embedded
	applications</emphasis></para>

	<para>This list discusses topics related to using FreeBSD
	in embedded systems. This is a technical mailing list
	for which strictly technical content is expected. For
	the purpose of this list we define embedded systems as
	those computing devices which are not desktops and which
	usually serve a single purpose as opposed to being
	general computing environments. Examples include, but
	are not limited to, all kinds of phone handsets, network
	equipment such as routers, switches and PBXs, remote
	measuring equipment, PDAs, Point Of Sale systems, and
	so on.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.emulation.name;</term>

	<listitem>
	<para><emphasis>Emulation of other systems such as
	Linux/&ms-dos;/&windows;</emphasis></para>

	<para>This is a forum for technical discussions related
	to running programs written for other operating systems
	on &os;.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.eol.name;</term>

	<listitem>
	<para><emphasis>Peer support of FreeBSD-related software
	that is no longer supported by the FreeBSD
	project.</emphasis></para>

	<para>This list is for those interested in providing or
	making use of peer support of FreeBSD-related software
	for which the FreeBSD project no longer provides
	official support (e.g., in the form of security
	advisories and patches).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.firewire.name;</term>

	<listitem>
	<para><emphasis>&firewire; (iLink, IEEE
	1394)</emphasis></para>

	<para>This is a mailing list for discussion of the design
	and implementation of a &firewire; (aka IEEE 1394 aka
	iLink) subsystem for FreeBSD. Relevant topics
	specifically include the standards, bus devices and
	their protocols, adapter boards/cards/chips sets, and
	the architecture and implementation of code for their
	proper support.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.fs.name;</term>

	<listitem>
	<para><emphasis>File systems</emphasis></para>

	<para>Discussions concerning FreeBSD file systems.
	This is a technical mailing list for which strictly
	technical content is expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.gecko.name;</term>

	<listitem>
	<para><emphasis>Gecko Rendering Engine</emphasis></para>

	<para>This is a forum about
	<application>Gecko</application> applications using
	&os;.</para>

	<para>Discussion centers around Gecko Ports applications,
	their installation, their development and their support
	within &os;.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.geom.name;</term>

	<listitem>
	<para><emphasis>GEOM</emphasis></para>

	<para>Discussions specific to GEOM and related
	implementations. This is a technical mailing list for
	which strictly technical content is expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.gnome.name;</term>

	<listitem>
	<para><emphasis>GNOME</emphasis></para>

	<para>Discussions concerning The
	<application>GNOME</application> Desktop Environment
	for FreeBSD systems. This is a technical mailing list
	for which strictly technical content is expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.infiniband.name;</term>

	<listitem>
	<para><emphasis>Infiniband on &os;</emphasis></para>

	<para>Technical mailing list discussing Infiniband, OFED,
	and OpenSM on &os;.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.ipfw.name;</term>

	<listitem>
	<para><emphasis>IP Firewall</emphasis></para>

	<para>This is the forum for technical discussions
	concerning the redesign of the IP firewall code in
	FreeBSD. This is a technical mailing list for which
	strictly technical content is expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.ia64.name;</term>

	<listitem>
	<para><emphasis>Porting FreeBSD to IA64</emphasis></para>

	<para>This is a technical mailing list for individuals
	actively working on porting FreeBSD to the IA-64
	platform from &intel;, to bring up problems or discuss
	alternative solutions. Individuals interested in
	following the technical discussion are also
	welcome.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.isdn.name;</term>

	<listitem>
	<para><emphasis>ISDN Communications</emphasis></para>

	<para>This is the mailing list for people discussing the
	development of ISDN support for FreeBSD.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.java.name;</term>

	<listitem>
	<para><emphasis>&java; Development</emphasis></para>

	<para>This is the mailing list for people discussing the
	development of significant &java; applications for
	FreeBSD and the porting and maintenance of
	&jdk;s.</para>
	</listitem>
	</varlistentry>

	<varlistentry id="eresources-charters-jobs">
	<term>&a.jobs.name;</term>

	<listitem>
	<para><emphasis>Jobs offered and sought</emphasis></para>

	<para>This is a forum for posting employment notices
	and resumes specifically related to &os;, e.g., if you
	are seeking &os;-related employment or have a job
	involving &os; to advertise then this is the right
	place. This is <emphasis>not</emphasis> a mailing list
	for general employment issues since adequate forums
	for that already exist elsewhere.</para>

	<para>Note that this list, like other <hostid
	role="domainname">FreeBSD.org</hostid> mailing lists,
	is distributed worldwide. Thus, you need to be clear
	about location and the extent to which telecommuting or
	assistance with relocation is available.</para>

	<para>Email should use open formats only —
	preferably plain text, but basic Portable Document
	Format (<acronym>PDF</acronym>), HTML, and a few others
	are acceptable to many readers. Closed formats such as
	&microsoft; Word (<filename>.doc</filename>) will be
	rejected by the mailing list server.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.kde.name;</term>

	<listitem>
	<para><emphasis>KDE</emphasis></para>

	<para>Discussions concerning
	<application>KDE</application> on FreeBSD systems.
	This is a technical mailing list for which strictly
	technical content is expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.hackers.name;</term>

	<listitem>
	<para><emphasis>Technical discussions</emphasis></para>

	<para>This is a forum for technical discussions related
	to FreeBSD. This is the primary technical mailing list.
	It is for individuals actively working on FreeBSD, to
	bring up problems or discuss alternative solutions.
	Individuals interested in following the technical
	discussion are also welcome. This is a technical
	mailing list for which strictly technical content is
	expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.hardware.name;</term>

	<listitem>
	<para><emphasis>General discussion of FreeBSD
	hardware</emphasis></para>

	<para>General discussion about the types of hardware
	that FreeBSD runs on, various problems and suggestions
	concerning what to buy or avoid.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.hubs.name;</term>

	<listitem>
	<para><emphasis>Mirror sites</emphasis></para>

	<para>Announcements and discussion for people who run
	FreeBSD mirror sites.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.isp.name;</term>

	<listitem>
	<para><emphasis>Issues for Internet Service
	Providers</emphasis></para>

	<para>This mailing list is for discussing topics relevant
	to Internet Service Providers (ISPs) using FreeBSD.
	This is a technical mailing list for which strictly
	technical content is expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.mono.name;</term>

	<listitem>
	<para><emphasis>Mono and C# applications on
	FreeBSD</emphasis></para>

	<para>This is a list for discussions related to the Mono
	development framework on &os;. This is a technical
	mailing list. It is for individuals actively working
	on porting Mono or C# applications to &os;, to bring
	up problems or discuss alternative solutions.
	Individuals interested in following the technical
	discussion are also welcome.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.office.name;</term>

	<listitem>
	<para><emphasis>Office applications on
	&os;</emphasis></para>

	<para>Discussion centers around office applications,
	their installation, their development and their support
	within &os;.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.ops-announce.name;</term>

	<listitem>
	<para><emphasis>Project Infrastructure
	Announcements</emphasis></para>

	<para>This is the mailing list for people interested in
	changes and issues related to the FreeBSD.org project
	infrastructure.</para>

	- <para>This list is strictly for announcements: no replies,
	+ <para>This moderated list is strictly for announcements: no replies,
	requests, discussions, or opinions.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.performance.name;</term>

	<listitem>
	<para><emphasis>Discussions about tuning or speedingup
	FreeBSD</emphasis></para>

	<para>This mailing list exists to provide a place for
	hackers, administrators, and/or concerned parties to
	discuss performance related topics pertaining to
	FreeBSD. Acceptable topics includes talking about
	FreeBSD installations that are either under high load,
	are experiencing performance problems, or are pushing
	the limits of FreeBSD. Concerned parties that are
	willing to work toward improving the performance of
	FreeBSD are highly encouraged to subscribe to this list.
	This is a highly technical list ideally suited for
	experienced FreeBSD users, hackers, or administrators
	interested in keeping FreeBSD fast, robust, and
	scalable. This list is not a question-and-answer list
	that replaces reading through documentation, but it is a
	place to make contributions or inquire about unanswered
	performance related topics.</para>

	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.pf.name;</term>

	<listitem>
	<para><emphasis>Discussion and questions about the packet
	filter firewall system</emphasis></para>

	<para>Discussion concerning the packet filter (pf)
	firewall system in terms of FreeBSD. Technical
	discussion and user questions are both welcome. This
	list is also a place to discuss the ALTQ QoS
	framework.</para>

	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.pkg.name;</term>

	<listitem>
	<para><emphasis>Binary package management and package
	tools discussion</emphasis></para>

	<para>Discussion of all aspects of managing &os; systems
	by using binary packages to install software, including
	binary package toolkits and formats, their development
	and support within &os;, package repository management,
	and 3rd party packages.</para>

	<para>Note that discussion of ports which fail to generate
	packages correctly should generally be considered as
	ports problems, and so inappropriate for this
	list.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.platforms.name;</term>

	<listitem>
	<para><emphasis>Porting to Non &intel;
	platforms</emphasis></para>

	<para>Cross-platform FreeBSD issues, general discussion
	and proposals for non &intel; FreeBSD ports. This is
	a technical mailing list for which strictly technical
	content is expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.ports.name;</term>

	<listitem>
	<para><emphasis>Discussion of
	<quote>ports</quote></emphasis></para>

	<para>Discussions concerning FreeBSD's <quote>ports
	collection</quote> (<filename>/usr/ports</filename>),
	ports infrastructure, and general ports coordination
	efforts. This is a technical mailing list for which
	strictly technical content is expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.ports-announce.name;</term>

	<listitem>
	<para><emphasis>Important news and instructions about the
	&os; <quote>Ports
	Collection</quote></emphasis></para>

	<para>Important news for developers, porters, and users
	of the <quote>Ports Collection</quote> (<filename
	role="directory">/usr/ports</filename>), including
	architecture/infrastructure changes, new capabilities,
	critical upgrade instructions, and release engineering
	information. This is a low-volume mailing list,
	intended for announcements.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.ports-bugs.name;</term>

	<listitem>
	<para><emphasis>Discussion of
	<quote>ports</quote> bugs</emphasis></para>

	<para>Discussions concerning problem reports for FreeBSD's
	<quote>ports collection</quote>
	(<filename>/usr/ports</filename>), proposed ports, or
	modifications to ports. This is a technical mailing
	list for which strictly technical content is
	expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.proliant.name;</term>

	<listitem>
	<para><emphasis>Technical discussion of FreeBSD on HP
	ProLiant server platforms</emphasis></para>

	<para>This mailing list is to be used for the technical
	discussion of the usage of FreeBSD on HP ProLiant
	servers, including the discussion of ProLiant-specific
	drivers, management software, configuration tools, and
	BIOS updates. As such, this is the primary place to
	discuss the hpasmd, hpasmcli, and hpacucli
	modules.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.python.name;</term>

	<listitem>
	<para><emphasis>Python on FreeBSD</emphasis></para>

	<para>This is a list for discussions related to improving
	Python-support on FreeBSD. This is a technical mailing
	list. It is for individuals working on porting Python,
	its 3rd party modules and
	<application>Zope</application> stuff to FreeBSD.
	Individuals interested in following the technical
	discussion are also welcome.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.questions.name;</term>

	<listitem>
	<para><emphasis>User questions</emphasis></para>

	<para>This is the mailing list for questions about
	FreeBSD. You should not send <quote>how to</quote>
	questions to the technical lists unless you consider
	the question to be pretty technical.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.ruby.name;</term>

	<listitem>
	<para><emphasis>FreeBSD-specific Ruby
	discussions</emphasis></para>

	<para>This is a list for discussions related to the Ruby
	support on FreeBSD. This is a technical mailing
	list. It is for individuals working on Ruby ports,
	3rd party libraries and frameworks.</para>

	<para>Individuals interested in the technical discussion
	are also welcome.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.scsi.name;</term>

	<listitem>
	<para><emphasis>SCSI subsystem</emphasis></para>

	<para>This is the mailing list for people working on
	the SCSI subsystem for FreeBSD. This is a technical
	mailing list for which strictly technical content is
	expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.security.name;</term>

	<listitem>
	<para><emphasis>Security issues</emphasis></para>

	<para>FreeBSD computer security issues (DES, Kerberos,
	known security holes and fixes, etc). This is a
	technical mailing list for which strictly technical
	discussion is expected. Note that this is not a
	question-and-answer list, but that contributions (BOTH
	question AND answer) to the FAQ are welcome.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.security-notifications.name;</term>

	<listitem>
	<para><emphasis>Security Notifications</emphasis></para>

	<para>Notifications of FreeBSD security problems and
	fixes. This is not a discussion list. The discussion
	list is FreeBSD-security.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.small.name;</term>

	<listitem>
	<para><emphasis>Using FreeBSD in embedded
	applications</emphasis></para>

	<para>This list discusses topics related to unusually
	small and embedded FreeBSD installations. This is a
	technical mailing list for which strictly technical
	content is expected.</para>

	<note>
	<para>This list has been obsoleted by
	&a.embedded.name;.</para>
	</note>

	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.snapshots.name;</term>

	<listitem>
	<para><emphasis>&os; Development Snapshot
	Announcements</emphasis></para>

	<para>This list will notify you about the availability
	of new &os; development snapshots for the head/ and
	stable/ branches.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.stable.name;</term>

	<listitem>
	<para><emphasis>Discussions about the use of
	&os.stable;</emphasis></para>

	<para>This is the mailing list for users of &os.stable;.
	It includes warnings about new features coming out in
	-STABLE that will affect the users, and instructions
	on steps that must be taken to remain -STABLE. Anyone
	running <quote>STABLE</quote> should subscribe to this
	list. This is a technical mailing list for which
	strictly technical content is expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.standards.name;</term>

	<listitem>
	<para><emphasis>C99 & POSIX
	Conformance</emphasis></para>

	<para>This is a forum for technical discussions related
	to FreeBSD Conformance to the C99 and the POSIX
	standards.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.toolchain.name;</term>

	<listitem>
	<para><emphasis>Maintenance of FreeBSD's integrated
	toolchain</emphasis></para>

	<para>This is the mailing list for discussions related
	to the maintenance of the toolchain shipped with &os;.
	This could include the state of Clang and GCC, but also
	pieces of software such as assemblers, linkers and
	debuggers.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.usb.name;</term>

	<listitem>
	<para><emphasis>Discussing &os; support for
	USB</emphasis></para>

	<para>This is a mailing list for technical discussions
	related to &os; support for USB.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.usergroups.name;</term>

	<listitem>
	<para><emphasis>User Group Coordination
	List</emphasis></para>

	<para>This is the mailing list for the coordinators from
	each of the local area Users Groups to discuss matters
	with each other and a designated individual from the
	Core Team. This mail list should be limited to meeting
	synopsis and coordination of projects that span User
	Groups.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term>&a.vendors.name;</term>
	-
	- <listitem>
	- <para><emphasis>Vendors</emphasis></para>
	-
	- <para>Coordination discussions between The FreeBSD
	- Project and Vendors of software and hardware for
	- FreeBSD.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.virtualization.name;</term>

	<listitem>
	<para><emphasis>Discussion of various virtualization
	techniques supported by &os;</emphasis></para>

	<para>A list to discuss the various virtualization
	techniques supported by &os;. On one hand the focus
	will be on the implementation of the basic functionality
	as well as adding new features. On the other hand users
	will have a forum to ask for help in case of problems or
	to discuss their use cases.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.wip-status.name;</term>

	<listitem>
	<para><emphasis>&os; Work-In-Progress
	Status</emphasis></para>

	<para>This mailing list can be used to announce creation
	and progress of your &os; related work. Messages
	will be moderated. It is suggested to send the message
	"To:" a more topical &os; list and only "BCC:"
	this list. This way your WIP can also be discussed on
	the topical list, as no discussion is allowed on this
	list.</para>

	<para>Look inside the archives for examples of suitable
	messages.</para>

	<para>An editorial digest of the messages to this list
	might be posted to the &os; website every few month
	as part of the Status Reports
	<footnote><para><ulink
	url="http://www.freebsd.org/news/status/"></ulink></para></footnote>.
	You can find more examples and past reports there,
	too.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.wireless.name;</term>

	<listitem>
	<para><emphasis>Discussions of 802.11 stack, tools device
	driver development</emphasis></para>

	<para>The FreeBSD-wireless list focuses on 802.11 stack
	(sys/net80211), device driver and tools development.
	This includes bugs, new features and maintenance.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.xen.name;</term>

	<listitem>
	<para><emphasis>Discussion of the &os; port to &xen;
	— implementation and usage</emphasis></para>

	<para>A list that focuses on the &os; &xen; port. The
	anticipated traffic level is small enough that it is
	intended as a forum for both technical discussions of
	the implementation and design details as well as
	administrative deployment issues.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.xfce.name;</term>

	<listitem>
	<para><emphasis>XFCE</emphasis></para>

	<para>This is a forum for discussions related to bring
	the <application>XFCE</application> environment to &os;.
	This is a technical mailing list. It is for individuals
	actively working on porting
	<application>XFCE</application> to &os;, to bring up
	problems or discuss alternative solutions. Individuals
	interested in following the technical discussion are
	also welcome.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&a.zope.name;</term>

	<listitem>
	<para><emphasis>Zope</emphasis></para>

	<para>This is a forum for discussions related to bring
	the <application>Zope</application> environment to &os;.
	This is a technical mailing list. It is for individuals
	actively working on porting
	<application>Zope</application> to &os;, to bring up
	problems or discuss alternative solutions. Individuals
	interested in following the technical discussion are
	also welcome.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect2>
	<sect2 id="eresources-mailfiltering">
	<title>Filtering on the Mailing Lists</title>

	<para>The &os; mailing lists are filtered in multiple ways to
	avoid the distribution of spam, viruses, and other unwanted
	emails. The filtering actions described in this section do
	not include all those used to protect the mailing
	lists.</para>

	<para>Only certain types of attachments are allowed on the
	mailing lists. All attachments with a MIME content type not
	found in the list below will be stripped before an email is
	distributed on the mailing lists.</para>

	<itemizedlist>
	<listitem>
	<para>application/octet-stream</para>
	</listitem>

	<listitem>
	<para>application/pdf</para>
	</listitem>

	<listitem>
	<para>application/pgp-signature</para>
	</listitem>

	<listitem>
	<para>application/x-pkcs7-signature</para>
	</listitem>

	<listitem>
	<para>message/rfc822</para>
	</listitem>

	<listitem>
	<para>multipart/alternative</para>
	</listitem>

	<listitem>
	<para>multipart/related</para>
	</listitem>

	<listitem>
	<para>multipart/signed</para>
	</listitem>

	<listitem>
	<para>text/html</para>
	</listitem>

	<listitem>
	<para>text/plain</para>
	</listitem>

	<listitem>
	<para>text/x-diff</para>
	</listitem>

	<listitem>
	<para>text/x-patch</para>
	</listitem>
	</itemizedlist>

	<note>
	<para>Some of the mailing lists might allow attachments of
	other MIME content types, but the above list should be
	applicable for most of the mailing lists.</para>
	</note>

	<para>If an email contains both an HTML and a plain text
	version, the HTML version will be removed. If an email
	contains only an HTML version, it will be converted to plain
	text.</para>
	</sect2>
	</sect1>

	<sect1 id="eresources-news">
	<title>Usenet Newsgroups</title>

	<para>In addition to two FreeBSD specific newsgroups, there are
	many others in which FreeBSD is discussed or are otherwise
	relevant to FreeBSD users.</para>

	<sect2>
	<title>BSD Specific Newsgroups</title>

	<itemizedlist>
	<listitem>
	<para><ulink
	url="news:comp.unix.bsd.freebsd.announce">comp.unix.bsd.freebsd.announce</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.unix.bsd.freebsd.misc">comp.unix.bsd.freebsd.misc</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:de.comp.os.unix.bsd">de.comp.os.unix.bsd</ulink>
	(German)</para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:fr.comp.os.bsd">fr.comp.os.bsd</ulink>
	(French)</para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:it.comp.os.freebsd">it.comp.os.freebsd</ulink>
	(Italian)</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2>
	<title>Other &unix; Newsgroups of Interest</title>

	<itemizedlist>
	<listitem>
	<para><ulink url="news:comp.unix">comp.unix</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.unix.questions">comp.unix.questions</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.unix.admin">comp.unix.admin</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.unix.programmer">comp.unix.programmer</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.unix.shell">comp.unix.shell</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.unix.user-friendly">comp.unix.user-friendly</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.security.unix">comp.security.unix</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.sources.unix">comp.sources.unix</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.unix.advocacy">comp.unix.advocacy</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.unix.misc">comp.unix.misc</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.unix.bsd">comp.unix.bsd</ulink></para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2>
	<title>X Window System</title>

	<itemizedlist>
	<listitem>
	<para><ulink
	url="news:comp.windows.x.i386unix">comp.windows.x.i386unix</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.windows.x">comp.windows.x</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.windows.x.apps">comp.windows.x.apps</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.windows.x.announce">comp.windows.x.announce</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.windows.x.intrinsics">comp.windows.x.intrinsics</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.windows.x.motif">comp.windows.x.motif</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.windows.x.pex">comp.windows.x.pex</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="news:comp.emulators.ms-windows.wine">comp.emulators.ms-windows.wine</ulink></para>
	</listitem>
	</itemizedlist>
	</sect2>
	</sect1>

	<sect1 id="eresources-web">
	<title>World Wide Web Servers</title>

	<sect2 id="eresources-web-social">
	<title>Forums, Blogs, and Social Networks</title>

	<itemizedlist>
	<listitem><para><ulink url="http://forums.freebsd.org/">The
	FreeBSD Forums</ulink> provide a web based discussion
	forum for FreeBSD questions and technical
	discussion.</para></listitem>

	<listitem><para><ulink
	url="http://planet.freebsdish.org/">Planet FreeBSD</ulink>
	offers an aggregation feed of dozens of blogs written by
	FreeBSD developers. Many developers use this to post quick
	notes about what they are working on, new patches, and other
	works in progress.</para></listitem>

	<listitem><para>The <ulink
	url="http://www.youtube.com/bsdconferences">BSDConferences
	YouTube Channel</ulink> provides a collection of high
	quality videos from BSD Conferences around the world. This
	is a great way to watch key developers give presentations
	about new work in FreeBSD.</para></listitem>
	</itemizedlist>
	</sect2>

	<sect2 id="eresources-web-mirrors">
	<title>Official Mirrors</title>

	&chap.eresources.www.inc;
	</sect2>
	</sect1>

	<sect1 id="eresources-email">
	<title>Email Addresses</title>

	<para>The following user groups provide FreeBSD related email
	addresses for their members. The listed administrator reserves
	the right to revoke the address if it is abused in any
	way.</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="4">
	<thead>
	<row>
	<entry>Domain</entry>
	<entry>Facilities</entry>
	<entry>User Group</entry>
	<entry>Administrator</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>ukug.uk.FreeBSD.org</entry>
	<entry>Forwarding only</entry>
	<entry><email>ukfreebsd@uk.FreeBSD.org</email></entry>
	<entry>Lee Johnston
	<email>lee@uk.FreeBSD.org</email></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</sect1>
	</appendix>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml (revision 41355)
	@@ -1,3122 +1,3122 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="firewalls">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Joseph J.</firstname>
	<surname>Barbish</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Brad</firstname>
	<surname>Davis</surname>
	<contrib>Converted to SGML and updated by </contrib>
	</author>
	</authorgroup>
	</chapterinfo>

	<title>Firewalls</title>

	<indexterm><primary>firewall</primary></indexterm>

	<indexterm>
	<primary>security</primary>

	<secondary>firewalls</secondary>
	</indexterm>

	<sect1 id="firewalls-intro">
	<title>Introduction</title>

	<para>Firewalls make it possible to filter the incoming and
	outgoing traffic that flows through a system. A firewall can
	use one or more sets of <quote>rules</quote> to inspect network
	packets as they come in or go out of network connections and
	either allows the traffic through or blocks it. The rules of
	a firewall can inspect one or more characteristics of the
	packets such as the protocol type, source or destination host
	address, and source or destination port.</para>

	<para>Firewalls can enhance the security of a host or a network.
	They can be used to do one or more of the following:</para>

	<itemizedlist>
	<listitem>
	<para>Protect and insulate the applications, services, and
	machines of an internal network from unwanted traffic from
	the public Internet.</para>
	</listitem>

	<listitem>
	<para>Limit or disable access from hosts of the internal
	network to services of the public Internet.</para>
	</listitem>

	<listitem>
	<para>Support network address translation
	(<acronym>NAT</acronym>), which allows an internal network
	to use private <acronym>IP</acronym> addresses and share a
	single connection to the public Internet using either a
	single <acronym>IP</acronym> address or a shared pool of
	automatically assigned public addresses.</para>
	</listitem>
	</itemizedlist>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>How to define packet filtering rules.</para>
	</listitem>

	<listitem>
	<para>The differences between the firewalls built into
	&os;.</para>
	</listitem>

	<listitem>
	<para>How to use and configure the
	<application>PF</application> firewall.</para>
	</listitem>

	<listitem>
	<para>How to use and configure the
	<application>IPFILTER</application> firewall.</para>
	</listitem>

	<listitem>
	<para>How to use and configure the
	<application>IPFW</application> firewall.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	<para>Understand basic &os; and Internet concepts.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="firewalls-concepts">
	<title>Firewall Concepts</title>

	<indexterm>
	<primary>firewall</primary>

	<secondary>rulesets</secondary>
	</indexterm>

	<para>A firewall ruleset can be either
	<quote>exclusive</quote> or <quote>inclusive</quote>. An
	exclusive firewall allows all traffic through except for the
	traffic matching the ruleset. An inclusive firewall does the
	reverse as it only allows traffic matching the rules through and
	blocks everything else.</para>

	<para>An inclusive firewall offers better control of the outgoing
	traffic, making it a better choice for systems that offer
	services to the public Internet. It also controls the type of
	traffic originating from the public Internet that can gain
	access to a private network. All traffic that does not match
	the rules is blocked and logged. Inclusive firewalls are
	generally safer than exclusive firewalls because they
	significantly reduce the risk of allowing unwanted
	traffic.</para>

	<note>
	<para>Unless noted otherwise, all configuration and example
	rulesets in this chapter create inclusive firewall
	rulesets.</para>
	</note>

	<para>Security can be tightened further using a <quote>stateful
	firewall</quote>. This type of firewall keeps track of open
	connections and only allows traffic which either matches an
	existing connection or opens a new, allowed connection. The
	disadvantage of a stateful firewall is that it can be vulnerable
	to Denial of Service (<acronym>DoS</acronym>) attacks if a lot
	of new connections are opened very fast. Most firewalls use a
	combination of stateful and non-stateful behavior.</para>
	</sect1>

	<sect1 id="firewalls-apps">
	<title>Firewall Packages</title>

	<para>&os; has three firewalls built into the base system:
	<emphasis>IPFILTER</emphasis>, also known as
	<acronym>IPF</acronym>, <emphasis>IPFIREWALL</emphasis>, also
	known as <acronym>IPFW</acronym>, and <acronym>PF</acronym>).
	&os; also provides two traffic shapers for controlling bandwidth
	usage: &man.altq.4; and &man.dummynet.4;. Dummynet has
	traditionally been closely tied with <acronym>IPFW</acronym>,
	and <acronym>ALTQ</acronym> with <acronym>PF</acronym>. Each
	firewall uses rules to control the access of packets to and from
	a &os; system, although they go about it in different ways and
	each has a different rule syntax.</para>

	<para>&os; provides multiple firewalls in order to meet the
	different requirements and preferences for a wide variety of
	users. Each user should evaluate which firewall best meets
	their needs.</para>

	<para>Since all firewalls are based on inspecting the values of
	selected packet control fields, the creator of the firewall
	ruleset must have an understanding of how
	<acronym>TCP/IP</acronym> works, what the different values in
	the packet control fields are, and how these values are used in
	a normal session conversation. For a good introduction, refer
	to <ulink
	url="http://www.ipprimer.com/overview.cfm">Daryl's TCP/IP
	Primer</ulink>.</para>
	</sect1>

	<sect1 id="firewalls-pf">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>John</firstname>
	<surname>Ferrell</surname>
	<contrib>Revised and updated by </contrib>
	<!-- 24 March 2008 -->
	</author>
	</authorgroup>
	</sect1info>

	<title>PF and <acronym>ALTQ</acronym></title>

	<indexterm>
	<primary>firewall</primary>

	<secondary>PF</secondary>
	</indexterm>

	<para>Since &os; 5.3, a ported version of OpenBSD's
	<acronym>PF</acronym> firewall has been included as an
	integrated part of the base system. <acronym>PF</acronym> is a
	complete, full-featured firewall that has optional support for
	<acronym>ALTQ</acronym> (Alternate Queuing), which provides
	Quality of Service (<acronym>QoS</acronym>).</para>

	<para>Since the OpenBSD Project maintains the definitive
	reference for <acronym>PF</acronym> in the<ulink
	url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink>, this
	section of the Handbook focuses on <acronym>PF</acronym> as it
	pertains to &os;, while providing some general usage
	information.</para>

	<para>More information about porting <acronym>PF</acronym> to &os;
	can be found at <ulink
	url="http://pf4freebsd.love2party.net/"></ulink>.</para>

	<sect2>
	<title>Using the PF Loadable Kernel Modules</title>

	<para>In order to use PF, the PF kernel module must be first
	loaded. Add the following line to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>pf_enable="YES"</programlisting>

	<para>Then, run the startup script to load the module:</para>

	<screen>&prompt.root; <userinput>service pf start</userinput></screen>

	<para>The PF module will not load if it cannot find the
	ruleset configuration file. The default location is
	<filename>/etc/pf.conf</filename>. If the PF ruleset is
	located somewhere else, add a line to
	<filename>/etc/rc.conf</filename> which specifies the full
	path to the file:</para>

	<programlisting>pf_rules="<replaceable>/path/to/pf.conf</replaceable>"</programlisting>

	<para>The sample <filename>pf.conf</filename>
	can be found in <filename
	class="directory">/usr/share/examples/pf/</filename>.</para>

	<para>The <acronym>PF</acronym> module can also be loaded
	manually from the command line:</para>

	<screen>&prompt.root; <userinput>kldload pf.ko</userinput></screen>

	<para>Logging support for PF is provided by
	<varname>pflog.ko</varname> which can be loaded by adding the
	following line to <filename>/etc/rc.conf</filename>:</para>

	<programlisting>pflog_enable="YES"</programlisting>

	<para>Then, run the startup script to load the module:</para>

	<screen>&prompt.root; <userinput>service pflog start</userinput></screen>

	</sect2>

	<sect2>
	<title>PF Kernel Options</title>

	<indexterm>
	<primary>kernel options</primary>

	<secondary>device pf</secondary>
	</indexterm>

	<indexterm>
	<primary>kernel options</primary>

	<secondary>device pflog</secondary>
	</indexterm>

	<indexterm>
	<primary>kernel options</primary>

	<secondary>device pfsync</secondary>
	</indexterm>

	<para>While it is not necessary to compile
	<acronym>PF</acronym> support into the &os; kernel, some of
	PF's advanced features are not included in the loadable
	module, namely &man.pfsync.4;, which is a pseudo-device that
	exposes certain changes to the state table used by
	<acronym>PF</acronym>. It can be paired with &man.carp.4; to
	create failover firewalls using <acronym>PF</acronym>. More
	information on <acronym>CARP</acronym> can be found in <link
	linkend="carp">of the Handbook</link>.</para>

	<para>The following <acronym>PF</acronym> kernel options can be
	found in <filename>/usr/src/sys/conf/NOTES</filename>:</para>

	<programlisting>device pf
	device pflog
	device pfsync</programlisting>

	<para><literal>device pf</literal> enables PF support.</para>

	<para><literal>device pflog</literal> enables the optional
	&man.pflog.4; pseudo network device which can be used to log
	traffic to a &man.bpf.4; descriptor. The &man.pflogd.8;
	daemon can then be used to store the logging information to
	disk.</para>

	<para><literal>device pfsync</literal> enables the optional
	&man.pfsync.4; pseudo-network device that is used to monitor
	<quote>state changes</quote>.</para>
	</sect2>

	<sect2>
	<title>Available <filename>rc.conf</filename> Options</title>

	<para>The following &man.rc.conf.5; statements can be used to
	configure <acronym>PF</acronym> and &man.pflog.4; at
	boot:</para>

	<programlisting>pf_enable="YES" # Enable PF (load module if required)
	pf_rules="/etc/pf.conf" # rules definition file for pf
	pf_flags="" # additional flags for pfctl startup
	pflog_enable="YES" # start pflogd(8)
	pflog_logfile="/var/log/pflog" # where pflogd should store the logfile
	pflog_flags="" # additional flags for pflogd startup</programlisting>

	<para>If there is a LAN behind the firewall and packets need to
	be forwarded for the computers on the LAN, or NAT is required,
	add the following option:</para>

	<programlisting>gateway_enable="YES" # Enable as LAN gateway</programlisting>
	</sect2>

	<sect2>
	<title>Creating Filtering Rules</title>

	<para>By default, <acronym>PF</acronym> reads its configuration
	rules from <filename>/etc/pf.conf</filename> and modifies,
	drops, or passes packets according to the rules or definitions
	specified in this file. The &os; installation includes
	several sample files located in
	<filename>/usr/share/examples/pf/</filename>. Refer to the
	<ulink url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink> for
	complete coverage of <acronym>PF</acronym> rulesets.</para>

	<warning>
	<para>When reading the <ulink
	url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink>,
	keep in mind that different versions of &os; contain
	different versions of PF. Currently,
	- &os; 8.<replaceable>X</replaceable> and prior is using
	- the same version of <acronym>PF</acronym> as
	+ &os; 8.<replaceable>X</replaceable> is using the
	+ same version of <acronym>PF</acronym> as
	OpenBSD 4.1. &os; 9.<replaceable>X</replaceable>
	and later is using the same version of <acronym>PF</acronym>
	as OpenBSD 4.5.</para>
	</warning>

	<para>The &a.pf; is a good place to ask questions about
	configuring and running the <acronym>PF</acronym> firewall.
	Do not forget to check the mailing list archives before asking
	questions.</para>
	</sect2>

	<sect2>
	<title>Working with PF</title>

	<para>To control <acronym>PF</acronym>, use &man.pfctl.8;.
	Below are some useful options to this command. Review
	&man.pfctl.8; for a description of all available
	options:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Command</entry>
	<entry>Purpose</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><command>pfctl
	<option>-e</option></command></entry>
	<entry>Enable PF.</entry>
	</row>

	<row>
	<entry><command>pfctl
	<option>-d</option></command></entry>
	<entry>Disable PF.</entry>
	</row>

	<row>
	<entry><command>pfctl <option>-F</option> all
	<option>-f</option> /etc/pf.conf</command></entry>
	<entry>Flush all NAT, filter, state, and table
	rules and reload
	<filename>/etc/pf.conf</filename>.</entry>
	</row>

	<row>
	<entry><command>pfctl <option>-s</option> [ rules \| nat
	state ]</command></entry>
	<entry>Report on the filter rules, NAT rules, or state
	table.</entry>
	</row>

	<row>
	<entry><command>pfctl <option>-vnf</option>
	/etc/pf.conf</command></entry>
	<entry>Check <filename>/etc/pf.conf</filename> for
	errors, but do not load ruleset.</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</sect2>

	<sect2>
	<title>Enabling <acronym>ALTQ</acronym></title>

	<para><acronym>ALTQ</acronym> is only available by compiling its
	support into the &os; kernel. <acronym>ALTQ</acronym> is not
	supported by all network card drivers. Refer to &man.altq.4;
	for a list of drivers that are supported by the release of
	&os;.</para>

	<para>The following kernel options will enable
	<acronym>ALTQ</acronym> and add additional
	functionality:</para>

	<programlisting>options ALTQ
	-options ALTQ_CBQ # Class Bases Queuing (CBQ)
	+options ALTQ_CBQ # Class Based Queuing (CBQ)
	options ALTQ_RED # Random Early Detection (RED)
	options ALTQ_RIO # RED In/Out
	options ALTQ_HFSC # Hierarchical Packet Scheduler (HFSC)
	options ALTQ_PRIQ # Priority Queuing (PRIQ)
	options ALTQ_NOPCC # Required for SMP build</programlisting>

	<para><literal>options ALTQ</literal> enables the
	<acronym>ALTQ</acronym> framework.</para>

	<para><literal>options ALTQ_CBQ</literal> enables
	<emphasis>Class Based Queuing</emphasis>
	(<acronym>CBQ</acronym>). <acronym>CBQ</acronym>
	can be used to divide a connection's bandwidth into different
	classes or queues to prioritize traffic based on filter
	rules.</para>

	<para><literal>options ALTQ_RED</literal> enables
	<emphasis>Random Early Detection</emphasis>
	(<acronym>RED</acronym>). <acronym>RED</acronym> is
	used to avoid network congestion by measuring the length of
	the queue and comparing it to the minimum and maximum
	thresholds for the queue. If the queue is over the maximum,
	all new packets will be dropped. <acronym>RED</acronym> drops
	packets from different connections randomly.</para>

	<para><literal>options ALTQ_RIO</literal> enables
	<emphasis>Random Early Detection In and Out</emphasis>.</para>

	<para><literal>options ALTQ_HFSC</literal> enables the
	<emphasis>Hierarchical Fair Service Curve Packet
	Scheduler</emphasis> <acronym>HFSC</acronym>. For more
	information, refer to <ulink
	url="http://www-2.cs.cmu.edu/~hzhang/HFSC/main.html"></ulink>.</para>

	<para><literal>options ALTQ_PRIQ</literal> enables
	<emphasis>Priority Queuing</emphasis>
	(<acronym>PRIQ</acronym>). <acronym>PRIQ</acronym> will
	always pass traffic that is in a higher queue first.</para>

	<para><literal>options ALTQ_NOPCC</literal> enables
	<acronym>SMP</acronym> support for <acronym>ALTQ</acronym>.
	This option is required on <acronym>SMP</acronym>
	systems.</para>
	</sect2>
	</sect1>

	<sect1 id="firewalls-ipf">
	<title>The IPFILTER (IPF) Firewall</title>

	<indexterm>
	<primary>firewall</primary>

	<secondary>IPFILTER</secondary>
	</indexterm>

	<para>IPFILTER is a cross-platform, open source firewall which
	has been ported to &os;, NetBSD, OpenBSD, &sunos;, HP/UX, and
	&solaris; operating systems.</para>

	<para>IPFILTER is based on a kernel-side firewall and
	<acronym>NAT</acronym> mechanism that can be controlled and
	monitored by userland interface programs. The firewall rules
	can be set or deleted using &man.ipf.8;. The
	<acronym>NAT</acronym> rules can be set or deleted using
	&man.ipnat.8;. Run-time statistics for the kernel parts of
	IPFILTER can be printed using &man.ipfstat.8;. To log IPFILTER
	actions to the system log files, use &man.ipmon.8;.</para>

	<para>IPF was originally written using a rule processing logic
	of <quote>the last matching rule wins</quote> and only used
	stateless rules. Over time, IPF has been enhanced to include a
	<quote>quick</quote> option and a stateful
	<quote>keep state</quote> option which modernized the rules
	processing logic. IPF's official documentation covers only the
	legacy rule coding parameters and rule file processing logic and
	the modernized functions are only included as additional
	options.</para>

	<para>The instructions contained in this section are based on
	using rules that contain <quote>quick</quote> and
	<quote>keep state</quote> as these provide the basic framework
	for configuring an inclusive firewall ruleset.</para>

	<para>For a detailed explanation of the legacy rules processing
	method, refer to <ulink
	url="http://www.munk.me.uk/ipf/ipf-howto.html"></ulink>
	and <ulink
	url="http://coombs.anu.edu.au/~avalon/ip-filter.html"></ulink>.</para>

	<para>The IPF FAQ is at <ulink
	url="http://www.phildev.net/ipf/index.html"></ulink>.</para>

	<para>A searchable archive of the IPFilter mailing list is
	available at <ulink
	url="http://marc.theaimsgroup.com/?l=ipfilter"></ulink>.</para>

	<sect2>
	<title>Enabling IPF</title>

	<indexterm>
	<primary>IPFILTER</primary>

	<secondary>enabling</secondary>
	</indexterm>

	<para>IPF is included in the basic &os; install as a kernel
	loadable module. The system will dynamically load
	this module at boot time when
	<varname>ipfilter_enable="YES"</varname> is added to
	<filename>rc.conf</filename>. The module enables logging and
	<literal>default pass all</literal>. To change the
	default to <literal>block all</literal>, add a
	<literal>block all</literal> rule at the end of the
	ruleset.</para>
	</sect2>

	<sect2>
	<title>Kernel Options</title>

	<indexterm>
	<primary>kernel options</primary>

	<secondary>IPFILTER</secondary>
	</indexterm>

	<indexterm>
	<primary>kernel options</primary>

	<secondary>IPFILTER_LOG</secondary>
	</indexterm>

	<indexterm>
	<primary>kernel options</primary>

	<secondary>IPFILTER_DEFAULT_BLOCK</secondary>
	</indexterm>

	<indexterm>
	<primary>IPFILTER</primary>

	<secondary>kernel options</secondary>
	</indexterm>

	<para>For users who prefer to statically compile IPF support
	into a custom kernel, the following IPF option statements,
	listed in <filename>/usr/src/sys/conf/NOTES</filename>, are
	available:</para>

	<programlisting>options IPFILTER
	options IPFILTER_LOG
	options IPFILTER_DEFAULT_BLOCK</programlisting>

	<para><literal>options IPFILTER</literal> enables support for
	the <quote>IPFILTER</quote> firewall.</para>

	<para><literal>options IPFILTER_LOG</literal> enables IPF
	logging using the <devicename>ipl</devicename> packet logging
	pseudo—device for every rule that has the
	<literal>log</literal> keyword.</para>

	<para><literal>options IPFILTER_DEFAULT_BLOCK</literal> changes
	the default behavior so that any packet not matching a
	firewall <literal>pass</literal> rule gets blocked.</para>

	<para>These settings will take effect only after installing a
	kernel that has been built with the above options set.</para>
	</sect2>

	<sect2>
	<title>Available <filename>rc.conf</filename> Options</title>

	<para>To activate IPF at boot time, the following statements
	need to be added to <filename>/etc/rc.conf</filename>:</para>

	<programlisting>ipfilter_enable="YES" # Start ipf firewall
	ipfilter_rules="/etc/ipf.rules" # loads rules definition text file
	ipmon_enable="YES" # Start IP monitor log
	ipmon_flags="-Ds" # D = start as daemon
	# s = log to syslog
	# v = log tcp window, ack, seq
	# n = map IP & port to names</programlisting>

	<para>If there is a LAN behind the firewall that uses the
	reserved private IP address ranges, the following lines have
	to be added to enable <acronym>NAT</acronym>
	functionality:</para>

	<programlisting>gateway_enable="YES" # Enable as LAN gateway
	ipnat_enable="YES" # Start ipnat function
	ipnat_rules="/etc/ipnat.rules" # rules definition file for ipnat</programlisting>
	</sect2>

	<sect2>
	<title>IPF</title>

	<indexterm><primary><command>ipf</command></primary></indexterm>

	<para>To load the ruleset file, use &man.ipf.8;. Custom rules
	are normally placed in a file, and the following command can
	be used to replace the currently running firewall
	rules:</para>

	<screen>&prompt.root; <userinput>ipf -Fa -f /etc/ipf.rules</userinput></screen>

	<para><option>-Fa</option> flushes all the internal rules
	tables.</para>

	<para><option>-f</option> specifies the file containing the
	rules to load.</para>

	<para>This provides the ability to make changes to a custom
	rules file, run the above IPF command, and thus update the
	running firewall with a fresh copy of the rules without having
	to reboot the system. This method is convenient for testing
	new rules as the procedure can be executed as many times as
	needed.</para>

	<para>Refer to &man.ipf.8; for details on the other flags
	available with this command.</para>

	<para>&man.ipf.8; expects the rules file to be a standard text
	file. It will not accept a rules file written as a script
	with symbolic substitution.</para>

	<para>There is a way to build IPF rules that utilize the power
	of script symbolic substitution. For more information, see
	<link linkend="firewalls-ipf-rules-script"></link>.</para>
	</sect2>

	<sect2>
	<title>IPFSTAT</title>

	<indexterm><primary><command>ipfstat</command></primary></indexterm>

	<indexterm>
	<primary>IPFILTER</primary>

	<secondary>statistics</secondary>
	</indexterm>

	<para>The default behavior of &man.ipfstat.8; is to retrieve
	and display the totals of the accumulated statistics gathered
	by applying the rules against packets going in and out of the
	firewall since it was last started, or since the last time the
	accumulators were reset to zero using <command>ipf
	-Z</command>.</para>

	<para>Refer to &man.ipfstat.8; for details.</para>

	<para>The default &man.ipfstat.8; output will look something
	like this:</para>

	<screen>input packets: blocked 99286 passed 1255609 nomatch 14686 counted 0
	output packets: blocked 4200 passed 1284345 nomatch 14687 counted 0
	input packets logged: blocked 99286 passed 0
	output packets logged: blocked 0 passed 0
	packets logged: input 0 output 0
	log failures: input 3898 output 0
	fragment state(in): kept 0 lost 0
	fragment state(out): kept 0 lost 0
	packet state(in): kept 169364 lost 0
	packet state(out): kept 431395 lost 0
	ICMP replies: 0 <acronym>TCP</acronym> RSTs sent: 0
	Result cache hits(in): 1215208 (out): 1098963
	IN Pullups succeeded: 2 failed: 0
	OUT Pullups succeeded: 0 failed: 0
	Fastroute successes: 0 failures: 0
	<acronym>TCP</acronym> cksum fails(in): 0 (out): 0
	Packet log flags set: (0)</screen>

	<para>When supplied with either <option>-i</option> for inbound
	or <option>-o</option> for outbound, the command will retrieve
	and display the appropriate list of filter rules currently
	installed and in use by the kernel.</para>

	<para><command>ipfstat -in</command> displays the inbound
	internal rules table with rule numbers.</para>

	<para><command>ipfstat -on</command> displays the outbound
	internal rules table with rule numbers.</para>

	<para>The output will look something like this:</para>

	<screen>@1 pass out on xl0 from any to any
	@2 block out on dc0 from any to any
	@3 pass out quick on dc0 proto tcp/udp from any to any keep state</screen>

	<para><command>ipfstat -ih</command> displays the inbound
	internal rules table, prefixing each rule with a count of how
	many times the rule was matched.</para>

	<para><command>ipfstat -oh</command> displays the outbound
	internal rules table, prefixing each rule with a count of how
	many times the rule was matched.</para>

	<para>The output will look something like this:</para>

	<screen>2451423 pass out on xl0 from any to any
	354727 block out on dc0 from any to any
	430918 pass out quick on dc0 proto tcp/udp from any to any keep state</screen>

	<para>One of the most important options of
	<command>ipfstat</command> is <option>-t</option> which
	displays the state table in a way similar to how &man.top.1;
	shows the &os; running process table. When a firewall is
	under attack, this function provides the ability to identify
	and see the attacking packets. The optional sub-flags give
	the ability to select the destination or source IP, port, or
	protocol to be monitored in real time. Refer to
	&man.ipfstat.8; for details.</para>
	</sect2>

	<sect2>
	<title>IPMON</title>

	<indexterm><primary><command>ipmon</command></primary></indexterm>

	<indexterm>
	<primary>IPFILTER</primary>

	<secondary>logging</secondary>
	</indexterm>

	<para>In order for <command>ipmon</command> to work properly,
	the kernel option <literal>IPFILTER_LOG</literal> must be
	turned on. This command has two different modes. Native mode
	is the default mode when the command is used without
	<option>-D</option>.</para>

	<para>Daemon mode provides a continuous system log file so that
	logging of past events may be reviewed. &os; has a built in
	facility to automatically rotate system logs. This is why
	outputting the log information to &man.syslogd.8; is better
	than the default of outputting to a regular file. The default
	<filename>rc.conf</filename>
	<literal>ipmon_flags</literal> statement uses
	<option>-Ds</option>:</para>

	<programlisting>ipmon_flags="-Ds" # D = start as daemon
	# s = log to syslog
	# v = log tcp window, ack, seq
	# n = map IP & port to names</programlisting>

	<para>Logging provides the ability to review, after the fact,
	information such as which packets were dropped, what addresses
	they came from and where they were going. These can all
	provide a significant edge in tracking down attackers.</para>

	<para>Even with the logging facility enabled, IPF will not
	generate any rule logging by default. The firewall
	administrator decides which rules in the ruleset should be
	logged and adds the log keyword to those rules. Normally,
	only deny rules are logged.</para>

	<para>It is customary to include a <quote>default deny
	everything</quote> rule with the log keyword included as the
	last rule in the ruleset. This makes it possible to see all
	the packets that did not match any of the rules in the
	ruleset.</para>
	</sect2>

	<sect2>
	<title>IPMON Logging</title>

	<para>&man.syslogd.8; uses its own method for segregation of log
	data. It uses groupings called <quote>facility</quote> and
	<quote>level</quote>. By default, IPMON in
	<option>-Ds</option> mode uses <literal>local0</literal> as
	the <quote>facility</quote> name. The following levels can be
	used to further segregate the logged data:</para>

	<screen>LOG_INFO - packets logged using the "log" keyword as the action rather than pass or block.
	LOG_NOTICE - packets logged which are also passed
	LOG_WARNING - packets logged which are also blocked
	LOG_ERR - packets which have been logged and which can be considered short</screen>

	<!-- XXX: "can be considered short" == "with incomplete header" -->

	<para>In order to setup IPFILTER to log all data to
	<filename>/var/log/ipfilter.log</filename>, first
	create the empty file:</para>

	<screen>&prompt.root; <userinput>touch /var/log/ipfilter.log</userinput></screen>

	<para>&man.syslogd.8; is controlled by definition statements in
	<filename>/etc/syslog.conf</filename>. This file offers
	considerable flexibility in how
	<application>syslog</application> will deal with system
	messages issued by software applications like IPF.</para>

	<para>To write all logged messages to the specified file,
	add the following statement to
	<filename>/etc/syslog.conf</filename>:</para>

	<programlisting>local0.* /var/log/ipfilter.log</programlisting>

	<para>To activate the changes and instruct &man.syslogd.8;
	to read the modified <filename>/etc/syslog.conf</filename>,
	run <command>service syslogd reload</command>.</para>

	<para>Do not forget to change
	<filename>/etc/newsyslog.conf</filename> to rotate the new
	log file.</para>
	</sect2>

	<sect2>
	<title>The Format of Logged Messages</title>

	<para>Messages generated by <command>ipmon</command> consist
	of data fields separated by white space. Fields common to
	all messages are:</para>

	<orderedlist>
	<listitem>
	<para>The date of packet receipt.</para>
	</listitem>

	<listitem>
	<para>The time of packet receipt. This is in the form
	HH:MM:SS.F, for hours, minutes, seconds, and fractions
	of a second.</para>
	</listitem>

	<listitem>
	<para>The name of the interface that processed the
	packet.</para>
	</listitem>

	<listitem>
	<para>The group and rule number of the rule in the format
	<literal>@0:17</literal>.</para>
	</listitem>
	</orderedlist>

	<para>These can be viewed with
	<command>ipfstat -in</command>.</para>

	<orderedlist>
	<listitem>
	<para>The action: <literal>p</literal> for passed,
	<literal>b</literal> for blocked, <literal>S</literal> for
	a short packet, <literal>n</literal> did not match any
	rules, and <literal>L</literal> for a log rule. The order
	of precedence in showing flags is: <literal>S</literal>,
	<literal>p</literal>, <literal>b</literal>,
	<literal>n</literal>, <literal>L</literal>. A capital
	<literal>P</literal> or <literal>B</literal> means that
	the packet has been logged due to a global logging
	setting, not a particular rule.</para>
	</listitem>

	<listitem>
	<para>The addresses written as three fields: the source
	address and port separated by a comma, the -> symbol,
	and the destination address and port. For example:
	<literal>209.53.17.22,80 ->
	198.73.220.17,1722</literal>.</para>
	</listitem>

	<listitem>
	<para><literal>PR</literal> followed by the protocol name
	or number: for example, <literal>PR tcp</literal>.</para>
	</listitem>

	<listitem>
	<para><literal>len</literal> followed by the header length
	and total length of the packet: for example,
	<literal>len 20 40</literal>.</para>
	</listitem>
	</orderedlist>

	<para>If the packet is a <acronym>TCP</acronym> packet, there
	will be an additional field starting with a hyphen followed by
	letters corresponding to any flags that were set. Refer to
	&man.ipf.5; for a list of letters and their flags.</para>

	<para>If the packet is an ICMP packet, there will be two fields
	at the end: the first always being <quote>ICMP</quote> and
	the next being the ICMP message and sub-message type,
	separated by a slash. For example: ICMP 3/3 for a port
	unreachable message.</para>
	</sect2>

	<sect2 id="firewalls-ipf-rules-script">
	<title>Building the Rule Script with Symbolic
	Substitution</title>

	<para>Some experienced IPF users create a file containing the
	rules and code them in a manner compatible with running them
	as a script with symbolic substitution. The major benefit
	of doing this is that only the value associated with the
	symbolic name needs to be changed, and when the script is
	run all the rules containing the symbolic name will have the
	value substituted in the rules. Being a script, symbolic
	substitution can be used to code frequently used values and
	substitute them in multiple rules. This can be seen in the
	following example.</para>

	<para>The script syntax used here is compatible with the
	&man.sh.1;, &man.csh.1;, and &man.tcsh.1; shells.</para>

	<para>Symbolic substitution fields are prefixed with a
	<literal>&dollar;</literal>.</para>

	<para>Symbolic fields do not have the &dollar; prefix.</para>

	<para>The value to populate the symbolic field must be enclosed
	between double quotes (<literal>"</literal>).</para>

	<para>Start the rule file with something like this:</para>

	<programlisting>############# Start of IPF rules script ########################

	oif="dc0" # name of the outbound interface
	odns="192.0.2.11" # ISP's DNS server IP address
	myip="192.0.2.7" # my static IP address from ISP
	ks="keep state"
	fks="flags S keep state"

	# You can choose between building /etc/ipf.rules file
	# from this script or running this script "as is".
	#
	# Uncomment only one line and comment out another.
	#
	# 1) This can be used for building /etc/ipf.rules:
	#cat > /etc/ipf.rules << EOF
	#
	# 2) This can be used to run script "as is":
	/sbin/ipf -Fa -f - << EOF

	# Allow out access to my ISP's Domain name server.
	pass out quick on &dollar;oif proto tcp from any to &dollar;odns port = 53 &dollar;fks
	pass out quick on &dollar;oif proto udp from any to &dollar;odns port = 53 &dollar;ks

	# Allow out non-secure standard www function
	pass out quick on &dollar;oif proto tcp from &dollar;myip to any port = 80 &dollar;fks

	# Allow out secure www function https over TLS SSL
	pass out quick on &dollar;oif proto tcp from &dollar;myip to any port = 443 &dollar;fks
	EOF
	################## End of IPF rules script ########################</programlisting>

	<para>The rules are not important in this example as it instead
	focuses on how the symbolic substitution fields are populated.
	If this example was in a file named
	<filename>/etc/ipf.rules.script</filename>, these rules could
	be reloaded by running:</para>

	<screen>&prompt.root; <userinput>sh /etc/ipf.rules.script</userinput></screen>

	<para>There is one problem with using a rules file with embedded
	symbolics: IPF does not understand symbolic substitution, and
	cannot read such scripts directly.</para>

	<para>This script can be used in one of two ways:</para>

	<itemizedlist>
	<listitem>
	<para>Uncomment the line that begins with
	<literal>cat</literal>, and comment out the line that
	begins with <literal>/sbin/ipf</literal>. Place
	<literal>ipfilter_enable="YES"</literal> into
	<filename>/etc/rc.conf</filename>, and run the script
	once after each modification to create or update
	<filename>/etc/ipf.rules</filename>.</para>
	</listitem>

	<listitem>
	<para>Disable IPFILTER in the system startup scripts by
	adding <literal>ipfilter_enable="NO"</literal>to
	<filename>/etc/rc.conf</filename>.</para>

	<para>Then, add a script like the following to <filename
	class="directory">/usr/local/etc/rc.d/</filename>.
	The script should have an obvious name like
	<filename>ipf.loadrules.sh</filename>, where the
	<filename>.sh</filename> extension is mandatory.</para>

	<programlisting>#!/bin/sh
	sh /etc/ipf.rules.script</programlisting>

	<para>The permissions on this script file must be read,
	write, execute for owner <username>root</username>:</para>

	<screen>&prompt.root; <userinput>chmod 700 /usr/local/etc/rc.d/ipf.loadrules.sh</userinput></screen>
	</listitem>
	</itemizedlist>

	<para>Now, when the system boots, the IPF rules will be
	loaded.</para>
	</sect2>

	<sect2>
	<title>IPF Rulesets</title>

	<para>A ruleset contains a group of IPF rules which pass or
	block packets based on the values contained in the packet.
	The bi-directional exchange of packets between hosts comprises
	a session conversation. The firewall ruleset processes both
	the packets arriving from the public Internet, as well as the
	packets produced by the system as a response to them.
	Each <acronym>TCP/IP</acronym> service is predefined by its
	protocol and listening port. Packets destined for a specific
	service originate from the source address using an
	unprivileged port and target the specific service port on the
	destination address. All the above parameters can be used as
	selection criteria to create rules which will pass or block
	services.</para>

	<indexterm>
	<primary>IPFILTER</primary>

	<secondary>rule processing order</secondary>
	</indexterm>

	<warning>
	<para>When working with the firewall rules, be <emphasis>very
	careful</emphasis>. Some configurations <emphasis>can
	lock the administrator out</emphasis> of the server. To be
	on the safe side, consider performing the initial firewall
	configuration from the local console rather than doing it
	remotely over <application>ssh</application>.</para>
	</warning>
	</sect2>

	<sect2>
	<title>Rule Syntax</title>

	<indexterm>
	<primary>IPFILTER</primary>

	<secondary>rule syntax</secondary>
	</indexterm>

	<para>The rule syntax presented here has been simplified to
	only address the modern stateful rule context and <quote>first
	matching rule wins</quote> logic. For the complete legacy
	rule syntax, refer to &man.ipf.8;.</para>

	<para>A <literal>#</literal> character is used to mark the
	start of a comment and may appear at the end of a rule line
	or on its own line. Blank lines are ignored.</para>

	<para>Rules contain keywords which must be written in a specific
	order from left to right on the line. Keywords are identified
	in bold type. Some keywords have sub-options which may be
	keywords themselves and also include more sub-options. Each
	of the headings in the below syntax has a bold section header
	which expands on the content.</para>

	<!-- This section is probably wrong. See the OpenBSD flag -->
	<!-- What is the "OpenBSD flag"? Reference please -->

	<para><replaceable>ACTION IN-OUT OPTIONS SELECTION STATEFUL
	PROTO SRC_ADDR,DST_ADDR OBJECT PORT_NUM TCP_FLAG
	STATEFUL</replaceable></para>

	<para><replaceable>ACTION</replaceable> = block \| pass</para>

	<para><replaceable>IN-OUT</replaceable> = in \| out</para>

	<para><replaceable>OPTIONS</replaceable> = log \| quick \| on
	interface-name</para>

	<para><replaceable>SELECTION</replaceable> = proto value \|
	source/destination IP \| port = number \| flags
	flag-value</para>

	<para><replaceable>PROTO</replaceable> = tcp/udp \| udp \| tcp \|
	icmp</para>

	<para><replaceable>SRC_ADD,DST_ADDR</replaceable> = all \| from
	object to object</para>

	<para><replaceable>OBJECT</replaceable> = IP address \|
	any</para>

	<para><replaceable>PORT_NUM</replaceable> = port number</para>

	<para><replaceable>TCP_FLAG</replaceable> = S</para>

	<para><replaceable>STATEFUL</replaceable> = keep state</para>

	<sect3>
	<title>ACTION</title>

	<para>The action keyword indicates what to do with the packet
	if it matches the rest of the filter rule. Each rule
	<emphasis>must</emphasis> have an action. The following
	actions are recognized:</para>

	<para><literal>block</literal> indicates that the packet
	should be dropped if the selection parameters match the
	packet.</para>

	<para><literal>pass</literal> indicates that the packet should
	exit the firewall if the selection parameters match the
	packet.</para>
	</sect3>

	<sect3>
	<title>IN-OUT</title>

	<para>A mandatory requirement is that each filter rule
	explicitly state which side of the I/O it is to be used
	on. The next keyword must be either <literal>in</literal>
	or <literal>out</literal> and one or the other has to be
	included or the rule will not pass syntax checks.</para>

	<para><literal>in</literal> means this rule is being applied
	against an inbound packet which has just been received on
	the interface facing the public Internet.</para>

	<para><literal>out</literal> means this rule is being applied
	against an outbound packet destined for the interface facing
	the public Internet.</para>
	</sect3>

	<sect3>
	<title>OPTIONS</title>

	<note>
	<para>These options must be used in the order shown
	here.</para>
	</note>

	<para><literal>log</literal> indicates that the packet header
	will be written to the &man.ipl.4; packet log pseudo-device
	if the selection parameters match the packet.</para>

	<para><literal>quick</literal> indicates that if the selection
	parameters match the packet, this rule will be the last
	rule checked, and no further processing of any following
	rules will occur for this packet.</para>

	<para><literal>on</literal> indicates the interface name to
	be incorporated into the selection parameters. Interface
	names are as displayed by &man.ifconfig.8;. Using this
	option, the rule will only match if the packet is going
	through that interface in the specified direction.</para>

	<para>When a packet is logged, the headers of the packet are
	written to the &man.ipl.4; packet logging pseudo-device.
	Immediately following the <literal>log</literal> keyword,
	the following qualifiers may be used in this order:</para>

	<para><literal>body</literal> indicates that the first 128
	bytes of the packet contents will be logged after the
	headers.</para>

	<para><literal>first</literal>. If the <literal>log</literal>
	keyword is being used in conjunction with a <literal>keep
	state</literal> option, this option is recommended so that
	only the triggering packet is logged and not every packet
	which matches the stateful connection.</para>
	</sect3>

	<sect3>
	<title>SELECTION</title>

	<para>The keywords described in this section are used to
	describe attributes of the packet to be checked when
	determining whether or not rules match. There is a
	keyword subject, and it has sub-option keywords, one of
	which has to be selected. The following general-purpose
	attributes are provided for matching, and must be used in
	this order:</para>
	</sect3>

	<sect3>
	<title>PROTO</title>

	<para><literal>proto</literal> is the subject keyword which
	must include one of its corresponding keyword sub-option
	values. The sub-option indicates a specific protocol to be
	matched against.</para>

	<para><literal>tcp/udp \| udp \| tcp \| icmp</literal> or any
	protocol names found in <filename>/etc/protocols</filename>
	are recognized and may be used. The special protocol
	keyword <literal>tcp/udp</literal> may be used to match
	either a <acronym>TCP</acronym> or a <acronym>UDP</acronym>
	packet, and has been added as a convenience to save
	duplication of otherwise identical rules.</para>
	</sect3>

	<sect3>
	<title>SRC_ADDR/DST_ADDR</title>

	<para>The <literal>all</literal> keyword is equivalent to
	<quote>from any to any</quote> with no other match
	parameters.</para>

	<para><literal>from \| to src to dst</literal>: the
	<literal>from</literal> and <literal>to</literal>
	keywords are used to match against IP addresses. Rules
	must specify <emphasis>both</emphasis> the source and
	destination parameters. <literal>any</literal> is a special
	keyword that matches any IP address. Examples include:
	<literal>from any to any</literal>, <literal>from 0.0.0.0/0
	to any</literal>, <literal>from any to
	0.0.0.0/0</literal>, <literal>from 0.0.0.0 to
	any</literal>, and <literal>from any to
	0.0.0.0</literal>.</para>

	<para>There is no way to match ranges of IP addresses which
	do not express themselves easily using the dotted numeric
	form / mask-length notation. The <filename
	role="package">net-mgmt/ipcalc</filename> port may be
	used to ease the calculation. Additional information
	is available at the utility's web page: <ulink
	url="http://jodies.de/ipcalc"></ulink>.</para>
	</sect3>

	<sect3>
	<title>PORT</title>

	<para>If a port match is included, for either or both of
	source and destination, it is only applied to
	<acronym>TCP</acronym> and <acronym>UDP</acronym> packets.
	When composing port comparisons, either the service name
	from <filename>/etc/services</filename> or an integer port
	number may be used. When the port appears as part of the
	<literal>from</literal> object, it matches the source port
	number. When it appears as part of the
	<literal>to</literal> object, it matches the destination
	port number. An example usage is <literal>from any to any
	port = 80</literal></para>

	<para>Single port comparisons may be done in a number of ways,
	using a number of different comparison operators. Instead
	of the <literal>=</literal> shown in the example above,
	the following operators may be used: <literal>!=</literal>,
	<literal><</literal>, <literal>></literal>,
	<literal><=</literal>, <literal>>=</literal>,
	<literal>eq</literal>, <literal>ne</literal>,
	<literal>lt</literal>, <literal>gt</literal>,
	<literal>le</literal>, and <literal>ge</literal>.</para>

	<para>To specify port ranges, place the two port numbers
	between <literal><></literal> or
	<literal>><</literal></para>
	</sect3>

	<sect3>
	<title><acronym>TCP</acronym>_FLAG</title>

	<para>Flags are only effective for <acronym>TCP</acronym>
	filtering. The letters represent one of the possible flags
	that can be matched against the <acronym>TCP</acronym>
	packet header.</para>

	<para>The modernized rules processing logic uses the
	<literal>flags S</literal> parameter to identify the TCP
	session start request.</para>
	</sect3>

	<sect3>
	<title>STATEFUL</title>

	<para><literal>keep state</literal> indicates that on a pass
	rule, any packets that match the rules selection parameters
	should activate the stateful filtering facility.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Stateful Filtering</title>

	<indexterm>
	<primary>IPFILTER</primary>

	<secondary>stateful filtering</secondary>
	</indexterm>

	<!-- XXX: duplicated -->

	<para>Stateful filtering treats traffic as a bi-directional
	exchange of packets comprising a session. When activated,
	<literal>keep-state</literal> dynamically generates
	internal rules for each anticipated packet being exchanged
	during the session. It has sufficient matching capabilities
	to determine if a packet is valid for a session. Any packets
	that do not properly fit the session template are
	automatically rejected.</para>

	<para>IPF stateful filtering will also allow
	<acronym>ICMP</acronym> packets related to an existing
	<acronym>TCP</acronym> or <acronym>UDP</acronym> session. So,
	if an <acronym>ICMP</acronym> type 3 code 4 packet is a
	response in a session started by a keep state rule, it will
	automatically be allowed. Any packet that IPF can be certain
	is part of an active session, even if it is a different
	protocol, will be allowed.</para>

	<para>Packets destined to go out through the interface connected
	to the public Internet are first checked against the dynamic
	state table. If the packet matches the next expected packet
	comprising an active session conversation, it exits the
	firewall and the state of the session conversation flow is
	updated in the dynamic state table. Packets that do not
	belong to an already active session, are checked against the
	outbound ruleset.</para>

	<para>Packets coming in from the interface connected to the
	public Internet are first checked against the dynamic state
	table. If the packet matches the next expected packet
	comprising an active session, it exits the firewall and the
	state of the session conversation flow is updated in the
	dynamic state table. Packets that do not belong to an already
	active session, are checked against the inbound
	ruleset.</para>

	<para>When the session completes, it is removed from the
	dynamic state table.</para>

	<para>Stateful filtering allows one to focus on blocking/passing
	new sessions. If the new session is passed, all its
	subsequent packets are allowed automatically and any impostor
	packets are automatically rejected. If a new session is
	blocked, none of its subsequent packets are allowed. Stateful
	filtering provides advanced matching abilities capable of
	defending against the flood of different attack methods
	employed by attackers.</para>
	</sect2>

	<sect2>
	<!-- XXX: This section needs a rewrite -->

	<title>Inclusive Ruleset Example</title>

	<para>The following ruleset is an example of an inclusive type
	of firewall which only allows services matching
	<literal>pass</literal> rules and blocks all others by
	default. Network firewalls intended to protect other machines
	should have at least two interfaces, and are generally
	configured to trust the <acronym>LAN</acronym> and to not
	trust the public Internet. Alternatively, a host based
	firewall might be configured to protect only the system it is
	running on, and is appropriate for servers on an untrusted
	network or a desktop system not protected by firewall on the
	network.</para>

	<para>&os; uses interface <devicename>lo0</devicename> and IP
	address <hostid role="ipaddr">127.0.0.1</hostid> for internal
	communication within the operating system. The firewall rules
	must contain rules to allow free movement of these internally
	used packets.</para>

	<para>The interface which faces the public Internet is the one
	specified in the rules that authorize and control access of
	the outbound and inbound connections.</para>

	<para>In cases where one or more NICs are cabled to private
	network segments, those interfaces may require rules to allow
	packets originating from those LAN interfaces transit to each
	other or to the Internet.</para>

	<para>The rules should be organized into three major
	sections: the trusted interfaces, then the public
	interface outbound, and lastly, the public untrusted interface
	inbound.</para>

	<para>The rules in each of the public interface sections should
	have the most frequently matched rules placed before less
	commonly matched rules, with the last rule in the section
	blocking and logging all packets on that interface and
	direction.</para>

	<para>The outbound section in the following ruleset only
	contains <literal>pass</literal> rules which uniquely identify
	the services that are authorized for public Internet access.
	All the rules use <literal>quick</literal>,
	<literal>on</literal>, <literal>proto</literal>,
	<literal>port</literal>, and <literal>keep state</literal>.
	The <literal>proto tcp</literal> rules include
	<literal>flag</literal> to identify the session start request
	as the triggering packet to activate the stateful
	facility.</para>

	<para>The inbound section blocks undesirable packets first, for
	two different reasons. The first is that malicious packets
	may be partial matches for legitimate traffic. These packets
	have to be discarded rather than allowed, based on their
	partial matches against the <literal>allow</literal> rules.
	The second reason is that known and uninteresting rejects may
	be blocked silently, rather than being logged by the last rule
	in the section.</para>

	<para>The ruleset should ensure that there is no response
	returned for any undesirable traffic. Invalid packets should
	be silently dropped so that the attacker has no knowledge if
	the packets reached the system. Rules that include a
	<literal>log first</literal> option, will only log the event
	the first time they are triggered. This option is included in
	the sample <literal>nmap OS fingerprint</literal> rule. The
	<filename role="package">security/nmap</filename> utility is
	commonly used by attackers who attempt to identify the
	operating system of the server.</para>

	<para>Any time there are logged messages on a rule with
	the <literal>log first</literal> option,
	<command>ipfstat -hio</command> should be executed
	to evaluate how many times the rule has been matched. A
	large number of matches usually indicates that the system is
	being flooded or is under attack.</para>

	<para>To lookup unknown port numbers, refer to
	<filename>/etc/services</filename>. Alternatively, visit
	<ulink
	url="http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers"></ulink>
	and do a port number lookup to find the purpose of a
	particular port number.</para>

	<para>Check out this link for port numbers used by Trojans
	<ulink
	url="http://www.sans.org/security-resources/idfaq/oddports.php"></ulink>.</para>

	<para>The following ruleset creates an
	<literal>inclusive</literal> firewall ruleset which can be
	easily customized by commenting out
	<literal>pass</literal> rules for services that should not
	be authorized.</para>

	<para>To avoid logging unwanted messages, add a
	<literal>block</literal> rule in the inbound section.</para>

	<para>Change the <devicename>dc0</devicename> interface name in
	every rule to the interface name that connects the system to
	the public Internet.</para>

	<para>The following statements were added to
	<filename>/etc/ipf.rules</filename>:</para>

	<programlisting>#################################################################
	# No restrictions on Inside LAN Interface for private network
	# Not needed unless you have LAN
	#################################################################

	#pass out quick on xl0 all
	#pass in quick on xl0 all

	#################################################################
	# No restrictions on Loopback Interface
	#################################################################
	pass in quick on lo0 all
	pass out quick on lo0 all

	#################################################################
	# Interface facing Public Internet (Outbound Section)
	# Match session start requests originating from behind the
	# firewall on the private network
	# or from this gateway server destined for the public Internet.
	#################################################################

	# Allow out access to my ISP's Domain name server.
	# xxx must be the IP address of your ISP's DNS.
	# Dup these lines if your ISP has more than one DNS server
	# Get the IP addresses from /etc/resolv.conf file
	pass out quick on dc0 proto tcp from any to xxx port = 53 flags S keep state
	pass out quick on dc0 proto udp from any to xxx port = 53 keep state

	# Allow out access to my ISP's DHCP server for cable or DSL networks.
	# This rule is not needed for 'user ppp' type connection to the
	# public Internet, so you can delete this whole group.
	# Use the following rule and check log for IP address.
	# Then put IP address in commented out rule & delete first rule
	pass out log quick on dc0 proto udp from any to any port = 67 keep state
	#pass out quick on dc0 proto udp from any to z.z.z.z port = 67 keep state


	# Allow out non-secure standard www function
	pass out quick on dc0 proto tcp from any to any port = 80 flags S keep state

	# Allow out secure www function https over TLS SSL
	pass out quick on dc0 proto tcp from any to any port = 443 flags S keep state

	# Allow out send & get email function
	pass out quick on dc0 proto tcp from any to any port = 110 flags S keep state
	pass out quick on dc0 proto tcp from any to any port = 25 flags S keep state

	# Allow out Time
	pass out quick on dc0 proto tcp from any to any port = 37 flags S keep state

	# Allow out nntp news
	pass out quick on dc0 proto tcp from any to any port = 119 flags S keep state

	# Allow out gateway & LAN users' non-secure FTP ( both passive & active modes)
	# This function uses the IP<acronym>NAT</acronym> built in FTP proxy function coded in
	# the nat rules file to make this single rule function correctly.
	# If you want to use the pkg_add command to install application packages
	# on your gateway system you need this rule.
	pass out quick on dc0 proto tcp from any to any port = 21 flags S keep state

	# Allow out ssh/sftp/scp (telnet/rlogin/FTP replacements)
	# This function is using SSH (secure shell)
	pass out quick on dc0 proto tcp from any to any port = 22 flags S keep state

	# Allow out insecure Telnet
	pass out quick on dc0 proto tcp from any to any port = 23 flags S keep state

	# Allow out FreeBSD CVSup
	pass out quick on dc0 proto tcp from any to any port = 5999 flags S keep state

	# Allow out ping to public Internet
	pass out quick on dc0 proto icmp from any to any icmp-type 8 keep state

	# Allow out whois from LAN to public Internet
	pass out quick on dc0 proto tcp from any to any port = 43 flags S keep state

	# Block and log only the first occurrence of everything
	# else that's trying to get out.
	# This rule implements the default block
	block out log first quick on dc0 all

	#################################################################
	# Interface facing Public Internet (Inbound Section)
	# Match packets originating from the public Internet
	# destined for this gateway server or the private network.
	#################################################################

	# Block all inbound traffic from non-routable or reserved address spaces
	block in quick on dc0 from 192.168.0.0/16 to any #RFC 1918 private IP
	block in quick on dc0 from 172.16.0.0/12 to any #RFC 1918 private IP
	block in quick on dc0 from 10.0.0.0/8 to any #RFC 1918 private IP
	block in quick on dc0 from 127.0.0.0/8 to any #loopback
	block in quick on dc0 from 0.0.0.0/8 to any #loopback
	block in quick on dc0 from 169.254.0.0/16 to any #DHCP auto-config
	block in quick on dc0 from 192.0.2.0/24 to any #reserved for docs
	block in quick on dc0 from 204.152.64.0/23 to any #Sun cluster interconnect
	block in quick on dc0 from 224.0.0.0/3 to any #Class D & E multicast

	##### Block a bunch of different nasty things. ############
	# That I do not want to see in the log

	# Block frags
	block in quick on dc0 all with frags

	# Block short tcp packets
	block in quick on dc0 proto tcp all with short

	# block source routed packets
	block in quick on dc0 all with opt lsrr
	block in quick on dc0 all with opt ssrr

	# Block nmap OS fingerprint attempts
	# Log first occurrence of these so I can get their IP address
	block in log first quick on dc0 proto tcp from any to any flags FUP

	# Block anything with special options
	block in quick on dc0 all with ipopts

	# Block public pings
	block in quick on dc0 proto icmp all icmp-type 8

	# Block ident
	block in quick on dc0 proto tcp from any to any port = 113

	# Block all Netbios service. 137=name, 138=datagram, 139=session
	# Netbios is MS/Windows sharing services.
	# Block MS/Windows hosts2 name server requests 81
	block in log first quick on dc0 proto tcp/udp from any to any port = 137
	block in log first quick on dc0 proto tcp/udp from any to any port = 138
	block in log first quick on dc0 proto tcp/udp from any to any port = 139
	block in log first quick on dc0 proto tcp/udp from any to any port = 81

	# Allow traffic in from ISP's DHCP server. This rule must contain
	# the IP address of your ISP's DHCP server as it is the only
	# authorized source to send this packet type. Only necessary for
	# cable or DSL configurations. This rule is not needed for
	# 'user ppp' type connection to the public Internet.
	# This is the same IP address you captured and
	# used in the outbound section.
	pass in quick on dc0 proto udp from z.z.z.z to any port = 68 keep state

	# Allow in standard www function because I have apache server
	pass in quick on dc0 proto tcp from any to any port = 80 flags S keep state

	# Allow in non-secure Telnet session from public Internet
	# labeled non-secure because ID/PW passed over public Internet as clear text.
	# Delete this sample group if you do not have telnet server enabled.
	#pass in quick on dc0 proto tcp from any to any port = 23 flags S keep state

	# Allow in secure FTP, Telnet, and SCP from public Internet
	# This function is using SSH (secure shell)
	pass in quick on dc0 proto tcp from any to any port = 22 flags S keep state

	# Block and log only first occurrence of all remaining traffic
	# coming into the firewall. The logging of only the first
	# occurrence avoids filling up disk with Denial of Service logs.
	# This rule implements the default block.
	block in log first quick on dc0 all
	################### End of rules file #####################################</programlisting>
	</sect2>

	<sect2>
	<title><acronym>NAT</acronym></title>

	<indexterm><primary>NAT</primary></indexterm>

	<indexterm>
	<primary>IP masquerading</primary>

	<see>NAT</see>
	</indexterm>

	<indexterm>
	<primary>network address translation</primary>

	<see>NAT</see>
	</indexterm>

	<para><acronym>NAT</acronym> stands for <emphasis>Network
	Address Translation</emphasis>. In &linux;, NAT is called
	<quote>IP Masquerading</quote>. The IPF
	<acronym>NAT</acronym> function enables the private LAN behind
	the firewall to share a single ISP-assigned IP address, even
	if that address is dynamically assigned. NAT allows each
	computer in the LAN to have Internet access, without
	having to pay the ISP for multiple Internet accounts or IP
	addresses.</para>

	<para><acronym>NAT</acronym> will automatically translate the
	private LAN IP address for each system on the LAN to the
	single public IP address as packets exit the firewall bound
	for the public Internet. It also performs the reverse
	translation for returning packets.</para>

	<para>According to RFC 1918, the following IP address ranges are
	reserved for private networks which will never be routed
	directly to the public Internet, and therefore are available
	for use with NAT:</para>

	<itemizedlist>
	<listitem>
	<para><literal>10.0.0.0/8</literal>.</para>
	</listitem>

	<listitem>
	<para><literal>172.16.0.0/12</literal>.</para>
	</listitem>

	<listitem>
	<para><literal>192.168.0.0/16</literal>.</para>
	</listitem>
	</itemizedlist>

	</sect2>

	<sect2>
	<title>IP<acronym>NAT</acronym></title>

	<indexterm>
	<primary>NAT</primary>

	<secondary>and IPFILTER</secondary>
	</indexterm>

	<indexterm><primary><command>ipnat</command></primary></indexterm>

	<para><acronym>NAT</acronym> rules are loaded using
	<command>ipnat</command>. Typically, the
	<acronym>NAT</acronym> rules are stored in
	<filename>/etc/ipnat.rules</filename>. See &man.ipnat.8; for
	details.</para>

	<para>When the file containing the <acronym>NAT</acronym> rules
	is edited after <acronym>NAT</acronym> has been started, run
	<command>ipnat</command> with <option>-CF</option> to delete
	the internal in use <acronym>NAT</acronym> rules and flush the
	contents of the translation table of all active
	entries.</para>

	<para>To reload the <acronym>NAT</acronym> rules, issue a
	command like this:</para>

	<screen>&prompt.root; <userinput>ipnat -CF -f
	/etc/ipnat.rules</userinput></screen>

	<para>To display some <acronym>NAT</acronym> statistics, use
	this command:</para>

	<screen>&prompt.root; <userinput>ipnat -s</userinput></screen>

	<para>To list the <acronym>NAT</acronym> table's current
	mappings, use this command:</para>

	<screen>&prompt.root; <userinput>ipnat -l</userinput></screen>

	<para>To turn verbose mode on and display information relating
	to rule processing and active rules/table entries:</para>

	<screen>&prompt.root; <userinput>ipnat -v</userinput></screen>
	</sect2>

	<sect2>
	<title>IP<acronym>NAT</acronym> Rules</title>

	<para><acronym>NAT</acronym> rules are flexible and can
	accomplish many different things to fit the needs of
	commercial and home users.</para>

	<para>The rule syntax presented here has been simplified to
	what is most commonly used in a non-commercial environment.
	For a complete rule syntax description, refer to
	&man.ipnat.5;.</para>

	<para>The syntax for a <acronym>NAT</acronym> rule looks like
	this:</para>

	<programlisting>map <replaceable>IF</replaceable> <replaceable>LAN_IP_RANGE</replaceable> -> <replaceable>PUBLIC_ADDRESS</replaceable></programlisting>

	<para>The keyword <literal>map</literal> starts the rule.</para>

	<para>Replace <replaceable>IF</replaceable> with the external
	interface.</para>

	<para>The <replaceable>LAN_IP_RANGE</replaceable> is used by the
	internal clients use for IP Addressing. Usually, this is
	something like <hostid
	role="ipaddr">192.168.1.0/24</hostid>.</para>

	<para>The <replaceable>PUBLIC_ADDRESS</replaceable> can either
	be the static external IP address or the special keyword
	<literal>0/32</literal> which uses the IP address assigned to
	<replaceable>IF</replaceable>.</para>
	</sect2>

	<sect2>
	<title>How <acronym>NAT</acronym> Works</title>

	<para>In IPF, when a packet arrives at the firewall from the LAN
	with a public destination, it passes through the outbound
	filter rules. <acronym>NAT</acronym> gets its turn at the
	packet and applies its rules top down, where the first
	matching rule wins. <acronym>NAT</acronym> tests each of its
	rules against the packet's interface name and source IP
	address. When a packet's interface name matches a
	<acronym>NAT</acronym> rule, the packet's source IP address in
	the private LAN is checked to see if it falls within the IP
	address range specified to the left of the arrow symbol on the
	<acronym>NAT</acronym> rule. On a match, the packet has its
	source IP address rewritten with the public IP address
	obtained by the <literal>0/32</literal> keyword.
	<acronym>NAT</acronym> posts an entry in its internal
	<acronym>NAT</acronym> table so when the packet returns from
	the public Internet it can be mapped back to its original
	private IP address and then passed to the filter rules for
	processing.</para>
	</sect2>

	<sect2>
	<title>Enabling IP<acronym>NAT</acronym></title>

	<para>To enable IP<acronym>NAT</acronym>, add these statements
	to <filename>/etc/rc.conf</filename>.</para>

	<para>To enable the machine to route traffic between
	interfaces:</para>

	<programlisting>gateway_enable="YES"</programlisting>

	<para>To start IP<acronym>NAT</acronym> automatically each
	time:</para>

	<programlisting>ipnat_enable="YES"</programlisting>

	<para>To specify where to load the IP<acronym>NAT</acronym>
	rules from:</para>

	<programlisting>ipnat_rules="/etc/ipnat.rules"</programlisting>
	</sect2>

	<sect2>
	<title><acronym>NAT</acronym> for a Large LAN</title>

	<para>For networks that have large numbers of systems on the LAN
	or networks with more than a single LAN, the process of
	funneling all those private IP addresses into a single public
	IP address becomes a resource problem that may cause problems
	with the same port numbers being used many times across many
	connections, causing collisions. There are two ways to
	relieve this resource problem.</para>

	<sect3>
	<title>Assigning Ports to Use</title>

	<para>A normal NAT rule would look like:</para>

	<programlisting>map dc0 192.168.1.0/24 -> 0/32</programlisting>

	<para>In the above rule, the packet's source port is unchanged
	as the packet passes through IP<acronym>NAT</acronym>. By
	adding the <literal>portmap</literal> keyword,
	IP<acronym>NAT</acronym> can be directed to only use
	source ports in the specified range. For example, the
	following rule will tell IP<acronym>NAT</acronym> to modify
	the source port to be within the range shown:</para>

	<programlisting>map dc0 192.168.1.0/24 -> 0/32 portmap tcp/udp 20000:60000</programlisting>

	<para>Additionally, the <literal>auto</literal> keyword tells
	IP<acronym>NAT</acronym> to determine which ports are
	available for use:</para>

	<programlisting>map dc0 192.168.1.0/24 -> 0/32 portmap tcp/udp auto</programlisting>
	</sect3>

	<sect3>
	<title>Using a Pool of Public Addresses</title>

	<para>In very large LANs there comes a point where there are
	just too many LAN addresses to fit into a single public
	address. If a block of public IP addresses is available,
	these addresses can be used as a <quote>pool</quote>, and
	IP<acronym>NAT</acronym> may pick one of the public IP
	addresses as packet addresses are mapped on their way
	out.</para>

	<para>For example, instead of mapping all packets through a
	single public IP address:</para>

	<programlisting>map dc0 192.168.1.0/24 -> 204.134.75.1</programlisting>

	<para>A range of public IP addresses can be specified either
	with a netmask:</para>

	<programlisting>map dc0 192.168.1.0/24 -> 204.134.75.0/255.255.255.0</programlisting>

	<para>or using CIDR notation:</para>

	<programlisting>map dc0 192.168.1.0/24 -> 204.134.75.0/24</programlisting>
	</sect3>
	</sect2>

	<sect2>
	<title>Port Redirection</title>

	<para>A common practice is to have a web server, email server,
	database server, and DNS server each segregated to a different
	system on the LAN. In this case, the traffic from these
	servers still has to undergo <acronym>NAT</acronym>, but there
	has to be some way to direct the inbound traffic to the
	correct server. For example, a web server operating on LAN
	address <hostid
	role="ipaddr">10.0.10.25</hostid> and using a single public
	IP address of <hostid role="ipaddr">20.20.20.5</hostid>, would
	use this rule:</para>

	<programlisting>rdr dc0 20.20.20.5/32 port 80 -> 10.0.10.25 port 80</programlisting>

	<para>or:</para>

	<programlisting>rdr dc0 0.0.0.0/0 port 80 -> 10.0.10.25 port 80</programlisting>

	<para>For a LAN DNS server on a private address of <hostid
	role="ipaddr">10.0.10.33</hostid> that needs to receive
	public DNS requests:</para>

	<programlisting>rdr dc0 20.20.20.5/32 port 53 -> 10.0.10.33 port 53 udp</programlisting>
	</sect2>

	<sect2>
	<title>FTP and <acronym>NAT</acronym></title>

	<para>FTP has two modes: active mode and passive mode. The
	difference is in how the data channel is acquired. Passive
	mode is more secure as the data channel is acquired by the
	ordinal ftp session requester. For a good explanation of FTP
	and the different modes, see <ulink
	url="http://www.slacksite.com/other/ftp.html"></ulink>.</para>

	<sect3>
	<title>IP<acronym>NAT</acronym> Rules</title>

	<para>IP<acronym>NAT</acronym> has a built in FTP proxy option
	which can be specified on the <acronym>NAT</acronym> map
	rule. It can monitor all outbound packet traffic for FTP
	active or passive start session requests and dynamically
	create temporary filter rules containing the port number
	being used by the data channel. This eliminates the
	security risk FTP normally exposes the firewall to as it no
	longer needs to open large ranges of high order ports for
	FTP connections.</para>

	<para>This rule will handle all the traffic for the internal
	LAN:</para>

	<programlisting>map dc0 10.0.10.0/29 -> 0/32 proxy port 21 ftp/tcp</programlisting>

	<para>This rule handles the FTP traffic from the
	gateway:</para>

	<programlisting>map dc0 0.0.0.0/0 -> 0/32 proxy port 21 ftp/tcp</programlisting>

	<para>This rule handles all non-FTP traffic from the internal
	LAN:</para>

	<programlisting>map dc0 10.0.10.0/29 -> 0/32</programlisting>

	<para>The FTP <literal>map</literal> rules go before the
	<acronym>NAT</acronym> rule so that when a packet matches an
	FTP rule, the FTP proxy creates temporary filter rules to
	let the FTP session packets pass and undergo
	<acronym>NAT</acronym>. All LAN packets that are not FTP
	will not match the FTP rules but will undergo
	<acronym>NAT</acronym> if they match the third rule.</para>
	</sect3>

	<sect3>
	<title>IP<acronym>NAT</acronym> FTP Filter Rules</title>

	<para>Only one filter rule is needed for FTP if the
	<acronym>NAT</acronym> FTP proxy is used.</para>

	<para>Without the FTP proxy, the following three rules will be
	needed:</para>

	<programlisting># Allow out LAN PC client FTP to public Internet
	# Active and passive modes
	pass out quick on rl0 proto tcp from any to any port = 21 flags S keep state

	# Allow out passive mode data channel high order port numbers
	pass out quick on rl0 proto tcp from any to any port > 1024 flags S keep state

	# Active mode let data channel in from FTP server
	pass in quick on rl0 proto tcp from any to any port = 20 flags S keep state</programlisting>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="firewalls-ipfw">
	<title>IPFW</title>

	<indexterm>
	<primary>firewall</primary>

	<secondary>IPFW</secondary>
	</indexterm>

	<para><acronym>IPFW</acronym>) is a stateful firewall written for
	&os; which also provides a traffic shaper, packet scheduler,
	and in-kernel NAT.</para>

	<para>&os; provides a sample ruleset in
	<filename>/etc/rc.firewall</filename>. The sample ruleset
	define several firewall types for common scenarios to assist
	novice users in generating an appropriate ruleset.
	&man.ipfw.8; provides a powerful syntax which advanced users can
	use to craft customized rulesets that meet the security
	requirements of a given environment.</para>

	<para>IPFW is composed of several components: the kernel firewall
	filter rule processor and its integrated packet accounting
	facility, the logging facility, the
	<literal>divert</literal> rule which triggers
	<acronym>NAT</acronym>, the dummynet traffic shaper facilities,
	the <literal>fwd rule</literal> forward facility, the bridge
	facility, and the ipstealth facility. IPFW supports both IPv4
	and IPv6.</para>

	<sect2 id="firewalls-ipfw-enable">
	<title>Enabling IPFW</title>

	<indexterm>
	<primary>IPFW</primary>

	<secondary>enabling</secondary>
	</indexterm>

	<para>IPFW is included in the basic &os; install as a run time
	loadable module. The system will dynamically load the kernel
	module when <filename>rc.conf</filename> contains the
	statement <literal>firewall_enable="YES"</literal>. After
	rebooting the system, the following white highlighted message
	is displayed on the screen as part of the boot process:</para>

	<screen>ipfw2 initialized, divert disabled, rule-based forwarding disabled, default to deny, logging disabled</screen>

	<para>The loadable module includes logging ability. To enable
	logging and set the verbose logging limit, add these
	statements to
	<filename>/etc/sysctl.conf</filename> before rebooting:</para>

	<programlisting>net.inet.ip.fw.verbose=1
	net.inet.ip.fw.verbose_limit=5</programlisting>
	</sect2>

	<sect2 id="firewalls-ipfw-kernel">
	<title>Kernel Options</title>

	<indexterm>
	<primary>kernel options</primary>

	<secondary>IPFIREWALL</secondary>
	</indexterm>

	<indexterm>
	<primary>kernel options</primary>

	<secondary>IPFIREWALL_VERBOSE</secondary>
	</indexterm>

	<indexterm>
	<primary>kernel options</primary>

	<secondary>IPFIREWALL_VERBOSE_LIMIT</secondary>
	</indexterm>

	<indexterm>
	<primary>IPFW</primary>

	<secondary>kernel options</secondary>
	</indexterm>

	<para>For those users who wish to statically compile kernel
	IPFW support, the following options are available for the
	custom kernel configuration file:</para>

	<programlisting>options IPFIREWALL</programlisting>

	<para>This option enables IPFW as part of the kernel.</para>

	<programlisting>options IPFIREWALL_VERBOSE</programlisting>

	<para>This option enables logging of packets that pass through
	IPFW and have the <literal>log</literal> keyword specified in
	the ruleset.</para>

	<programlisting>options IPFIREWALL_VERBOSE_LIMIT=5</programlisting>

	<para>This option limits the number of packets logged through
	&man.syslogd.8;, on a per-entry basis. This option may be
	used in hostile environments, when firewall activity logging
	is desired. This will close a possible denial of service
	attack via syslog flooding.</para>

	<indexterm>
	<primary>kernel options</primary>

	<secondary>IPFIREWALL_DEFAULT_TO_ACCEPT</secondary>
	</indexterm>

	<programlisting>options IPFIREWALL_DEFAULT_TO_ACCEPT</programlisting>

	<para>This option allows everything to pass through the firewall
	by default, which is a good idea when the firewall is being
	set up for the first time.</para>

	<indexterm>
	<primary>kernel options</primary>

	<secondary>IPDIVERT</secondary>
	</indexterm>

	<programlisting>options IPDIVERT</programlisting>

	<para>This option enables the use of <acronym>NAT</acronym>
	functionality.</para>

	<note>
	<para>The firewall will block all incoming and outgoing
	packets if either the
	<literal>IPFIREWALL_DEFAULT_TO_ACCEPT</literal> kernel
	option or a rule to explicitly allow these connections is
	missing.</para>
	</note>
	</sect2>

	<sect2 id="firewalls-ipfw-rc">
	<title><filename>/etc/rc.conf</filename> Options</title>

	<para>Enables the firewall:</para>

	<programlisting>firewall_enable="YES"</programlisting>

	<para>To select one of the default firewall types provided by
	&os;, select one by reading
	<filename>/etc/rc.firewall</filename> and specify it in
	the following:</para>

	<programlisting>firewall_type="open"</programlisting>

	<para>Available values for this setting are:</para>

	<itemizedlist>
	<listitem>
	<para><literal>open</literal>: passes all traffic.</para>
	</listitem>
	<listitem>
	<para><literal>client</literal>: protects only this
	machine.</para>
	</listitem>
	<listitem>
	<para><literal>simple</literal>: protects the whole
	network.</para>
	</listitem>
	<listitem>
	<para><literal>closed</literal>: entirely disables IP
	traffic except for the loopback interface.</para>
	</listitem>
	<listitem>
	<para><literal>UNKNOWN</literal>: disables the loading of
	firewall rules.</para>
	</listitem>
	<listitem>
	<para><filename><replaceable>filename</replaceable></filename>:
	absolute path of the file containing the firewall
	rules.</para>
	</listitem>
	</itemizedlist>

	<para>Two methods are available for loading custom
	<application>ipfw</application> rules. One is to set the
	<literal>firewall_type</literal> variable to the absolute
	path of the file which contains the firewall rules.</para>

	<para>The other method is to set the
	<literal>firewall_script</literal> variable to the absolute
	path of an executable script that includes
	<command>ipfw</command> commands. A ruleset script that
	blocks all incoming and outgoing traffic would look like
	this:</para>

	<programlisting>#!/bin/sh

	ipfw -q flush

	ipfw add deny in
	ipfw add deny out</programlisting>

	<note>
	<para>If <literal>firewall_type</literal> is set to either
	<literal>client</literal> or <literal>simple</literal>,
	modify the default rules found in
	<filename>/etc/rc.firewall</filename> to fit the
	configuration of the system. The examples used in this
	section assume that the <literal>firewall_script</literal>
	is set to <filename>/etc/ipfw.rules</filename>.</para>
	</note>

	<para>Enable logging:</para>

	<programlisting>firewall_logging="YES"</programlisting>

	<warning>
	<para><varname>firewall_logging</varname> sets the
	<varname>net.inet.ip.fw.verbose</varname> sysctl
	variable to the value of <literal>1</literal>. There is no
	<filename>rc.conf</filename> variable to set log
	limitations, but the desired value can be set using
	<command>sysctl</command> or by adding the following
	variable and desired value to
	<filename>/etc/sysctl.conf</filename>:</para>

	<programlisting>net.inet.ip.fw.verbose_limit=5</programlisting>
	</warning>

	<para>If the machine is acting as a gateway providing
	<acronym>NAT</acronym> using &man.natd.8;,
	refer to <link linkend="network-natd"></link> for information
	regarding the required <filename>/etc/rc.conf</filename>
	options.</para>
	</sect2>

	<sect2 id="firewalls-ipfw-cmd">
	<title>The IPFW Command</title>

	<indexterm><primary><command>ipfw</command></primary></indexterm>

	<para><command>ipfw</command> can be used to make manual,
	single rule additions or deletions to the active firewall
	while it is running. The problem with using this method is
	that all the changes are lost when the system reboots. It is
	recommended to instead write all the rules in a file and to
	use that file to load the rules at boot time and to replace
	the currently running firewall rules whenever that file
	changes.</para>

	<para><command>ipfw</command> is a useful way to display the
	running firewall rules to the console screen. The IPFW
	accounting facility dynamically creates a counter for each
	rule that counts each packet that matches the rule. During
	the process of testing a rule, listing the rule with its
	counter is one way to determine if the rule is
	functioning as expected.</para>

	<para>To list all the running rules in sequence:</para>

	<screen>&prompt.root; <userinput>ipfw list</userinput></screen>

	<para>To list all the running rules with a time stamp of when
	the last time the rule was matched:</para>

	<screen>&prompt.root; <userinput>ipfw -t list</userinput></screen>

	<para>The next example lists accounting information and the
	packet count for matched rules along with the rules
	themselves. The first column is the rule number, followed by
	the number of outgoing matched packets, followed by the number
	of incoming matched packets, followed by the rule
	itself.</para>

	<screen>&prompt.root; <userinput>ipfw -a list</userinput></screen>

	<para>To list dynamic rules in addition to static rules:</para>

	<screen>&prompt.root; <userinput>ipfw -d list</userinput></screen>

	<para>To also show the expired dynamic rules:</para>

	<screen>&prompt.root; <userinput>ipfw -d -e list</userinput></screen>

	<para>To zero the counters:</para>

	<screen>&prompt.root; <userinput>ipfw zero</userinput></screen>

	<para>To zero the counters for just the rule with number
	<replaceable>NUM</replaceable>:</para>

	<screen>&prompt.root; <userinput>ipfw zero <replaceable>NUM</replaceable></userinput></screen>
	</sect2>

	<sect2 id="firewalls-ipfw-rules">
	<title>IPFW Rulesets</title>

	<indexterm>
	<primary>IPFW</primary>

	<secondary>rule processing order</secondary>
	</indexterm>

	<para>When a packet enters the <acronym>IPFW</acronym> firewall,
	it is compared against the first rule in the ruleset and
	progresses one rule at a time, moving from top to bottom of
	the set in ascending rule number sequence order. When the
	packet matches the selection parameters of a rule, the rule's
	action field value is executed and the search of the ruleset
	terminates for that packet. This is referred to as
	<quote>first match wins</quote>. If the packet does not match
	any of the rules, it gets caught by the mandatory IPFW default
	rule, number 65535, which denies all packets and silently
	discards them. However, if the packet matches a rule that
	contains the <literal>count</literal>,
	<literal>skipto</literal>, or <literal>tee</literal> keywords,
	the search continues. Refer to &man.ipfw.8; for details on
	how these keywords affect rule processing.</para>

	<para>The examples in this section create an inclusive type
	firewall ruleset containing the stateful <literal>keep
	state</literal>, <literal>limit</literal>,
	<literal>in</literal>, <literal>out</literal> and
	<literal>via</literal> options. For a complete rule syntax
	description, refer to &man.ipfw.8;.</para>

	<warning>
	<para>Be careful when working with firewall rules, as it is
	easy to lock out even the administrator.</para>
	</warning>

	<sect3 id="firewalls-ipfw-rules-syntax">
	<title>Rule Syntax</title>

	<indexterm>
	<primary>IPFW</primary>

	<secondary>rule syntax</secondary>
	</indexterm>

	<para>This section describes the keywords which comprise an
	<acronym>IPFW</acronym> rule. Keywords must be written in
	the following order. <literal>#</literal> is used to mark
	the start of a comment and may appear at the end of a rule
	line or on its own line. Blank lines are ignored.</para>

	<para><replaceable>CMD RULE_NUMBER ACTION LOGGING SELECTION
	STATEFUL</replaceable></para>

	<sect4>
	<title>CMD</title>

	<para>Each new rule has to be prefixed with
	<parameter>add</parameter> to add the rule to the internal
	table.</para>
	</sect4>

	<sect4>
	<title>RULE_NUMBER</title>

	<para>Each rule is associated with a rule_number in the
	range of <literal>1</literal> to
	<literal>65535</literal>.</para>
	</sect4>

	<sect4>
	<title>ACTION</title>

	<para>A rule can be associated with one of the following
	actions. The specified action will be executed when the
	packet matches the selection criterion of the rule.</para>

	<para><parameter>allow \| accept \| pass \|
	permit</parameter></para>

	<para>These keywords are equivalent as they allow packets
	that match the rule to exit the firewall rule processing.
	The search terminates at this rule.</para>

	<para><parameter>check-state</parameter></para>

	<para>Checks the packet against the dynamic rules table.
	If a match is found, execute the action associated with
	the rule which generated this dynamic rule, otherwise
	move to the next rule. A <literal>check-state</literal>
	rule does not have selection criterion. If no
	<literal>check-state</literal> rule is present in the
	ruleset, the dynamic rules table is checked at the first
	<literal>keep-state</literal> or <literal>limit</literal>
	rule.</para>

	<para><parameter>deny \| drop</parameter></para>

	<para>Both words mean the same thing, which is to discard
	packets that match this rule. The search
	terminates.</para>
	</sect4>

	<sect4>
	<title>Logging</title>

	<para>When a packet matches a rule with the
	<literal>log</literal> keyword, a message will be logged
	to &man.syslogd.8; with a facility name of
	<literal>SECURITY</literal>. Logging only occurs if the
	number of packets logged for that particular rule does not
	exceed the <literal>logamount</literal> parameter. If no
	<literal>logamount</literal> is specified, the limit is
	taken from the <command>sysctl</command> value of
	<varname>net.inet.ip.fw.verbose_limit</varname>. In both
	cases, a value of zero removes the logging limit. Once
	the limit is reached, logging can be re-enabled by
	clearing the logging counter or the packet counter for
	that rule, using <command>ipfw reset log</command>.</para>

	<note>
	<para>Logging is done after all other packet matching
	conditions have been met, and before performing the
	final action on the packet. The administrator decides
	which rules to enable logging on.</para>
	</note>
	</sect4>

	<sect4>
	<title>Selection</title>

	<para>The keywords described in this section are used to
	describe attributes of the packet to be checked when
	determining whether rules match the packet or not.
	The following general-purpose attributes are provided for
	matching, and must be used in this order:</para>

	<para><parameter>udp \| tcp \| icmp</parameter></para>

	<para>Any other protocol names found in
	<filename>/etc/protocols</filename> can be used. The
	value specified is the protocol to be matched against.
	This is a mandatory keyword.</para>

	<para><parameter>from src to dst</parameter></para>

	<para>The <literal>from</literal> and <literal>to</literal>
	keywords are used to match against IP addresses. Rules
	must specify <emphasis>both</emphasis> source and
	destination parameters. <literal>any</literal> is a
	special keyword that matches any IP address.
	<literal>me</literal> is a special keyword that matches
	any IP address configured on an interface in the &os;
	system to represent the PC the firewall is running on.
	Example usage includes <literal>from me to any</literal>,
	<literal>from any to me</literal>, <literal>from 0.0.0.0/0
	to any</literal>, <literal>from any to
	0.0.0.0/0</literal>, <literal>from 0.0.0.0 to
	any</literal>. <literal>from any to 0.0.0.0</literal>,
	and <literal>from me to 0.0.0.0</literal>. IP addresses
	are specified in dotted IP address format followed by the
	mask in CIDR notation, or as a single host in dotted IP
	address format. This keyword is a mandatory requirement.
	The <filename role="package">net-mgmt/ipcalc</filename>
	port may be used to assist the mask calculation.</para>

	<para><parameter>port number</parameter></para>

	<para>For protocols which support port numbers, such as
	<acronym>TCP</acronym> and <acronym>UDP</acronym>, it
	is mandatory to include the port number of the service
	that will be matched. Service names from
	<filename>/etc/services</filename> may be used instead
	of numeric port values.</para>

	<para><parameter>in \| out</parameter></para>

	<para>Matches incoming or outgoing packets. It is mandatory
	that one or the other is included as part of the rule
	matching criterion.</para>

	<para><parameter>via IF</parameter></para>

	<para>Matches packets going through the interface specified
	by device name. The <literal>via</literal> keyword causes
	the interface to always be checked as part of the match
	process.</para>

	<para><parameter>setup</parameter></para>

	<para>This mandatory keyword identifies the session start
	request for <acronym>TCP</acronym> packets.</para>

	<para><parameter>keep-state</parameter></para>

	<para>This is a mandatory keyword. Upon a match, the
	firewall will create a dynamic rule, whose default
	behavior is to match bidirectional traffic between source
	and destination IP/port using the same protocol.</para>

	<para><parameter>limit {src-addr \| src-port \| dst-addr \|
	dst-port}</parameter></para>

	<para>The firewall will only allow
	<replaceable>N</replaceable> connections with the same
	set of parameters as specified in the rule. One or more
	of source and destination addresses and ports can be
	specified. <literal>limit</literal> and
	<literal>keep-state</literal> can not be used on the same
	rule as they provide the same stateful function.</para>
	</sect4>
	</sect3>

	<sect3>
	<title>Stateful Rule Option</title>

	<indexterm>
	<primary>IPFW</primary>

	<secondary>stateful filtering</secondary>
	</indexterm>

	<para>The <literal>check-state</literal> option is used to
	identify where in the IPFW ruleset the packet is to be
	tested against the dynamic rules facility. On a match, the
	packet exits the firewall to continue on its way and a new
	rule is dynamically created for the next anticipated packet
	being exchanged during this session. On a no match, the
	packet advances to the next rule in the ruleset for
	testing.</para>

	<para>The dynamic rules facility is vulnerable to resource
	depletion from a SYN-flood attack which would open a huge
	number of dynamic rules. To counter this type of attack
	with <acronym>IPFW</acronym>, use <literal>limit</literal>.
	This keyword limits the number of simultaneous sessions by
	checking that rule's source or destinations fields and using
	the packet's IP address in a search of the open dynamic
	rules, counting the number of times this rule and IP address
	combination occurred. If this count is greater than the
	value specified by <literal>limit</literal>, the packet is
	discarded.</para>
	</sect3>

	<sect3>
	<title>Logging Firewall Messages</title>

	<indexterm>
	<primary>IPFW</primary>

	<secondary>logging</secondary>
	</indexterm>

	<para>Even with the logging facility enabled, IPFW will not
	generate any rule logging on its own. The firewall
	administrator decides which rules in the ruleset will be
	logged, and adds the <literal>log</literal> keyword to those
	rules. Normally only deny rules are logged. It is
	customary to duplicate the <quote>ipfw default deny
	everything</quote> rule with the <literal>log</literal>
	keyword included as the last rule in the ruleset. This
	way, it is possible to see all the packets that did not
	match any of the rules in the ruleset.</para>

	<para>Logging is a two edged sword. If one is not careful,
	an over abundance of log data or a DoS attack can fill the
	disk with log files. Log messages are not only written to
	<application>syslogd</application>, but also are displayed
	on the root console screen and soon become annoying.</para>

	<para>The <literal>IPFIREWALL_VERBOSE_LIMIT=5</literal>
	kernel option limits the number of consecutive messages
	sent to &man.syslogd.8;, concerning the packet matching of a
	given rule. When this option is enabled in the kernel, the
	number of consecutive messages concerning a particular rule
	is capped at the number specified. There is nothing to be
	gained from 200 identical log messages. With this option
	set to five,
	five consecutive messages concerning a particular rule
	would be logged to <application>syslogd</application> and
	the remainder identical consecutive messages would be
	counted and posted to <application>syslogd</application>
	with a phrase like the following:</para>

	<programlisting>last message repeated 45 times</programlisting>

	<para>All logged packets messages are written by default to
	<filename>/var/log/security</filename>, which is
	defined in <filename>/etc/syslog.conf</filename>.</para>
	</sect3>

	<sect3 id="firewalls-ipfw-rules-script">
	<title>Building a Rule Script</title>

	<para>Most experienced IPFW users create a file containing
	the rules and code them in a manner compatible with running
	them as a script. The major benefit of doing this is the
	firewall rules can be refreshed in mass without the need
	of rebooting the system to activate them. This method is
	convenient in testing new rules as the procedure can
	be executed as many times as needed. Being a script,
	symbolic substitution can be used for frequently used
	values to be substituted into multiple rules.</para>

	<para>This example script is compatible with the syntax used
	by the &man.sh.1;, &man.csh.1;, and &man.tcsh.1; shells.
	Symbolic substitution fields are prefixed with a dollar sign
	(&dollar;). Symbolic fields do not have the &dollar;
	prefix. The value to populate the symbolic field must be
	enclosed in double quotes ("").</para>

	<para>Start the rules file like this:</para>

	<programlisting>############### start of example ipfw rules script #############
	#
	ipfw -q -f flush # Delete all rules
	# Set defaults
	oif="tun0" # out interface
	odns="192.0.2.11" # ISP's DNS server IP address
	cmd="ipfw -q add " # build rule prefix
	ks="keep-state" # just too lazy to key this each time
	&dollar;cmd 00500 check-state
	&dollar;cmd 00502 deny all from any to any frag
	&dollar;cmd 00501 deny tcp from any to any established
	&dollar;cmd 00600 allow tcp from any to any 80 out via &dollar;oif setup &dollar;ks
	&dollar;cmd 00610 allow tcp from any to &dollar;odns 53 out via &dollar;oif setup &dollar;ks
	&dollar;cmd 00611 allow udp from any to &dollar;odns 53 out via &dollar;oif &dollar;ks
	################### End of example ipfw rules script ############</programlisting>

	<para>The rules are not important as the focus of this example
	is how the symbolic substitution fields are
	populated.</para>

	<para>If the above example was in
	<filename>/etc/ipfw.rules</filename>, the rules could be
	reloaded by the following command:</para>

	<screen>&prompt.root; <userinput>sh /etc/ipfw.rules</userinput></screen>

	<para><filename>/etc/ipfw.rules</filename> can be located
	anywhere and the file can have any name.</para>

	<para>The same thing could be accomplished by running these
	commands by hand:</para>

	<screen>&prompt.root; <userinput>ipfw -q -f flush</userinput>
	&prompt.root; <userinput>ipfw -q add check-state</userinput>
	&prompt.root; <userinput>ipfw -q add deny all from any to any frag</userinput>
	&prompt.root; <userinput>ipfw -q add deny tcp from any to any established</userinput>
	&prompt.root; <userinput>ipfw -q add allow tcp from any to any 80 out via tun0 setup keep-state</userinput>
	&prompt.root; <userinput>ipfw -q add allow tcp from any to 192.0.2.11 53 out via tun0 setup keep-state</userinput>
	&prompt.root; <userinput>ipfw -q add 00611 allow udp from any to 192.0.2.11 53 out via tun0 keep-state</userinput></screen>
	</sect3>

	<sect3>
	<title>An Example Stateful Ruleset</title>

	<para>The following sample ruleset is a complete inclusive
	type ruleset. Comment out any
	<literal>pass</literal> rules for services that are not
	required. To avoid logging undesired messages, add a
	<literal>deny</literal> rule in the inbound section.
	Change the <devicename>dc0</devicename> in every rule to the
	device name of the interface that connects the system to the
	Internet.</para>

	<para>There is a noticeable pattern in the usage of these
	rules.</para>

	<itemizedlist>
	<listitem>
	<para>All statements that are a request to start a session
	to the Internet use
	<literal>keep-state</literal>.</para>
	</listitem>

	<listitem>
	<para>All the authorized services that originate from
	the Internet use <literal>limit</literal> to prevent
	flooding.</para>
	</listitem>

	<listitem>
	<para>All rules use <literal>in</literal> or
	<literal>out</literal> to clarify direction.</para>
	</listitem>

	<listitem>
	<para>All rules use <literal>via</literal>
	<replaceable>interface-name</replaceable> to specify
	the interface the packet is traveling over.</para>
	</listitem>
	</itemizedlist>

	<para>The following rules go into
	<filename>/etc/ipfw.rules</filename>:</para>

	<programlisting>################ Start of IPFW rules file ###############################
	# Flush out the list before we begin.
	ipfw -q -f flush

	# Set rules command prefix
	cmd="ipfw -q add"
	pif="dc0" # public interface name of NIC
	# facing the public Internet

	#################################################################
	# No restrictions on Inside LAN Interface for private network
	# Not needed unless you have LAN.
	# Change xl0 to your LAN NIC interface name
	#################################################################
	#&dollar;cmd 00005 allow all from any to any via xl0

	#################################################################
	# No restrictions on Loopback Interface
	#################################################################
	&dollar;cmd 00010 allow all from any to any via lo0

	#################################################################
	# Allow the packet through if it has previous been added to the
	# the "dynamic" rules table by a allow keep-state statement.
	#################################################################
	&dollar;cmd 00015 check-state

	#################################################################
	# Interface facing Public Internet (Outbound Section)
	# Interrogate session start requests originating from behind the
	# firewall on the private network or from this gateway server
	# destined for the public Internet.
	#################################################################

	# Allow out access to my ISP's Domain name server.
	# x.x.x.x must be the IP address of your ISP.s DNS
	# Dup these lines if your ISP has more than one DNS server
	# Get the IP addresses from /etc/resolv.conf file
	&dollar;cmd 00110 allow tcp from any to x.x.x.x 53 out via &dollar;pif setup keep-state
	&dollar;cmd 00111 allow udp from any to x.x.x.x 53 out via &dollar;pif keep-state

	# Allow out access to my ISP's DHCP server for cable/DSL configurations.
	# This rule is not needed for .user ppp. connection to the public Internet.
	# so you can delete this whole group.
	# Use the following rule and check log for IP address.
	# Then put IP address in commented out rule & delete first rule
	&dollar;cmd 00120 allow log udp from any to any 67 out via &dollar;pif keep-state
	#&dollar;cmd 00120 allow udp from any to x.x.x.x 67 out via &dollar;pif keep-state

	# Allow out non-secure standard www function
	&dollar;cmd 00200 allow tcp from any to any 80 out via &dollar;pif setup keep-state

	# Allow out secure www function https over TLS SSL
	&dollar;cmd 00220 allow tcp from any to any 443 out via &dollar;pif setup keep-state

	# Allow out send & get email function
	&dollar;cmd 00230 allow tcp from any to any 25 out via &dollar;pif setup keep-state
	&dollar;cmd 00231 allow tcp from any to any 110 out via &dollar;pif setup keep-state

	# Allow out FBSD (make install & CVSUP) functions
	# Basically give user root "GOD" privileges.
	&dollar;cmd 00240 allow tcp from me to any out via &dollar;pif setup keep-state uid root

	# Allow out ping
	&dollar;cmd 00250 allow icmp from any to any out via &dollar;pif keep-state

	# Allow out Time
	&dollar;cmd 00260 allow tcp from any to any 37 out via &dollar;pif setup keep-state

	# Allow out nntp news (i.e., news groups)
	&dollar;cmd 00270 allow tcp from any to any 119 out via &dollar;pif setup keep-state

	# Allow out secure FTP, Telnet, and SCP
	# This function is using SSH (secure shell)
	&dollar;cmd 00280 allow tcp from any to any 22 out via &dollar;pif setup keep-state

	# Allow out whois
	&dollar;cmd 00290 allow tcp from any to any 43 out via &dollar;pif setup keep-state

	# deny and log everything else that.s trying to get out.
	# This rule enforces the block all by default logic.
	&dollar;cmd 00299 deny log all from any to any out via &dollar;pif

	#################################################################
	# Interface facing Public Internet (Inbound Section)
	# Check packets originating from the public Internet
	# destined for this gateway server or the private network.
	#################################################################

	# Deny all inbound traffic from non-routable reserved address spaces
	&dollar;cmd 00300 deny all from 192.168.0.0/16 to any in via &dollar;pif #RFC 1918 private IP
	&dollar;cmd 00301 deny all from 172.16.0.0/12 to any in via &dollar;pif #RFC 1918 private IP
	&dollar;cmd 00302 deny all from 10.0.0.0/8 to any in via &dollar;pif #RFC 1918 private IP
	&dollar;cmd 00303 deny all from 127.0.0.0/8 to any in via &dollar;pif #loopback
	&dollar;cmd 00304 deny all from 0.0.0.0/8 to any in via &dollar;pif #loopback
	&dollar;cmd 00305 deny all from 169.254.0.0/16 to any in via &dollar;pif #DHCP auto-config
	&dollar;cmd 00306 deny all from 192.0.2.0/24 to any in via &dollar;pif #reserved for docs
	&dollar;cmd 00307 deny all from 204.152.64.0/23 to any in via &dollar;pif #Sun cluster interconnect
	&dollar;cmd 00308 deny all from 224.0.0.0/3 to any in via &dollar;pif #Class D & E multicast

	# Deny public pings
	&dollar;cmd 00310 deny icmp from any to any in via &dollar;pif

	# Deny ident
	&dollar;cmd 00315 deny tcp from any to any 113 in via &dollar;pif

	# Deny all Netbios service. 137=name, 138=datagram, 139=session
	# Netbios is MS/Windows sharing services.
	# Block MS/Windows hosts2 name server requests 81
	&dollar;cmd 00320 deny tcp from any to any 137 in via &dollar;pif
	&dollar;cmd 00321 deny tcp from any to any 138 in via &dollar;pif
	&dollar;cmd 00322 deny tcp from any to any 139 in via &dollar;pif
	&dollar;cmd 00323 deny tcp from any to any 81 in via &dollar;pif

	# Deny any late arriving packets
	&dollar;cmd 00330 deny all from any to any frag in via &dollar;pif

	# Deny ACK packets that did not match the dynamic rule table
	&dollar;cmd 00332 deny tcp from any to any established in via &dollar;pif

	# Allow traffic in from ISP's DHCP server. This rule must contain
	# the IP address of your ISP.s DHCP server as it.s the only
	# authorized source to send this packet type.
	# Only necessary for cable or DSL configurations.
	# This rule is not needed for .user ppp. type connection to
	# the public Internet. This is the same IP address you captured
	# and used in the outbound section.
	#&dollar;cmd 00360 allow udp from any to x.x.x.x 67 in via &dollar;pif keep-state

	# Allow in standard www function because I have apache server
	&dollar;cmd 00400 allow tcp from any to me 80 in via &dollar;pif setup limit src-addr 2

	# Allow in secure FTP, Telnet, and SCP from public Internet
	&dollar;cmd 00410 allow tcp from any to me 22 in via &dollar;pif setup limit src-addr 2

	# Allow in non-secure Telnet session from public Internet
	# labeled non-secure because ID & PW are passed over public
	# Internet as clear text.
	# Delete this sample group if you do not have telnet server enabled.
	&dollar;cmd 00420 allow tcp from any to me 23 in via &dollar;pif setup limit src-addr 2

	# Reject & Log all incoming connections from the outside
	&dollar;cmd 00499 deny log all from any to any in via &dollar;pif

	# Everything else is denied by default
	# deny and log all packets that fell through to see what they are
	&dollar;cmd 00999 deny log all from any to any
	################ End of IPFW rules file ###############################</programlisting>
	</sect3>

	<sect3>
	<title>An Example <acronym>NAT</acronym> and Stateful
	Ruleset</title>

	<indexterm>
	<primary>NAT</primary>

	<secondary>and IPFW</secondary>
	</indexterm>

	<para>There are some additional configuration statements that
	need to be enabled to activate the <acronym>NAT</acronym>
	function of IPFW. For a customized kernel, the kernel
	configuration file needs
	<literal>option IPDIVERT</literal> added to the other
	<literal>IPFIREWALL</literal> options.</para>

	<para>In addition to the normal IPFW options in
	<filename>/etc/rc.conf</filename>, the following are
	needed:</para>

	<programlisting>natd_enable="YES" # Enable <acronym>NAT</acronym>D function
	natd_interface="rl0" # interface name of public Internet NIC
	natd_flags="-dynamic -m" # -m = preserve port numbers if possible</programlisting>

	<para>Utilizing stateful rules with a
	<literal>divert natd</literal> rule complicates the ruleset
	logic. The positioning of the
	<literal>check-state</literal>, and
	<literal>divert natd</literal> rules in the ruleset is
	critical and a new action type is used, called
	<literal>skipto</literal>. When using
	<literal>skipto</literal>, it is mandatory that each rule is
	numbered, so that the <literal>skipto</literal> rule knows
	which rule to jump to.</para>

	<para>The following is an uncommented example of a ruleset
	which explains the sequence of the packet flow.</para>

	<para>The processing flow starts with the first rule from the
	top of the ruleset and progresses one rule at a time until
	the end is reached or the packet matches and the packet is
	released out of the firewall. Take note of the location of
	rule numbers 100 101, 450, 500, and 510. These rules
	control the translation of the outbound and inbound packets
	so that their entries in the dynamic keep-state table always
	register the private LAN IP address. All the allow and deny
	rules specify the direction of the packet and the interface.
	All start outbound session requests will
	<literal>skipto rule 500</literal> to undergo NAT.</para>

	<para>Consider a web browser which initializes a new HTTP
	session over port 80. When the first outbound packet enters
	the firewall, it does not match rule 100 because it is
	headed out rather than in. It passes rule 101 because this
	is the first packet, and it has not been posted to the
	dynamic keep-state table yet. The packet finally matches
	rule 125 as it is outbound through the NIC facing the
	Internet and has a source IP address as a private LAN IP
	address. On matching this rule, two actions take place.
	<literal>keep-state</literal> adds this rule to the dynamic
	keep-state rules table and the specified action is executed
	and posted as part of the info in the dynamic table. In
	this case, the action is <literal>skipto rule 500</literal>.
	Rule 500 <acronym>NAT</acronym>s the packet IP address and
	sends it out to the Internet. This packet makes its way to
	the destination web server, where a response packet is
	generated and sent back. This new packet enters the top of
	the ruleset. It matches rule 100 and has it destination IP
	address mapped back to the corresponding LAN IP address. It
	then is processed by the <literal>check-state</literal>
	rule, is found in the table as an existing session, and is
	released to the LAN. It goes to the LAN system that sent it
	and a new packet is sent requesting another segment of the
	data from the remote server. This time it matches the
	<literal>check-state</literal> rule, its outbound entry is
	found, and the associated action,
	<literal>skipto 500</literal>, is executed. The packet
	jumps to rule 500, gets <acronym>NAT</acronym>ed, and is
	released to the Internet.</para>

	<para>On the inbound side, everything coming in that is part
	of an existing session is automatically handled by the
	<literal>check-state</literal> rule and the properly placed
	<literal>divert natd</literal> rules. The ruleset only has
	to deny bad packets and allow only authorized services.
	Consider a web server running on the firewall where web
	requests from the Internet should have access to the local
	web site. An inbound start request packet will match rule
	100 and its IP address will be mapped to the LAN IP address
	of the firewall. The packet is then matched against all the
	nasty things that need to be checked and finally matches
	rule 425 where two actions occur. The packet rule is posted
	to the dynamic keep-state table but this time, any new
	session requests originating from that source IP address are
	limited to 2. This defends against DoS attacks against the
	service running on the specified port number. The action is
	<literal>allow</literal>, so the packet is released to the
	LAN. The packet generated as a response is recognized by the
	<literal>check-state</literal> as belonging to an existing
	session. It is then sent to rule 500 for
	<acronym>NAT</acronym>ing and released to the outbound
	interface.</para>

	<para>Example Ruleset #1:</para>

	<programlisting>#!/bin/sh
	cmd="ipfw -q add"
	skip="skipto 500"
	pif=rl0
	ks="keep-state"
	good_tcpo="22,25,37,43,53,80,443,110,119"

	ipfw -q -f flush

	&dollar;cmd 002 allow all from any to any via xl0 # exclude LAN traffic
	&dollar;cmd 003 allow all from any to any via lo0 # exclude loopback traffic

	&dollar;cmd 100 divert natd ip from any to any in via &dollar;pif
	&dollar;cmd 101 check-state

	# Authorized outbound packets
	&dollar;cmd 120 &dollar;skip udp from any to xx.168.240.2 53 out via &dollar;pif &dollar;ks
	&dollar;cmd 121 &dollar;skip udp from any to xx.168.240.5 53 out via &dollar;pif &dollar;ks
	&dollar;cmd 125 &dollar;skip tcp from any to any &dollar;good_tcpo out via &dollar;pif setup &dollar;ks
	&dollar;cmd 130 &dollar;skip icmp from any to any out via &dollar;pif &dollar;ks
	&dollar;cmd 135 &dollar;skip udp from any to any 123 out via &dollar;pif &dollar;ks


	# Deny all inbound traffic from non-routable reserved address spaces
	&dollar;cmd 300 deny all from 192.168.0.0/16 to any in via &dollar;pif #RFC 1918 private IP
	&dollar;cmd 301 deny all from 172.16.0.0/12 to any in via &dollar;pif #RFC 1918 private IP
	&dollar;cmd 302 deny all from 10.0.0.0/8 to any in via &dollar;pif #RFC 1918 private IP
	&dollar;cmd 303 deny all from 127.0.0.0/8 to any in via &dollar;pif #loopback
	&dollar;cmd 304 deny all from 0.0.0.0/8 to any in via &dollar;pif #loopback
	&dollar;cmd 305 deny all from 169.254.0.0/16 to any in via &dollar;pif #DHCP auto-config
	&dollar;cmd 306 deny all from 192.0.2.0/24 to any in via &dollar;pif #reserved for docs
	&dollar;cmd 307 deny all from 204.152.64.0/23 to any in via &dollar;pif #Sun cluster
	&dollar;cmd 308 deny all from 224.0.0.0/3 to any in via &dollar;pif #Class D & E multicast

	# Authorized inbound packets
	&dollar;cmd 400 allow udp from xx.70.207.54 to any 68 in &dollar;ks
	&dollar;cmd 420 allow tcp from any to me 80 in via &dollar;pif setup limit src-addr 1


	&dollar;cmd 450 deny log ip from any to any

	# This is skipto location for outbound stateful rules
	&dollar;cmd 500 divert natd ip from any to any out via &dollar;pif
	&dollar;cmd 510 allow ip from any to any

	######################## end of rules ##################</programlisting>

	<para>The next example is functionally equivalent, but uses
	descriptive comments to help the inexperienced IPFW rule
	writer to better understand what the rules are doing.</para>

	<para>Example Ruleset #2:</para>

	<programlisting>#!/bin/sh
	################ Start of IPFW rules file ###############################
	# Flush out the list before we begin.
	ipfw -q -f flush

	# Set rules command prefix
	cmd="ipfw -q add"
	skip="skipto 800"
	pif="rl0" # public interface name of NIC
	# facing the public Internet

	#################################################################
	# No restrictions on Inside LAN Interface for private network
	# Change xl0 to your LAN NIC interface name
	#################################################################
	&dollar;cmd 005 allow all from any to any via xl0

	#################################################################
	# No restrictions on Loopback Interface
	#################################################################
	&dollar;cmd 010 allow all from any to any via lo0

	#################################################################
	# check if packet is inbound and nat address if it is
	#################################################################
	&dollar;cmd 014 divert natd ip from any to any in via &dollar;pif

	#################################################################
	# Allow the packet through if it has previous been added to the
	# the "dynamic" rules table by a allow keep-state statement.
	#################################################################
	&dollar;cmd 015 check-state

	#################################################################
	# Interface facing Public Internet (Outbound Section)
	# Check session start requests originating from behind the
	# firewall on the private network or from this gateway server
	# destined for the public Internet.
	#################################################################

	# Allow out access to my ISP's Domain name server.
	# x.x.x.x must be the IP address of your ISP's DNS
	# Dup these lines if your ISP has more than one DNS server
	# Get the IP addresses from /etc/resolv.conf file
	&dollar;cmd 020 &dollar;skip tcp from any to x.x.x.x 53 out via &dollar;pif setup keep-state


	# Allow out access to my ISP's DHCP server for cable/DSL configurations.
	&dollar;cmd 030 &dollar;skip udp from any to x.x.x.x 67 out via &dollar;pif keep-state

	# Allow out non-secure standard www function
	&dollar;cmd 040 &dollar;skip tcp from any to any 80 out via &dollar;pif setup keep-state

	# Allow out secure www function https over TLS SSL
	&dollar;cmd 050 &dollar;skip tcp from any to any 443 out via &dollar;pif setup keep-state

	# Allow out send & get email function
	&dollar;cmd 060 &dollar;skip tcp from any to any 25 out via &dollar;pif setup keep-state
	&dollar;cmd 061 &dollar;skip tcp from any to any 110 out via &dollar;pif setup keep-state

	# Allow out FreeBSD (make install & CVSUP) functions
	# Basically give user root "GOD" privileges.
	&dollar;cmd 070 &dollar;skip tcp from me to any out via &dollar;pif setup keep-state uid root

	# Allow out ping
	&dollar;cmd 080 &dollar;skip icmp from any to any out via &dollar;pif keep-state

	# Allow out Time
	&dollar;cmd 090 &dollar;skip tcp from any to any 37 out via &dollar;pif setup keep-state

	# Allow out nntp news (i.e., news groups)
	&dollar;cmd 100 &dollar;skip tcp from any to any 119 out via &dollar;pif setup keep-state

	# Allow out secure FTP, Telnet, and SCP
	# This function is using SSH (secure shell)
	&dollar;cmd 110 &dollar;skip tcp from any to any 22 out via &dollar;pif setup keep-state

	# Allow out whois
	&dollar;cmd 120 &dollar;skip tcp from any to any 43 out via &dollar;pif setup keep-state

	# Allow ntp time server
	&dollar;cmd 130 &dollar;skip udp from any to any 123 out via &dollar;pif keep-state

	#################################################################
	# Interface facing Public Internet (Inbound Section)
	# Check packets originating from the public Internet
	# destined for this gateway server or the private network.
	#################################################################

	# Deny all inbound traffic from non-routable reserved address spaces
	&dollar;cmd 300 deny all from 192.168.0.0/16 to any in via &dollar;pif #RFC 1918 private IP
	&dollar;cmd 301 deny all from 172.16.0.0/12 to any in via &dollar;pif #RFC 1918 private IP
	&dollar;cmd 302 deny all from 10.0.0.0/8 to any in via &dollar;pif #RFC 1918 private IP
	&dollar;cmd 303 deny all from 127.0.0.0/8 to any in via &dollar;pif #loopback
	&dollar;cmd 304 deny all from 0.0.0.0/8 to any in via &dollar;pif #loopback
	&dollar;cmd 305 deny all from 169.254.0.0/16 to any in via &dollar;pif #DHCP auto-config
	&dollar;cmd 306 deny all from 192.0.2.0/24 to any in via &dollar;pif #reserved for docs
	&dollar;cmd 307 deny all from 204.152.64.0/23 to any in via &dollar;pif #Sun cluster
	&dollar;cmd 308 deny all from 224.0.0.0/3 to any in via &dollar;pif #Class D & E multicast

	# Deny ident
	&dollar;cmd 315 deny tcp from any to any 113 in via &dollar;pif

	# Deny all Netbios service. 137=name, 138=datagram, 139=session
	# Netbios is MS/Windows sharing services.
	# Block MS/Windows hosts2 name server requests 81
	&dollar;cmd 320 deny tcp from any to any 137 in via &dollar;pif
	&dollar;cmd 321 deny tcp from any to any 138 in via &dollar;pif
	&dollar;cmd 322 deny tcp from any to any 139 in via &dollar;pif
	&dollar;cmd 323 deny tcp from any to any 81 in via &dollar;pif

	# Deny any late arriving packets
	&dollar;cmd 330 deny all from any to any frag in via &dollar;pif

	# Deny ACK packets that did not match the dynamic rule table
	&dollar;cmd 332 deny tcp from any to any established in via &dollar;pif

	# Allow traffic in from ISP's DHCP server. This rule must contain
	# the IP address of your ISP's DHCP server as it is the only
	# authorized source to send this packet type.
	# Only necessary for cable or DSL configurations.
	# This rule is not needed for 'user ppp' type connection to
	# the public Internet. This is the same IP address you captured
	# and used in the outbound section.
	&dollar;cmd 360 allow udp from x.x.x.x to any 68 in via &dollar;pif keep-state

	# Allow in standard www function because I have Apache server
	&dollar;cmd 370 allow tcp from any to me 80 in via &dollar;pif setup limit src-addr 2

	# Allow in secure FTP, Telnet, and SCP from public Internet
	&dollar;cmd 380 allow tcp from any to me 22 in via &dollar;pif setup limit src-addr 2

	# Allow in non-secure Telnet session from public Internet
	# labeled non-secure because ID & PW are passed over public
	# Internet as clear text.
	# Delete this sample group if you do not have telnet server enabled.
	&dollar;cmd 390 allow tcp from any to me 23 in via &dollar;pif setup limit src-addr 2

	# Reject & Log all unauthorized incoming connections from the public Internet
	&dollar;cmd 400 deny log all from any to any in via &dollar;pif

	# Reject & Log all unauthorized out going connections to the public Internet
	&dollar;cmd 450 deny log all from any to any out via &dollar;pif

	# This is skipto location for outbound stateful rules
	&dollar;cmd 800 divert natd ip from any to any out via &dollar;pif
	&dollar;cmd 801 allow ip from any to any

	# Everything else is denied by default
	# deny and log all packets that fell through to see what they are
	&dollar;cmd 999 deny log all from any to any
	################ End of IPFW rules file ###############################</programlisting>
	</sect3>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/install/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/install/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/install/chapter.xml (revision 41355)
	@@ -1,5015 +1,4953 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="install">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Jim</firstname>
	<surname>Mock</surname>
	<contrib>Restructured, reorganized, and parts
	rewritten by </contrib>
	</author>
	</authorgroup>

	<authorgroup>
	<author>
	<firstname>Randy</firstname>
	<surname>Pratt</surname>
	<contrib>The sysinstall walkthrough, screenshots, and general
	copy by </contrib>
	</author>
	</authorgroup>
	<!-- January 2000 -->
	</chapterinfo>

	<title>Installing &os; 8.<replaceable>X</replaceable> and Earlier</title>

	<sect1 id="install-synopsis">
	<title>Synopsis</title>

	<indexterm><primary>installation</primary></indexterm>

	<para>FreeBSD is provided with a text-based, easy to use installation
	program. &os; 9.0-RELEASE and later use the installation program
	known as <application>bsdinstall</application>, with releases prior
	to 9.0-RELEASE using <application>sysinstall</application> for
	installation. This chapter describes the use of <application>sysinstall</application>
	to install &os;. The use of <application>bsdinstall</application>
	is covered in <xref linkend="bsdinstall"/>.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>How to create the FreeBSD installation disks.</para>
	</listitem>

	<listitem>
	<para>How FreeBSD refers to, and subdivides, your hard disks.</para>
	</listitem>

	<listitem>
	<para>How to start <application>sysinstall</application>.</para>
	</listitem>

	<listitem>
	<para>The questions <application>sysinstall</application> will ask
	you, what they mean, and how to answer them.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	<para>Read the supported hardware list that shipped with the version
	of FreeBSD you are installing, and verify that your hardware is
	supported.</para>
	</listitem>
	</itemizedlist>

	<note>
	<para>In general, these installation instructions are written
	for &i386; (<quote>PC compatible</quote>) architecture
	computers. Where applicable, instructions specific to other
	platforms will be listed. Although this
	guide is kept as up to date as possible, you may find minor
	differences between the installer and what is shown here. It is
	suggested that you use this chapter as a general guide rather
	than a literal installation manual.</para>
	</note>

	</sect1>

	<sect1 id="install-hardware">
	<title>Hardware Requirements</title>

	<sect2 id="install-hardware-minimal">
	<title>Minimal Configuration</title>

	<para>The minimal configuration to install &os; varies with the
	&os; version and the hardware architecture.</para>

	<para>A summary of this information is given in the following sections.
	Depending on the method you choose to install &os;, you may
	also need a floppy drive, a supported CDROM drive, and in some
	case a network adapter. This will be covered by the <xref
	linkend="install-boot-media"/>.</para>

	<sect3>
	<title>&os;/&arch.i386; and &os;/&arch.pc98;</title>

	<para>Both &os;/&arch.i386; and &os;/&arch.pc98; require a 486 or
	better processor and at least 24 MB of RAM. You will
	need at least 150 MB of free hard drive space for the
	most minimal installation.</para>

	<note>
	<para>In case of old configurations, most of time, getting
	more RAM and more hard drive space is more important than
	getting a faster processor.</para>
	</note>
	</sect3>

	<sect3>
	<title>&os;/&arch.amd64;</title>

	<para>There are two classes of processors capable of running
	&os;/&arch.amd64;. The first are AMD64 processors,
	including the &amd.athlon;64,
	&amd.athlon;64-FX, &amd.opteron; or better
	processors.</para>

	<para>The second class of processors that can use
	&os;/&arch.amd64; includes those using the &intel; EM64T
	architecture. Examples of these processors include the
	&intel; &core; 2 Duo, Quad, Extreme processor
	families, and the &intel; &xeon; 3000, 5000, and 7000
	sequences of processors.</para>

	<para>If you have a machine based on an nVidia nForce3
	Pro-150, you <emphasis>must</emphasis> use the BIOS setup to
	disable the IO APIC. If you do not have an option to do
	this, you will likely have to disable ACPI instead. There
	are bugs in the Pro-150 chipset that we have not found a
	workaround for yet.</para>
	</sect3>

	<sect3>
	<title>&os;/&arch.sparc64;</title>

	<para>To install &os;/&arch.sparc64;, you will need a supported
	platform (see <xref
	linkend="install-hardware-supported"/>).</para>

	<para>You will need a dedicated disk for &os;/&arch.sparc64;. It
	is not possible to share a disk with another operating
	system at this time.</para>
	</sect3>
	</sect2>

	<sect2 id="install-hardware-supported">
	<title>Supported Hardware</title>

	<para>A list of supported hardware is provided with each &os;
	release in the &os; Hardware Notes. This document can usually
	be found in a file named <filename>HARDWARE.TXT</filename>, in
	the top-level directory of a CDROM or FTP distribution or in
	<application>sysinstall</application>'s documentation menu.
	It lists, for a given architecture, what hardware devices are
	known to be supported by each release of &os;. Copies of the
	supported hardware list for various releases and architectures
	can also be found on the <ulink
	url="http://www.FreeBSD.org/releases/index.html">Release
	Information</ulink> page of the &os; Web site.</para>
	</sect2>
	</sect1>

	<sect1 id="install-pre">
	<title>Pre-installation Tasks</title>

	<sect2 id="install-inventory">
	<title>Inventory Your Computer</title>

	- <para>Before installing FreeBSD you should attempt to inventory the
	- components in your computer. The FreeBSD installation routines will
	+ <para>Before installing &os; you should attempt to inventory the
	+ components in your computer. The &os; installation routines will
	show you the components (hard disks, network cards, CDROM drives, and
	- so forth) with their model number and manufacturer. FreeBSD will also
	+ so forth) with their model number and manufacturer. &os; will also
	attempt to determine the correct configuration for these devices,
	which includes information about IRQ and IO port usage. Due to the
	vagaries of PC hardware this process is not always completely
	- successful, and you may need to correct FreeBSD's determination of
	+ successful, and you may need to correct &os;'s determination of
	your configuration.</para>

	<para>If you already have another operating system installed, such as
	&windows; or Linux, it is a good idea to use the facilities provided
	by those operating systems to see how your hardware is already
	configured. If you are not sure what settings an expansion
	card is using, you may find it printed on the card itself. Popular IRQ
	numbers are 3, 5, and 7, and IO port addresses are normally written as
	hexadecimal numbers, such as 0x330.</para>

	<para>We recommend you print or write down this information before
	- installing FreeBSD. It may help to use a table, like this:</para>
	+ installing &os;. It may help to use a table, like this:</para>

	<table pgwide="1" frame="none">
	<title>Sample Device Inventory</title>

	<tgroup cols="4">
	<colspec colwidth="2*"/>
	<colspec colwidth="1*"/>
	<colspec colwidth="1*"/>
	<colspec colwidth="4*"/>
	<thead>
	<row>
	<entry>Device Name</entry>

	<entry>IRQ</entry>

	<entry>IO port(s)</entry>

	<entry>Notes</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>First hard disk</entry>

	<entry>N/A</entry>

	<entry>N/A</entry>

	<entry>40 GB, made by Seagate, first IDE master</entry>
	</row>

	<row>
	<entry>CDROM</entry>

	<entry>N/A</entry>

	<entry>N/A</entry>

	<entry>First IDE slave</entry>
	</row>

	<row>
	<entry>Second hard disk</entry>

	<entry>N/A</entry>

	<entry>N/A</entry>

	<entry>20 GB, made by IBM, second IDE master</entry>
	</row>

	<row>
	<entry>First IDE controller</entry>

	<entry>14</entry>

	<entry>0x1f0</entry>

	<entry></entry>
	</row>

	<row>
	<entry>Network card</entry>

	<entry>N/A</entry>

	<entry>N/A</entry>

	<entry>&intel; 10/100</entry>
	</row>

	<row>
	<entry>Modem</entry>

	<entry>N/A</entry>

	<entry>N/A</entry>

	<entry>&tm.3com; 56K faxmodem, on COM1</entry>
	</row>

	<row>
	<entry>…</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>Once the inventory of the components in your computer is
	done, you have to check if they match the hardware
	requirements of the &os; release you want to install.</para>
	</sect2>

	<sect2>
	<title>Backup Your Data</title>

	- <para>If the computer you will be installing FreeBSD on contains
	+ <para>If the computer you will be installing &os; on contains
	valuable data, then ensure you have it backed up, and that you have
	- tested the backups before installing FreeBSD. The FreeBSD
	+ tested the backups before installing &os;. The &os;
	installation routine will prompt you before writing any
	data to your disk, but once that process has started it cannot be
	undone.</para>
	</sect2>

	<sect2 id="install-where">
	- <title>Decide Where to Install FreeBSD</title>
	+ <title>Decide Where to Install &os;</title>

	- <para>If you want FreeBSD to use your entire hard disk, then there is nothing
	+ <para>If you want &os; to use your entire hard disk, then there is nothing
	more to concern yourself with at this point — you can skip this
	section.</para>

	- <para>However, if you need FreeBSD to co-exist with other operating
	+ <para>However, if you need &os; to co-exist with other operating
	systems then you need to have a rough understanding of how data is
	laid out on the disk, and how this affects you.</para>

	<sect3 id="install-where-i386">
	<title>Disk Layouts for &os;/&arch.i386;</title>

	<para>A PC disk can be divided into discrete chunks. These chunks are
	called <firstterm>partitions</firstterm>. Since
	&os; internally also has partitions, the naming
	can become confusing very quickly, therefore these
	disk chunks are referred to as disk slices or simply slices
	- in &os; itself. For example, the FreeBSD utility
	+ in &os; itself. For example, the &os; utility
	<command>fdisk</command> which operates on the PC disk partitions,
	refers to slices instead of partitions. By design, the PC only
	supports four partitions per disk. These partitions are called
	<firstterm>primary partitions</firstterm>. To work around this
	limitation and allow more than four partitions, a new partition type
	was created, the <firstterm>extended partition</firstterm>. A disk
	may contain only one extended partition. Special partitions, called
	<firstterm>logical partitions</firstterm>, can be created inside this
	extended partition.</para>

	<para>Each partition has a <firstterm>partition ID</firstterm>, which is
	- a number used to identify the type of data on the partition. FreeBSD
	+ a number used to identify the type of data on the partition. &os;
	partitions have the partition ID of <literal>165</literal>.</para>

	<para>In general, each operating system that you use will identify
	partitions in a particular way. For example, &ms-dos;, and its
	descendants, like &windows;, assign each primary and logical partition a
	<firstterm>drive letter</firstterm>, starting with
	<devicename>C:</devicename>.</para>

	- <para>FreeBSD must be installed into a primary partition. FreeBSD can
	+ <para>&os; must be installed into a primary partition. &os; can
	keep all its data, including any files that you create, on this one
	partition. However, if you have multiple disks, then you can create a
	- FreeBSD partition on all, or some, of them. When you install FreeBSD,
	+ &os; partition on all, or some, of them. When you install &os;,
	you must have one partition available. This might be a blank
	partition that you have prepared, or it might be an existing partition
	that contains data that you no longer care about.</para>

	<para>If you are already using all the partitions on all your disks, then
	- you will have to free one of them for FreeBSD using the tools
	+ you will have to free one of them for &os; using the tools
	provided by the other operating systems you use (e.g.,
	<command>fdisk</command> on &ms-dos; or &windows;).</para>

	<para>If you have a spare partition then you can use that. However, you
	may need to shrink one or more of your existing partitions
	first.</para>

	- <para>A minimal installation of FreeBSD takes as little as 100 MB
	+ <para>A minimal installation of &os; takes as little as 100 MB
	of disk
	space. However, that is a <emphasis>very</emphasis> minimal install,
	leaving almost no space for your own files. A more realistic minimum
	is 250 MB without a graphical environment, and 350 MB or
	more if you
	want a graphical user interface. If you intend to install a lot of
	third-party software as well, then you will need more space.</para>

	<para>You can use a commercial tool such as <application>&partitionmagic;</application>,
	or a free tool such as <application>GParted</application>,
	to resize your partitions and make space for
	&os;. Both
	<application>&partitionmagic;</application> and
	<application>GParted</application> are known to work on
	<acronym>NTFS</acronym>. <application>GParted</application>
	is available on a number of Live CD Linux distributions, such as
	<ulink url="http://www.sysresccd.org/">SystemRescueCD</ulink>.</para>

	<para>Problems have been reported resizing &microsoft; Vista
	partitions. Having a Vista installation CDROM handy when
	attempting such an operation is recommended. As with all
	such disk maintenance tasks, a current set of backups is
	also strongly advised.</para>

	<warning>
	<para>Incorrect use of these tools can delete the data on your disk.
	Be sure that you have recent, working backups before using
	them.</para>
	</warning>

	<example>
	<title>Using an Existing Partition Unchanged</title>

	<para>Suppose that you have a computer with a single 4 GB disk
	that
	already has a version of &windows; installed, and you have split the
	disk into two drive letters, <devicename>C:</devicename> and
	<devicename>D:</devicename>, each of which is 2 GB in size.
	You have 1 GB of data on <devicename>C:</devicename>, and
	0.5 GB of data on
	<devicename>D:</devicename>.</para>

	<para>This means that your disk has two partitions on it, one per
	drive letter. You can copy all your existing data from
	<devicename>D:</devicename> to <devicename>C:</devicename>, which
	- will free up the second partition, ready for FreeBSD.</para>
	+ will free up the second partition, ready for &os;.</para>
	</example>

	<example>
	<title>Shrinking an Existing Partition</title>

	<para>Suppose that you have a computer with a single 4 GB disk
	that already has a version of &windows; installed. When you installed
	&windows; you created one large partition, giving you a
	<devicename>C:</devicename> drive that is 4 GB in size. You are
	- currently using 1.5 GB of space, and want FreeBSD to have 2 GB
	+ currently using 1.5 GB of space, and want &os; to have 2 GB
	of space.</para>

	- <para>In order to install FreeBSD you will need to either:</para>
	+ <para>In order to install &os; you will need to either:</para>

	<orderedlist>
	<listitem>
	<para>Backup your &windows; data, and then reinstall &windows;,
	asking for a 2 GB partition at install time.</para>
	</listitem>

	<listitem>
	<para>Use one of the tools such as <application>&partitionmagic;</application>,
	described above, to shrink your &windows;
	partition.</para>
	</listitem>
	</orderedlist>
	</example>

	</sect3>
	</sect2>

	<sect2>
	<title>Collect Your Network Configuration Details</title>

	- <para>If you intend to connect to a network as part of your FreeBSD
	+ <para>If you intend to connect to a network as part of your &os;
	installation (for example, if you will be installing from an FTP
	site or an
	NFS server), then you need to know your network configuration. You
	will be prompted for this information during the installation so that
	- FreeBSD can connect to the network to complete the install.</para>
	+ &os; can connect to the network to complete the install.</para>

	<sect3>
	<title>Connecting to an Ethernet Network or Cable/DSL Modem</title>

	<para>If you connect to an Ethernet network, or you have an Internet
	connection using an Ethernet adapter via cable or DSL, then you will
	need the following information:</para>

	<orderedlist>
	<listitem>
	<para>IP address</para>
	</listitem>

	<listitem>
	<para>IP address of the default gateway</para>
	</listitem>

	<listitem>
	<para>Hostname</para>
	</listitem>

	<listitem>
	<para>DNS server IP addresses</para>
	</listitem>

	<listitem>
	<para>Subnet Mask</para>
	</listitem>
	</orderedlist>

	<para>If you do not know this information, then ask your system
	administrator or service provider. They may say that this
	information is assigned automatically, using
	<firstterm>DHCP</firstterm>. If so, make a note of this.</para>
	</sect3>

	<sect3>
	<title>Connecting Using a Modem</title>

	<para>If you dial up to an ISP using a regular modem then you can
	- still install FreeBSD over the Internet, it will just take a very
	+ still install &os; over the Internet, it will just take a very
	long time.</para>

	<para>You will need to know:</para>

	<orderedlist>
	<listitem>
	<para>The phone number to dial for your ISP</para>
	</listitem>

	<listitem>
	<para>The COM: port your modem is connected to</para>
	</listitem>

	<listitem>
	<para>The username and password for your ISP account</para>
	</listitem>
	</orderedlist>
	</sect3>
	</sect2>
	<sect2>
	- <title>Check for FreeBSD Errata</title>
	+ <title>Check for &os; Errata</title>

	- <para>Although the FreeBSD project strives to ensure that each release
	- of FreeBSD is as stable as possible, bugs do occasionally creep into
	+ <para>Although the &os; project strives to ensure that each release
	+ of &os; is as stable as possible, bugs do occasionally creep into
	the process. On very rare occasions those bugs affect the
	installation process. As these problems are discovered and fixed, they
	- are noted in the <ulink url="http://www.FreeBSD.org/releases/&rel.current;R/errata.html">FreeBSD Errata</ulink>,
	- which is found on the FreeBSD web site. You
	+ are noted in the <ulink url="http://www.FreeBSD.org/releases/&rel.current;R/errata.html">&os; Errata</ulink>,
	+ which is found on the &os; web site. You
	should check the errata before installing to make sure that there are
	no late-breaking problems which you should be aware of.</para>

	<para>Information about all the releases, including the errata for each
	release, can be found on the
	<ulink
	url="&url.base;/releases/index.html">release
	information</ulink> section of the
	<ulink
	- url="&url.base;/index.html">FreeBSD web site</ulink>.</para>
	+ url="&url.base;/index.html">&os; web site</ulink>.</para>
	</sect2>

	<sect2>
	- <title>Obtain the FreeBSD Installation Files</title>
	+ <title>Obtain the &os; Installation Files</title>

	- <para>The FreeBSD installation process can install FreeBSD from files
	+ <para>The &os; installation process can install &os; from files
	located in any of the following places:</para>

	<itemizedlist>
	<title>Local Media</title>

	<listitem>
	<para>A CDROM or DVD</para>
	</listitem>

	<listitem>
	<para>A USB Memory Stick</para>
	</listitem>

	<listitem>
	<para>A &ms-dos; partition on the same computer</para>
	</listitem>

	<listitem>
	<para>A SCSI or QIC tape</para>
	</listitem>

	<listitem>
	<para>Floppy disks</para>
	</listitem>
	</itemizedlist>

	<itemizedlist>
	<title>Network</title>

	<listitem>
	<para>An FTP site, going through a firewall, or using an HTTP proxy,
	as necessary</para>
	</listitem>

	<listitem>
	<para>An NFS server</para>
	</listitem>

	<listitem>
	<para>A dedicated parallel or serial connection</para>
	</listitem>
	</itemizedlist>

	- <para>If you have purchased FreeBSD on CD or DVD then you already have
	+ <para>If you have purchased &os; on CD or DVD then you already have
	everything you need, and should proceed to the next section
	(<xref linkend="install-boot-media"/>).</para>

	- <para>If you have not obtained the FreeBSD installation files you should
	+ <para>If you have not obtained the &os; installation files you should
	skip ahead to <xref linkend="install-diff-media"/> which explains how
	- to prepare to install FreeBSD from any of the above. After reading
	+ to prepare to install &os; from any of the above. After reading
	that section, you should come back here, and read on to
	<xref linkend="install-boot-media"/>.</para>
	</sect2>

	<sect2 id="install-boot-media">
	<title>Prepare the Boot Media</title>

	- <para>The FreeBSD installation process is started by booting your
	- computer into the FreeBSD installer—it is not a program you run
	- within another operating system. Your computer normally boots using
	- the operating system installed on your hard disk, but it can also be
	- configured to use a <quote>bootable</quote> floppy disk.
	- Most modern computers can also
	- boot from a CDROM in the CDROM drive or from a USB disk.</para>
	+ <para>The &os; installation process is started by booting the
	+ computer into the &os; installer—it is not a program you run
	+ within another operating system. The computer normally boots
	+ using the operating system installed on the hard disk, but it
	+ can also be configured to boot from a CDROM or from a USB
	+ disk.</para>

	<tip>
	- <para>If you have FreeBSD on CDROM or DVD (either one you purchased
	+ <para>If you have &os; on CDROM or DVD (either one you purchased
	or you prepared yourself), and your computer allows you to boot from
	the CDROM or DVD (typically a BIOS option called <quote>Boot
	Order</quote> or similar), then you can skip this section. The
	- FreeBSD CDROM and DVD images are bootable and can be used to install
	- FreeBSD without any other special preparation.</para>
	+ &os; CDROM and DVD images are bootable and can be used to install
	+ &os; without any other special preparation.</para>
	</tip>

	<para>To create a bootable memory stick, follow these
	steps:</para>

	<procedure>
	<step>
	<title>Acquire the Memory Stick Image</title>

	<para>Memory stick images for
	&os; 8.<replaceable>X</replaceable> and earlier can be downloaded from
	the <filename class="directory">ISO-IMAGES/</filename>
	directory at
	<literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/<replaceable>arch</replaceable>/ISO-IMAGES/<replaceable>version</replaceable>/&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-memstick.img</literal>.
	Replace <replaceable>arch</replaceable> and
	<replaceable>version</replaceable> with the
	architecture and the version number which you want to
	install, respectively. For example, the memory stick
	images for &os;/&arch.i386; &rel2.current;-RELEASE are
	available from <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/ISO-IMAGES/&rel2.current;/&os;-&rel2.current;-RELEASE-&arch.i386;-memstick.img"></ulink>.</para>

	<tip>
	<para>A different directory path is used for
	&os; 9.0-RELEASE and later versions. Details of
	download and installation of &os; 9.0-RELEASE and
	later is covered in <xref linkend="bsdinstall"/>.</para>
	</tip>

	<para>The memory stick image has a <filename>.img</filename>
	extension. The <filename
	class="directory">ISO-IMAGES/</filename> directory
	contains a number of different images, and the one you
	will need to use will depend on the version of &os; you
	are installing, and in some cases, the hardware you are
	installing to.</para>

	<important>
	<para>Before proceeding, <emphasis>back up</emphasis> the
	data you currently have on your USB stick, as this
	procedure will <emphasis>erase</emphasis> it.</para>
	</important>
	</step>

	<step>
	<title>Write The Image File to the Memory Stick</title>

	<procedure>
	- <title>Using FreeBSD To Write the Image</title>
	+ <title>Using &os; To Write the Image</title>

	<warning>
	<para>The example below
	lists <filename class="devicefile">/dev/da0</filename> as the
	target device where the image will be written. Be very careful
	that you have the correct device as the output target, or you
	may destroy your existing data.</para>
	</warning>

	<step>
	<title>Writing the Image with &man.dd.1;</title>

	<para>The <filename>.img</filename> file
	is <emphasis>not</emphasis> a regular file you copy to the
	memory stick. It is an image of the complete contents of the
	disk. This means that you <emphasis>cannot</emphasis> simply
	copy files from one disk to another. Instead, you must use
	&man.dd.1; to write the image directly to the disk:</para>

	<screen>&prompt.root; <userinput>dd if=&os;-&rel2.current;-RELEASE-&arch.i386;-memstick.img of=/dev/<replaceable>da0</replaceable> bs=64k</userinput></screen>

	<para>If an
	<computeroutput>Operation not permitted</computeroutput>
	error is displayed, make certain that the target device
	is not in use, mounted, or being automounted by some
	well-intentioned utility program. Then try
	again.</para>
	</step>
	</procedure>

	<procedure>
	<title>Using &windows; To Write the Image</title>

	<warning>
	<para>Make sure you use the correct drive letter as the output
	target, or you may overwrite and destroy existing data.</para>
	</warning>

	<step>
	<title>Obtaining <application>Image Writer for Windows</application></title>

	<para><application>Image Writer for Windows</application> is a
	free application that can correctly write an image file to a
	memory stick. Download it from
	<ulink url="https://launchpad.net/win32-image-writer/"></ulink>
	and extract it into a folder.</para>
	</step>

	<step>
	<title>Writing The Image with Image Writer</title>

	<para>Double-click
	the <application>Win32DiskImager</application> icon to start
	the program. Verify that the drive letter shown
	under <computeroutput>Device</computeroutput> is the drive
	with the memory stick. Click the folder icon and select the
	image to be written to the memory stick.
	Click <guibutton>Save</guibutton> to accept the image file
	name. Verify that everything is correct, and that no folders
	on the memory stick are open in other windows. Finally,
	click <guibutton>Write</guibutton> to write the image file to
	the drive.</para>
	</step>
	</procedure>
	</step>
	</procedure>

	- <para>To create boot floppy images, follow these steps:</para>
	+ <para>To create the boot floppy images for a &os;/&arch.pc98;
	+ installation, follow these steps:</para>

	<procedure>
	<step>
	<title>Acquire the Boot Floppy Images</title>

	- <important>
	- <para>Please note, as of &os; 8.<replaceable>X</replaceable>, floppy disk images are
	- no longer available. Please see above for instructions
	- on how to install &os; using a USB memory stick or just
	- use a CDROM or a DVD.</para>
	- </important>
	+ <para>The &os;/&arch.pc98; boot disks
	+ can be downloaded from the floppies directory,
	+ <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/pc98/<replaceable>version</replaceable>-RELEASE/floppies/</literal>.
	+ Replace <replaceable>version</replaceable> with the
	+ version number to install.</para>

	- <para>The boot disks are available on your installation media
	- in the <filename>floppies/</filename> directory, and
	- can also be downloaded from the floppies directory,
	- <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>version</replaceable>-RELEASE/floppies/</literal>.
	- Replace <replaceable>arch</replaceable> and
	- <replaceable>version</replaceable>
	- with the architecture and the version number
	- which you want to install, respectively.
	- For example, the boot floppy images for
	- &os;/&arch.i386; &rel2.current;-RELEASE are available
	- from <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/floppies/"></ulink>.</para>
	+ <para>The floppy images have a <filename>.flp</filename>
	+ extension. <filename
	+ class="directory">floppies/</filename> contains a number
	+ of different images. Download
	+ <filename>boot.flp</filename> as well as the number of
	+ files associated with the type of installation, such as
	+ <literal>kern.small*</literal> or
	+ <literal>kern*</literal>.</para>

	- <para>The floppy images have a <filename>.flp</filename> extension.
	- The <filename>floppies/</filename> directory contains a number of
	- different images, and the ones you will need to use depends on the
	- version of FreeBSD you are installing, and in some cases, the
	- hardware you are installing to.
	- In most cases you will need four
	- floppies, <filename>boot.flp</filename>,
	- <filename>kern1.flp</filename>,
	- <filename>kern2.flp</filename>, and
	- <filename>kern3.flp</filename>. Check
	- <filename>README.TXT</filename> in the same directory for the
	- most up to date information about these floppy images.</para>
	-
	<important>
	<para>Your FTP program must use <emphasis>binary mode</emphasis>
	to download these disk images. Some web browsers have been
	known to use <emphasis>text</emphasis> (or
	<emphasis>ASCII</emphasis>) mode, which will be apparent if you
	cannot boot from the disks.</para>
	</important>
	</step>

	<step>
	<title>Prepare the Floppy Disks</title>

	- <para>You must prepare one floppy disk per image file you had to
	+ <para>Prepare one floppy disk per image file you had to
	download. It is imperative that these disks are free from
	defects. The easiest way to test this is to format the disks
	for yourself. Do not trust pre-formatted floppies. The format
	utility in &windows; will not tell about the presence of
	bad blocks, it simply marks them as <quote>bad</quote>
	and ignores them. It is advised that you use brand new
	floppies if choosing this installation route.</para>

	<important>
	- <para>If you try to install FreeBSD and the installation
	+ <para>If you try to install &os; and the installation
	program crashes, freezes, or otherwise misbehaves, one of
	- the first things to suspect is the floppies. Try writing
	+ the first things to suspect is the floppies. Write
	the floppy image files to new disks and try
	again.</para>
	</important>
	</step>

	<step>
	<title>Write the Image Files to the Floppy Disks</title>

	<para>The <filename>.flp</filename> files are
	<emphasis>not</emphasis> regular files you copy to the disk.
	They are images of the complete contents of the
	disk. This means that you <emphasis>cannot</emphasis> simply
	copy files from one disk to another.
	Instead, you must use specific tools to write the
	images directly to the disk.</para>

	<indexterm><primary>DOS</primary></indexterm>
	<para>If you are creating the floppies on a computer running
	&ms-dos; / &windows;, then we provide a tool to do
	this called <command>fdimage</command>.</para>

	<para>If you are using the floppies from the CDROM, and your
	CDROM is the <devicename>E:</devicename> drive, then you would
	run this:</para>

	<screen><prompt>E:\></prompt> <userinput>tools\fdimage floppies\boot.flp A:</userinput></screen>

	<para>Repeat this command for each <filename>.flp</filename>
	file, replacing the floppy disk each time, being sure to label
	the disks with the name of the file that you copied to them.
	Adjust the command line as necessary, depending on where you have
	placed the <filename>.flp</filename> files. If you do not have
	the CDROM, then <command>fdimage</command> can be downloaded from
	the <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/"><filename class="directory">tools</filename>
	- directory</ulink> on the FreeBSD FTP site.</para>
	+ directory</ulink> on the &os; FTP site.</para>

	<para>If you are writing the floppies on a &unix; system (such as
	- another FreeBSD system) you can use the &man.dd.1; command to
	- write the image files directly to disk. On FreeBSD, you would
	+ another &os; system) you can use the &man.dd.1; command to
	+ write the image files directly to disk. On &os;, you would
	run:</para>

	<screen>&prompt.root; <userinput>dd if=boot.flp of=/dev/fd0</userinput></screen>

	- <para>On FreeBSD, <filename>/dev/fd0</filename> refers to the
	+ <para>On &os;, <filename>/dev/fd0</filename> refers to the
	first floppy disk (the <devicename>A:</devicename> drive).
	<filename>/dev/fd1</filename> would be the
	<devicename>B:</devicename> drive, and so on. Other &unix;
	variants might have different names for the floppy disk
	devices, and you will need to check the documentation for the
	system as necessary.</para>
	</step>
	</procedure>

	- <para>You are now ready to start installing FreeBSD.</para>
	+ <para>You are now ready to start installing &os;.</para>
	</sect2>
	</sect1>

	<sect1 id="install-start">
	<title>Starting the Installation</title>

	<important>
	<para>By default, the installation will not make any changes to your
	disk(s) until you see the following message:</para>

	<literallayout class="monospaced">Last Chance: Are you SURE you want continue the installation?

	If you're running this on a disk with data you wish to save then WE
	STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding!

	We can take no responsibility for lost disk contents!</literallayout>

	<para>The install can be exited at any time prior to the final
	warning without changing the contents of the hard drive. If you are
	concerned that you have configured something incorrectly you can just
	turn the computer off before this point, and no damage will be
	done.</para>
	</important>

	<sect2 id="install-starting">
	<title>Booting</title>

	<sect3 id="install-starting-i386">
	<title>Booting for the &i386;</title>

	<procedure>
	<step>
	<para>Start with your computer turned off.</para>
	</step>

	<step>
	<para>Turn on the computer. As it starts it should display an
	option to enter the system set up menu, or BIOS, commonly reached
	by keys like <keycap>F2</keycap>, <keycap>F10</keycap>,
	<keycap>Del</keycap>, or
	<keycombo action="simul">
	<keycap>Alt</keycap>
	<keycap>S</keycap>
	</keycombo>. Use whichever keystroke is indicated on screen. In
	some cases your computer may display a graphic while it starts.
	Typically, pressing <keycap>Esc</keycap> will dismiss the graphic
	and allow you to see the necessary messages.</para>
	</step>

	<step>
	<para>Find the setting that controls which devices the system boots
	from. This is usually labeled as the <quote>Boot Order</quote>
	and commonly shown as a list of devices, such as
	<literal>Floppy</literal>, <literal>CDROM</literal>,
	<literal>First Hard Disk</literal>, and so on.</para>

	<para>If you are booting from the CDROM then make sure that
	the CDROM is selected. If you are booting from a USB disk or
	a floppy disk then
	make sure that is selected instead. In case of doubt, you
	should consult the manual that came with your computer, and/or its
	motherboard.</para>

	<para>Make the change, then save and exit. The computer should now
	restart.</para>
	</step>

	<step>
	<para>If you prepared a <quote>bootable</quote> USB stick, as described in
	<xref linkend="install-boot-media"/>, then plug in your USB
	stick before turning on the computer.</para>

	<para>If you are booting from CDROM, then you will need to turn on
	the computer, and insert the CDROM at the first
	opportunity.</para>

	<note>
	- <para>For &os; 7.<replaceable>X</replaceable>, installation
	- boot floppies are available and can be prepared as
	- described in <xref linkend="install-boot-media"/>. One of
	- them will be the first boot disc:
	- <filename>boot.flp</filename>. Put this disc in your
	- floppy drive and boot the computer.</para>
	+ <para>For &os;/&arch.pc98;, installation boot floppies are
	+ available and can be prepared as described in <xref
	+ linkend="install-boot-media"/>. The first floppy
	+ disc will contain <filename>boot.flp</filename>. Put
	+ this floppy in the floppy drive to boot into the
	+ installer.</para>
	</note>

	<para>If your computer starts up as normal and loads your existing
	operating system, then either:</para>

	<orderedlist>
	<listitem>
	<para>The disks were not inserted early enough in the boot
	process. Leave them in, and try restarting your
	computer.</para>
	</listitem>

	<listitem>
	<para>The BIOS changes earlier did not work correctly. You
	should redo that step until you get the right option.</para>
	</listitem>

	<listitem>
	<para>Your particular BIOS does not support booting from
	the desired media.</para>
	</listitem>
	</orderedlist>
	</step>

	<step>
	- <para>FreeBSD will start to boot. If you are booting from CDROM you
	+ <para>&os; will start to boot. If you are booting from CDROM you
	will see a display similar to this (version information
	omitted):</para>

	<screen>Booting from CD-Rom...
	645MB medium detected
	CD Loader 1.2

	Building the boot loader arguments
	Looking up /BOOT/LOADER... Found
	Relocating the loader and the BTX
	Starting the BTX loader

	BTX loader 1.00 BTX version is 1.02
	Consoles: internal video/keyboard
	BIOS CD is cd0
	BIOS drive C: is disk0
	BIOS drive D: is disk1
	BIOS 636kB/261056kB available memory

	FreeBSD/i386 bootstrap loader, Revision 1.1

	Loading /boot/defaults/loader.conf
	/boot/kernel/kernel text=0x64daa0 data=0xa4e80+0xa9e40 syms=[0x4+0x6cac0+0x4+0x88e9d]
	\</screen>

	<para>If you are booting from floppy disc, you will see a display
	similar to this (version information omitted):</para>

	<screen>Booting from Floppy...
	Uncompressing ... done

	BTX loader 1.00 BTX version is 1.01
	Console: internal video/keyboard
	BIOS drive A: is disk0
	BIOS drive C: is disk1
	BIOS 639kB/261120kB available memory

	FreeBSD/i386 bootstrap loader, Revision 1.1

	Loading /boot/defaults/loader.conf
	/kernel text=0x277391 data=0x3268c+0x332a8 \|

	Insert disk labelled "Kernel floppy 1" and press any key...</screen>

	<para>Follow these instructions by removing the
	<filename>boot.flp</filename> disc, insert the
	<filename>kern1.flp</filename> disc, and press
	<keycap>Enter</keycap>. Boot from first floppy;
	when prompted, insert the other disks as required.</para>
	</step>

	<step>
	<para>Whether you booted from CDROM, USB stick or floppy, the
	boot process will then get to the &os; boot loader
	menu:</para>

	<figure id="boot-loader-menu">
	<title>&os; Boot Loader Menu</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/boot-loader-menu" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Either wait ten seconds, or press <keycap>Enter</keycap>.</para>
	</step>
	</procedure>

	</sect3>

	<sect3>
	<title>Booting for &sparc64;</title>

	<para>Most &sparc64; systems are set up to boot automatically
	from disk. To install &os;, you need to boot over the
	network or from a CDROM, which requires you to break into
	the PROM (OpenFirmware).</para>

	<para>To do this, reboot the system, and wait until the boot
	message appears. It depends on the model, but should look
	about like:</para>

	<screen>Sun Blade 100 (UltraSPARC-IIe), Keyboard Present
	Copyright 1998-2001 Sun Microsystems, Inc. All rights reserved.
	OpenBoot 4.2, 128 MB memory installed, Serial #51090132.
	Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4.</screen>

	<para>If your system proceeds to boot from disk at this point,
	you need to press
	<keycombo action="simul"><keycap>L1</keycap><keycap>A</keycap></keycombo>
	or
	<keycombo action="simul"><keycap>Stop</keycap><keycap>A</keycap></keycombo>
	on the keyboard, or send a <command>BREAK</command> over the
	serial console (using for example <command>~#</command> in
	&man.tip.1; or &man.cu.1;) to get to the PROM prompt. It
	looks like this:</para>

	<screenco>
	<areaspec>
	<area id="prompt-single" coords="1 5"/>
	<area id="prompt-smp" coords="2 5"/>
	</areaspec>

	<screen><prompt>ok </prompt>
	<prompt>ok {0} </prompt></screen>

	<calloutlist>
	<callout arearefs="prompt-single">
	<para>This is the prompt used on systems with just one
	CPU.</para>
	</callout>

	<callout arearefs="prompt-smp">
	<para>This is the prompt used on SMP systems, the digit
	indicates the number of the active CPU.</para>
	</callout>
	</calloutlist>
	</screenco>

	<para>At this point, place the CDROM into your drive, and from
	the PROM prompt, type <command>boot cdrom</command>.</para>

	</sect3>

	</sect2>

	<sect2 id="view-probe">
	<title>Reviewing the Device Probe Results</title>

	<para>The last few hundred lines that have been displayed on screen are
	stored and can be reviewed.</para>

	<para>To review the buffer, press <keycap>Scroll Lock</keycap>. This
	turns on scrolling in the display. You can then use the arrow keys, or
	<keycap>PageUp</keycap> and <keycap>PageDown</keycap> to view the
	results. Press <keycap>Scroll Lock</keycap> again to stop
	scrolling.</para>

	<para>Do this now, to review the text that scrolled off the screen when
	the kernel was carrying out the device probes. You will see text
	similar to <xref linkend="install-dev-probe"/>, although the precise
	text will differ depending on the devices that you have in your
	computer.</para>

	<figure id="install-dev-probe">
	<title>Typical Device Probe Results</title>

	<screen>avail memory = 253050880 (247120K bytes)
	Preloaded elf kernel "kernel" at 0xc0817000.
	Preloaded mfs_root "/mfsroot" at 0xc0817084.
	md0: Preloaded image </mfsroot> 4423680 bytes at 0xc03ddcd4

	md1: Malloc disk
	Using $PIR table, 4 entries at 0xc00fde60
	npx0: <math processor> on motherboard
	npx0: INT 16 interface
	pcib0: <Host to PCI bridge> on motherboard
	pci0: <PCI bus> on pcib0
	pcib1:<VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge> at device 1.0 on pci0
	pci1: <PCI bus> on pcib1
	pci1: <Matrox MGA G200 AGP graphics accelerator> at 0.0 irq 11
	isab0: <VIA 82C586 PCI-ISA bridge> at device 7.0 on pci0
	isa0: <iSA bus> on isab0
	atapci0: <VIA 82C586 ATA33 controller> port 0xe000-0xe00f at device 7.1 on pci0
	ata0: at 0x1f0 irq 14 on atapci0
	ata1: at 0x170 irq 15 on atapci0
	uhci0 <VIA 83C572 USB controller> port 0xe400-0xe41f irq 10 at device 7.2 on pci
	0
	usb0: <VIA 83572 USB controller> on uhci0
	usb0: USB revision 1.0
	uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr1
	uhub0: 2 ports with 2 removable, self powered
	pci0: <unknown card> (vendor=0x1106, dev=0x3040) at 7.3
	dc0: <ADMtek AN985 10/100BaseTX> port 0xe800-0xe8ff mem 0xdb000000-0xeb0003ff ir
	q 11 at device 8.0 on pci0
	dc0: Ethernet address: 00:04:5a:74:6b:b5
	miibus0: <MII bus> on dc0
	ukphy0: <Generic IEEE 802.3u media interface> on miibus0
	ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
	ed0: <NE2000 PCI Ethernet (RealTek 8029)> port 0xec00-0xec1f irq 9 at device 10.
	0 on pci0
	ed0 address 52:54:05:de:73:1b, type NE2000 (16 bit)
	isa0: too many dependant configs (8)
	isa0: unexpected small tag 14
	orm0: <Option ROM> at iomem 0xc0000-0xc7fff on isa0
	fdc0: <NEC 72065B or clone> at port 0x3f0-0x3f5,0x3f7 irq 6 drq2 on isa0
	fdc0: FIFO enabled, 8 bytes threshold
	fd0: <1440-KB 3.5” drive> on fdc0 drive 0
	atkbdc0: <Keyboard controller (i8042)> at port 0x60,0x64 on isa0
	atkbd0: <AT Keyboard> flags 0x1 irq1 on atkbdc0
	kbd0 at atkbd0
	psm0: <PS/2 Mouse> irq 12 on atkbdc0
	psm0: model Generic PS/@ mouse, device ID 0
	vga0: <Generic ISA VGA> at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0
	sc0: <System console> at flags 0x100 on isa0
	sc0: VGA <16 virtual consoles, flags=0x300>
	sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0
	sio0: type 16550A
	sio1 at port 0x2f8-0x2ff irq 3 on isa0
	sio1: type 16550A
	ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0
	pppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode
	ppc0: FIFO with 16/16/15 bytes threshold
	plip0: <PLIP network interface> on ppbus0
	ad0: 8063MB <IBM-DHEA-38451> [16383/16/63] at ata0-master UDMA33
	acd0: CD-RW <LITE-ON LTR-1210B> at ata1-slave PIO4
	Mounting root from ufs:/dev/md0c
	/stand/sysinstall running as init on vty0</screen>
	</figure>

	- <para>Check the probe results carefully to make sure that FreeBSD found
	+ <para>Check the probe results carefully to make sure that &os; found
	all the devices you expected. If a device was not found, then it will
	not be listed. A <link linkend="kernelconfig">custom kernel</link>
	allows you to add in support for devices which are not in the
	<filename>GENERIC</filename> kernel, such as sound cards.</para>

	<para>After the procedure of device
	probing, you will see <xref linkend="config-country"/>. Use the
	arrow key to choose a country, region, or group. Then press
	<keycap>Enter</keycap>, it will set your country
	easily.</para>

	<figure id="config-country">
	<title>Selecting Country Menu</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/config-country" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>If you selected <guimenuitem>United States</guimenuitem>
	as country, the standard American keyboard map will be used,
	if a different country is chosen the following menu will be
	displayed. Use the arrow keys to choose the correct keyboard
	map and press <keycap>Enter</keycap>.</para>

	<figure id="config-keymap">
	<title>Selecting Keyboard Menu</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/config-keymap" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>After the country selecting, the <application>sysinstall</application>
	main menu will display.</para>
	</sect2>
	</sect1>

	<sect1 id="using-sysinstall">
	<title>Introducing Sysinstall</title>

	<para>The <application>sysinstall</application> utility is the installation
	- application provided by the FreeBSD Project. It is console based and is
	+ application provided by the &os; Project. It is console based and is
	divided into a number of menus and screens that you can use to
	configure and control the installation process.</para>

	<para>The <application>sysinstall</application> menu system is controlled
	by the arrow keys, <keycap>Enter</keycap>, <keycap>Tab</keycap>,
	<keycap>Space</keycap>, and
	other keys. A detailed description of these keys and what they do is
	contained in <application>sysinstall</application>'s usage
	information.</para>

	<para>To review this information, ensure that the
	<guimenuitem>Usage</guimenuitem> entry is highlighted and that the
	<guibutton>[Select]</guibutton> button is selected, as shown in <xref
	linkend="sysinstall-main3"/>, then press <keycap>Enter</keycap>.</para>

	<para>The instructions for using the menu system will be displayed. After
	reviewing them, press <keycap>Enter</keycap> to return to the Main
	Menu.</para>

	<figure id="sysinstall-main3">
	<title>Selecting Usage from Sysinstall Main Menu</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/main1" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<sect2 id="select-doc">
	<title>Selecting the Documentation Menu</title>

	<para>From the Main Menu, select <guimenuitem>Doc</guimenuitem> with
	the arrow keys and
	press <keycap>Enter</keycap>.</para>

	<figure id="main-doc">
	<title>Selecting Documentation Menu</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/main-doc" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>This will display the Documentation Menu.</para>

	<figure id="docmenu1">
	<title>Sysinstall Documentation Menu</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/docmenu1" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>It is important to read the documents provided.</para>

	<para>To view a document, select it with the arrow keys and
	press <keycap>Enter</keycap>. When finished reading a document,
	pressing <keycap>Enter</keycap> will return to the Documentation
	Menu.</para>

	<para>To return to the Main Installation Menu, select
	<guimenuitem>Exit</guimenuitem> with the
	arrow keys and press <keycap>Enter</keycap>.</para>
	</sect2>

	<sect2 id="keymap">
	<title>Selecting the Keymap Menu</title>

	<para>To change the keyboard mapping, use the arrow keys to select
	<guimenuitem>Keymap</guimenuitem> from the menu and press
	<keycap>Enter</keycap>. This is only required if you are
	using a non-standard or non-US keyboard.</para>

	<figure id="sysinstall-keymap">
	<title>Sysinstall Main Menu</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/main-keymap" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>A different keyboard mapping may be chosen by selecting the
	menu item using up/down arrow keys and pressing <keycap>Space</keycap>.
	Pressing <keycap>Space</keycap> again will unselect the item.
	When finished, choose the &gui.ok; using the arrow keys and press
	<keycap>Enter</keycap>.</para>

	<para>Only a partial list is shown in this screen representation.
	Selecting &gui.cancel; by pressing <keycap>Tab</keycap> will use the
	default keymap and return to the Main Install Menu.</para>

	<figure id="sysinstall-keymap-menu">
	<title>Sysinstall Keymap Menu</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/keymap" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	</sect2>

	<sect2 id="viewsetoptions">
	<title>Installation Options Screen</title>

	<para>Select <guimenuitem>Options</guimenuitem> and press
	<keycap>Enter</keycap>.</para>

	<figure id="sysinstall-options">
	<title>Sysinstall Main Menu</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/main-options" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<figure id="options">
	<title>Sysinstall Options</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/options" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The default values are usually fine for most users and do
	not need to be changed. The release name will vary according
	to the version being installed.</para>

	<para>The description of the selected item will appear at the
	bottom of the screen highlighted in blue. Notice that one of the
	options is <guimenuitem>Use Defaults</guimenuitem> to reset all
	values to startup defaults.</para>

	<para>Press <keycap>F1</keycap> to read the help screen about the
	various options.</para>

	<para>Pressing <keycap>Q</keycap> will return to the Main Install
	menu.</para>
	</sect2>

	<sect2 id="start-install">
	<title>Begin a Standard Installation</title>

	<para>The <guimenuitem>Standard</guimenuitem> installation is the
	- option recommended for those new to &unix; or FreeBSD. Use the arrow
	+ option recommended for those new to &unix; or &os;. Use the arrow
	keys to select <guimenuitem>Standard</guimenuitem> and
	then press <keycap>Enter</keycap> to start the installation.</para>

	<figure id="sysinstall-standard">
	<title>Begin Standard Installation</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/main-std" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>
	</sect2>
	</sect1>

	<sect1 id="install-steps">
	<title>Allocating Disk Space</title>

	- <para>Your first task is to allocate disk space for FreeBSD, and label
	+ <para>Your first task is to allocate disk space for &os;, and label
	that space so that <application>sysinstall</application> can prepare
	- it. In order to do this you need to know how FreeBSD expects to find
	+ it. In order to do this you need to know how &os; expects to find
	information on the disk.</para>

	<sect2 id="install-drive-bios-numbering">
	<title>BIOS Drive Numbering</title>

	- <para>Before you install and configure FreeBSD on your system, there is an
	+ <para>Before you install and configure &os; on your system, there is an
	important subject that you should be aware of, especially if you have
	multiple hard drives.</para>

	<indexterm><primary>MS-DOS</primary></indexterm>
	<indexterm><primary>Microsoft Windows</primary></indexterm>
	<para>In a PC running a BIOS-dependent operating system such as
	&ms-dos; or &microsoft.windows;, the BIOS is able to abstract the
	normal disk drive order, and
	the operating system goes along with the change. This allows the user
	to boot from a disk drive other than the so-called <quote>primary
	master</quote>. This is especially convenient for some users who have
	found that the simplest and cheapest way to keep a system backup is to
	buy an identical second hard drive, and perform routine copies of the
	first drive to the second drive using
	<application><trademark class="registered">Ghost</trademark></application> or <application>XCOPY</application>
	. Then, if the
	first drive fails, or is attacked by a virus, or is scribbled upon by an
	operating system defect, he can easily recover by instructing the BIOS
	to logically swap the drives. It is like switching the cables on the
	drives, but without having to open the case.</para>

	<indexterm><primary>SCSI</primary></indexterm>
	<indexterm><primary>BIOS</primary></indexterm>
	<para>More expensive systems with SCSI controllers often include BIOS
	extensions which allow the SCSI drives to be re-ordered in a similar
	fashion for up to seven drives.</para>

	<para>A user who is accustomed to taking advantage of these features may
	- become surprised when the results with FreeBSD are not as expected.
	- FreeBSD does not use the BIOS, and does not know the <quote>logical BIOS
	+ become surprised when the results with &os; are not as expected.
	+ &os; does not use the BIOS, and does not know the <quote>logical BIOS
	drive mapping</quote>. This can lead to very perplexing situations,
	especially when drives are physically identical in geometry, and have
	also been made as data clones of one another.</para>

	- <para>When using FreeBSD, always restore the BIOS to natural drive
	- numbering before installing FreeBSD, and then leave it that way. If you
	+ <para>When using &os;, always restore the BIOS to natural drive
	+ numbering before installing &os;, and then leave it that way. If you
	need to switch drives around, then do so, but do it the hard way, and
	open the case and move the jumpers and cables.</para>

	<sidebar>
	<title>An Illustration from the Files of Bill and Fred's Exceptional
	Adventures:</title>

	- <para>Bill breaks-down an older Wintel box to make another FreeBSD box
	+ <para>Bill breaks-down an older Wintel box to make another &os; box
	for Fred. Bill installs a single SCSI drive as SCSI unit zero and
	- installs FreeBSD on it.</para>
	+ installs &os; on it.</para>

	<para>Fred begins using the system, but after several days notices that
	the older SCSI drive is reporting numerous soft errors and reports
	this fact to Bill.</para>

	<para>After several more days, Bill decides it is time to address the
	situation, so he grabs an identical SCSI drive from the disk drive
	<quote>archive</quote> in the back room. An initial surface scan
	indicates that
	this drive is functioning well, so Bill installs this drive as SCSI
	unit four and makes an image copy from drive zero to drive four. Now
	that the new drive is installed and functioning nicely, Bill decides
	that it is a good idea to start using it, so he uses features in the
	SCSI BIOS to re-order the disk drives so that the system boots from
	- SCSI unit four. FreeBSD boots and runs just fine.</para>
	+ SCSI unit four. &os; boots and runs just fine.</para>

	<para>Fred continues his work for several days, and soon Bill and Fred
	decide that it is time for a new adventure — time to upgrade
	to a
	- newer version of FreeBSD. Bill removes SCSI unit zero because it was
	+ newer version of &os;. Bill removes SCSI unit zero because it was
	a bit flaky and replaces it with another identical disk drive from
	the <quote>archive</quote>. Bill then installs the new version of
	- FreeBSD onto the new SCSI unit zero using Fred's magic Internet FTP
	+ &os; onto the new SCSI unit zero using Fred's magic Internet FTP
	floppies. The installation goes well.</para>

	- <para>Fred uses the new version of FreeBSD for a few days, and certifies
	+ <para>Fred uses the new version of &os; for a few days, and certifies
	that it is good enough for use in the engineering department. It is
	time to copy all of his work from the old version. So Fred mounts
	- SCSI unit four (the latest copy of the older FreeBSD version). Fred
	+ SCSI unit four (the latest copy of the older &os; version). Fred
	is dismayed to find that none of his precious work is present on SCSI
	unit four.</para>

	<para>Where did the data go?</para>

	<para>When Bill made an image copy of the original SCSI unit zero onto
	SCSI unit four, unit four became the <quote>new clone</quote>.
	When Bill re-ordered the SCSI BIOS so that he could boot from
	SCSI unit four, he was only fooling himself.
	- FreeBSD was still running on SCSI unit zero.
	+ &os; was still running on SCSI unit zero.
	Making this kind of BIOS change will cause some or all of the Boot and
	Loader code to be fetched from the selected BIOS drive, but when the
	- FreeBSD kernel drivers take-over, the BIOS drive numbering will be
	- ignored, and FreeBSD will transition back to normal drive numbering.
	+ &os; kernel drivers take-over, the BIOS drive numbering will be
	+ ignored, and &os; will transition back to normal drive numbering.
	In the illustration at hand, the system continued to operate on the
	original SCSI unit zero, and all of Fred's data was there, not on SCSI
	unit four. The fact that the system appeared to be running on SCSI
	unit four was simply an artifact of human expectations.</para>

	<para>We are delighted to mention that no data bytes were killed or
	harmed in any way by our discovery of this phenomenon. The older SCSI
	unit zero was retrieved from the bone pile, and all of Fred's work was
	returned to him, (and now Bill knows that he can count as high as
	zero).</para>

	<para>Although SCSI drives were used in this illustration, the concepts
	apply equally to IDE drives.</para>
	</sidebar>
	</sect2>

	<sect2 id="main-fdisk">
	<title>Creating Slices Using FDisk</title>

	<note>
	<para>No changes you make at this point will be written to the disk.
	If you think you have made a mistake and want to start again you can
	use the menus to exit <application>sysinstall</application> and try
	again or press <keycap>U</keycap> to use the
	<guimenuitem>Undo</guimenuitem> option.
	If you get confused and can not see how to exit you can
	always turn your computer off.</para>
	</note>

	<para>After choosing to begin a standard installation in
	<application>sysinstall</application> you will be shown this
	message:</para>

	<screen> Message
	In the next menu, you will need to set up a DOS-style ("fdisk")
	partitioning scheme for your hard disk. If you simply wish to devote
	all disk space to FreeBSD (overwriting anything else that might be on
	the disk(s) selected) then use the (A)ll command to select the default
	partitioning scheme followed by a (Q)uit. If you wish to allocate only
	free space to FreeBSD, move to a partition marked "unused" and use the
	(C)reate command.
	[ OK ]

	[ Press enter or space ]</screen>

	<para>Press <keycap>Enter</keycap> as instructed. You will then be
	shown a list of all the hard drives that the kernel found when it
	carried out the device probes.
	<xref linkend="sysinstall-fdisk-drive1"/> shows an example from a
	system with two IDE disks. They have been called
	<devicename>ad0</devicename> and <devicename>ad2</devicename>.</para>

	<figure id="sysinstall-fdisk-drive1">
	<title>Select Drive for FDisk</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/fdisk-drive1" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>You might be wondering why <devicename>ad1</devicename> is not
	listed here. Why has it been missed?</para>

	<para>Consider what would happen if you had two IDE hard disks, one
	as the master on the first IDE controller, and one as the master on
	- the second IDE controller. If FreeBSD numbered these as it found
	+ the second IDE controller. If &os; numbered these as it found
	them, as <devicename>ad0</devicename> and
	<devicename>ad1</devicename> then everything would work.</para>

	<para>But if you then added a third disk, as the slave device on the
	first IDE controller, it would now be <devicename>ad1</devicename>,
	and the previous <devicename>ad1</devicename> would become
	<devicename>ad2</devicename>. Because device names (such as
	<devicename>ad1s1a</devicename>) are used to find filesystems, you
	may suddenly discover that some of your filesystems no longer
	- appear correctly, and you would need to change your FreeBSD
	+ appear correctly, and you would need to change your &os;
	configuration.</para>

	<para>To work around this, the kernel can be configured to name IDE
	disks based on where they are, and not the order in which they were
	found. With this scheme the master disk on the second IDE
	controller will <emphasis>always</emphasis> be
	<devicename>ad2</devicename>, even if there are no
	<devicename>ad0</devicename> or <devicename>ad1</devicename>
	devices.</para>

	- <para>This configuration is the default for the FreeBSD kernel, which
	+ <para>This configuration is the default for the &os; kernel, which
	is why this display shows <devicename>ad0</devicename> and
	<devicename>ad2</devicename>. The machine on which this screenshot
	was taken had IDE disks on both master channels of the IDE
	controllers, and no disks on the slave channels.</para>

	- <para>You should select the disk on which you want to install FreeBSD,
	+ <para>You should select the disk on which you want to install &os;,
	and then press &gui.ok;.
	<application>FDisk</application> will start, with a display similar to
	that shown in <xref linkend="sysinstall-fdisk1"/>.</para>

	<para>The <application>FDisk</application> display is broken into three
	sections.</para>

	<para>The first section, covering the first two lines of the display,
	- shows details about the currently selected disk, including its FreeBSD
	+ shows details about the currently selected disk, including its &os;
	name, the disk geometry, and the total size of the disk.</para>

	<para>The second section shows the slices that are currently on the
	- disk, where they start and end, how large they are, the name FreeBSD
	+ disk, where they start and end, how large they are, the name &os;
	gives them, and their description and sub-type. This example shows two
	small unused slices, which are artifacts of disk layout schemes on the
	PC. It also shows one large <acronym>FAT</acronym> slice, which
	almost certainly appears as <devicename>C:</devicename> in
	&ms-dos; / &windows;, and an extended slice, which may contain other
	drive letters for &ms-dos; / &windows;.</para>

	<para>The third section shows the commands that are available in
	<application>FDisk</application>.</para>

	<figure id="sysinstall-fdisk1">
	<title>Typical <command>fdisk</command> Partitions Before Editing</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/fdisk-edit1" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>What you do now will depend on how you want to slice up your
	disk.</para>

	- <para>If you want to use FreeBSD for the entire disk (which will delete
	+ <para>If you want to use &os; for the entire disk (which will delete
	all the other data on this disk when you confirm that you want
	<application>sysinstall</application> to continue later in the
	installation process) then you can press <keycap>A</keycap>, which
	corresponds to the <guimenuitem>Use Entire Disk</guimenuitem> option.
	The existing slices will be removed, and replaced with a small area
	flagged as <literal>unused</literal> (again, an artifact of PC disk
	- layout), and then one large slice for FreeBSD. If you do this, then
	- you should select the newly created FreeBSD slice using the arrow
	+ layout), and then one large slice for &os;. If you do this, then
	+ you should select the newly created &os; slice using the arrow
	keys, and press <keycap>S</keycap> to mark the slice as being
	bootable. The screen will then look very similar to
	<xref linkend="sysinstall-fdisk2"/>. Note the
	<literal>A</literal> in the <literal>Flags</literal> column, which
	indicates that this slice is <emphasis>active</emphasis>, and will be
	booted from.</para>

	<para>If you will be deleting an existing slice to make space for
	- FreeBSD then you should select the slice using the arrow keys, and
	+ &os; then you should select the slice using the arrow keys, and
	then press <keycap>D</keycap>. You can then press <keycap>C</keycap>,
	and be prompted for size of slice you want to create. Enter the
	appropriate figure and press <keycap>Enter</keycap>. The default
	value in this box represents the largest possible slice you can
	make, which could be the largest contiguous block of unallocated
	space or the size of the entire hard disk.</para>

	- <para>If you have already made space for FreeBSD (perhaps by using a
	+ <para>If you have already made space for &os; (perhaps by using a
	tool such as <application>&partitionmagic;</application>) then you can
	press <keycap>C</keycap> to create a new slice. Again, you will be
	prompted for the size of slice you would like to create.</para>

	<figure id="sysinstall-fdisk2">
	<title>Fdisk Partition Using Entire Disk</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/fdisk-edit2" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>When finished, press <keycap>Q</keycap>. Your changes will be
	saved in <application>sysinstall</application>, but will not yet be
	written to disk.</para>
	</sect2>

	<sect2 id="bootmgr">
	<title>Install a Boot Manager</title>

	<para>You now have the option to install a boot manager. In general,
	- you should choose to install the FreeBSD boot manager if:</para>
	+ you should choose to install the &os; boot manager if:</para>

	<itemizedlist>
	<listitem>
	- <para>You have more than one drive, and have installed FreeBSD onto
	+ <para>You have more than one drive, and have installed &os; onto
	a drive other than the first one.</para>
	</listitem>

	<listitem>
	- <para>You have installed FreeBSD alongside another operating system
	- on the same disk, and you want to choose whether to start FreeBSD
	+ <para>You have installed &os; alongside another operating system
	+ on the same disk, and you want to choose whether to start &os;
	or the other operating system when you start the computer.</para>
	</listitem>
	</itemizedlist>

	- <para>If FreeBSD is going to be the only operating system on
	+ <para>If &os; is going to be the only operating system on
	this machine, installed on the first hard disk, then the
	<guimenuitem>Standard</guimenuitem> boot manager will suffice.
	Choose <guimenuitem>None</guimenuitem> if you are using a
	- third-party boot manager capable of booting FreeBSD.</para>
	+ third-party boot manager capable of booting &os;.</para>

	<para>Make your choice and press <keycap>Enter</keycap>.</para>

	<figure id="sysinstall-bootmgr">
	<title>Sysinstall Boot Manager Menu</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/boot-mgr" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The help screen, reached by pressing <keycap>F1</keycap>,
	discusses the problems that can be encountered when trying to share
	the hard disk between operating systems.</para>
	</sect2>

	<sect2>
	<title>Creating Slices on Another Drive</title>

	<para>If there is more than one drive, it will return to the
	Select Drives screen after the boot manager selection. If you wish to
	- install FreeBSD on to more than one disk, then you can select another
	+ install &os; on to more than one disk, then you can select another
	disk here and repeat the slice process using
	<application>FDisk</application>.</para>

	<important>
	- <para>If you are installing FreeBSD on a drive other than your
	- first, then the FreeBSD boot manager needs to be installed on
	+ <para>If you are installing &os; on a drive other than your
	+ first, then the &os; boot manager needs to be installed on
	both drives.</para>
	</important>

	<figure id="sysinstall-fdisk-drive2">
	<title>Exit Select Drive</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/fdisk-drive2" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The <keycap>Tab</keycap> key toggles between the last drive
	selected, &gui.ok;, and
	&gui.cancel;.</para>

	<para>Press the <keycap>Tab</keycap> once to toggle to the
	&gui.ok;, then
	press <keycap>Enter</keycap>
	to continue with the installation.</para>
	</sect2>

	<sect2 id="bsdlabeleditor">
	<title>Creating Partitions Using
	<application>Disklabel</application></title>

	<para>You must now create some partitions inside each slice that you
	have just created. Remember that each partition is lettered, from
	<literal>a</literal> through to <literal>h</literal>, and that
	partitions <literal>b</literal>, <literal>c</literal>, and
	<literal>d</literal> have conventional meanings that you should adhere
	to.</para>

	<para>Certain applications can benefit from particular partition
	schemes, especially if you are laying out partitions across more than
	- one disk. However, for this, your first FreeBSD installation, you do
	+ one disk. However, for this, your first &os; installation, you do
	not need to give too much thought to how you partition the disk. It
	- is more important that you install FreeBSD and start learning how to
	- use it. You can always re-install FreeBSD to change your partition
	+ is more important that you install &os; and start learning how to
	+ use it. You can always re-install &os; to change your partition
	scheme when you are more familiar with the operating system.</para>

	<para>This scheme features four partitions—one for swap space, and
	three for filesystems.</para>

	<table frame="none" pgwide="1">
	<title>Partition Layout for First Disk</title>

	<tgroup cols="4">
	<colspec colwidth="1*"/>
	<colspec colwidth="1*"/>
	<colspec colwidth="1*"/>
	<colspec colwidth="4*"/>

	<thead>
	<row>
	<entry>Partition</entry>

	<entry>Filesystem</entry>

	<entry>Size</entry>

	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>a</literal></entry>

	<entry><filename>/</filename></entry>

	<entry>1 GB</entry>

	<entry>This is the root filesystem. Every other filesystem
	will be mounted somewhere under this one. 1 GB is a
	reasonable size for this filesystem. You will not be storing
	- too much data on it, as a regular FreeBSD install will put
	+ too much data on it, as a regular &os; install will put
	about 128 MB of data here. The remaining space is for
	temporary data, and also leaves expansion space if future
	versions of
	- FreeBSD need more space in <filename>/</filename>.</entry>
	+ &os; need more space in <filename>/</filename>.</entry>
	</row>

	<row>
	<entry><literal>b</literal></entry>

	<entry>N/A</entry>

	<entry>2-3 x RAM</entry>

	<entry><para>The system's swap space is kept on the <literal>b</literal> partition.
	Choosing the right amount of swap space can be a bit of an
	art. A good rule of thumb is that your swap
	space should be two or three times as much as the
	available physical memory (RAM).
	You should also have at least 64 MB of swap, so if you
	have less than 32 MB of RAM in your computer then set
	the swap amount to 64 MB.</para><para>

	If you have more than one disk then you can put swap
	- space on each disk. FreeBSD will then use each disk for
	+ space on each disk. &os; will then use each disk for
	swap, which effectively speeds up the act of swapping. In
	this case, calculate the total amount of swap you need
	(e.g., 128 MB), and then divide this by the number of
	disks you have (e.g., two disks) to give the amount of swap
	you should put on each disk, in this example, 64 MB of
	swap per disk.</para></entry>
	</row>

	<row>
	<entry><literal>e</literal></entry>

	<entry><filename>/var</filename></entry>

	<entry>512 MB to 4096 MB</entry>

	<entry>The <filename>/var</filename> directory contains
	files that are constantly varying;
	log files, and other administrative files. Many
	of these files are read-from or written-to extensively during
	- FreeBSD's day-to-day running. Putting these files on another
	- filesystem allows FreeBSD to optimize the access of these
	+ &os;'s day-to-day running. Putting these files on another
	+ filesystem allows &os; to optimize the access of these
	files without affecting other files in other directories that
	do not have the same access pattern.</entry>
	</row>

	<row>
	<entry><literal>f</literal></entry>

	<entry><filename>/usr</filename></entry>

	<entry>Rest of disk (at least 8 GB)</entry>

	<entry>All your other files will typically be stored in
	<filename>/usr</filename> and its subdirectories.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<warning>
	<para>The values above are given as example and should be used
	by experienced users only. Users are encouraged to use the
	automatic partition layout called <literal>Auto
	Defaults</literal> by the &os; partition editor.</para>
	</warning>

	- <para>If you will be installing FreeBSD on to more than one disk then
	+ <para>If you will be installing &os; on to more than one disk then
	you must also create partitions in the other slices that you
	configured. The easiest way to do this is to create two partitions on
	each disk, one for the swap space, and one for a filesystem.</para>

	<table frame="none" pgwide="1">
	<title>Partition Layout for Subsequent Disks</title>

	<tgroup cols="4">
	<colspec colwidth="1*"/>
	<colspec colwidth="1*"/>
	<colspec colwidth="2*"/>
	<colspec colwidth="3*"/>

	<thead>
	<row>
	<entry>Partition</entry>

	<entry>Filesystem</entry>

	<entry>Size</entry>

	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>b</literal></entry>

	<entry>N/A</entry>

	<entry>See description</entry>

	<entry>As already discussed, you can split swap space across
	each disk. Even though the <literal>a</literal> partition is
	free, convention dictates that swap space stays on the
	<literal>b</literal> partition.</entry>
	</row>

	<row>
	<entry><literal>e</literal></entry>

	<entry>/disk<replaceable>n</replaceable></entry>

	<entry>Rest of disk</entry>

	<entry>The rest of the disk is taken up with one big partition.
	This could easily be put on the <literal>a</literal>
	partition, instead of the <literal>e</literal> partition.
	However, convention says that the <literal>a</literal>
	partition on a slice is reserved for the filesystem that will
	be the root (<filename>/</filename>) filesystem. You do not
	have to follow this convention, but
	<application>sysinstall</application> does, so following it
	yourself makes the installation slightly cleaner. You can
	choose to mount this filesystem anywhere; this example
	suggests that you mount them as directories
	<filename>/disk<replaceable>n</replaceable></filename>, where
	<replaceable>n</replaceable> is a number that changes for each
	disk. But you can use another scheme if you prefer.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>Having chosen your partition layout you can now create it using
	<application>sysinstall</application>. You will see this
	message:</para>

	<screen> Message
	Now, you need to create BSD partitions inside of the fdisk
	partition(s) just created. If you have a reasonable amount of disk
	space (1GB or more) and don't have any special requirements, simply
	use the (A)uto command to allocate space automatically. If you have
	more specific needs or just don't care for the layout chosen by
	(A)uto, press F1 for more information on manual layout.

	[ OK ]
	[ Press enter or space ]</screen>

	<para>Press <keycap>Enter</keycap> to start the FreeBSD partition
	editor, called <application>Disklabel</application>.</para>

	<para><xref linkend="sysinstall-label"/> shows the display when you first
	start <application>Disklabel</application>. The display is divided in
	to three sections.</para>

	<para>The first few lines show the name of the disk you are currently
	working on, and the slice that contains the partitions you are
	creating (at this point <application>Disklabel</application> calls
	this the <literal>Partition name</literal> rather than slice name).
	This display also shows the amount of free space within the slice;
	that is, space that was set aside in the slice, but that has not yet
	been assigned to a partition.</para>

	<para>The middle of the display shows the partitions that have been
	created, the name of the filesystem that each partition contains,
	their size, and some options pertaining to the creation of the
	filesystem.</para>

	<para>The bottom third of the screen shows the keystrokes that are valid
	in <application>Disklabel</application>.</para>

	<figure id="sysinstall-label">
	<title>Sysinstall Disklabel Editor</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/disklabel-ed1" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para><application>Disklabel</application> can automatically create
	partitions for you and assign them default sizes. The default sizes
	are calculated with the help of an internal partition sizing algorithm
	based on the disk size. Try this now, by
	Pressing <keycap>A</keycap>. You will see a display similar to that
	shown in <xref linkend="sysinstall-label2"/>. Depending on the size of
	the disk you are using, the defaults may or may not be appropriate.
	This does not matter, as you do not have to accept the
	defaults.</para>

	<note>
	<para>The default partitioning assigns
	the <filename>/tmp</filename> directory its own partition instead
	of being part of the <filename>/</filename> partition. This
	helps avoid filling the <filename>/</filename> partition with
	temporary files.</para>
	</note>

	<figure id="sysinstall-label2">
	<title>Sysinstall Disklabel Editor with Auto Defaults</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/disklabel-auto" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>If you choose to not use the default partitions and wish to
	replace them with your
	own, use the arrow keys to select the first partition, and press
	<keycap>D</keycap> to delete it. Repeat this to delete all the
	suggested partitions.</para>

	<para>To create the first partition (<literal>a</literal>, mounted as
	<filename>/</filename> — root), make sure the proper disk slice
	at the top of
	the screen is selected and press <keycap>C</keycap>. A dialog box
	will appear prompting you for the size of the new partition (as shown
	in <xref linkend="sysinstall-label-add"/>). You can enter the size as
	the number of disk blocks you want to use, or as a
	number followed by either <literal>M</literal> for megabytes,
	<literal>G</literal> for gigabytes, or <literal>C</literal> for
	cylinders.</para>

	<figure id="sysinstall-label-add">
	<title>Free Space for Root Partition</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/disklabel-root1" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The default size shown will create a partition that takes up the
	rest of the slice. If you are using the partition sizes described
	in the earlier example, then delete the existing figure using
	<keycap>Backspace</keycap>, and then type in
	<userinput>512M</userinput>, as shown in
	<xref linkend="sysinstall-label-add2"/>. Then press
	&gui.ok;.</para>

	<figure id="sysinstall-label-add2">
	<title>Edit Root Partition Size</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/disklabel-root2" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Having chosen the partition's size you will then be asked whether
	this partition will contain a filesystem or swap space. The dialog
	box is shown in <xref linkend="sysinstall-label-type"/>. This first
	partition will contain a filesystem, so check that
	<guimenuitem>FS</guimenuitem> is selected and press
	<keycap>Enter</keycap>.</para>

	<figure id="sysinstall-label-type">
	<title>Choose the Root Partition Type</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/disklabel-fs" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Finally, because you are creating a filesystem, you must tell
	<application>Disklabel</application> where the filesystem is to be
	mounted. The dialog box is shown in
	<xref linkend="sysinstall-label-mount"/>. The root filesystem's mount
	point is <filename>/</filename>, so type <userinput>/</userinput>, and
	then press <keycap>Enter</keycap>.</para>

	<figure id="sysinstall-label-mount">
	<title>Choose the Root Mount Point</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/disklabel-root3" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The display will then update to show you the newly created
	partition. You should repeat this procedure for the other
	partitions. When you create the swap partition, you will not be
	prompted for the filesystem mount point, as swap partitions are never
	mounted. When you create the final partition,
	<filename>/usr</filename>, you can leave the suggested size as is, to
	use the rest of the slice.</para>

	- <para>Your final FreeBSD DiskLabel Editor screen will appear similar to
	+ <para>Your final &os; DiskLabel Editor screen will appear similar to
	<xref linkend="sysinstall-label4"/>, although your values chosen may
	be different. Press <keycap>Q</keycap> to finish.</para>

	<figure id="sysinstall-label4">
	<title>Sysinstall Disklabel Editor</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/disklabel-ed2" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>
	</sect2>
	</sect1>

	<sect1 id="install-choosing">
	<title>Choosing What to Install</title>

	<sect2 id="distset">
	<title>Select the Distribution Set</title>

	<para>Deciding which distribution set to install will depend largely
	on the intended use of the system and the amount of disk space
	available. The predefined options range from installing the
	smallest possible configuration to everything. Those who are
	- new to &unix; and/or FreeBSD should almost certainly select one
	+ new to &unix; and/or &os; should almost certainly select one
	of these canned options. Customizing a distribution set is
	typically for the more experienced user.</para>

	<para>Press <keycap>F1</keycap> for more information on the
	distribution set options and what they contain. When finished
	reviewing the help, pressing <keycap>Enter</keycap> will return
	to the Select Distributions Menu.</para>

	<para>If a graphical user interface is desired then the
	configuration of the X server and selection of a default
	desktop must be done after the installation of &os;. More
	information regarding the installation and configuration of a
	X server can be found in <xref linkend="x11"/>.</para>

	<para>If compiling a custom kernel is anticipated, select an option
	which includes the source code. For more information on why a
	custom kernel should be built or how to build a custom kernel, see
	<xref linkend="kernelconfig"/>.</para>

	<para>Obviously, the most versatile system is one that includes
	everything. If there is adequate disk space, select
	<guimenuitem>All</guimenuitem> as shown in
	<xref linkend="distribution-set1"/> by using the arrow keys and
	press <keycap>Enter</keycap>. If there is a concern about disk
	space consider using an option that is more suitable for the
	situation.
	Do not fret over the perfect choice, as other distributions can be
	added after installation.</para>

	<figure id="distribution-set1">
	<title>Choose Distributions</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/dist-set" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>
	</sect2>

	<sect2 id="portscol">
	<title>Installing the Ports Collection</title>

	<para>After selecting the desired distribution, an opportunity to
	- install the FreeBSD Ports Collection is presented. The ports
	+ install the &os; Ports Collection is presented. The ports
	collection is an easy and convenient way to install software.
	The Ports Collection does not contain the source code necessary
	to compile the software. Instead, it is a collection of files which
	automates the downloading, compiling and installation
	of third-party software packages.
	<xref linkend="ports"/> discusses how to use the ports
	collection.</para>

	<para>The installation program does not check to see if you have
	adequate space. Select this option only if you have
	- adequate hard disk space. As of FreeBSD &rel.current;, the FreeBSD
	+ adequate hard disk space. As of &os; &rel.current;, the &os;
	Ports Collection takes up about &ports.size; of disk space.
	You can safely assume a larger value for more recent versions
	- of FreeBSD.</para>
	+ of &os;.</para>

	<screen> User Confirmation Requested
	Would you like to install the FreeBSD ports collection?

	This will give you ready access to over &os.numports; ported software packages,
	at a cost of around &ports.size; of disk space when "clean" and possibly much
	more than that if a lot of the distribution tarballs are loaded
	(unless you have the extra CDs from a FreeBSD CD/DVD distribution
	available and can mount it on /cdrom, in which case this is far less
	of a problem).

	The Ports Collection is a very valuable resource and well worth having
	on your /usr partition, so it is advisable to say Yes to this option.

	For more information on the Ports Collection & the latest ports,
	visit:
	http://www.FreeBSD.org/ports

	[ Yes ] No</screen>

	<para>Select &gui.yes; with the arrow keys to
	install the Ports Collection or &gui.no; to
	skip this option. Press <keycap>Enter</keycap> to continue.
	The Choose Distributions menu will redisplay.</para>

	<figure id="distribution-set2">
	<title>Confirm Distributions</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/dist-set2" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>If satisfied with the options, select
	<guimenuitem>Exit</guimenuitem> with the arrow keys, ensure that
	&gui.ok; is highlighted, and pressing
	<keycap>Enter</keycap> to continue.</para>

	</sect2>
	</sect1>

	<sect1 id="install-media">
	<title>Choosing Your Installation Media</title>

	<para>If Installing from a CDROM or DVD, use the arrow keys to highlight
	<guimenuitem>Install from a FreeBSD CD/DVD</guimenuitem>. Ensure
	that &gui.ok; is highlighted, then press
	<keycap>Enter</keycap> to proceed with the installation.</para>

	<para>For other methods of installation, select the appropriate
	option and follow the instructions.</para>

	<para>Press <keycap>F1</keycap> to display the Online Help for
	installation media. Press <keycap>Enter</keycap> to return
	to the media selection menu.</para>

	<figure id="choose-media">
	<title>Choose Installation Media</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/media" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<note>
	<title>FTP Installation Modes</title>

	<indexterm>
	<primary>installation</primary>
	<secondary>network</secondary>
	<tertiary>FTP</tertiary>
	</indexterm>

	<para>There are three FTP installation modes you can choose from:
	active FTP, passive FTP, or via a HTTP proxy.</para>

	<variablelist>
	<varlistentry>
	<term>FTP Active: <guimenuitem>Install from an FTP
	server</guimenuitem></term>

	<listitem>
	<para>This option will make all FTP transfers
	use <quote>Active</quote>
	mode. This will not work through firewalls, but will
	often work with older FTP servers that do not support
	passive mode. If your connection hangs with passive
	mode (the default), try active!</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>FTP Passive: <guimenuitem>Install from an FTP server through a
	firewall</guimenuitem></term>

	<listitem>
	<indexterm>
	<primary>FTP</primary>
	<secondary>passive mode</secondary>
	</indexterm>

	<para>This option instructs <application>sysinstall</application>
	to <quote>Passive</quote> mode for all FTP operations.
	This allows the user to pass through firewalls
	that do not allow incoming connections on random TCP ports.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>FTP via a HTTP proxy: <guimenuitem>Install from an FTP server
	through a http proxy</guimenuitem></term>

	<listitem>
	<indexterm>
	<primary>FTP</primary>
	<secondary>via a HTTP proxy</secondary>
	</indexterm>

	<para>This option instructs <application>sysinstall</application>
	to use the HTTP
	protocol (like a web browser) to connect to a proxy
	for all FTP operations. The proxy will translate
	the requests and send them to the FTP server.
	This allows the user to pass through firewalls
	that do not allow FTP at all, but offer a HTTP
	proxy.
	In this case, you have to specify the proxy in
	addition to the FTP server.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>For a proxy FTP server, you should usually give the name of the
	server you really want as a part of the username, after an
	<quote>@</quote> sign. The proxy server then <quote>fakes</quote>
	the real server. For example, assuming you want to install from
	<hostid role="fqdn">ftp.FreeBSD.org</hostid>, using the proxy FTP
	server <hostid role="fqdn">foo.example.com</hostid>, listening on port
	1234.</para>

	<para>In this case, you go to the options menu, set the FTP username
	to <literal>ftp@ftp.FreeBSD.org</literal>, and the password to your
	email address. As your installation media, you specify FTP (or
	passive FTP, if the proxy supports it), and the URL
	<literal>ftp://foo.example.com:1234/pub/FreeBSD</literal>.</para>

	<para>Since <filename>/pub/FreeBSD</filename> from
	<hostid role="fqdn">ftp.FreeBSD.org</hostid> is proxied under
	<hostid role="fqdn">foo.example.com</hostid>, you are able to install
	from <emphasis>that</emphasis> machine (which will fetch the files
	from <hostid role="fqdn">ftp.FreeBSD.org</hostid> as your
	installation requests them).</para>
	</note>
	</sect1>

	<sect1 id="install-final-warning">
	<title>Committing to the Installation</title>

	<para>The installation can now proceed if desired. This is also
	the last chance for aborting the installation to prevent changes
	to the hard drive.</para>

	<screen> User Confirmation Requested
	Last Chance! Are you SURE you want to continue the installation?

	If you're running this on a disk with data you wish to save then WE
	STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding!

	We can take no responsibility for lost disk contents!

	[ Yes ] No</screen>

	<para>Select &gui.yes; and press
	<keycap>Enter</keycap> to proceed.</para>

	<para>The installation time will vary according to the distribution
	chosen, installation media, and the speed of the computer.
	There will be a series of
	messages displayed indicating the status.</para>

	<para>The installation is complete when the following message is
	displayed:</para>

	<screen> Message

	Congratulations! You now have FreeBSD installed on your system.

	We will now move on to the final configuration questions.
	For any option you do not wish to configure, simply select No.

	If you wish to re-enter this utility after the system is up, you may
	do so by typing: /usr/sbin/sysinstall.

	[ OK ]

	[ Press enter or space ]</screen>

	<para>Press <keycap>Enter</keycap> to proceed with post-installation
	configurations.</para>

	<para>Selecting &gui.no; and pressing
	<keycap>Enter</keycap> will abort
	the installation so no changes will be made to your system. The
	following message will appear:</para>

	<screen> Message
	Installation complete with some errors. You may wish to scroll
	through the debugging messages on VTY1 with the scroll-lock feature.
	You can also choose "No" at the next prompt and go back into the
	installation menus to retry whichever operations have failed.

	[ OK ]</screen>

	<para>This message is generated because nothing was installed.
	Pressing <keycap>Enter</keycap> will return to the
	Main Installation Menu to exit the installation.</para>
	</sect1>

	<sect1 id="install-post">
	<title>Post-installation</title>

	<para>Configuration of various options follows the successful
	installation. An option can be configured by re-entering the
	- configuration options before booting the new FreeBSD
	+ configuration options before booting the new &os;
	system or after installation using
	<command>sysinstall</command>
	and selecting
	<guimenuitem>Configure</guimenuitem>.</para>

	<sect2 id="inst-network-dev">
	<title>Network Device Configuration</title>

	<para>If you previously configured PPP for an FTP install, this screen
	will not display and can be configured later as described
	above.</para>

	<para>For detailed information on Local Area Networks and
	- configuring FreeBSD as a gateway/router refer to the
	+ configuring &os; as a gateway/router refer to the
	<link linkend="advanced-networking">Advanced Networking</link>
	chapter.</para>

	<screen> User Confirmation Requested
	Would you like to configure any Ethernet or PPP network devices?

	[ Yes ] No</screen>

	<para>To configure a network device, select
	&gui.yes; and press <keycap>Enter</keycap>.
	Otherwise, select &gui.no; to continue.</para>

	<figure id="ed-config1">
	<title>Selecting an Ethernet Device</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/ed0-conf" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Select the interface to be configured with the arrow keys and press
	<keycap>Enter</keycap>.</para>

	<screen> User Confirmation Requested
	Do you want to try IPv6 configuration of the interface?

	Yes [ No ]</screen>

	<para>In this private local area network, the current Internet
	type protocol (<acronym>IPv4</acronym>) was sufficient and &gui.no;
	was selected with the arrow keys and <keycap>Enter</keycap>
	pressed.</para>

	<para>If you are connected to an existing <acronym>IPv6</acronym> network
	with an <acronym>RA</acronym> server, then choose
	&gui.yes; and press <keycap>Enter</keycap>.
	It will take several seconds to scan for RA servers.</para>

	<screen> User Confirmation Requested
	Do you want to try DHCP configuration of the interface?

	Yes [ No ]</screen>

	<para>If DHCP (Dynamic Host Configuration Protocol) is not required
	select &gui.no; with the arrow keys and press
	<keycap>Enter</keycap>.</para>

	<para>Selecting &gui.yes; will execute
	<application>dhclient</application>, and if successful, will fill
	in the network configuration information automatically. Refer to
	<xref linkend="network-dhcp"/> for more information.</para>

	<para>The following Network Configuration screen shows the
	configuration of the Ethernet device for a system that will act
	as the gateway for a Local Area Network.</para>

	<figure id="ed-config2">
	<title>Set Network Configuration for <replaceable>ed0</replaceable></title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/ed0-conf2" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Use <keycap>Tab</keycap> to select the information fields and
	fill in appropriate information:</para>

	<variablelist>
	<varlistentry>
	<term>Host</term>

	<listitem>
	<para>The fully-qualified hostname, such as
	<hostid role="fqdn">k6-2.example.com</hostid> in
	this case.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Domain</term>

	<listitem>
	<para>The name of the domain that your machine is
	in, such as <hostid role="domainname">example.com</hostid>
	for this case.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>IPv4 Gateway</term>

	<listitem>
	<para>IP address of host forwarding packets to non-local
	destinations. You must fill this in if the machine is a node
	on the network. <emphasis>Leave this field blank</emphasis>
	if the machine is the gateway to the Internet for the
	network. The IPv4 Gateway is also known as the default
	gateway or default route.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Name server</term>

	<listitem>
	<para>IP address of your local DNS server. There is no local
	DNS server on this private local area network so the IP
	address of the provider's DNS server
	(<hostid role="ipaddr">208.163.10.2</hostid>) was used.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>IPv4 address</term>

	<listitem>
	<para>The IP address to be used for this interface was
	<hostid role="ipaddr">192.168.0.1</hostid></para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Netmask</term>

	<listitem>
	<para>The address block being used for this local area
	network is
	<hostid role="ipaddr">192.168.0.0</hostid> -
	<hostid role="ipaddr">192.168.0.255</hostid>
	with a netmask of
	<hostid role="netmask">255.255.255.0</hostid>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Extra options to ifconfig</term>

	<listitem>
	<para>Any interface-specific options to <command>ifconfig</command>
	you would like to add. There were none in this case.</para>
	</listitem>
	</varlistentry>

	</variablelist>

	<para>Use <keycap>Tab</keycap> to select &gui.ok;
	when finished and press <keycap>Enter</keycap>.</para>


	<screen> User Confirmation Requested
	Would you like to bring the ed0 interface up right now?

	[ Yes ] No</screen>

	<para>Choosing &gui.yes; and pressing
	<keycap>Enter</keycap> will bring
	the machine up on the network and be ready for use. However,
	this does not accomplish much during installation, since
	the machine still needs to be rebooted.</para>
	</sect2>

	<sect2 id="gateway">
	<title>Configure Gateway</title>

	<screen> User Confirmation Requested
	Do you want this machine to function as a network gateway?

	[ Yes ] No</screen>

	<para>If the machine will be acting as the gateway for a local area
	network and forwarding packets between other machines then select
	&gui.yes; and press <keycap>Enter</keycap>.
	If the machine is a node on a network then
	select &gui.no; and press
	<keycap>Enter</keycap> to continue.</para>
	</sect2>

	<sect2 id="inetd-services">
	<title>Configure Internet Services</title>

	<screen> User Confirmation Requested
	Do you want to configure inetd and the network services that it provides?

	Yes [ No ]</screen>

	<para>If &gui.no; is selected, various services
	such <application>telnetd</application> will not be enabled. This
	means that remote users will not be able to
	<application>telnet</application> into this machine. Local users
	will still be able to access remote machines with
	<application>telnet</application>.</para>

	<para>These services can be enabled after installation by editing
	<filename>/etc/inetd.conf</filename> with your favorite text editor.
	See <xref linkend="network-inetd-overview"/> for more information.</para>

	<para>Select &gui.yes; if you wish to
	configure these services during install. An additional
	confirmation will display:</para>

	<screen> User Confirmation Requested
	The Internet Super Server (inetd) allows a number of simple Internet
	services to be enabled, including finger, ftp and telnetd. Enabling
	these services may increase risk of security problems by increasing
	the exposure of your system.

	With this in mind, do you wish to enable inetd?

	[ Yes ] No</screen>

	<para>Select &gui.yes; to continue.</para>

	<screen> User Confirmation Requested
	inetd(8) relies on its configuration file, /etc/inetd.conf, to determine
	which of its Internet services will be available. The default FreeBSD
	inetd.conf(5) leaves all services disabled by default, so they must be
	specifically enabled in the configuration file before they will
	function, even once inetd(8) is enabled. Note that services for
	IPv6 must be separately enabled from IPv4 services.

	Select [Yes] now to invoke an editor on /etc/inetd.conf, or [No] to
	use the current settings.

	[ Yes ] No</screen>

	<para>Selecting &gui.yes; will allow adding
	services by deleting the <literal>#</literal> at the beginning
	of a line.</para>

	<figure id="inetd-edit">
	<title>Editing <filename>inetd.conf</filename></title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/edit-inetd-conf" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>After adding the desired services, pressing <keycap>Esc</keycap>
	will display a menu which will allow exiting and saving
	the changes.</para>

	</sect2>

	<sect2 id="ssh-login">
	<title>Enabling SSH login</title>

	<indexterm>
	<primary>SSH</primary>
	<secondary>sshd</secondary>
	</indexterm>

	<screen> User Confirmation Requested
	Would you like to enable SSH login?
	Yes [ No ]</screen>

	<para>Selecting &gui.yes; will enable &man.sshd.8;, the daemon
	program for <application>OpenSSH</application>. This will
	allow secure remote access to your machine. For more
	information about <application>OpenSSH</application> see <xref
	linkend="openssh"/>.</para>
	</sect2>

	<sect2 id="ftpanon">
	<title>Anonymous FTP</title>

	<indexterm>
	<primary>FTP</primary>
	<secondary>anonymous</secondary>
	</indexterm>

	<screen> User Confirmation Requested
	Do you want to have anonymous FTP access to this machine?

	Yes [ No ]</screen>

	<sect3 id="deny-anon">
	<title>Deny Anonymous FTP</title>

	<para>Selecting the default &gui.no; and pressing
	<keycap>Enter</keycap> will still allow users who have accounts
	with passwords to use FTP to access the machine.</para>
	</sect3>

	<sect3 id="ftpallow">
	<title>Allow Anonymous FTP</title>

	<para>Anyone can access your machine if you elect to allow
	anonymous FTP connections. The security implications should be
	considered before enabling this option. For more information
	about security see <xref linkend="security"/>.</para>

	<para>To allow anonymous FTP, use the arrow keys to select
	&gui.yes; and press <keycap>Enter</keycap>.
	An additional confirmation will display:</para>

	<screen> User Confirmation Requested
	Anonymous FTP permits un-authenticated users to connect to the system
	FTP server, if FTP service is enabled. Anonymous users are
	restricted to a specific subset of the file system, and the default
	configuration provides a drop-box incoming directory to which uploads
	are permitted. You must separately enable both inetd(8), and enable
	ftpd(8) in inetd.conf(5) for FTP services to be available. If you
	did not do so earlier, you will have the opportunity to enable inetd(8)
	again later.

	If you want the server to be read-only you should leave the upload
	directory option empty and add the -r command-line option to ftpd(8)
	in inetd.conf(5)

	Do you wish to continue configuring anonymous FTP?

	[ Yes ] No</screen>

	<para>This message informs you that the FTP service will also
	have to be enabled in <filename>/etc/inetd.conf</filename>
	if you want to allow anonymous FTP connections, see <xref
	linkend="inetd-services"/>. Select &gui.yes; and press
	<keycap>Enter</keycap> to continue; the following screen
	will display:</para>

	<figure id="anon-ftp2">
	<title>Default Anonymous FTP Configuration</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/ftp-anon1" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Use <keycap>Tab</keycap> to select the information
	fields and fill in appropriate information:</para>

	<variablelist>
	<varlistentry>
	<term>UID</term>

	<listitem>
	<para>The user ID you wish to assign to the anonymous
	FTP user. All files uploaded will be owned by this
	ID.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Group</term>

	<listitem>
	<para>Which group you wish the anonymous FTP user to be
	in.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Comment</term>

	<listitem>
	<para>String describing this user in
	<filename>/etc/passwd</filename>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>FTP Root Directory</term>

	<listitem>
	<para>Where files available for anonymous FTP will be
	kept.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Upload Subdirectory</term>

	<listitem>
	<para>Where files uploaded by anonymous FTP users will
	go.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>The FTP root directory will be put in <filename>/var</filename>
	by default. If you do not have enough room there for the
	anticipated FTP needs, the <filename>/usr</filename> directory
	could be used by setting the FTP root directory to
	<filename>/usr/ftp</filename>.</para>

	<para>When you are satisfied with the values, press
	<keycap>Enter</keycap> to continue.</para>

	<screen> User Confirmation Requested
	Create a welcome message file for anonymous FTP users?

	[ Yes ] No</screen>

	<para>If you select &gui.yes; and press
	<keycap>Enter</keycap>, an editor will automatically start
	allowing you to edit the message.</para>

	<figure id="anon-ftp4">
	<title>Edit the FTP Welcome Message</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/ftp-anon2" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>This is a text editor called <command>ee</command>. Use the
	instructions to change the message or change the message later
	using a text editor of your choice. Note the file name/location
	at the bottom of the editor screen.</para>

	<para>Press <keycap>Esc</keycap> and a pop-up menu will default
	to <guimenuitem>a) leave editor</guimenuitem>. Press
	<keycap>Enter</keycap> to exit and continue. Press
	<keycap>Enter</keycap> again to save changes if you made
	any.</para>
	</sect3>
	</sect2>

	<sect2 id="nfsconf">
	<title>Configure Network File System</title>

	<para>Network File System (NFS) allows sharing of files across a
	network. A machine can be configured as a server, a client, or
	both. Refer to <xref linkend="network-nfs"/> for a more information.</para>

	<sect3 id="nsf-server-options">
	<title>NFS Server</title>

	<screen> User Confirmation Requested
	Do you want to configure this machine as an NFS server?

	Yes [ No ]</screen>

	<para>If there is no need for a Network File System server,
	select &gui.no; and press
	<keycap>Enter</keycap>.</para>

	<para>If &gui.yes; is chosen, a message will
	pop-up indicating that the <filename>exports</filename> file must be
	created.</para>

	<screen> Message
	Operating as an NFS server means that you must first configure an
	/etc/exports file to indicate which hosts are allowed certain kinds of
	access to your local filesystems.
	Press [Enter] now to invoke an editor on /etc/exports
	[ OK ]</screen>

	<para>Press <keycap>Enter</keycap> to continue. A text editor will
	start allowing the <filename>exports</filename> file to be created
	and edited.</para>

	<figure id="nfs-server-edit">
	<title>Editing <filename>exports</filename></title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/nfs-server-edit" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Use the instructions to add the actual exported filesystems
	now or later using a text editor of your choice. Note the
	file name/location at the bottom of the editor screen.</para>

	<para>Press <keycap>Esc</keycap> and a pop-up menu will default to
	<guimenuitem>a) leave editor</guimenuitem>. Press
	<keycap>Enter</keycap> to exit and continue.</para>
	</sect3>

	<sect3 id="nfs-client-options">
	<title>NFS Client</title>

	<para>The NFS client allows your machine to access NFS servers.</para>

	<screen> User Confirmation Requested
	Do you want to configure this machine as an NFS client?

	Yes [ No ]</screen>

	<para>With the arrow keys, select &gui.yes;
	or &gui.no; as appropriate and
	press <keycap>Enter</keycap>.</para>
	</sect3>
	</sect2>

	<sect2 id="console">
	<title>System Console Settings</title>

	<para>There are several options available to customize the system
	console.</para>

	<screen> User Confirmation Requested
	Would you like to customize your system console settings?

	[ Yes ] No</screen>

	<para>To view and configure the options, select
	&gui.yes; and press
	<keycap>Enter</keycap>.</para>

	<figure id="saver-options">
	<title>System Console Configuration Options</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/console-saver1" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>A commonly used option is the screen saver. Use the arrow keys
	to select <guimenuitem>Saver</guimenuitem> and then press
	<keycap>Enter</keycap>.</para>

	<figure id="saver-select">
	<title>Screen Saver Options</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/console-saver2" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Select the desired screen saver using the arrow keys
	and then press <keycap>Enter</keycap>. The System Console
	Configuration menu will redisplay.</para>

	<para>The default time interval is 300 seconds. To change the time
	interval, select <guimenuitem>Saver</guimenuitem> again. At the
	Screen Saver Options menu, select <guimenuitem>Timeout</guimenuitem>
	using the arrow keys and press <keycap>Enter</keycap>. A pop-up
	menu will appear:</para>

	<figure id="saver-timeout">
	<title>Screen Saver Timeout</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/console-saver3" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The value can be changed, then select &gui.ok;
	and press <keycap>Enter</keycap> to return to the System Console
	Configuration menu.</para>

	<figure id="saver-exit">
	<title>System Console Configuration Exit</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/console-saver4" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Selecting <guimenuitem>Exit</guimenuitem> and pressing
	<keycap>Enter</keycap> will continue with the post-installation
	configurations.</para>
	</sect2>

	<sect2 id="timezone">
	<title>Setting the Time Zone</title>

	<para>Setting the time zone for your machine will allow it to
	automatically correct for any regional time changes and perform
	other time zone related functions properly.</para>

	<para>The example shown is for a machine located in the Eastern
	time zone of the United States. Your selections will vary according
	to your geographical location.</para>

	<screen> User Confirmation Requested
	Would you like to set this machine's time zone now?

	[ Yes ] No</screen>

	<para>Select &gui.yes; and press
	<keycap>Enter</keycap> to set the time zone.</para>

	<screen> User Confirmation Requested
	Is this machine's CMOS clock set to UTC? If it is set to local time
	or you don't know, please choose NO here!

	Yes [ No ]</screen>

	<para>Select &gui.yes;
	or &gui.no; according to how the machine's
	clock is configured and press <keycap>Enter</keycap>.</para>

	<figure id="set-timezone-region">
	<title>Select Your Region</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/timezone1" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The appropriate region is selected using the arrow keys
	and then pressing <keycap>Enter</keycap>.</para>

	<figure id="set-timezone-country">
	<title>Select Your Country</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/timezone2" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Select the appropriate country using the arrow keys
	and press <keycap>Enter</keycap>.</para>

	<figure id="set-timezone-locality">
	<title>Select Your Time Zone</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/timezone3" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The appropriate time zone is selected using the arrow
	keys and pressing <keycap>Enter</keycap>.</para>

	<screen> Confirmation
	Does the abbreviation 'EDT' look reasonable?

	[ Yes ] No</screen>

	<para>Confirm the abbreviation for the time zone is correct.
	If it looks okay, press <keycap>Enter</keycap> to continue with
	the post-installation configuration.</para>
	</sect2>

	- <sect2 id="linuxcomp">
	- <title>Linux Compatibility</title>
	-
	- <note>
	- <para>This part only applies to &os; 7.<replaceable>X</replaceable>
	- installation, if you install &os; 8.<replaceable>X</replaceable>
	- this screen will not be proposed.</para>
	- </note>
	-
	- <screen> User Confirmation Requested
	- Would you like to enable Linux binary compatibility?
	-
	- [ Yes ] No</screen>
	-
	- <para>Selecting &gui.yes; and pressing
	- <keycap>Enter</keycap> will allow
	- running Linux software on FreeBSD. The install will add
	- the appropriate packages for Linux compatibility.</para>
	-
	- <para>If installing by FTP, the machine will need to be connected to
	- the Internet. Sometimes a remote ftp site will not have all the
	- distributions like the Linux binary compatibility. This can
	- be installed later if necessary.</para>
	- </sect2>
	-
	<sect2 id="mouse">
	<title>Mouse Settings</title>

	<para>This option will allow you to cut and paste text in the
	console and user programs with a 3-button mouse. If using a 2-button
	mouse, refer to manual page, &man.moused.8;, after installation for
	details on emulating the 3-button style. This example depicts a
	non-USB mouse configuration (such as a PS/2 or COM port mouse):</para>

	<screen> User Confirmation Requested
	Does this system have a PS/2, serial, or bus mouse?

	[ Yes ] No </screen>

	<para>Select &gui.yes; for a PS/2, serial or bus mouse, or
	&gui.no; for a USB mouse and press
	<keycap>Enter</keycap>.</para>

	<figure id="mouse-protocol">
	<title>Select Mouse Protocol Type</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/mouse1" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Use the arrow keys to select <guimenuitem>Type</guimenuitem> and
	press <keycap>Enter</keycap>.</para>

	<figure id="set-mouse-protocol">
	<title>Set Mouse Protocol</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/mouse2" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The mouse used in this example is a PS/2 type, so the default
	<guimenuitem>Auto</guimenuitem> was appropriate. To change protocol,
	use the arrow keys to select another option. Ensure that &gui.ok; is
	highlighted and press <keycap>Enter</keycap> to exit this menu.</para>

	<figure id="config-mouse-port">
	<title>Configure Mouse Port</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/mouse3" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Use the arrow keys to select <guimenuitem>Port</guimenuitem> and
	press <keycap>Enter</keycap>.</para>

	<figure id="set-mouse-port">
	<title>Setting the Mouse Port</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/mouse4" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>This system had a PS/2 mouse, so the default
	<guimenuitem>PS/2</guimenuitem> was appropriate. To change the port,
	use the arrow keys and then press <keycap>Enter</keycap>.</para>

	<figure id="test-daemon">
	<title>Enable the Mouse Daemon</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/mouse5" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Last, use the arrow keys to select
	<guimenuitem>Enable</guimenuitem>, and press
	<keycap>Enter</keycap> to enable and test the mouse
	daemon.</para>


	<figure id="test-mouse-daemon">
	<title>Test the Mouse Daemon</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/mouse6" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Move the mouse around the screen and verify the cursor
	shown responds properly. If it does, select
	&gui.yes; and press <keycap>Enter</keycap>. If
	not, the mouse has not been configured correctly — select
	&gui.no; and try using different configuration
	options.</para>

	<para>Select <guimenuitem>Exit</guimenuitem> with the arrow keys
	and press <keycap>Enter</keycap> to return to continue with the
	post-installation configuration.</para>
	</sect2>

	<sect2 id="packages">
	<title>Install Packages</title>

	<para>Packages are pre-compiled binaries and are a convenient
	way to install software.</para>

	<para>Installation of one package is shown for purposes of
	illustration. Additional packages can also be added at this
	time if desired. After installation
	<command>sysinstall</command> can be used to add additional
	packages.</para>

	<screen> User Confirmation Requested
	The FreeBSD package collection is a collection of hundreds of
	ready-to-run applications, from text editors to games to WEB servers
	and more. Would you like to browse the collection now?

	[ Yes ] No</screen>

	<para>Selecting &gui.yes; and pressing
	<keycap>Enter</keycap> will be
	followed by the Package Selection screens:</para>

	<figure id="package-category">
	<title>Select Package Category</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/pkg-cat" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Only packages on the current installation media are
	available for installation at any given time.</para>

	<para>All packages available will be displayed if
	<guimenuitem>All</guimenuitem> is selected or you can select a
	particular category. Highlight your selection with the arrow
	keys and press <keycap>Enter</keycap>.</para>

	<para>A menu will display showing all the packages available for
	the selection made:</para>

	<figure id="package-select">
	<title>Select Packages</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/pkg-sel" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The <application>bash</application> shell is shown selected.
	Select as many as desired by highlighting the package and pressing the
	<keycap>Space</keycap> key. A short description of each package will
	appear in the lower left corner of the screen.</para>

	<para>Pressing the <keycap>Tab</keycap> key will toggle between the last
	selected package, &gui.ok;, and &gui.cancel;.</para>

	<para>When you have finished marking the packages for installation,
	press <keycap>Tab</keycap> once to toggle to the &gui.ok; and press
	<keycap>Enter</keycap> to return to the Package Selection menu.</para>

	<para>The left and right arrow keys will also toggle between &gui.ok;
	and &gui.cancel;. This method can also be used to select &gui.ok; and
	press <keycap>Enter</keycap> to return to the Package Selection
	menu.</para>

	<figure id="package-install">
	<title>Install Packages</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/pkg-install" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Use the <keycap>Tab</keycap> and arrow keys to select <guibutton>[ Install ]</guibutton>
	and press <keycap>Enter</keycap>. You will then need to confirm
	that you want to install the packages:</para>

	<figure id="package-install-confirm">
	<title>Confirm Package Installation</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/pkg-confirm" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Selecting &gui.ok; and pressing <keycap>Enter</keycap> will start
	the package installation. Installing messages will appear until
	completed. Make note if there are any error messages.</para>

	<para>The final configuration continues after packages are
	installed. If you end up not selecting any packages, and wish
	to return to the final configuration, select
	<guibutton>Install</guibutton> anyways.</para>
	</sect2>

	<sect2 id="addusers">
	<title>Add Users/Groups</title>

	<para>You should add at least one user during the installation so
	that you can use the system without being logged in as
	<username>root</username>. The root partition is generally small
	and running applications as <username>root</username> can quickly
	fill it. A bigger danger is noted below:</para>

	<screen> User Confirmation Requested
	Would you like to add any initial user accounts to the system? Adding
	at least one account for yourself at this stage is suggested since
	working as the "root" user is dangerous (it is easy to do things which
	adversely affect the entire system).

	[ Yes ] No</screen>

	<para>Select &gui.yes; and press
	<keycap>Enter</keycap> to continue with adding a user.</para>

	<figure id="add-user2">
	<title>Select User</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/adduser1" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Select <guimenuitem>User</guimenuitem> with the arrow keys
	and press <keycap>Enter</keycap>.</para>

	<figure id="add-user3">
	<title>Add User Information</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/adduser2" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The following descriptions will appear in the lower part of
	the screen as the items are selected with <keycap>Tab</keycap>
	to assist with entering the required information:</para>

	<variablelist>
	<varlistentry>
	<term>Login ID</term>

	<listitem>
	<para>The login name of the new user (mandatory).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>UID</term>

	<listitem>
	<para>The numerical ID for this user (leave blank for
	automatic choice).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Group</term>

	<listitem>
	<para>The login group name for this user (leave blank for
	automatic choice).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Password</term>

	<listitem>
	<para>The password for this user (enter this field with
	care!).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Full name</term>

	<listitem>
	<para>The user's full name (comment).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Member groups</term>

	<listitem>
	<para>The groups this user belongs to (i.e., gets access
	rights for).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Home directory</term>

	<listitem>
	<para>The user's home directory (leave blank for
	default).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Login shell</term>
	<listitem>
	<para>The user's login shell (leave blank for
	default, e.g., <filename>/bin/sh</filename>).</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>The login shell was changed from <filename>/bin/sh</filename> to
	<filename>/usr/local/bin/bash</filename> to use the
	<application>bash</application> shell that was previously installed as
	a package. Do not try to use a shell that does not exist or you will
	not be able to login. The most common shell used in the
	BSD-world is the C shell, which can be indicated as
	<filename>/bin/tcsh</filename>.</para>

	<para>The user was also added to the <groupname>wheel</groupname> group
	to be able to become a superuser with <username>root</username>
	privileges.</para>

	<para>When you are satisfied, press &gui.ok; and
	the User and Group Management menu will redisplay:</para>

	<figure id="add-user4">
	<title>Exit User and Group Management</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/adduser3" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Groups can also be added at this time if specific needs
	are known. Otherwise, this may be accessed through using
	<command>sysinstall</command>
	after installation is
	completed.</para>

	<para>When you are finished adding users, select
	<guimenuitem>Exit</guimenuitem> with the arrow keys and press
	<keycap>Enter</keycap> to continue the installation.</para>
	</sect2>

	<sect2 id="rootpass">
	<title>Set the <username>root</username> Password</title>

	<screen> Message
	Now you must set the system manager's password.
	This is the password you'll use to log in as "root".

	[ OK ]

	[ Press enter or space ]</screen>

	<para>Press <keycap>Enter</keycap> to set the <username>root</username>
	password.</para>

	<para>The password will need to be typed in twice correctly. Needless to
	say, make sure you have a way of finding the password if you
	forget. Notice that the password you type in is not echoed, nor
	are asterisks displayed.</para>

	<screen>New password:
	Retype new password :</screen>

	<para>The installation will continue after the password is
	successfully entered.</para>
	</sect2>

	<sect2 id="exit-inst">
	<title>Exiting Install</title>

	<para>If you need to configure
	<link linkend="network-services">additional network services</link>
	or any other configuration, you can do it at this point or
	after installation with <command>sysinstall</command>.</para>

	<screen> User Confirmation Requested
	Visit the general configuration menu for a chance to set any last
	options?

	Yes [ No ]</screen>

	<para>Select &gui.no; with the arrow keys
	and press <keycap>Enter</keycap> to return to the Main
	Installation Menu.</para>

	<figure id="final-main">
	<title>Exit Install</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/mainexit" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Select <guibutton>[X Exit Install]</guibutton> with the arrow
	keys and press <keycap>Enter</keycap>. You will be asked to
	confirm exiting the installation:</para>

	<screen> User Confirmation Requested
	Are you sure you wish to exit? The system will reboot.

	[ Yes ] No</screen>

	<para>Select &gui.yes;. If you are booting from the CDROM drive
	the following message will remind you to remove the
	disk:</para>

	<screen> Message
	Be sure to remove the media from the drive.

	[ OK ]
	[ Press enter or space ]</screen>

	<para>The CDROM drive is locked until the machine
	starts to reboot then the disk can
	be removed from drive (quickly). Press &gui.ok; to reboot.</para>

	<para>The system will reboot so watch for any error messages that
	may appear, see <xref linkend="freebsdboot"/> for more
	details.</para>
	</sect2>

	<sect2 id="network-services">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>
	<title>Configure Additional Network Services</title>

	<para>Configuring network services can be a daunting
	task for new users if they lack previous
	knowledge in this area. Networking, including the Internet,
	is critical to all modern operating systems including &os;;
	as a result, it is very useful to have some understanding
	&os;'s extensive networking capabilities. Doing this
	during the installation will ensure users have some
	understanding of the various services available to them.</para>

	<para>Network services are programs that accept input from
	anywhere on the network. Every effort is made to make sure
	these programs will not do anything <quote>harmful</quote>.
	Unfortunately, programmers are not perfect and through time
	there have been cases where bugs in network services have been
	exploited by attackers to do bad things. It is important that
	you only enable the network services you know that you need. If
	in doubt it is best if you do not enable a network service until
	you find out that you do need it. You can always enable it
	later by re-running <application>sysinstall</application> or by
	using the features provided by the
	<filename>/etc/rc.conf</filename> file.</para>

	<para>Selecting the <guimenu>Networking</guimenu> option will display
	a menu similar to the one below:</para>

	<figure id="network-configuration">
	<title>Network Configuration Upper-level</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/net-config-menu1" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The first option, <guimenuitem>Interfaces</guimenuitem>, was
	previously covered during the <xref linkend="inst-network-dev"/>,
	thus this option can safely be ignored.</para>

	<para>Selecting the <guimenuitem>AMD</guimenuitem> option adds
	support for the <acronym>BSD</acronym> automatic mount utility.
	This is usually used in conjunction with the
	<acronym>NFS</acronym> protocol (see below)
	for automatically mounting remote file systems.
	No special configuration is required here.</para>

	<para>Next in line is the <guimenuitem>AMD Flags</guimenuitem>
	option. When selected, a menu will pop up for you
	to enter specific <acronym>AMD</acronym> flags.
	The menu already contains a set of default options:</para>

	<screen>-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map</screen>

	<para>The <option>-a</option> option sets the default mount
	location which is specified here as
	<filename>/.amd_mnt</filename>. The <option>-l</option>
	option specifies the default <filename>log</filename> file;
	however, when <literal>syslogd</literal> is used all log
	activity will be sent to the system log daemon. The
	<filename class="directory">/host</filename> directory is used
	to mount an exported file system from a remote
	host, while <filename class="directory">/net</filename>
	directory is used to mount an exported file system from an
	<acronym>IP</acronym> address. The
	<filename>/etc/amd.map</filename> file defines the default
	options for <acronym>AMD</acronym> exports.</para>

	<indexterm>
	<primary>FTP</primary>
	<secondary>anonymous</secondary>
	</indexterm>

	<para>The <guimenuitem>Anon FTP</guimenuitem> option permits anonymous
	<acronym>FTP</acronym> connections. Select this option to
	make this machine an anonymous <acronym>FTP</acronym> server.
	Be aware of the security risks involved with this option.
	Another menu will be displayed to explain the security risks
	and configuration in depth.</para>

	<para>The <guimenuitem>Gateway</guimenuitem> configuration menu will set
	the machine up to be a gateway as explained previously. This
	can be used to unset the <guimenuitem>Gateway</guimenuitem> option if
	you accidentally selected it during the installation process.</para>

	<para>The <guimenuitem>Inetd</guimenuitem> option can be used to configure
	or completely disable the &man.inetd.8; daemon as discussed
	above.</para>

	<para>The <guimenuitem>Mail</guimenuitem> option is used to configure the
	system's default <acronym>MTA</acronym> or Mail Transfer Agent.
	Selecting this option will bring up the following menu:</para>

	<figure id="mta-selection">
	<title>Select a default MTA</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/mta-main" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>Here you are offered a choice as to which
	<acronym>MTA</acronym> to install
	and set as the default. An <acronym>MTA</acronym> is nothing
	more than a mail server which delivers email to users on the
	system or the Internet.</para>

	<para>Selecting <guimenuitem>Sendmail</guimenuitem> will install
	the popular <application>sendmail</application> server which
	is the &os; default. The <guimenuitem>Sendmail local</guimenuitem>
	option will set <application>sendmail</application> to be the default
	<acronym>MTA</acronym>, but disable its ability to receive
	incoming email from the Internet. The other options here,
	<guimenuitem>Postfix</guimenuitem> and
	<guimenuitem>Exim</guimenuitem> act similar to
	<guimenuitem>Sendmail</guimenuitem>. They both deliver
	email; however, some users prefer these alternatives to the
	<application>sendmail</application>
	<acronym>MTA</acronym>.</para>

	<para>After selecting an <acronym>MTA</acronym>, or choosing
	not to select an MTA, the network configuration menu will appear
	with the next option being <guimenuitem>NFS client</guimenuitem>.</para>

	<para>The <guimenuitem>NFS client</guimenuitem> option will
	configure the system to communicate with a server via
	<acronym>NFS</acronym>. An <acronym>NFS</acronym> server
	makes file systems available to other machines on the
	network via the <acronym>NFS</acronym> protocol. If this is
	a stand-alone machine, this option can remain unselected.
	The system may require more configuration later; see
	<xref linkend="network-nfs"/> for more
	information about client and server configuration.</para>

	<para>Below that option is the <guimenuitem>NFS server</guimenuitem>
	option, permitting you to set the system up as an
	<acronym>NFS</acronym> server. This adds the required
	information to start up the <acronym>RPC</acronym> remote
	procedure call services. <acronym>RPC</acronym> is used to
	coordinate connections between hosts and programs.</para>

	<para>Next in line is the <guimenuitem>Ntpdate</guimenuitem> option,
	which deals with time synchronization. When selected, a menu
	like the one below shows up:</para>

	<figure id="Ntpdate-config">
	<title>Ntpdate Configuration</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/ntp-config" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>From this menu, select the server which is the closest
	to your location. Selecting a close one will make the time
	synchronization more accurate as a server further from your
	location may have more connection latency.</para>

	<para>The next option is the <acronym>PCNFSD</acronym> selection.
	This option will install the
	<filename role="package">net/pcnfsd</filename> package from
	the Ports Collection. This is a useful utility which provides
	<acronym>NFS</acronym> authentication services for systems which
	are unable to provide their own, such as Microsoft's
	&ms-dos; operating system.</para>

	<para>Now you must scroll down a bit to see the other
	options:</para>

	<figure id="Network-configuration-cont">
	<title>Network Configuration Lower-level</title>

	<mediaobject>
	<imageobject>
	<imagedata fileref="install/net-config-menu2" format="PNG"/>
	</imageobject>
	</mediaobject>
	</figure>

	<para>The &man.rpcbind.8;, &man.rpc.statd.8;, and
	&man.rpc.lockd.8; utilities are all used for Remote Procedure
	Calls (<acronym>RPC</acronym>).
	The <command>rpcbind</command> utility manages communication
	between <acronym>NFS</acronym> servers and clients, and is
	required for <acronym>NFS</acronym> servers to operate
	correctly. The <application>rpc.statd</application> daemon interacts
	with the <application>rpc.statd</application> daemon on other hosts to
	provide status monitoring. The reported status is usually held
	in the <filename>/var/db/statd.status</filename> file. The
	next option listed here is the <guimenuitem>rpc.lockd</guimenuitem>
	option, which, when selected, will provide file locking
	services. This is usually used with
	<application>rpc.statd</application> to monitor what hosts are
	requesting locks and how frequently they request them.
	While these last two options are marvelous for debugging, they
	are not required for <acronym>NFS</acronym> servers and clients
	to operate correctly.</para>

	<para>As you progress down the list the next item here is
	<guimenuitem>Routed</guimenuitem>, which is the routing daemon. The
	&man.routed.8; utility manages network routing tables,
	discovers multicast routers, and supplies a copy of the routing
	tables to any physically connected host on the network upon
	request. This is mainly used for machines which act as a
	gateway for the local network. When selected, a menu will be
	presented requesting the default location of the utility.
	The default location is already defined for you and can be
	selected with the <keycap>Enter</keycap> key. You will then
	be presented with yet another menu, this time asking for the
	flags you wish to pass on to <application>routed</application>. The
	default is <option>-q</option> and it should already appear
	on the screen.</para>

	<para>Next in line is the <guimenuitem>Rwhod</guimenuitem> option which,
	when selected, will start the &man.rwhod.8; daemon
	during system initialization. The <command>rwhod</command>
	utility broadcasts system messages across the network
	periodically, or collects them when in <quote>consumer</quote>
	mode. More information can be found in the &man.ruptime.1; and
	&man.rwho.1; manual pages.</para>

	<para>The next to the last option in the list is for the
	&man.sshd.8; daemon. This is the secure shell server for
	<application>OpenSSH</application> and it is highly recommended
	over the standard <application>telnet</application> and
	<acronym>FTP</acronym> servers. The <application>sshd</application>
	server is used to create a secure connection from one host to
	another by using encrypted connections.</para>

	<para>Finally there is the <guimenuitem>TCP Extensions</guimenuitem>
	option. This enables the <acronym>TCP</acronym> Extensions
	defined in <acronym>RFC</acronym> 1323 and
	<acronym>RFC</acronym> 1644. While on many hosts this can
	speed up connections, it can also cause some connections to be
	dropped. It is not recommended for servers, but may be
	beneficial for stand alone machines.</para>

	<para>Now that you have configured the network services, you can
	scroll up to the very top item which is
	<guimenuitem>X Exit</guimenuitem>
	and continue on to the next configuration item or simply exit
	<application>sysinstall</application> in selecting
	<guimenuitem>X Exit</guimenuitem> twice then <guibutton>[X
	Exit Install]</guibutton>.</para>

	</sect2>

	<sect2 id="freebsdboot">
	<title>&os; Bootup</title>

	<sect3 id="freebsdboot-i386">
	<title>&os;/&arch.i386; Bootup</title>

	<para>If everything went well, you will see messages scroll
	off the screen and you will arrive at a login prompt. You can view
	the content of the messages by pressing <keycap>Scroll-Lock</keycap>
	and using <keycap>PgUp</keycap> and <keycap>PgDn</keycap>.
	Pressing <keycap>Scroll-Lock</keycap> again will return
	to the prompt.</para>

	<para>The entire message may not display (buffer limitation) but
	it can be viewed from the command line after logging in by typing
	<command>dmesg</command> at the prompt.</para>

	<para>Login using the username/password you set during installation
	(<username>rpratt</username>, in this example). Avoid logging in as
	<username>root</username> except when necessary.</para>

	<para>Typical boot messages (version information omitted):</para>

	<screen>Copyright (c) 1992-2002 The FreeBSD Project.
	Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994
	The Regents of the University of California. All rights reserved.

	Timecounter "i8254" frequency 1193182 Hz
	CPU: AMD-K6(tm) 3D processor (300.68-MHz 586-class CPU)
	Origin = "AuthenticAMD" Id = 0x580 Stepping = 0
	Features=0x8001bf<FPU,VME,DE,PSE,TSC,MSR,MCE,CX8,MMX>
	AMD Features=0x80000800<SYSCALL,3DNow!>
	real memory = 268435456 (262144K bytes)
	config> di sn0
	config> di lnc0
	config> di le0
	config> di ie0
	config> di fe0
	config> di cs0
	config> di bt0
	config> di aic0
	config> di aha0
	config> di adv0
	config> q
	avail memory = 256311296 (250304K bytes)
	Preloaded elf kernel "kernel" at 0xc0491000.
	Preloaded userconfig_script "/boot/kernel.conf" at 0xc049109c.
	md0: Malloc disk
	Using $PIR table, 4 entries at 0xc00fde60
	npx0: <math processor> on motherboard
	npx0: INT 16 interface
	pcib0: <Host to PCI bridge> on motherboard
	pci0: <PCI bus> on pcib0
	pcib1: <VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge> at device 1.0 on pci0
	pci1: <PCI bus> on pcib1
	pci1: <Matrox MGA G200 AGP graphics accelerator> at 0.0 irq 11
	isab0: <VIA 82C586 PCI-ISA bridge> at device 7.0 on pci0
	isa0: <ISA bus> on isab0
	atapci0: <VIA 82C586 ATA33 controller> port 0xe000-0xe00f at device 7.1 on pci0
	ata0: at 0x1f0 irq 14 on atapci0
	ata1: at 0x170 irq 15 on atapci0
	uhci0: <VIA 83C572 USB controller> port 0xe400-0xe41f irq 10 at device 7.2 on pci0
	usb0: <VIA 83C572 USB controller> on uhci0
	usb0: USB revision 1.0
	uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr 1
	uhub0: 2 ports with 2 removable, self powered
	chip1: <VIA 82C586B ACPI interface> at device 7.3 on pci0
	ed0: <NE2000 PCI Ethernet (RealTek 8029)> port 0xe800-0xe81f irq 9 at
	device 10.0 on pci0
	ed0: address 52:54:05:de:73:1b, type NE2000 (16 bit)
	isa0: too many dependant configs (8)
	isa0: unexpected small tag 14
	fdc0: <NEC 72065B or clone> at port 0x3f0-0x3f5,0x3f7 irq 6 drq 2 on isa0
	fdc0: FIFO enabled, 8 bytes threshold
	fd0: <1440-KB 3.5" drive> on fdc0 drive 0
	atkbdc0: <keyboard controller (i8042)> at port 0x60-0x64 on isa0
	atkbd0: <AT Keyboard> flags 0x1 irq 1 on atkbdc0
	kbd0 at atkbd0
	psm0: <PS/2 Mouse> irq 12 on atkbdc0
	psm0: model Generic PS/2 mouse, device ID 0
	vga0: <Generic ISA VGA> at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0
	sc0: <System console> at flags 0x1 on isa0
	sc0: VGA <16 virtual consoles, flags=0x300>
	sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0
	sio0: type 16550A
	sio1 at port 0x2f8-0x2ff irq 3 on isa0
	sio1: type 16550A
	ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0
	ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode
	ppc0: FIFO with 16/16/15 bytes threshold
	ppbus0: IEEE1284 device found /NIBBLE
	Probing for PnP devices on ppbus0:
	plip0: <PLIP network interface> on ppbus0
	lpt0: <Printer> on ppbus0
	lpt0: Interrupt-driven port
	ppi0: <Parallel I/O> on ppbus0
	ad0: 8063MB <IBM-DHEA-38451> [16383/16/63] at ata0-master using UDMA33
	ad2: 8063MB <IBM-DHEA-38451> [16383/16/63] at ata1-master using UDMA33
	acd0: CDROM <DELTA OTC-H101/ST3 F/W by OIPD> at ata0-slave using PIO4
	Mounting root from ufs:/dev/ad0s1a
	swapon: adding /dev/ad0s1b as swap device
	Automatic boot in progress...
	/dev/ad0s1a: FILESYSTEM CLEAN; SKIPPING CHECKS
	/dev/ad0s1a: clean, 48752 free (552 frags, 6025 blocks, 0.9% fragmentation)
	/dev/ad0s1f: FILESYSTEM CLEAN; SKIPPING CHECKS
	/dev/ad0s1f: clean, 128997 free (21 frags, 16122 blocks, 0.0% fragmentation)
	/dev/ad0s1g: FILESYSTEM CLEAN; SKIPPING CHECKS
	/dev/ad0s1g: clean, 3036299 free (43175 frags, 374073 blocks, 1.3% fragmentation)
	/dev/ad0s1e: filesystem CLEAN; SKIPPING CHECKS
	/dev/ad0s1e: clean, 128193 free (17 frags, 16022 blocks, 0.0% fragmentation)
	Doing initial network setup: hostname.
	ed0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
	inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
	inet6 fe80::5054::5ff::fede:731b%ed0 prefixlen 64 tentative scopeid 0x1
	ether 52:54:05:de:73:1b
	lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384
	inet6 fe80::1%lo0 prefixlen 64 scopeid 0x8
	inet6 ::1 prefixlen 128
	inet 127.0.0.1 netmask 0xff000000
	Additional routing options: IP gateway=YES TCP keepalive=YES
	routing daemons:.
	additional daemons: syslogd.
	Doing additional network setup:.
	Starting final network daemons: creating ssh RSA host key
	Generating public/private rsa1 key pair.
	Your identification has been saved in /etc/ssh/ssh_host_key.
	Your public key has been saved in /etc/ssh/ssh_host_key.pub.
	The key fingerprint is:
	cd:76:89:16:69:0e:d0:6e:f8:66:d0:07:26:3c:7e:2d root@k6-2.example.com
	creating ssh DSA host key
	Generating public/private dsa key pair.
	Your identification has been saved in /etc/ssh/ssh_host_dsa_key.
	Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub.
	The key fingerprint is:
	f9:a1:a9:47:c4:ad:f9:8d:52:b8:b8:ff:8c:ad:2d:e6 root@k6-2.example.com.
	setting ELF ldconfig path: /usr/lib /usr/lib/compat /usr/X11R6/lib
	/usr/local/lib
	a.out ldconfig path: /usr/lib/aout /usr/lib/compat/aout /usr/X11R6/lib/aout
	starting standard daemons: inetd cron sshd usbd sendmail.
	Initial rc.i386 initialization:.
	rc.i386 configuring syscons: blank_time screensaver moused.
	Additional ABI support: linux.
	Local package initialization:.
	Additional TCP options:.

	FreeBSD/i386 (k6-2.example.com) (ttyv0)

	login: rpratt
	Password:</screen>

	<para>Generating the RSA and DSA keys may take some time on slower
	machines. This happens only on the initial boot-up of a new
	installation. Subsequent boots will be faster.</para>

	<para>If the X server has been configured and a Default Desktop
	chosen, it can be started by typing <command>startx</command> at
	the command line.</para>

	</sect3>
	</sect2>

	<sect2 id="shutdown">
	- <title>FreeBSD Shutdown</title>
	+ <title>&os; Shutdown</title>

	<para>It is important to properly shutdown the operating
	system. Do not just turn off power. First, become a superuser by
	typing <command>su</command> at the command line and entering the
	<username>root</username> password. This will work only if the user
	is a member of the <groupname>wheel</groupname> group.
	Otherwise, login as <username>root</username> and use
	<command>shutdown -h now</command>.</para>

	<screen>The operating system has halted.
	Please press any key to reboot.</screen>

	<para>It is safe to turn off the power after the shutdown command
	has been issued and the message
	<quote>Please press any key to reboot</quote>
	appears. If any key is pressed instead of turning off the power
	switch, the system will reboot.</para>

	<para>You could also use the
	<keycombo action="simul">
	<keycap>Ctrl</keycap>
	<keycap>Alt</keycap>
	<keycap>Del</keycap>
	</keycombo>
	key combination to reboot the system, however this is not recommended
	during normal operation.</para>

	</sect2>
	</sect1>

	<sect1 id="install-trouble">
	<title>Troubleshooting</title>

	<indexterm>
	<primary>installation</primary>
	<secondary>troubleshooting</secondary>
	</indexterm>
	<para>The following section covers basic installation troubleshooting,
	such as common problems people have reported. There are also a few
	- questions and answers for people wishing to dual-boot FreeBSD with
	+ questions and answers for people wishing to dual-boot &os; with
	&ms-dos; or &windows;.</para>

	<sect2>
	<title>What to Do If Something Goes Wrong</title>

	<para>Due to various limitations of the PC architecture, it is
	impossible for probing to be 100% reliable, however, there are a
	few things you can do if it fails.</para>

	<para>Check the <ulink
	url="http://www.FreeBSD.org/releases/index.html">Hardware Notes
	</ulink> document for your version of &os; to make sure your
	hardware is supported.</para>

	<para>If your hardware is supported and you still experience
	lock-ups or other problems, you will need to build a <link
	linkend="kernelconfig">custom kernel</link>. This will
	allow you to add in support for devices which are not present in the
	<filename>GENERIC</filename> kernel. The kernel on the boot disks
	is configured assuming that most hardware devices are in their
	factory default configuration in terms of IRQs, IO addresses, and
	DMA channels. If your hardware has been reconfigured, you will most
	likely need to edit the kernel configuration and recompile to tell
	&os; where to find things.</para>

	<para>It is also possible that a probe for a device not present will
	cause a later probe for another device that is present to fail. In
	that case, the probes for the conflicting driver(s) should be
	disabled.</para>

	<note>
	<para>Some installation problems can be avoided or alleviated
	by updating the firmware on various hardware components, most notably
	the motherboard. The motherboard firmware may also be referred to
	as <acronym>BIOS</acronym> and most of the motherboard or computer
	manufactures have a website where the upgrades and upgrade
	information may be located.</para>

	<para>Most manufacturers strongly advise against upgrading the
	motherboard <acronym>BIOS</acronym> unless there is a good reason
	for doing so, which
	could possibly be a critical update of sorts. The upgrade process
	<emphasis>can</emphasis> go wrong, causing permanent damage to the
	<acronym>BIOS</acronym> chip.</para>
	</note>
	</sect2>

	<sect2>
	<title>Using &ms-dos; and &windows; File Systems</title>

	<para>At this time, &os; does not support file systems compressed with
	the <application>Double Space™</application> application.
	Therefore the file system will need to be uncompressed before &os; can
	access the data. This
	can be done by running the <application>Compression Agent</application>
	located in the
	<guimenuitem>Start</guimenuitem>> <guimenuitem>Programs</guimenuitem> >
	<guimenuitem>System Tools</guimenuitem> menu.</para>

	<para>&os; can support &ms-dos; file systems (sometimes called
	FAT file systems). The &man.mount.msdosfs.8; command grafts such file
	systems onto the existing directory hierarchy, allowing the file
	system's contents to be accessed. The &man.mount.msdosfs.8; program
	is not usually
	invoked directly; instead, it is called by the system through a line
	in <filename>/etc/fstab</filename> or by a call to the &man.mount.8;
	utility with the appropriate parameters.</para>

	<para>A typical line in <filename>/etc/fstab</filename> is:</para>

	<programlisting>/dev/ad0sN /dos msdosfs rw 0 0</programlisting>

	<note><para>The <filename>/dos</filename> directory must already
	exist for this to work. For details about the format of
	<filename>/etc/fstab</filename>, see &man.fstab.5;.</para></note>

	<para>A typical call to &man.mount.8; for a &ms-dos; file system
	looks like:</para>

	<screen>&prompt.root; <userinput>mount -t msdosfs /dev/ad0s1 /mnt</userinput></screen>

	<para>In this example, the &ms-dos; file system is located on the first
	partition of the primary hard disk. Your situation may be different,
	check the output from the <command>dmesg</command>, and
	<command>mount</command> commands. They should produce enough
	information to give an idea of the partition layout.</para>

	<note><para>&os; may number disk slices (that is, &ms-dos; partitions)
	differently than other operating systems. In particular, extended
	&ms-dos; partitions are usually given higher slice numbers than
	primary &ms-dos; partitions. The &man.fdisk.8; utility can help
	determine which slices belong to &os; and which belong to other
	operating systems.</para></note>

	<para>NTFS partitions can also be mounted in a similar manner
	using the &man.mount.ntfs.8; command.</para>
	</sect2>

	<sect2>
	<title>Troubleshooting Questions and Answers</title>

	<qandaset>
	<qandaentry>
	<question>
	<para>My system hangs while probing hardware during boot,
	or it behaves strangely during install, or the floppy
	drive is not probed.</para>
	</question>
	<answer>
	<para>&os; makes extensive use of the system
	ACPI service on the i386, amd64 and ia64 platforms to
	aid in system configuration if it is detected during
	boot. Unfortunately, some bugs still exist in both the
	ACPI driver and within system motherboards and BIOS.
	The use of ACPI can be disabled by setting
	the <literal>hint.acpi.0.disabled</literal> hint in the
	third stage boot loader:</para>

	<screen><userinput>set hint.acpi.0.disabled="1"</userinput></screen>

	<para>This is reset each time the system is booted, so it
	is necessary to
	add <literal>hint.acpi.0.disabled="1"</literal> to the
	file
	<filename>/boot/loader.conf</filename>. More
	information about the boot loader can be found
	in <xref linkend="boot-synopsis"/>.</para>
	</answer>
	</qandaentry>
	<qandaentry>
	<question>
	<para>I go to boot from the hard disk for the first time
	after installing &os;, the kernel loads and probes my
	hardware, but stops with messages like:</para>

	<screen>changing root device to ad1s1a panic: cannot mount root</screen>

	<para>What is wrong? What can I do?</para>

	<para>What is this
	<literal>bios_drive:interface(unit,partition)kernel_name</literal>
	thing that is displayed with the boot help?</para>
	</question>
	<answer>
	<para>There is a longstanding problem in the case where
	the boot disk is not the first disk in the system. The
	BIOS uses a different numbering scheme to &os;, and
	working out which numbers correspond to which is
	difficult to get right.</para>

	<para>In the case where the boot disk is not the first
	disk in the system, &os; can need some help finding it.
	There are two common situations here, and in both of
	these cases, you need to tell &os; where the root
	filesystem is. You do this by specifying the BIOS disk
	number, the disk type and the &os; disk number for that
	type.</para>

	<para>The first situation is where you have two IDE disks,
	each configured as the master on their respective IDE
	busses, and wish to boot &os; from the second disk. The
	BIOS sees these as disk 0 and disk 1, while &os; sees
	them as <devicename>ad0</devicename> and
	<devicename>ad2</devicename>.</para>

	<para>&os; is on BIOS disk 1, of type
	<literal>ad</literal> and the &os; disk number is 2, so
	you would say:</para>

	<screen><userinput>1:ad(2,a)kernel</userinput></screen>

	<para>Note that if you have a slave on the primary bus,
	the above is not necessary (and is effectively
	wrong).</para>

	<para>The second situation involves booting from a SCSI
	disk when you have one or more IDE disks in the system.
	In this case, the &os; disk number is lower than the
	BIOS disk number. If you have two IDE disks as well as
	the SCSI disk, the SCSI disk is BIOS disk 2,
	type <literal>da</literal> and &os; disk number 0, so
	you would say:</para>

	<screen><userinput>2:da(0,a)kernel</userinput></screen>

	<para>To tell &os; that you want to boot from BIOS disk 2,
	which is the first SCSI disk in the system. If you only
	had one IDE disk, you would use <literal>1:</literal>
	instead.</para>

	<para>Once you have determined the correct values to use,
	you can put the command exactly as you would have typed
	it in the <filename>/boot.config</filename> file using a
	standard text editor. Unless instructed otherwise, &os;
	will use the contents of this file as the default
	response to the <literal>boot:</literal> prompt.</para>
	</answer>
	</qandaentry>
	<qandaentry>
	<question>
	<para>I go to boot from the hard disk for the first time
	after installing &os;, but the Boot Manager prompt just
	prints <literal>F?</literal> at the boot menu each time
	but the boot will not go any further.</para>
	</question>
	<answer>
	<para>The hard disk geometry was set incorrectly in the
	partition editor when you installed &os;. Go back into
	the partition editor and specify the actual geometry of
	your hard disk. You must reinstall &os; again from the
	beginning with the correct geometry.</para>

	<para>If you are failing entirely in figuring out the
	correct geometry for your machine, here is a tip: Install
	a small &ms-dos; partition at the beginning of the disk and
	install &os; after that. The install program will see
	the &ms-dos; partition and try to infer the correct geometry
	from it, which usually works.</para>

	<para>The following tip is no longer recommended, but is
	left here for reference:</para>

	<blockquote>
	<para>If you are setting up a truly dedicated &os;
	server or workstation where you do not care for
	(future) compatibility with &ms-dos;, Linux or another
	operating system, you also have got the option to use
	the entire disk (<guimenuitem>A</guimenuitem> in the partition
	editor), selecting the non-standard option where &os; occupies
	the entire disk from the very first to the very last
	sector. This will leave all geometry considerations
	aside, but is somewhat limiting unless you're never
	going to run anything other than &os; on a
	disk.</para>
	</blockquote>
	</answer>
	</qandaentry>
	<qandaentry>
	<question>
	<para>The system finds my &man.ed.4; network card, but I
	keep getting device timeout errors.</para>
	</question>
	<answer>
	<para>Your card is probably on a different IRQ from what
	is specified in
	the <filename>/boot/device.hints</filename> file. The
	&man.ed.4; driver does not use the <quote>soft</quote>
	configuration by default (values entered using EZSETUP in
	&ms-dos;),
	but it will use the software configuration if you
	specify <literal>-1</literal> in the hints for the
	interface.</para>

	<para>Either move the jumper on the card to a hard
	configuration setting (altering the kernel settings if
	necessary), or specify the IRQ as <literal>-1</literal>
	by setting the hint <literal>hint.ed.0.irq="-1"</literal>.
	This will tell the kernel to use the soft
	configuration.</para>

	<para>Another possibility is that your card is at IRQ 9,
	which is shared by IRQ 2 and frequently a cause of
	problems (especially when you have a VGA card using IRQ
	2!). You should not use IRQ 2 or 9 if at all
	possible.</para>
	</answer>
	</qandaentry>

	<qandaentry>

	<question>
	<indexterm>
	<primary>color</primary>
	<secondary>contrast</secondary>
	</indexterm>
	<para>When <application>sysinstall</application> is used
	in an X11 terminal, the yellow font is difficult to read
	against the light gray background. Is there a way to
	provide higher contrast for this application?</para>
	</question>
	<answer>
	<para>If you already have X11 installed and the default
	colors chosen by <application>sysinstall</application>
	make text illegible while using &man.xterm.1; or &man.rxvt.1;,
	add the following to your <filename>~/.Xdefaults</filename> to
	get a darker background gray: <literal>XTerm*color7:
	#c0c0c0</literal></para>
	</answer>
	</qandaentry>
	</qandaset>
	</sect2>
	</sect1>

	<sect1 id="install-advanced">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Valentino</firstname>
	<surname>Vaschetto</surname>
	<contrib>Contributed by </contrib>
	</author>
	<!-- May 2001 -->
	</authorgroup>

	<authorgroup>
	<author>
	<firstname>Marc</firstname>
	<surname>Fonvieille</surname>
	<contrib>Updated by </contrib>
	</author>
	</authorgroup>
	<!-- August 2010 -->
	</sect1info>

	<title>Advanced Installation Guide</title>

	- <para>This section describes how to install FreeBSD in exceptional
	+ <para>This section describes how to install &os; in exceptional
	cases.</para>

	<sect2 id="headless-install">
	- <title>Installing FreeBSD on a System without a Monitor or
	+ <title>Installing &os; on a System without a Monitor or
	Keyboard</title>

	<indexterm>
	<primary>installation</primary>
	<secondary>headless (serial console)</secondary>
	</indexterm>
	<indexterm><primary>serial console</primary></indexterm>
	<para>This type of installation is called a <quote>headless
	install</quote>, because the machine that you are trying to install
	- FreeBSD on either does not have a monitor attached to it, or does not
	+ &os; on either does not have a monitor attached to it, or does not
	even have a VGA output. How is this possible you ask? Using a
	serial console. A serial console is basically using another
	machine to act as the main display and keyboard for a
	system. To do this, just follow the steps to create
	an installation USB memstick, explained in <xref
	linkend="install-boot-media"/> or download the correct
	installation ISO image, see <xref
	linkend="install-cdrom"/>.</para>

	<para>To modify these media to boot into a serial console, follow
	these steps (If you want to use a CDROM you can skip the first
	step):</para>

	<procedure>
	<step>
	<title>Enabling the Installation USB Stick to Boot into a
	Serial Console</title>

	<indexterm>
	<primary><command>mount</command></primary>
	</indexterm>
	<para>If you were to boot into the USB stick that you just
	- made, FreeBSD would boot into its normal install mode. We
	- want FreeBSD to boot into a serial console for our
	+ made, &os; would boot into its normal install mode. We
	+ want &os; to boot into a serial console for our
	install. To do this, you have to mount the
	USB disk onto your &os;
	system using the &man.mount.8; command.</para>

	<screen>&prompt.root; <userinput>mount /dev/<replaceable>da0a</replaceable> <replaceable>/mnt</replaceable></userinput></screen>

	<note>
	<para>Adapt the device node and the mount point to your
	situation.</para>
	</note>

	<para>Now that you have the stick mounted, you must set
	the USB stick to boot into a serial console. You have
	to add to the <filename>loader.conf</filename> file of
	the USB stick file system a line setting the serial
	console as the system console:</para>

	<screen>&prompt.root; <userinput>echo 'console="comconsole"' >> <replaceable>/mnt</replaceable>/boot/loader.conf</userinput></screen>

	<para>Now that you have your USB stick configured correctly,
	you must unmount the disk using the &man.umount.8;
	command:</para>

	<screen>&prompt.root; <userinput>umount <replaceable>/mnt</replaceable></userinput></screen>

	<para>Now you can unplug the USB stick and jump directly
	to the third step of this procedure.</para>
	</step>

	<step>
	<title>Enabling the Installation CD to Boot into a
	Serial Console</title>

	<indexterm>
	<primary><command>mount</command></primary>
	</indexterm>
	<para>If you were to boot into the CD that you just
	made from the installation ISO image (see <xref
	linkend="install-cdrom"/>), &os; would boot into its
	normal install mode. We want &os; to boot into a serial
	console for our install. To do this, you have to
	extract, modify and regenerate the ISO image before
	burning it on a CD-R media.</para>

	<para>From the &os; system where is saved the installation
	ISO image, for example
	<filename>&os;-<replaceable>&rel.current;</replaceable>-RELEASE-<replaceable>i386</replaceable>-disc1.iso</filename>,
	use the &man.tar.1; utility to extract all the files:</para>

	<screen>&prompt.root; <userinput>mkdir <replaceable>/path/to/headless-iso</replaceable></userinput>
	&prompt.root; <userinput>tar -C <replaceable>/path/to/headless-iso</replaceable> -pxvf &os;-<replaceable>&rel.current;</replaceable>-RELEASE-<replaceable>i386</replaceable>-disc1.iso</userinput></screen>

	<para>Now you must set the installation media to boot into a
	serial console. You have to add to the
	<filename>loader.conf</filename> file from the extracted
	ISO image a line setting the serial console as the
	system console:</para>

	<screen>&prompt.root; <userinput>echo 'console="comconsole"' >> <replaceable>/path/to/headless-iso</replaceable>/boot/loader.conf</userinput></screen>

	<para>Then we can create a new ISO image from the modified
	tree. The &man.mkisofs.8; tool from the <filename
	role="package">sysutils/cdrtools</filename> port is
	used:</para>

	<screen>&prompt.root; <userinput>mkisofs -v -b boot/cdboot -no-emul-boot -r -J -V "<replaceable>Headless_install</replaceable>" \
	-o <replaceable>Headless-</replaceable>&os;-<replaceable>&rel.current;</replaceable>-RELEASE-<replaceable>i386</replaceable>-disc1.iso <replaceable>/path/to/headless-iso</replaceable></userinput></screen>

	<para>Now that you have your ISO image configured correctly,
	you can burn it on a CD-R with your favorite burning
	application.</para>
	</step>

	<step>
	<title>Connecting Your Null-modem Cable</title>

	<indexterm><primary>null-modem cable</primary></indexterm>
	<para>You now need to connect a
	<link linkend="term-cables-null">null-modem cable</link> between
	the two machines. Just connect the cable to the serial
	ports of the 2 machines. <emphasis>A normal serial cable
	will not work here</emphasis>, you need a null-modem
	cable because it has some of the wires inside crossed
	over.</para>
	</step>

	<step>
	<title>Booting Up for the Install</title>

	<para>It is now time to go ahead and start the install. Plug in
	the USB memstick on
	the machine you are doing the headless install
	on, and power on the machine. If you are using a
	prepared CDROM, power on the machine and insert the disk
	to boot on.</para>
	</step>

	<step>
	<title>Connecting to Your Headless Machine</title>

	<indexterm>
	<primary><command>cu</command></primary>
	</indexterm>

	<para>Now you have to connect to that machine with
	&man.cu.1;:</para>

	<screen>&prompt.root; <userinput>cu -l /dev/cuau0</userinput></screen>

	- <para>On &os; 7.<replaceable>X</replaceable> use the following command
	- instead:</para>
	-
	- <screen>&prompt.root; <userinput>cu -l /dev/cuad0</userinput></screen>
	-
	</step>
	</procedure>

	<para>That's it! You should now be able to control the headless machine
	through your <command>cu</command> session. It will load the kernel
	and then it will come up
	with a selection of what kind of terminal to use. Select the
	- FreeBSD color console and proceed with your install!</para>
	+ &os; color console and proceed with your install!</para>

	</sect2>
	</sect1>

	<sect1 id="install-diff-media">
	<title>Preparing Your Own Installation Media</title>

	<note>
	- <para>To prevent repetition, <quote>FreeBSD disc</quote> in this context
	- means a FreeBSD CDROM or DVD that you have purchased or produced
	+ <para>To prevent repetition, <quote>&os; disc</quote> in this context
	+ means a &os; CDROM or DVD that you have purchased or produced
	yourself.</para>
	</note>

	<para>There may be some situations in which you need to create your own
	- FreeBSD installation media and/or source. This might be physical media,
	+ &os; installation media and/or source. This might be physical media,
	such as a tape, or a source that <application>sysinstall</application>
	can use to retrieve the files, such as a local FTP site, or an &ms-dos;
	partition.</para>

	<para>For example:</para>

	<itemizedlist>
	<listitem>
	<para>You have many machines connected to your local network, and one
	- FreeBSD disc. You want to create a local FTP site using the
	- contents of the FreeBSD disc, and then have your machines use this
	+ &os; disc. You want to create a local FTP site using the
	+ contents of the &os; disc, and then have your machines use this
	local FTP site instead of needing to connect to the Internet.</para>
	</listitem>

	<listitem>
	- <para>You have a FreeBSD disc, and FreeBSD does not recognize your
	+ <para>You have a &os; disc, and &os; does not recognize your
	CD/DVD drive, but &ms-dos; / &windows; does. You want to copy the
	- FreeBSD installation files to a &ms-dos; partition on the same
	- computer, and then install FreeBSD using those files.</para>
	+ &os; installation files to a &ms-dos; partition on the same
	+ computer, and then install &os; using those files.</para>
	</listitem>

	<listitem>
	<para>The computer you want to install on does not have a CD/DVD
	drive or a network card, but you can connect a
	<quote>Laplink-style</quote> serial or parallel cable to a computer
	that does.</para>
	</listitem>

	<listitem>
	<para>You want to create a tape that can be used to install
	- FreeBSD.</para>
	+ &os;.</para>
	</listitem>
	</itemizedlist>

	<sect2 id="install-cdrom">
	<title>Creating an Installation CDROM</title>

	- <para>As part of each release, the FreeBSD project makes available at
	+ <para>As part of each release, the &os; project makes available at
	least two CDROM images (<quote>ISO images</quote>) per supported
	architecture. These images can be written
	(<quote>burned</quote>) to CDs if you have a CD writer, and then used
	- to install FreeBSD. If you have a CD writer, and bandwidth is cheap,
	- then this is the easiest way to install FreeBSD.</para>
	+ to install &os;. If you have a CD writer, and bandwidth is cheap,
	+ then this is the easiest way to install &os;.</para>

	<procedure>
	<step>
	<title>Download the Correct ISO Images</title>

	<para>The ISO images for each release can be downloaded from <filename>ftp://ftp.FreeBSD.org/pub/FreeBSD/ISO-IMAGES-<replaceable>arch</replaceable>/<replaceable>version</replaceable></filename> or the closest mirror.
	Substitute <replaceable>arch</replaceable> and
	<replaceable>version</replaceable> as appropriate.</para>

	<para>That directory will normally contain the following images:</para>

	<table frame="none">
	- <title>FreeBSD 7.<replaceable>X</replaceable> and 8.<replaceable>X</replaceable>
	+ <title>&os;
	ISO Image Names and Meanings</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Filename</entry>

	<entry>Contents</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-bootonly.iso</filename></entry>

	<entry>This CD image allows you to start the installation
	process by booting from a CD-ROM drive but it does not
	contain the support for installing &os; from the CD
	itself. You would need to perform a network based install
	(e.g. from an FTP server) after booting from this CD.</entry>
	</row>

	<row>
	<entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-dvd1.iso.gz</filename></entry>

	<entry>This DVD image contains everything necessary to
	- install the base FreeBSD operating system, a
	+ install the base &os; operating system, a
	collection of pre-built packages, and the
	documentation. It also supports booting into a
	<quote>livefs</quote> based rescue mode.</entry>
	</row>

	<row>
	<entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-memstick.img</filename></entry>

	<entry>This image can be written to an USB memory stick
	and used to do an install on machines capable of booting
	off USB drives. It also supports booting into a
	<quote>livefs</quote> based rescue mode. The
	documentation packages are provided but no other
	- packages. This image is not available for &os; 7.<replaceable>X</replaceable>.</entry>
	+ packages.</entry>
	</row>

	<row>
	<entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-disc1.iso</filename></entry>

	<entry>This CD image contains the base &os; operating
	system and the documentation packages but no other
	packages.</entry>
	</row>

	<row>
	<entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-disc2.iso</filename></entry>

	<entry>A CD image with as many third-party packages
	as would fit on the disc. This image is not
	- available for &os; 8.<replaceable>X</replaceable>.</entry>
	+ available for &os; 9.<replaceable>X</replaceable>.</entry>
	</row>

	<row>
	<entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-disc3.iso</filename></entry>

	<entry>Another CD image with as many third-party
	packages as would fit on the disc. This image is
	- not available for &os; 8.<replaceable>X</replaceable>.</entry>
	+ not available for &os; 9.<replaceable>X</replaceable>.</entry>
	</row>

	<row>
	- <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-docs.iso</filename></entry>
	-
	- <entry>The &os; documentation. This image is
	- not available for &os; 8.<replaceable>X</replaceable>.</entry>
	- </row>
	-
	- <row>
	<entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-livefs.iso</filename></entry>

	<entry>This CD image contains support for booting into
	a <quote>livefs</quote> based rescue mode but does not
	support doing an install from the CD itself.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	- <note>
	- <para>&os; 7.<replaceable>X</replaceable> releases before
	- &os; 7.3 and &os; 8.0 used a
	- different naming convention. The names of their ISO
	- images are not prefixed with
	- <literal>&os;-</literal>.</para>
	- </note>
	-
	<para>You <emphasis>must</emphasis> download one of either
	the <literal>bootonly</literal> ISO image,
	or the image of <literal>disc1</literal>. Do not download
	both of them, since the <literal>disc1</literal> image
	contains everything that the <literal>bootonly</literal>
	ISO image contains.</para>

	<para>Use the <literal>bootonly</literal> ISO if Internet
	access is cheap for you. It will let you install &os;, and
	you can then install third-party
	packages by downloading them using the ports/packages system (see
	<xref linkend="ports"/>) as
	necessary.</para>

	<para>Use the image of <literal>dvd1</literal> if you want to
	install a &os;
	release and want a reasonable selection of third-party packages
	on the disc as well.</para>

	<para>The additional disc images are useful, but not essential,
	especially if you have high-speed access to the Internet.</para>
	</step>

	<step>
	<title>Write the CDs</title>

	<para>You must then write the CD images to disc. If you will be
	- doing this on another FreeBSD system then see
	+ doing this on another &os; system then see
	<xref linkend="creating-cds"/> for more information (in
	particular, <xref linkend="burncd"/> and
	<xref linkend="cdrecord"/>).</para>

	<para>If you will be doing this on another platform then you will
	need to use whatever utilities exist to control your CD writer on
	that platform. The images provided are in the standard ISO format,
	which many CD writing applications support.</para>
	</step>
	</procedure>

	<note><para>If you are interested in building a customized
	- release of FreeBSD, please see the <ulink
	+ release of &os;, please see the <ulink
	url="&url.articles.releng;">Release Engineering
	Article</ulink>.</para></note>

	</sect2>

	<sect2 id="install-ftp">
	- <title>Creating a Local FTP Site with a FreeBSD Disc</title>
	+ <title>Creating a Local FTP Site with a &os; Disc</title>

	<indexterm>
	<primary>installation</primary>
	<secondary>network</secondary>
	<tertiary>FTP</tertiary>
	</indexterm>

	- <para>FreeBSD discs are laid out in the same way as the FTP site. This
	+ <para>&os; discs are laid out in the same way as the FTP site. This
	makes it very easy for you to create a local FTP site that can be used
	- by other machines on your network when installing FreeBSD.</para>
	+ by other machines on your network when installing &os;.</para>

	<procedure>
	<step>
	- <para>On the FreeBSD computer that will host the FTP site, ensure
	+ <para>On the &os; computer that will host the FTP site, ensure
	that the CDROM is in the drive, and mounted on
	<filename>/cdrom</filename>.</para>

	<screen>&prompt.root; <userinput>mount /cdrom</userinput></screen>
	</step>

	<step>
	<para>Create an account for anonymous FTP in
	<filename>/etc/passwd</filename>. Do this by editing
	<filename>/etc/passwd</filename> using &man.vipw.8; and adding
	this line:</para>

	<programlisting>ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
	</step>

	<step>
	<para>Ensure that the FTP service is enabled in
	<filename>/etc/inetd.conf</filename>.</para>
	</step>
	</procedure>

	<para>Anyone with network connectivity to your machine can now
	chose a media type of FTP and type in
	<userinput>ftp://<replaceable>your machine</replaceable></userinput>
	after picking <quote>Other</quote> in the FTP sites menu during
	the install.</para>

	<note>
	<para>If the boot media (floppy disks, usually) for your FTP
	clients is not precisely the same version as that provided
	by the local FTP site, then <application>sysinstall</application>
	will not let you
	complete the installation. If the versions are not similar and
	you want to override this, you must go into the
	<guimenu>Options</guimenu> menu and change distribution name to
	<guimenuitem>any</guimenuitem>.</para>
	</note>

	<warning>
	<para>This approach is OK for a machine that is on your local network,
	and that is protected by your firewall. Offering up FTP services to
	other machines over the Internet (and not your local network)
	exposes your computer to the attention of crackers and other
	undesirables. We strongly recommend that you follow good security
	practices if you do this.</para>
	</warning>
	</sect2>

	<sect2>
	<title>Creating Installation Floppies</title>

	<indexterm>
	<primary>installation</primary>
	<secondary>floppies</secondary>
	</indexterm>

	<para>If you must install from floppy disk (which we suggest you
	do <emphasis>not</emphasis> do), either due to unsupported
	hardware or simply because you insist on doing things the hard
	way, you must first prepare some floppies for the installation.</para>

	<para>At a minimum, you will need as many 1.44 MB floppies
	as it takes to hold all the files in the
	<filename>base</filename> (base distribution) directory. If
	you are preparing the floppies from &ms-dos;, then they
	<emphasis>must</emphasis> be formatted using the &ms-dos;
	<command>FORMAT</command> command. If you are using &windows;,
	use Explorer to format the disks (right-click on the
	<devicename>A:</devicename> drive, and select
	<quote>Format</quote>).</para>

	<para>Do <emphasis>not</emphasis> trust factory pre-formatted
	floppies. Format them again yourself, just to be sure. Many
	problems reported by our users in the past have resulted from
	the use of improperly formatted media, which is why we are
	making a point of it now.</para>

	- <para>If you are creating the floppies on another FreeBSD machine,
	+ <para>If you are creating the floppies on another &os; machine,
	a format is still not a bad idea, though you do not need to put
	a &ms-dos; filesystem on each floppy. You can use the
	<command>bsdlabel</command> and <command>newfs</command>
	commands to put a UFS filesystem on them instead, as the
	following sequence of commands (for a 3.5" 1.44 MB floppy)
	illustrates:</para>

	<screen>&prompt.root; <userinput>fdformat -f 1440 fd0.1440</userinput>
	&prompt.root; <userinput>bsdlabel -w fd0.1440 floppy3</userinput>
	&prompt.root; <userinput>newfs -t 2 -u 18 -l 1 -i 65536 /dev/fd0</userinput></screen>

	<para>Then you can mount and write to them like any other
	filesystem.</para>

	<para>After you have formatted the floppies, you will need to copy
	the files to them. The distribution files are split into chunks
	conveniently sized so that five of them will fit on a conventional
	1.44 MB floppy. Go through all your floppies, packing as many
	files as will fit on each one, until you have all of the
	distributions you want packed up in this fashion. Each
	distribution should go into a subdirectory on the floppy, e.g.:
	<filename>a:\base\base.aa</filename>,
	<filename>a:\base\base.ab</filename>, and so on.</para>

	<important>
	<para>The <filename>base.inf</filename> file also needs to go on the
	first floppy of the <filename>base</filename> set since it is read
	by the installation program in order to figure out how many
	additional pieces to look for when fetching and concatenating the
	distribution.</para>
	</important>

	<para>Once you come to the Media screen during the install
	process, select <guimenuitem>Floppy</guimenuitem> and you
	will be prompted for the rest.</para>
	</sect2>

	<sect2 id="install-msdos">
	<title>Installing from an &ms-dos; Partition</title>

	<indexterm>
	<primary>installation</primary>
	<secondary>from MS-DOS</secondary>
	</indexterm>
	<para>To prepare for an installation from an &ms-dos; partition,
	copy the files from the distribution into a directory
	called <filename>freebsd</filename> in the root directory of the
	partition. For example, <filename>c:\freebsd</filename>. The
	directory structure of the CDROM or FTP site must be partially
	reproduced within this directory, so we suggest using the &ms-dos;
	<command>xcopy</command> command if you are copying it from a CD.
	For example, to prepare for a minimal installation of
	- FreeBSD:</para>
	+ &os;:</para>

	<screen><prompt>C:\></prompt> <userinput>md c:\freebsd</userinput>
	<prompt>C:\></prompt> <userinput>xcopy e:\bin c:\freebsd\bin\ /s</userinput>
	<prompt>C:\></prompt> <userinput>xcopy e:\manpages c:\freebsd\manpages\ /s</userinput></screen>

	<para>Assuming that <devicename>C:</devicename> is where you have
	free space and <devicename>E:</devicename> is where your CDROM
	is mounted.</para>

	<para>If you do not have a CDROM drive, you can download the
	distribution from <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/">ftp.FreeBSD.org</ulink>.
	Each distribution is in its own directory; for example, the
	<emphasis>base</emphasis> distribution can be found in the <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/base/">&rel.current;/base/</ulink>
	directory.</para>

	<para>For as many distributions you wish to install from an &ms-dos;
	partition (and you have the free space for), install each one
	under <filename>c:\freebsd</filename> — the
	<literal>BIN</literal> distribution is the only one required for
	a minimum installation.</para>
	</sect2>

	<sect2>
	<title>Creating an Installation Tape</title>

	<indexterm>
	<primary>installation</primary>
	<secondary>from QIC/SCSI Tape</secondary>
	</indexterm>
	<para>Installing from tape is probably the easiest method, short
	of an online FTP install or CDROM install. The installation
	program expects the files to be simply tarred onto the tape.
	After getting all of the distribution files you are interested
	in, simply tar them onto the tape:</para>

	<screen>&prompt.root; <userinput>cd /freebsd/distdir</userinput>
	&prompt.root; <userinput>tar cvf /dev/rwt0 dist1 ... dist2</userinput></screen>

	<para>When you perform the installation, you should make
	sure that you leave enough room in some temporary directory
	(which you will be allowed to choose) to accommodate the
	<emphasis>full</emphasis> contents of the tape you have created.
	Due to the non-random access nature of tapes, this method of
	installation requires quite a bit of temporary storage.</para>

	<note>
	<para>When starting the installation, the tape must be in the
	drive <emphasis>before</emphasis> booting from the boot
	floppy. The installation probe may otherwise fail to find
	it.</para>
	</note>
	</sect2>

	<sect2>
	<title>Before Installing over a Network</title>

	<indexterm>
	<primary>installation</primary>
	<secondary>network</secondary>
	<tertiary>serial (PPP)</tertiary>
	</indexterm>
	<indexterm>
	<primary>installation</primary>
	<secondary>network</secondary>
	<tertiary>parallel (PLIP)</tertiary>
	</indexterm>
	<indexterm>
	<primary>installation</primary>
	<secondary>network</secondary>
	<tertiary>Ethernet</tertiary>
	</indexterm>
	<para>There are three types of network installations available.
	Ethernet (a standard Ethernet controller), Serial port (PPP), or
	Parallel port (PLIP (laplink cable)).</para>

	<para>For the fastest possible network installation, an
	- Ethernet adapter is always a good choice! FreeBSD supports most
	+ Ethernet adapter is always a good choice! &os; supports most
	common PC Ethernet cards; a table of supported cards (and their
	required settings) is provided in the Hardware Notes for each
	- release of FreeBSD. If you are using one of the supported PCMCIA
	+ release of &os;. If you are using one of the supported PCMCIA
	Ethernet cards, also be sure that it is plugged in
	- <emphasis>before</emphasis> the laptop is powered on! FreeBSD does
	+ <emphasis>before</emphasis> the laptop is powered on! &os; does
	not, unfortunately, currently support hot insertion of PCMCIA cards
	during installation.</para>

	<para>You will also need to know your IP address on the network,
	the netmask value for your address class, and the name of your
	machine. If you are installing over a PPP connection and do not
	have a static IP, fear not, the IP address can be dynamically
	assigned by your ISP. Your system administrator can tell you
	which values to use for your particular network setup. If you
	will be referring to other hosts by name rather than IP address,
	you will also need a name server and possibly the address of a
	gateway (if you are using PPP, it is your provider's IP address)
	to use in talking to it. If you want to install by FTP via a
	HTTP proxy, you will also need the proxy's address.
	If you do not know the answers to all or most of these questions,
	then you should really probably talk to your system administrator
	or ISP <emphasis>before</emphasis> trying this type of
	installation.</para>

	<para>If you are using a modem, then PPP is almost certainly
	your only choice. Make sure that you have your service
	provider's information handy as you will need to know it fairly
	early in the installation process.</para>

	<para>If you use PAP or CHAP to connect your ISP (in other words, if
	you can connect to the ISP in &windows; without using a script), then
	all you will need to do is type in <command>dial</command> at the
	<application>ppp</application> prompt. Otherwise, you will need to
	know how to dial your ISP using the <quote>AT commands</quote>
	specific to your modem, as the PPP dialer provides only a very
	simple terminal emulator. Please refer to the user-ppp <link
	linkend="userppp">handbook</link> and <ulink
	url="&url.books.faq;/ppp.html">FAQ</ulink>
	entries for further information.
	If you have problems, logging can be directed to the screen using
	the command <command>set log local ...</command>.</para>

	- <para>If a hard-wired connection to another FreeBSD
	+ <para>If a hard-wired connection to another &os;
	machine is available, you might also consider installing
	over a <quote>laplink</quote> parallel port cable. The data rate
	over the parallel port is much higher than what is typically
	possible over a serial line (up to 50 kbytes/sec), thus
	resulting in a quicker installation.</para>

	<sect3>
	<title>Before Installing via NFS</title>

	<indexterm>
	<primary>installation</primary>
	<secondary>network</secondary>
	<tertiary>NFS</tertiary>
	</indexterm>
	<para>The NFS installation is fairly straight-forward. Simply
	- copy the FreeBSD distribution files you want onto an NFS server
	+ copy the &os; distribution files you want onto an NFS server
	and then point the NFS media selection at it.</para>

	<para>If this server supports only <quote>privileged port</quote>
	(as is generally the default for Sun workstations), you will
	need to set the option <literal>NFS Secure</literal> in the
	<guimenu>Options</guimenu> menu before installation can
	proceed.</para>

	<para>If you have a poor quality Ethernet card which suffers
	from very slow transfer rates, you may also wish to toggle the
	<literal>NFS Slow</literal> flag.</para>

	<para>In order for NFS installation to work, the server must
	support subdir mounts, for example, if your
	- FreeBSD &rel.current; distribution directory lives on:
	+ &os; &rel.current; distribution directory lives on:
	<filename>ziggy:/usr/archive/stuff/FreeBSD</filename>, then
	<hostid>ziggy</hostid> will have to allow the direct mounting
	of <filename>/usr/archive/stuff/FreeBSD</filename>, not just
	<filename>/usr</filename> or
	<filename>/usr/archive/stuff</filename>.</para>

	- <para>In FreeBSD's <filename>/etc/exports</filename> file, this
	+ <para>In &os;'s <filename>/etc/exports</filename> file, this
	is controlled by the <option>-alldirs</option> options. Other NFS
	servers may have different conventions. If you are getting
	<errorname>permission denied</errorname> messages from the
	server, then it is likely that you do not have this enabled
	properly.</para>
	</sect3>

	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/introduction/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/introduction/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/introduction/chapter.xml (revision 41355)
	@@ -1,1102 +1,1080 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="introduction">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Jim</firstname>
	<surname>Mock</surname>
	<contrib>Restructured, reorganized, and parts
	rewritten by </contrib>
	</author>
	</authorgroup>
	</chapterinfo>

	<title>Introduction</title>

	<sect1 id="introduction-synopsis">
	<title>Synopsis</title>

	<para>Thank you for your interest in &os;! The following chapter
	covers various aspects of the &os; Project, such as its
	history, goals, development model, and so on.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>How &os; relates to other computer operating
	systems.</para>
	</listitem>

	<listitem>
	<para>The history of the &os; Project.</para>
	</listitem>

	<listitem>
	<para>The goals of the &os; Project.</para>
	</listitem>

	<listitem>
	<para>The basics of the &os; open-source development
	model.</para>
	</listitem>

	<listitem>
	<para>And of course: where the name <quote>&os;</quote> comes
	from.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="nutshell">
	<title>Welcome to &os;!</title>

	<indexterm><primary>4.4BSD-Lite</primary></indexterm>

	<para>&os; is a 4.4BSD-Lite based operating system for
	Intel (x86 and &itanium;), AMD64, Sun
	&ultrasparc; computers. Ports to other
	architectures are also underway. You can also
	read about <link linkend="history">the history of &os;</link>,
	or the <link linkend="relnotes">current release</link>. If you
	are interested in contributing something to the Project (code,
	hardware, funding), see the <ulink
	url="&url.articles.contributing;/index.html">Contributing to
	&os;</ulink> article.</para>

	<sect2 id="os-overview">
	<title>What Can &os; Do?</title>

	<para>&os; has many noteworthy features. Some of these
	are:</para>

	<itemizedlist>
	<listitem>
	<indexterm><primary>preemptive
	multitasking</primary></indexterm>

	<para><emphasis>Preemptive multitasking</emphasis> with
	dynamic priority adjustment to ensure smooth and fair
	sharing of the computer between applications and users,
	even under the heaviest of loads.</para>
	</listitem>

	<listitem>
	<indexterm><primary>multi-user
	facilities</primary></indexterm>

	<para><emphasis>Multi-user facilities</emphasis> which allow
	many people to use a &os; system simultaneously for a
	variety of things. This means, for example, that system
	peripherals such as printers and tape drives are properly
	shared between all users on the system or the network and
	that individual resource limits can be placed on users or
	groups of users, protecting critical system resources from
	over-use.</para>
	</listitem>
	<listitem>
	<indexterm><primary>TCP/IP networking</primary></indexterm>

	<para>Strong <emphasis>TCP/IP networking</emphasis> with
	support for industry standards such as SCTP, DHCP, NFS,
	NIS, PPP, SLIP, IPsec, and IPv6. This means that your
	&os; machine can interoperate easily with other systems as
	well as act as an enterprise server, providing vital
	functions such as NFS (remote file access) and email
	services or putting your organization on the Internet with
	WWW, FTP, routing and firewall (security) services.</para>
	</listitem>

	<listitem>
	<indexterm><primary>memory protection</primary></indexterm>

	<para><emphasis>Memory protection</emphasis> ensures that
	applications (or users) cannot interfere with each other.
	One application crashing will not affect others in any
	way.</para>
	</listitem>

	<listitem>
	<para>&os; is a <emphasis>32-bit</emphasis> operating
	system (<emphasis>64-bit</emphasis> on the &itanium;,
	AMD64, and &ultrasparc;) and was designed as such from
	the ground up.</para>
	</listitem>

	<listitem>
	<indexterm>
	<primary>X Window System</primary>
	</indexterm>

	<para>The industry standard <emphasis>X Window
	System</emphasis> (X11R7) provides a graphical user
	interface (GUI) for the cost of a common VGA card and
	monitor and comes with full sources.</para>
	</listitem>

	<listitem>
	<indexterm>
	<primary>binary compatibility</primary>
	<secondary>Linux</secondary>
	</indexterm>
	<indexterm>
	<primary>binary compatibility</primary>
	<secondary>SCO</secondary>
	</indexterm>
	<indexterm>
	<primary>binary compatibility</primary>
	<secondary>SVR4</secondary>
	</indexterm>
	<indexterm>
	<primary>binary compatibility</primary>
	<secondary>BSD/OS</secondary>
	</indexterm>
	<indexterm>
	<primary>binary compatibility</primary>
	<secondary>NetBSD</secondary>
	</indexterm>

	<para><emphasis>Binary compatibility</emphasis> with many
	programs built for Linux, SCO, SVR4, BSDI and
	NetBSD.</para>
	</listitem>

	<listitem>
	<para>Thousands of <emphasis>ready-to-run</emphasis>
	applications are available from the &os;
	<emphasis>ports</emphasis> and
	<emphasis>packages</emphasis> collection. Why search the
	net when you can find it all right here?</para>
	</listitem>

	<listitem>
	<para>Thousands of additional and
	<emphasis>easy-to-port</emphasis> applications are
	available on the Internet. &os; is source code compatible
	with most popular commercial &unix; systems and thus most
	applications require few, if any, changes to
	compile.</para>
	</listitem>
	<listitem>
	<indexterm><primary>virtual memory</primary></indexterm>

	<para>Demand paged <emphasis>virtual memory</emphasis> and
	<quote>merged VM/buffer cache</quote> design efficiently
	satisfies applications with large appetites for memory
	while still maintaining interactive response to other
	users.</para>
	</listitem>

	<listitem>
	<indexterm>
	<primary>Symmetric Multi-Processing (SMP)</primary>
	</indexterm>

	<para><emphasis>SMP</emphasis> support for machines with
	multiple CPUs.</para>
	</listitem>

	<listitem>
	<indexterm>
	<primary>compilers</primary>
	<secondary>C</secondary>
	</indexterm>
	<indexterm>
	<primary>compilers</primary>
	<secondary>C++</secondary>
	</indexterm>

	<para>A full complement of <emphasis>C</emphasis>
	and <emphasis>C++</emphasis>
	development tools.
	Many additional languages for advanced research
	and development are also available in the ports and
	packages collection.</para>
	</listitem>

	<listitem>
	<indexterm><primary>source code</primary></indexterm>

	<para><emphasis>Source code</emphasis> for the entire system
	means you have the greatest degree of control over your
	environment. Why be locked into a proprietary solution
	at the mercy of your vendor when you can have a truly open
	system?</para>
	</listitem>

	<listitem>
	<para>Extensive <emphasis>online
	documentation</emphasis>.</para>
	</listitem>

	<listitem>
	<para><emphasis>And many more!</emphasis></para>
	</listitem>
	</itemizedlist>

	<indexterm><primary>4.4BSD-Lite</primary></indexterm>
	<indexterm>
	<primary>Computer Systems Research Group (CSRG)</primary>
	</indexterm>
	<indexterm><primary>U.C. Berkeley</primary></indexterm>
	<para>&os; is based on the 4.4BSD-Lite release from Computer
	Systems Research Group (CSRG) at the University of California
	at Berkeley, and carries on the distinguished tradition of BSD
	systems development. In addition to the fine work provided by
	CSRG, the &os; Project has put in many thousands of hours
	in fine tuning the system for maximum performance and
	reliability in real-life load situations. As many of the
	commercial giants struggle to field PC operating systems with
	such features, performance and reliability, &os; can offer
	them <emphasis>now</emphasis>!</para>

	<para>The applications to which &os; can be put are truly
	limited only by your own imagination. From software
	development to factory automation, inventory control to
	azimuth correction of remote satellite antennae; if it can be
	done with a commercial &unix; product then it is more than
	likely that you can do it with &os; too! &os; also benefits
	significantly from literally thousands of high quality
	applications developed by research centers and universities
	around the world, often available at little to no cost.
	Commercial applications are also available and appearing in
	greater numbers every day.</para>

	<para>Because the source code for &os; itself is generally
	available, the system can also be customized to an almost
	unheard of degree for special applications or projects, and in
	ways not generally possible with operating systems from most
	major commercial vendors. Here is just a sampling of some of
	the applications in which people are currently using
	&os;:</para>

	<itemizedlist>
	<listitem>
	<para><emphasis>Internet Services:</emphasis> The robust
	TCP/IP networking built into &os; makes it an ideal
	platform for a variety of Internet services such
	as:</para>

	<itemizedlist>
	<listitem>
	<indexterm><primary>FTP servers</primary></indexterm>

	<para>FTP servers</para>
	</listitem>

	<listitem>
	<indexterm><primary>web servers</primary></indexterm>

	<para>World Wide Web servers (standard or secure
	[SSL])</para>
	</listitem>

	<listitem>
	<para>IPv4 and IPv6 routing</para>
	</listitem>

	<listitem>
	<indexterm><primary>firewall</primary></indexterm>

	<indexterm><primary>NAT</primary></indexterm>

	<para>Firewalls and NAT (<quote>IP masquerading</quote>)
	gateways</para>
	</listitem>

	<listitem>
	<indexterm>
	<primary>electronic mail</primary>
	<see>email</see>
	</indexterm>
	<indexterm>
	<primary>email</primary>
	</indexterm>

	<para>Electronic Mail servers</para>
	</listitem>

	<listitem>
	<indexterm><primary>USENET</primary></indexterm>

	<para>USENET News or Bulletin Board Systems</para>
	</listitem>

	<listitem>
	<para>And more...</para>
	</listitem>
	</itemizedlist>

	<para>With &os;, you can easily start out small with an
	inexpensive 386 class PC and upgrade all the way up to a
	quad-processor Xeon with RAID storage as your enterprise
	grows.</para>
	</listitem>

	<listitem>
	<para><emphasis>Education:</emphasis> Are you a student of
	computer science or a related engineering field? There
	is no better way of learning about operating systems,
	computer architecture and networking than the hands on,
	under the hood experience that &os; can provide. A number
	of freely available CAD, mathematical and graphic design
	packages also make it highly useful to those whose primary
	interest in a computer is to get
	<emphasis>other</emphasis> work done!</para>
	</listitem>

	<listitem>
	<para><emphasis>Research:</emphasis> With source code for
	the entire system available, &os; is an excellent platform
	for research in operating systems as well as other
	branches of computer science. &os;'s freely available
	nature also makes it possible for remote groups to
	collaborate on ideas or shared development without having
	to worry about special licensing agreements or limitations
	on what may be discussed in open forums.</para>
	</listitem>

	<listitem>
	<indexterm><primary>router</primary></indexterm>

	<indexterm><primary>DNS Server</primary></indexterm>

	<para><emphasis>Networking:</emphasis> Need a new router?
	A name server (DNS)? A firewall to keep people out of your
	internal network? &os; can easily turn that unused 386 or
	486 PC sitting in the corner into an advanced router with
	sophisticated packet-filtering capabilities.</para>
	</listitem>

	<listitem>
	<indexterm>
	<primary>X Window System</primary>
	</indexterm>
	<indexterm>
	<primary>X Window System</primary>
	<secondary>Accelerated-X</secondary>
	</indexterm>

	<para><emphasis>X Window workstation:</emphasis> &os; is a
	fine choice for an inexpensive X terminal solution,
	using the freely available X11 server.
	Unlike an X terminal, &os; allows many applications to
	be run locally if desired, thus relieving the burden on a
	central server. &os; can even boot
	<quote>diskless</quote>, making individual workstations
	even cheaper and easier to administer.</para>
	</listitem>

	<listitem>
	<indexterm><primary>GNU Compiler
	Collection</primary></indexterm>

	<para><emphasis>Software Development:</emphasis> The basic
	&os; system comes with a full complement of development
	tools including the renowned GNU C/C++ compiler and
	debugger.</para>
	</listitem>
	</itemizedlist>

	<para>&os; is available in both source and binary form on
	CD-ROM, DVD, and via anonymous FTP. Please see <xref
	linkend="mirrors"/> for more information about obtaining
	&os;.</para>
	</sect2>

	<sect2 id="introduction-nutshell-users">
	<title>Who Uses &os;?</title>

	<indexterm>
	<primary>users</primary>
	<secondary>large sites running &os;</secondary>
	</indexterm>

	<para>&os; is used as a platform for devices and products from
	many of the world's largest IT companies, including:</para>

	<itemizedlist>
	<listitem>
	<indexterm><primary>Apple</primary></indexterm>
	<para><ulink
	url="http://www.apple.com/">Apple</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>Cisco</primary></indexterm>
	<para><ulink
	url="http://www.cisco.com/">Cisco</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="http://www.juniper.net/">Juniper</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>NetApp</primary></indexterm>
	<para><ulink
	url="http://www.netapp.com/">NetApp</ulink></para>
	</listitem>
	</itemizedlist>

	<para>&os; is also used to power some of the biggest sites on
	the Internet, including:</para>

	<itemizedlist>
	<listitem>
	<indexterm><primary>Yahoo!</primary></indexterm>
	<para><ulink
	url="http://www.yahoo.com/">Yahoo!</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>Yandex</primary></indexterm>
	<para><ulink
	url="http://www.yandex.ru/">Yandex</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>Apache</primary></indexterm>
	<para><ulink
	url="http://www.apache.org/">Apache</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>Rambler</primary></indexterm>
	<para><ulink
	url="http://www.rambler.ru/">Rambler</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>Sina</primary></indexterm>
	<para><ulink url="http://www.sina.com/">Sina</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>Pair Networks</primary></indexterm>

	<para><ulink
	url="http://www.pair.com/">Pair Networks</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>Sony Japan</primary></indexterm>

	<para><ulink
	url="http://www.sony.co.jp/">Sony Japan</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>Netcraft</primary></indexterm>

	<para><ulink
	url="http://www.netcraft.com/">Netcraft</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>NetEase</primary></indexterm>

	<para><ulink
	url="http://www.163.com/">NetEase</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>Weathernews</primary></indexterm>

	<para><ulink
	url="http://www.wni.com/">Weathernews</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>TELEHOUSE America</primary></indexterm>

	<para><ulink url="http://www.telehouse.com/">TELEHOUSE
	America</ulink></para>
	</listitem>

	<listitem>
	<indexterm><primary>Experts Exchange</primary></indexterm>

	<para><ulink url="http://www.experts-exchange.com/">Experts
	Exchange</ulink></para>
	</listitem>
	</itemizedlist>

	<para>and many more.</para>
	</sect2>
	</sect1>

	<sect1 id="history">
	<title>About the &os; Project</title>

	<para>The following section provides some background information
	on the project, including a brief history, project goals, and
	the development model of the project.</para>

	<sect2 id="intro-history">
	<sect2info role="firstperson">
	<authorgroup>
	<author>
	<firstname>Jordan</firstname>
	<surname>Hubbard</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>A Brief History of &os;</title>

	<indexterm><primary>386BSD Patchkit</primary></indexterm>
	<indexterm><primary>Hubbard, Jordan</primary></indexterm>
	<indexterm><primary>Williams, Nate</primary></indexterm>
	<indexterm><primary>Grimes, Rod</primary></indexterm>
	<indexterm>
	<primary>FreeBSD Project</primary>
	<secondary>history</secondary>
	</indexterm>
	<para>The &os; Project had its genesis in the early part
	of 1993, partially as an outgrowth of the <quote>Unofficial
	386BSDPatchkit</quote> by the patchkit's last 3
	coordinators: Nate Williams, Rod Grimes and myself.</para>

	<indexterm><primary>386BSD</primary></indexterm>
	<para>Our original goal was to produce an intermediate snapshot
	of 386BSD in order to fix a number of problems with it that
	the patchkit mechanism just was not capable of solving. Some
	of you may remember the early working title for the project
	being <quote>386BSD 0.5</quote> or <quote>386BSD
	Interim</quote> in reference to that fact.</para>

	<indexterm><primary>Jolitz, Bill</primary></indexterm>
	<para>386BSD was Bill Jolitz's operating system, which had been
	up to that point suffering rather severely from almost a
	year's worth of neglect. As the patchkit swelled ever more
	uncomfortably with each passing day, we were in unanimous
	agreement that something had to be done and decided to assist
	Bill by providing this interim <quote>cleanup</quote>
	snapshot. Those plans came to a rude halt when Bill Jolitz
	suddenly decided to withdraw his sanction from the project
	without any clear indication of what would be done
	instead.</para>

	<indexterm><primary>Greenman, David</primary></indexterm>
	<indexterm><primary>Walnut Creek CDROM</primary></indexterm>
	<para>It did not take us long to decide that the goal remained
	worthwhile, even without Bill's support, and so we adopted the
	name <quote>&os;</quote>, coined by David Greenman. Our
	initial objectives were set after consulting with the system's
	current users and, once it became clear that the project was
	on the road to perhaps even becoming a reality, I contacted
	Walnut Creek CDROM with an eye toward improving &os;'s
	distribution channels for those many unfortunates without easy
	access to the Internet. Walnut Creek CDROM not only supported
	the idea of distributing &os; on CD but also went so far as to
	provide the project with a machine to work on and a fast
	Internet connection. Without Walnut Creek CDROM's almost
	unprecedented degree of faith in what was, at the time, a
	completely unknown project, it is quite unlikely that &os;
	would have gotten as far, as fast, as it has today.</para>

	<indexterm><primary>4.3BSD-Lite</primary></indexterm>
	<indexterm><primary>Net/2</primary></indexterm>
	<indexterm><primary>U.C. Berkeley</primary></indexterm>
	<indexterm><primary>386BSD</primary></indexterm>
	<indexterm><primary>Free Software
	Foundation</primary></indexterm>
	<para>The first CD-ROM (and general net-wide) distribution was
	&os; 1.0, released in December of 1993. This was based
	on the 4.3BSD-Lite (<quote>Net/2</quote>) tape from U.C.
	Berkeley, with many components also provided by 386BSD and the
	Free Software Foundation. It was a fairly reasonable success
	for a first offering, and we followed it with the highly
	successful &os; 1.1 release in May of 1994.</para>

	<indexterm><primary>Novell</primary></indexterm>
	<indexterm><primary>U.C. Berkeley</primary></indexterm>
	<indexterm><primary>Net/2</primary></indexterm>
	<indexterm><primary>AT&T</primary></indexterm>
	<para>Around this time, some rather unexpected storm clouds
	formed on the horizon as Novell and U.C. Berkeley settled
	their long-running lawsuit over the legal status of the
	Berkeley Net/2 tape. A condition of that settlement was U.C.
	Berkeley's concession that large parts of Net/2 were
	<quote>encumbered</quote> code and the property of Novell, who
	had in turn acquired it from AT&T some time previously.
	What Berkeley got in return was Novell's
	<quote>blessing</quote> that the 4.4BSD-Lite release, when
	it was finally released, would be declared unencumbered and
	all existing Net/2 users would be strongly encouraged to
	switch. This included &os;, and the project was given until
	the end of July 1994 to stop shipping its own Net/2 based
	product. Under the terms of that agreement, the project was
	allowed one last release before the deadline, that release
	being &os; 1.1.5.1.</para>

	<para>&os; then set about the arduous task of literally
	re-inventing itself from a completely new and rather
	incomplete set of 4.4BSD-Lite bits. The <quote>Lite</quote>
	releases were light in part because Berkeley's CSRG had
	removed large chunks of code required for actually
	constructing a bootable running system (due to various legal
	requirements) and the fact that the Intel port of 4.4 was
	highly incomplete. It took the project until November of 1994
	to make this transition, at which point it released
	&os; 2.0 to the net and on CD-ROM (in late December).
	Despite being still more than a little rough around the edges,
	the release was a significant success and was followed by the
	more robust and easier to install &os; 2.0.5 release in
	June of 1995.</para>

	<para>We released &os; 2.1.5 in August of 1996, and it
	appeared to be popular enough among the ISP and commercial
	communities that another release along the 2.1-STABLE branch
	was merited. This was &os; 2.1.7.1, released in February
	1997 and capping the end of mainstream development on
	2.1-STABLE. Now in maintenance mode, only security
	enhancements and other critical bug fixes will be done on this
	branch (RELENG_2_1_0).</para>

	<para>&os; 2.2 was branched from the development mainline
	(<quote>-CURRENT</quote>) in November 1996 as the RELENG_2_2
	branch, and the first full release (2.2.1) was released in
	April 1997. Further releases along the 2.2 branch were done
	in the summer and fall of '97, the last of which (2.2.8)
	appeared in November 1998. The first official 3.0 release
	appeared in October 1998 and spelled the beginning of the end
	for the 2.2 branch.</para>

	<para>The tree branched again on Jan 20, 1999, leading to the
	4.0-CURRENT and 3.X-STABLE branches. From 3.X-STABLE, 3.1 was
	released on February 15, 1999, 3.2 on May 15, 1999, 3.3 on
	September 16, 1999, 3.4 on December 20, 1999, and 3.5 on
	June 24, 2000, which was followed a few days later by a minor
	point release update to 3.5.1, to incorporate some last-minute
	security fixes to Kerberos. This will be the final release
	in the 3.X branch.</para>

	<para>There was another branch on March 13, 2000, which saw the
	emergence of the 4.X-STABLE branch. There have been several
	releases from it so far: 4.0-RELEASE was introduced in March
	2000, and the last 4.11-RELEASE came out in January
	2005.</para>

	<para>The long-awaited 5.0-RELEASE was announced on January 19,
	2003. The culmination of nearly three years of work, this
	release started &os; on the path of advanced multiprocessor
	and application thread support and introduced support for the
	&ultrasparc; and <literal>ia64</literal> platforms. This
	release was followed by 5.1 in June of 2003. The last 5.X
	release from the -CURRENT branch was 5.2.1-RELEASE, introduced
	in February 2004.</para>

	<para>The RELENG_5 branch, created in August 2004, was followed
	by 5.3-RELEASE, which marked the beginning of the 5-STABLE
	branch releases. The most recent 5.5-RELEASE release came out
	in May 2006. There will be no additional releases from the
	RELENG_5 branch.</para>

	<para>The tree was branched again in July 2005, this time for
	RELENG_6. 6.0-RELEASE, the first release of the 6.X branch,
	was released in November 2005. The most recent 6.4-RELEASE
	came out in November 2008. There will be no additional
	releases from the RELENG_6 branch. This branch is the last
	branch to support the Alpha architecture.</para>

	<para>The RELENG_7 branch was created in October 2007. The
	first release of this branch was 7.0-RELEASE, which came
	out in February 2008. The most recent 7.4-RELEASE came out
	in February 2011. There will be no additional releases from
	the RELENG_7 branch.</para>

	<para>The tree was branched again in August 2009, this time for
	RELENG_8. 8.0-RELEASE, the first release of the 8.X branch,
	was released in November 2009. The most recent
	&rel2.current;-RELEASE came out in &rel2.current.date;. There
	will be additional releases from the RELENG_8 branch.</para>

	<para>The RELENG_9 branch was created in September 2011. The
	first release of this branch was 9.0-RELEASE, which came
	out in January 2012. The most recent &rel.current;-RELEASE
	came out in &rel.current.date;. There will be additional
	releases from the RELENG_9 branch.</para>

	<para>For now, long-term development projects continue to take
	place in the 10.X-CURRENT (trunk) branch, and SNAPshot
	releases of 10.X on CD-ROM (and, of course, on the net) are
	continually made available from <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/">the
	snapshot server</ulink> as work progresses.</para>
	</sect2>

	<sect2 id="goals">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Jordan</firstname>
	<surname>Hubbard</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>&os; Project Goals</title>

	<indexterm>
	<primary>FreeBSD Project</primary>
	<secondary>goals</secondary>
	</indexterm>
	<para>The goals of the &os; Project are to provide software
	that may be used for any purpose and without strings attached.
	Many of us have a significant investment in the code (and
	project) and would certainly not mind a little financial
	compensation now and then, but we are definitely not prepared
	to insist on it. We believe that our first and foremost
	<quote>mission</quote> is to provide code to any and all
	comers, and for whatever purpose, so that the code gets the
	widest possible use and provides the widest possible benefit.
	This is, I believe, one of the most fundamental goals of Free
	Software and one that we enthusiastically support.</para>

	<indexterm>
	<primary>GNU General Public License (GPL)</primary>
	</indexterm>
	<indexterm>
	<primary>GNU Lesser General Public License (LGPL)</primary>
	</indexterm>
	<indexterm><primary>BSD Copyright</primary></indexterm>
	<para>That code in our source tree which falls under the GNU
	General Public License (GPL) or Library General Public License
	(LGPL) comes with slightly more strings attached, though at
	least on the side of enforced access rather than the usual
	opposite. Due to the additional complexities that can evolve
	in the commercial use of GPL software we do, however, prefer
	software submitted under the more relaxed BSD copyright when
	it is a reasonable option to do so.</para>
	</sect2>

	<sect2 id="development">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Satoshi</firstname>
	<surname>Asami</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>The &os; Development Model</title>

	<indexterm>
	<primary>FreeBSD Project</primary>
	<secondary>development model</secondary>
	</indexterm>
	<para>The development of &os; is a very open and flexible
	process, being literally built from the contributions
	of hundreds of people around the world, as can be seen from
	our <ulink
	url="&url.articles.contributors;/article.html">list of
	contributors</ulink>. &os;'s development infrastructure
	allow these hundreds of developers to collaborate over the
	Internet. We are constantly on the lookout for new developers
	and ideas, and those interested in becoming more closely
	involved with the project need simply contact us at the
	&a.hackers;. The &a.announce; is also available to those
	wishing to make other &os; users aware of major areas of
	work.</para>

	<para>Useful things to know about the &os; Project and its
	development process, whether working independently or in close
	cooperation:</para>

	<variablelist>
	<varlistentry>
	- <term>The SVN and CVS repositories<anchor
	+ <term>The SVN repositories<anchor
	id="development-cvs-repository"/></term>
	<listitem>
	<indexterm>
	<primary>CVS</primary>
	</indexterm>

	<indexterm>
	<primary>CVS Repository</primary>
	</indexterm>

	<indexterm>
	<primary>Concurrent Versions System</primary>
	<see>CVS</see>
	</indexterm>

	<indexterm>
	<primary>Subversion</primary>
	</indexterm>

	<indexterm>
	<primary>Subversion Repository</primary>
	</indexterm>

	<indexterm>
	<primary>SVN</primary>
	<see>Subversion</see>
	</indexterm>

	<para>For several years, the central source tree for &os;
	was maintained by
	<ulink url="http://www.nongnu.org/cvs/">CVS</ulink>
	(Concurrent Versions System), a freely available source
	code control tool that comes bundled with &os;. In June
	2008, the Project switched to using <ulink
	url="http://subversion.tigris.org">SVN</ulink>
	(Subversion). The switch was deemed necessary, as the
	technical limitations imposed by
	<application>CVS</application> were becoming obvious
	due to the rapid expansion of the source tree and the
	amount of history already stored. The Documentation
	Project and Ports Collection repositories also moved
	from <application>CVS</application> to
	<application>SVN</application> in May 2012 and July
	- 2012, respectively.</para>
	-
	- <para>While the <literal>src/</literal> and
	- <literal>ports/</literal> repositories now use
	- <application>SVN</application>, client side tools like
	- <application>csup</application> that depend on the older
	- <application>CVS</application> infrastructure, continue
	- to work normally — changes in the
	- <application>SVN</application> repository are backported
	- to <application>CVS</application> for this purpose.
	- Unlike <literal>src/</literal> and
	- <literal>ports/</literal>,
	- the documentation <application>SVN</application>
	- repository is not backported to
	- <application>CVS</application>.</para>
	-
	- <para>The primary <application>CVS</application>
	- <ulink
	- url="http://www.FreeBSD.org/cgi/cvsweb.cgi">repository</ulink>
	- resides on a machine in Santa Clara CA, USA
	- from where it is replicated to numerous mirror machines
	- throughout the world. The
	- <application>SVN</application> tree, which contains the
	- <link linkend="current">-CURRENT</link> and <link
	- linkend="stable">-STABLE</link> trees, can all be
	- easily replicated to your own machine as well. Please
	+ 2012, respectively. Please
	refer to the <link linkend="synching">Synchronizing
	your source tree</link> section for more information on
	- doing this.</para>
	+ obtaining the &os; <literal>src/</literal> repository
	+ and <link linkend="ports-using">Using the Ports
	+ Collection</link> for details on obtaining the &os;
	+ Ports Collection.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>The committers list<anchor
	id="development-committers"/></term>

	<listitem>
	<indexterm><primary>committers</primary></indexterm>

	<para>The <firstterm>committers</firstterm>
	are the people who have <emphasis>write</emphasis>
	access to the Subversion tree, and are authorized to
	make modifications to the &os; source (the term
	<quote>committer</quote> comes from the source control
	<command>commit</command> command, which is used to
	bring new changes into the repository). The best way of
	making submissions for review by the committers list is
	to use the &man.send-pr.1; command. If something
	appears to be jammed in the system, then you may also
	reach them by sending mail to the &a.committers;.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>The FreeBSD core team<anchor
	id="development-core"/></term>

	<listitem>
	<indexterm><primary>core team</primary></indexterm>

	<para>The <firstterm>&os; core team</firstterm>
	would be equivalent to the board of directors if the
	&os; Project were a company. The primary task of
	the core team is to make sure the project, as a whole,
	is in good shape and is heading in the right directions.
	Inviting dedicated and responsible developers to join
	our group of committers is one of the functions of the
	core team, as is the recruitment of new core team
	members as others move on. The current core team was
	elected from a pool of committer candidates in July
	2012. Elections are held every 2 years.</para>

	<para>Some core team members also have specific areas of
	responsibility, meaning that they are committed to
	ensuring that some large portion of the system works as
	advertised. For a complete list of &os; developers
	and their areas of responsibility, please see the <ulink
	url="&url.articles.contributors;/article.html">Contributors
	List</ulink></para>

	<note>
	<para>Most members of the core team are volunteers when
	it comes to &os; development and do not benefit from
	the project financially, so <quote>commitment</quote>
	should also not be misconstrued as meaning
	<quote>guaranteed support.</quote> The <quote>board
	of directors</quote> analogy above is not very
	accurate, and it may be more suitable to say that
	these are the people who gave up their lives in favor
	of &os; against their better judgement!</para>
	</note>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Outside contributors</term>

	<listitem>
	<indexterm><primary>contributors</primary></indexterm>

	<para>Last, but definitely not least, the largest group of
	developers are the users themselves who provide feedback
	and bug fixes to us on an almost constant basis. The
	primary way of keeping in touch with &os;'s more
	non-centralized development is to subscribe to the
	&a.hackers; where such things are discussed. See <xref
	linkend="eresources"/> for more information about the
	various &os; mailing lists.</para>

	<para><citetitle><ulink
	url="&url.articles.contributors;/article.html">The
	&os; Contributors List</ulink></citetitle> is a long
	and growing one, so why not join it by contributing
	something back to &os; today?</para>

	<para>Providing code is not the only way of contributing
	to the project; for a more complete list of things that
	need doing, please refer to the <ulink
	url="&url.base;/index.html">&os; Project web
	site</ulink>.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>In summary, our development model is organized as a loose
	set of concentric circles. The centralized model is designed
	for the convenience of the <emphasis>users</emphasis> of &os;,
	who are provided with an easy way of tracking one central code
	base, not to keep potential contributors out! Our desire is to
	present a stable operating system with a large set of coherent
	<link linkend="ports">application programs</link> that the
	users can easily install and use — this model works very
	well in accomplishing that.</para>

	<para>All we ask of those who would join us as &os; developers
	is some of the same dedication its current people have to its
	continued success!</para>
	</sect2>

	<sect2 id="relnotes">
	<title>The Current &os; Release</title>

	<indexterm><primary>NetBSD</primary></indexterm>
	<indexterm><primary>OpenBSD</primary></indexterm>
	<indexterm><primary>386BSD</primary></indexterm>
	<indexterm><primary>Free Software
	Foundation</primary></indexterm>
	<indexterm><primary>U.C. Berkeley</primary></indexterm>
	<indexterm>
	<primary>Computer Systems Research Group (CSRG)</primary>
	</indexterm>
	<para>&os; is a freely available, full source 4.4BSD-Lite based
	release for Intel &i386;, &i486;, &pentium;,
	&pentium; Pro,
	&celeron;,
	&pentium; II,
	&pentium; III,
	&pentium; 4 (or compatible),
	&xeon;,
	and Sun &ultrasparc; based computer
	systems. It is based primarily on software from U.C.
	Berkeley's CSRG group, with some enhancements from NetBSD,
	OpenBSD, 386BSD, and the Free Software Foundation.</para>

	<para>Since our release of &os; 2.0 in late 1994, the
	performance, feature set, and stability of &os; has improved
	dramatically.
	<!-- XXX is the rest of this paragraph still true ? -->
	The largest change is a revamped virtual memory system with a
	merged VM/file buffer cache that not only increases
	performance, but also reduces &os;'s memory footprint, making
	a 5 MB configuration a more acceptable minimum. Other
	enhancements include full NIS client and server support,
	transaction TCP support, dial-on-demand PPP, integrated DHCP
	support, an improved SCSI subsystem, ISDN support, support for
	ATM, FDDI, Fast and Gigabit Ethernet (1000 Mbit)
	adapters, improved support for the latest Adaptec controllers,
	and many thousands of bug fixes.</para>

	<para>In addition to the base distributions, &os; offers a
	ported software collection with thousands of commonly
	sought-after programs. At the time of this printing, there
	were over &os.numports; ports! The list of ports ranges from
	http (WWW) servers, to games, languages, editors, and almost
	everything in between. The entire Ports Collection requires
	approximately &ports.size; of storage, all ports being
	expressed as <quote>deltas</quote> to their original sources.
	This makes it much easier for us to update ports, and greatly
	reduces the disk space demands made by the older 1.0 Ports
	Collection. To compile a port, you simply change to the
	directory of the program you wish to install, type
	<command>make install</command>, and let the system do the
	rest. The full original distribution for each port you build
	is retrieved dynamically off the CD-ROM or a local FTP site,
	so you need only enough disk space to build the ports you
	want. Almost every port is also provided as a pre-compiled
	<quote>package</quote>, which can be installed with a simple
	command (<command>pkg_add</command>) by those who do not wish
	to compile their own ports from source. More information on
	packages and ports can be found in <xref
	linkend="ports"/>.</para>

	<para>All recent &os; versions provide an option in the
	installer (either &man.sysinstall.8; or &man.bsdinstall.8;) to
	install additional documentation under <filename
	class="directory">/usr/local/share/doc/freebsd</filename>
	during the initial system setup. Documentation may also be
	installed at any later time using packages as described in
	<xref linkend="doc-ports-install-package"/>. You may view the
	locally installed manuals with any HTML capable browser using
	the following URLs:</para>

	<variablelist>
	<varlistentry>
	<term>The FreeBSD Handbook</term>

	<listitem>
	<para><ulink type="html"
	url="file://localhost/usr/local/share/doc/freebsd/handbook/index.html"><filename>/usr/local/share/doc/freebsd/handbook/index.html</filename></ulink></para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>The FreeBSD FAQ</term>

	<listitem>
	<para><ulink type="html"
	url="file://localhost/usr/local/share/doc/freebsd/faq/index.html"><filename>/usr/local/share/doc/freebsd/faq/index.html</filename></ulink></para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>You can also view the master (and most frequently updated)
	copies at <ulink
	url="http://www.FreeBSD.org/"></ulink>.</para>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml (revision 41355)
	@@ -1,1598 +1,1497 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="kernelconfig">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Jim</firstname>
	<surname>Mock</surname>
	<contrib>Updated and restructured by </contrib>
	<!-- Mar 2000 -->
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Jake</firstname>
	<surname>Hamby</surname>
	<contrib>Originally contributed by </contrib>
	<!-- 6 Oct 1995 -->
	</author>
	</authorgroup>
	</chapterinfo>

	<title>Configuring the FreeBSD Kernel</title>

	<sect1 id="kernelconfig-synopsis">
	<title>Synopsis</title>

	<indexterm>
	<primary>kernel</primary>
	<secondary>building a custom kernel</secondary>
	</indexterm>

	<para>The kernel is the core of the &os; operating system. It
	is responsible for managing memory, enforcing security controls,
	- networking, disk access, and much more. While more and more
	- of &os; becomes dynamically configurable it is still
	- occasionally necessary to reconfigure and recompile your
	- kernel.</para>
	+ networking, disk access, and much more. While much of &os; is
	+ dynamically configurable, it is still occasionally necessary to
	+ configure and compile a custom kernel.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	- <para>Why you might need to build a custom kernel.</para>
	+ <para>When to build a custom kernel.</para>
	</listitem>

	<listitem>
	- <para>How to write a kernel configuration file, or alter an
	- existing configuration file.</para>
	+ <para>How to customize a kernel configuration file.</para>
	</listitem>

	<listitem>
	<para>How to use the kernel configuration file to create and
	build a new kernel.</para>
	</listitem>

	<listitem>
	<para>How to install the new kernel.</para>
	</listitem>

	<listitem>
	<para>How to troubleshoot if things go wrong.</para>
	</listitem>
	</itemizedlist>

	- <para>All of the commands listed within this chapter by way of
	- example should be executed as <username>root</username> in
	- order to succeed.</para>
	+ <para>All of the commands listed in the examples in this chapter
	+ should be executed as <username>root</username>.</para>
	</sect1>

	<sect1 id="kernelconfig-custom-kernel">
	<title>Why Build a Custom Kernel?</title>

	- <para>Traditionally, &os; has had what is called a
	- <quote>monolithic</quote> kernel. This means that the kernel
	- was one large program, supported a fixed list of devices, and
	- if you wanted to change the kernel's behavior then you had to
	- compile a new kernel, and then reboot your computer with the
	- new kernel.</para>
	+ <para>Traditionally, &os; used a <quote>monolithic</quote> kernel.
	+ The kernel was one large program, supported a fixed list of
	+ devices, and in order to change the kernel's behavior, one had
	+ to compile a new kernel, and then reboot into the new
	+ kernel.</para>

	- <para>Today, &os; is rapidly moving to a model where much of the
	- kernel's functionality is contained in modules which can be
	- dynamically loaded and unloaded from the kernel as necessary.
	- This allows the kernel to adapt to new hardware suddenly
	- becoming available (such as PCMCIA cards in a laptop), or for
	- new functionality to be brought into the kernel that was not
	- necessary when the kernel was originally compiled. This is
	- known as a modular kernel.</para>
	+ <para>Today, most of the functionality in the &os; kernel is
	+ contained in modules which can be dynamically loaded and
	+ unloaded from the kernel as necessary. This allows the
	+ running kernel to adapt immediately to new hardware or for new
	+ functionality to be brought into the kernel. This is known as
	+ a modular kernel.</para>

	- <para>Despite this, it is still necessary to carry out some
	- static kernel configuration. In some cases this is because
	- the functionality is so tied to the kernel that it can not be
	- made dynamically loadable. In others it may simply be because
	- no one has yet taken the time to write a dynamic loadable kernel
	- module for that functionality.</para>
	+ <para>Occasionally, it is still necessary to perform static kernel
	+ configuration. This may be because the functionality is so tied
	+ to the kernel that it can not be made dynamically loadable.
	+ Some security environments prevent the loading and unloading of
	+ kernel modules, and require that only needed functionality is
	+ statically compiled into the kernel.</para>

	- <para>Building a custom kernel is one of the most important rites
	- of passage for advanced BSD users. This process, while
	- time consuming, will provide many benefits to your &os; system.
	- Unlike the <filename>GENERIC</filename> kernel, which must
	- support a wide range of hardware, a custom kernel only contains
	- support for <emphasis>your</emphasis> PC's hardware. This has
	- a number of benefits, such as:</para>
	+ <para>Building a custom kernel is often a rite of passage for
	+ advanced BSD users. This process, while time consuming, can
	+ provide benefits to the &os; system. Unlike the
	+ <filename>GENERIC</filename> kernel, which must support a wide
	+ range of hardware, a custom kernel can be stripped down to only
	+ provide support for that computer's hardware. This has a number
	+ of benefits, such as:</para>

	<itemizedlist>
	<listitem>
	- <para>Faster boot time. Since the kernel will only probe
	- the hardware you have on your system, the time it takes
	- your system to boot can decrease dramatically.</para>
	+ <para>Faster boot time. Since the kernel will only probe the
	+ hardware on the system, the time it takes the system to boot
	+ can decrease.</para>
	</listitem>

	<listitem>
	<para>Lower memory usage. A custom kernel often uses less
	memory than the <filename>GENERIC</filename> kernel by
	omitting unused features and device drivers. This is
	important because the kernel code remains resident in
	physical memory at all times, preventing that memory from
	being used by applications. For this reason, a custom
	- kernel is especially useful on a system with a small amount
	- of RAM.</para>
	+ kernel is useful on a system with a small amount of
	+ RAM.</para>
	</listitem>

	<listitem>
	- <para>Additional hardware support. A custom kernel allows
	- you to add in support for devices which are not present
	- in the <filename>GENERIC</filename> kernel, such as
	- sound cards.</para>
	+ <para>Additional hardware support. A custom kernel can add in
	+ support for devices which are not present in the
	+ <filename>GENERIC</filename> kernel.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="kernelconfig-devices">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Finding the System Hardware</title>

	<para>Before venturing into kernel configuration, it would be
	wise to get an inventory of the machine's hardware. In cases
	where &os; is not the primary operating system, the inventory
	- list may easily be created by viewing the current operating
	- system configuration. For example, &microsoft;'s
	- <application>Device Manager</application> normally contains
	- important information about installed devices. The
	- <application>Device Manager</application> is located in the
	- control panel.</para>
	+ list can be created by viewing the current operating system
	+ configuration. For example, &microsoft;'s
	+ <application>Device Manager</application> contains information
	+ about installed devices.</para>

	<note>
	<para>Some versions of &microsoft.windows; have a
	<application>System</application> icon which will display a
	screen where <application>Device Manager</application> may
	be accessed.</para>
	</note>

	<para>If another operating system does not exist on the machine,
	the administrator must find this information out manually. One
	- method is using the &man.dmesg.8; utility and the &man.man.1;
	- commands. Most device drivers on &os; have a manual page,
	- listing supported hardware, and during the boot probe, found
	- hardware will be listed. For example, the following lines
	- indicate that the <devicename>psm</devicename> driver found
	- a mouse:</para>
	+ method is using &man.dmesg.8; and &man.man.1;. Most device
	+ drivers on &os; have a manual page, listing supported hardware.
	+ During the boot probe, found hardware will be listed. For
	+ example, the following lines indicate that the &man.psm.4;
	+ driver found a mouse:</para>

	<programlisting>psm0: <PS/2 Mouse> irq 12 on atkbdc0
	psm0: [GIANT-LOCKED]
	psm0: [ITHREAD]
	psm0: model Generic PS/2 mouse, device ID 0</programlisting>

	<para>This driver will need to be included in the custom kernel
	configuration file or loaded using &man.loader.conf.5;.</para>

	<para>On occasion, the data from <command>dmesg</command> will
	only show system messages instead of the boot probe output. In
	- these situations, the output may be obtained by viewing the
	- <filename>/var/run/dmesg.boot</filename> file.</para>
	+ these situations, the output may be obtained by reading
	+ <filename>/var/run/dmesg.boot</filename>.</para>

	- <para>Another method of finding hardware is by using the
	- &man.pciconf.8; utility which provides more verbose output.
	- For example:</para>
	+ <para>Another method for finding hardware is to use
	+ &man.pciconf.8; which provides more verbose output. For
	+ example:</para>

	<programlisting>ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00
	vendor = 'Atheros Communications Inc.'
	device = 'AR5212 Atheros AR5212 802.11abg wireless'
	class = network
	subclass = ethernet</programlisting>

	- <para>This bit of output, obtained using
	- <command>pciconf <option>-lv</option></command> shows that the
	+ <para>This output, obtained by using
	+ <command>pciconf <option>-lv</option></command>, shows that the
	<devicename>ath</devicename> driver located a wireless Ethernet
	- device. Using
	- <command>man <replaceable>ath</replaceable></command> will
	- return the &man.ath.4; manual page.</para>
	+ device. Type <command>man
	+ <replaceable>ath</replaceable></command> to read
	+ &man.ath.4;.</para>

	<para>The <option>-k</option> flag, when passed to &man.man.1;
	- can also be used to provide useful information. From the
	- above, one can issue:</para>
	+ can be used to provide useful information. For example, to
	+ display a list of manual pages which contain the specified
	+ word::</para>

	<screen>&prompt.root; man -k <replaceable>Atheros</replaceable></screen>

	- <para>To get a list of manual pages which contain that particular
	- word:</para>
	-
	<programlisting>ath(4) - Atheros IEEE 802.11 wireless network driver
	ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>

	<para>Armed with a hardware inventory list, the process of
	building a custom kernel should appear less daunting.</para>
	</sect1>

	<sect1 id="kernelconfig-modules">
	<title>Kernel Drivers, Subsystems, and Modules</title>

	<indexterm>
	<primary>kernel</primary>
	<secondary>drivers / modules / subsystems</secondary>
	</indexterm>

	- <para>Before building a custom kernel, consider the reasons for
	+ <para>Before building a custom kernel, consider the reason for
	doing so. If there is a need for specific hardware support,
	it may already exist as a module.</para>

	- <para>Kernel modules exist in the
	- <filename class="directory">/boot/kernel</filename> directory
	- and may be dynamically loaded into the running kernel using
	+ <para>Kernel modules exist in <filename
	+ class="directory">/boot/kernel</filename> and may be
	+ dynamically loaded into the running kernel using
	&man.kldload.8;. Most, if not all kernel drivers have a
	- specific module and manual page. For example, the last section
	- noted the <devicename>ath</devicename> wireless Ethernet driver.
	- This device has the following information in its manual
	- page:</para>
	+ loadable module and manual page. For example, the &man.ath.4;
	+ wireless Ethernet driver has the following information in its
	+ manual page:</para>

	<programlisting>Alternatively, to load the driver as a module at boot time, place the
	following line in &man.loader.conf.5;:

	if_ath_load="YES"</programlisting>

	- <para>As instructed, adding the
	- <literal>if_ath_load="YES"</literal> line to the
	- <filename>/boot/loader.conf</filename> file will
	- enable loading this module dynamically at boot time.</para>
	+ <para>Adding <literal>if_ath_load="YES"</literal> to
	+ <filename>/boot/loader.conf</filename> will enable loading this
	+ module dynamically at boot time.</para>

	- <para>In some cases; however, there is no associated module.
	- This is mostly true for certain subsystems and very important
	- drivers, for instance, the fast file system
	- (<acronym>FFS</acronym>) is a required option in the kernel.
	- As is network support (INET). Unfortunately the only way to
	- tell if a driver is required is to check for the module
	- itself.</para>
	+ <para>In some cases, there is no associated module. This is
	+ mostly true for certain subsystems. One way to tell if a driver
	+ is available is to check for the module itself.</para>

	<warning>
	- <para>It is easy to remove support for a
	- device or option and end up with a broken kernel. For
	- example, if the &man.ata.4; driver is removed from the kernel
	- configuration file, a system using <acronym>ATA</acronym>
	- disk drivers may not boot without the module added to
	- <filename>loader.conf</filename>. When in doubt, check for
	- the module and then just leave support in the kernel.</para>
	+ <para>It is easy to remove support for a device or option and
	+ end up with a broken kernel. For example, if the &man.ata.4;
	+ driver is removed from the kernel configuration file, a system
	+ using <acronym>ATA</acronym> disk drivers may not boot. When
	+ in doubt, just leave support in the kernel.</para>
	</warning>
	</sect1>

	<sect1 id="kernelconfig-building">
	<title>Building and Installing a Custom Kernel</title>

	<indexterm>
	<primary>kernel</primary>
	<secondary>building / installing</secondary>
	</indexterm>

	<note>
	<para>It is required to have the full &os; source tree installed
	to build the kernel.</para>
	</note>

	- <para>First, let us take a quick tour of the kernel build
	- directory. All directories mentioned will be relative to the
	- main <filename>/usr/src/sys</filename> directory, which is
	- also accessible through the path name <filename>/sys</filename>.
	- There are a number of subdirectories here representing different
	- parts of the kernel, but the most important for our purposes
	- are <filename><replaceable>arch</replaceable>/conf</filename>,
	- where you will edit your custom kernel configuration, and
	- <filename>compile</filename>, which is the staging area where
	- your kernel will be built. <replaceable>arch</replaceable>
	- represents one of <filename>i386</filename>,
	- <filename>amd64</filename>, <filename>ia64</filename>,
	- <filename>powerpc</filename>, <filename>sparc64</filename>,
	- or <filename>pc98</filename> (an alternative development branch
	- of PC hardware, popular in Japan). Everything inside a
	+ <para>The kernel build is located at <filename
	+ class="directory">/usr/src/sys</filename>. It contains a
	+ number of subdirectories representing different parts of the
	+ kernel. These include <filename
	+ class="directory"><replaceable>arch</replaceable>/conf</filename>,
	+ which contains the kernel configuration file, and
	+ <filename class="directory">compile</filename>, which is the
	+ staging area where the kernel will be built.
	+ <replaceable>arch</replaceable> contains subdirectories for each
	+ supported architecture: <filename
	+ class="directory">i386</filename>, <filename
	+ class="directory">amd64</filename>, <filename
	+ class="directory">ia64</filename>, <filename
	+ class="directory">powerpc</filename>, <filename
	+ class="directory">sparc64</filename>, and <filename
	+ class="directory">pc98</filename>. Everything inside a
	particular architecture's directory deals with that architecture
	- only; the rest of the code is machine independent code common
	- to all platforms to which &os; could potentially be ported.
	- Notice the logical organization of the directory structure,
	- with each supported device, file system, and option in its
	- own subdirectory.</para>
	+ only and the rest of the code is machine independent code common
	+ to all platforms. Notice the logical organization of the
	+ directory structure, with each supported device, file system,
	+ and option in its own subdirectory.</para>

	- <para>The examples in this chapter assume that you are using
	- the i386 architecture. If your system has a different
	- architecture you need to change the path names
	- accordingly.</para>
	+ <para>The examples in this chapter assume the i386 architecture.
	+ If the system has a different architecture, change the path
	+ names accordingly.</para>

	<note>
	- <para>If the directory <filename>/usr/src/</filename> does not
	- exist on your system (or if it is empty), then the sources
	- have not been installed. The easiest way to install the full
	- source is to use &man.csup.1; as described in <xref
	- linkend="synching"/>. You should also create a symlink to
	+ <para>If <filename class="directory">/usr/src/</filename> does
	+ not exist or it is empty, source has not been installed. The
	+ easiest way to install source is to use
	+ <application>svn</application> as described in <link
	+ linkend="svn"></link>. One should also create a symlink to
	<filename class="directory">/usr/src/sys/</filename>:</para>

	<screen>&prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput></screen>
	</note>

	- <para>Next, change to the
	- <filename><replaceable>arch</replaceable>/conf</filename>
	- directory and copy the <filename>GENERIC</filename>
	- configuration file to the name you want to give your kernel.
	- For example:</para>
	+ <para>Next, <application>cd</application> to <filename
	+ class="directory"><replaceable>arch</replaceable>/conf</filename>
	+ and copy the <filename>GENERIC</filename> configuration file to
	+ the name of the custom kernel. For example:</para>

	<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
	&prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen>

	- <para>Traditionally, this name is in all capital letters and,
	- if you are maintaining multiple &os; machines with different
	- hardware, it is a good idea to name it after your machine's
	- hostname. We will call it
	- <filename><replaceable>MYKERNEL</replaceable></filename> for
	- the purpose of this example.</para>
	+ <para>Traditionally, this name is in all capital letters. When
	+ maintaining multiple &os; machines with different hardware, it
	+ is a good idea to name it after the machine's hostname. This
	+ example uses
	+ <filename><replaceable>MYKERNEL</replaceable></filename>.</para>

	<tip>
	- <para>Storing your kernel configuration file directly under
	- <filename>/usr/src</filename> can be a bad idea. If you are
	- experiencing problems it can be tempting to just delete
	- <filename>/usr/src</filename> and start again. After doing
	- this, it usually only takes a few seconds for
	- you to realize that you have deleted your custom kernel
	- configuration file. Also, do not edit
	- <filename>GENERIC</filename> directly, as it may get
	- overwritten the next time you
	- <link linkend="updating-upgrading">update your source
	- tree</link>,
	- and your kernel modifications will be lost.</para>
	+ <para>When finished customizing the kernel configuration file,
	+ save a backup copy to a location outside of <filename
	+ class="directory">/usr/src</filename>. Do not edit
	+ <filename>GENERIC</filename> directly.</para>

	- <para>You might want to keep your kernel configuration file
	- elsewhere, and then create a symbolic link to the file in
	- the <filename><replaceable>i386</replaceable></filename>
	- directory.</para>
	+ <para>Alternately, keep the kernel configuration file elsewhere
	+ and create a symbolic link to the file in <filename
	+ class="directory"><replaceable>i386</replaceable></filename>.</para>

	<para>For example:</para>

	<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
	&prompt.root; <userinput>mkdir /root/kernels</userinput>
	&prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput>
	&prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
	</tip>

	- <para>Now, edit
	+ <para>Edit
	<filename><replaceable>MYKERNEL</replaceable></filename>
	- with your favorite text editor. If you are just starting out,
	- the only editor available will probably be
	- <application>vi</application>, which is too complex to explain
	- here, but is covered well in many books in the <link
	- linkend="bibliography">bibliography</link>. However, &os;
	- does offer an easier editor called <application>ee</application>
	- which, if you are a beginner, should be your editor of choice.
	- Feel free to change the comment lines at the top to reflect
	- your configuration or the changes you have made to differentiate
	+ with a text editor. The default editor is
	+ <application>vi</application>, whose usage is covered well in
	+ many books in the <link
	+ linkend="bibliography">bibliography</link>. An easier editor
	+ for beginners, called <application>ee</application>, is also
	+ available. Feel free to change the comment lines at the top to
	+ reflect the configuration or the changes made to differentiate
	it from <filename>GENERIC</filename>.</para>
	- <indexterm><primary>SunOS</primary></indexterm>

	- <para>If you have built a kernel under &sunos; or some other BSD
	- operating system, much of this file will be very familiar to
	- you. If you are coming from some other operating system such
	- as DOS, on the other hand, the <filename>GENERIC</filename>
	- configuration file might seem overwhelming to you, so follow
	- the descriptions in the
	- <link linkend="kernelconfig-config">Configuration File</link>
	+ <para>If the <filename>GENERIC</filename> configuration file seems
	+ overwhelming, follow the descriptions in the <link
	+ linkend="kernelconfig-config">Configuration File</link>
	section slowly and carefully.</para>

	<note>
	- <para>If you <link
	- linkend="updating-upgrading">sync your source tree</link>
	- with the latest sources of the &os; project, be sure to always
	- check the file <filename>/usr/src/UPDATING</filename> before
	- you perform any update steps. This file describes any
	+ <para>After <link linkend="svn">syncing the source tree</link>
	+ with the latest sources, <emphasis>always</emphasis> read
	+ <filename class="directory">/usr/src/UPDATING</filename>
	+ before performing any update steps. This file describes any
	important issues or areas requiring special attention within
	the updated source code.
	<filename>/usr/src/UPDATING</filename> always matches
	- your version of the &os; source, and is therefore more up
	- to date with new information than this handbook.</para>
	+ the version of the &os; source and contains more up-to-date
	+ information than this Handbook.</para>
	</note>

	- <para>You must now compile the source code for the kernel.</para>
	+ <para>After saving the edits, compile the source code for the
	+ kernel.</para>

	<procedure>
	<title>Building a Kernel</title>

	<note>
	<para>It is required to have the full &os; source tree
	installed to build the kernel.</para>
	</note>

	<step>
	- <para>Change to the <filename
	- class="directory">/usr/src</filename> directory:</para>
	+ <para><command>cd</command> to <filename
	+ class="directory">/usr/src</filename>:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
	</step>

	<step>
	- <para>Compile the kernel:</para>
	+ <para>Compile the new kernel by specifying the name of the
	+ custom kernel configuration file:</para>

	<screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
	</step>

	<step>
	<para>Install the new kernel:</para>

	<screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
	</step>
	</procedure>

	<tip>
	- <para>By default, when you build a custom kernel,
	- <emphasis>all</emphasis> kernel modules will be rebuilt as
	- well. If you want to update a kernel faster or to build only
	- custom modules, you should edit
	- <filename>/etc/make.conf</filename> before starting to build
	- the kernel:</para>
	+ <para>By default, when a custom kernel is compiled,
	+ <emphasis>all</emphasis> kernel modules are rebuilt as well.
	+ To update a kernel faster or to build only custom modules,
	+ edit <filename>/etc/make.conf</filename> before starting to
	+ build the kernel:</para>

	<programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting>

	- <para>This variable sets up a list of modules to build instead
	- of all of them.</para>
	+ <para>This variable specifies the list of modules to build
	+ instead the default of building of all of them.</para>

	<programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting>

	<para>This variable sets up a list of top level modules to
	- exclude from the build process. For other variables which
	- you may find useful in the process of building kernel, refer
	- to &man.make.conf.5; manual page.</para>
	+ exclude from the build process. For other available
	+ variables, refer to &man.make.conf.5;.</para>
	</tip>

	<indexterm>
	- <primary><filename class="directory">/boot/kernel.old</filename></primary>
	+ <primary><filename
	+ class="directory">/boot/kernel.old</filename></primary>
	</indexterm>

	- <para>The new kernel will be copied to the <filename
	- class="directory">/boot/kernel</filename> directory as
	+ <para>The new kernel will be copied to <filename
	+ class="directory">/boot/kernel</filename> as
	<filename>/boot/kernel/kernel</filename> and the old kernel
	will be moved to <filename>/boot/kernel.old/kernel</filename>.
	- Now, shutdown the system and reboot to use your new kernel.
	- If something goes wrong, there are some <link
	+ Now, shutdown the system and reboot into the new kernel.
	+ If something goes wrong, refer to the <link
	linkend="kernelconfig-trouble">troubleshooting</link>
	- instructions at the end of this chapter that you may find
	- useful. Be sure to read the section which explains how to
	- recover in case your new kernel <link
	+ instructions and the section which explains how to
	+ recover when the new kernel <link
	linkend="kernelconfig-noboot">does not boot</link>.</para>

	<note>
	<para>Other files relating to the boot process, such as the boot
	- &man.loader.8; and configuration are stored in
	- <filename>/boot</filename>. Third party or custom modules
	- can be placed in <filename
	- class="directory">/boot/kernel</filename>,
	- although users should be aware that keeping modules in sync
	- with the compiled kernel is very important. Modules not
	- intended to run with the compiled kernel may result in
	- instability or incorrectness.</para>
	+ &man.loader.8; and configuration, are stored in <filename
	+ class="directory">/boot</filename>. Third party or
	+ custom modules can be placed in <filename
	+ class="directory">/boot/kernel</filename>, although users
	+ should be aware that keeping modules in sync with the compiled
	+ kernel is very important. Modules not intended to run with
	+ the compiled kernel may result in instability.</para>
	</note>
	</sect1>

	<sect1 id="kernelconfig-config">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Joel</firstname>
	<surname>Dahl</surname>
	<contrib>Updated by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>The Configuration File</title>

	<indexterm>
	<primary>kernel</primary>
	<secondary>NOTES</secondary>
	</indexterm>
	<indexterm><primary>NOTES</primary></indexterm>
	<indexterm>
	<primary>kernel</primary>
	<secondary>configuration file</secondary>
	</indexterm>

	<para>The general format of a configuration file is quite simple.
	Each line contains a keyword and one or more arguments. For
	simplicity, most lines only contain one argument. Anything
	following a <literal>#</literal> is considered a comment and
	ignored. The following sections describe each keyword, in
	the order they are listed in <filename>GENERIC</filename>.
	- <anchor
	- id="kernelconfig-options"/> For an exhaustive list of
	- architecture dependent options and devices, see the
	- <filename>NOTES</filename> file in the same directory as the
	- <filename>GENERIC</filename> file. For architecture independent
	- options, see
	+ For an exhaustive list of architecture dependent options and
	+ devices, refer to <filename>NOTES</filename> in the same
	+ directory as <filename>GENERIC</filename> for that architecture.
	+ For architecture independent options, refer to
	<filename>/usr/src/sys/conf/NOTES</filename>.</para>

	- <para>An <literal>include</literal> directive is
	- available for use in configuration files. This allows another
	- configuration file to be logically included in the current
	- one, making it easy to maintain small changes relative to an
	- existing file. For example, if you require a
	- <filename>GENERIC</filename> kernel with only a small number
	- of additional options or drivers, this allows you to maintain
	- only a delta with respect to GENERIC:</para>
	+ <para>An <literal>include</literal> directive is available for use
	+ in configuration files. This allows another configuration file
	+ to be included in the current one, making it easy to maintain
	+ small changes relative to an existing file. For example, if
	+ only a small number of additional options or drivers are
	+ required, this allows a delta to be maintained with respect
	+ to GENERIC:</para>

	<programlisting>include GENERIC
	ident MYKERNEL

	options IPFIREWALL
	options DUMMYNET
	options IPFIREWALL_DEFAULT_TO_ACCEPT
	options IPDIVERT</programlisting>

	- <para>Many administrators will find that this model offers
	- significant benefits over the historic writing of configuration
	- files from scratch: the local configuration file will express
	- only local differences from a <filename>GENERIC</filename>
	- kernel and as upgrades are performed, new features added to
	- <filename>GENERIC</filename> will be added to the local kernel
	- unless specifically prevented using
	+ <para>Using this method, the local configuration file expresses
	+ local differences from a <filename>GENERIC</filename>
	+ kernel. As upgrades are performed, new features added to
	+ <filename>GENERIC</filename> will be also be added to the local
	+ kernel unless they are specifically prevented using
	<literal>nooptions</literal> or <literal>nodevice</literal>.
	The remainder of this chapter addresses the contents of a
	typical configuration file and the role various options and
	devices play.</para>

	<note>
	<para>To build a file which contains all available options,
	- as normally done for testing purposes, run the following
	- command as <username>root</username>:</para>
	+ run the following command as <username>root</username>:</para>

	<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf && make LINT</userinput></screen>
	</note>

	<indexterm>
	<primary>kernel</primary>
	<secondary>configuration file</secondary>
	</indexterm>

	<para>The following is an example of the
	<filename>GENERIC</filename> kernel configuration file with
	various additional comments where needed for clarity. This
	- example should match your copy in
	+ example should match the copy in
	<filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/GENERIC</filename>
	fairly closely.</para>

	<indexterm>
	<primary>kernel options</primary>
	<secondary>machine</secondary>
	</indexterm>

	<programlisting>machine i386</programlisting>

	<para>This is the machine architecture. It must be either
	- <literal>amd64</literal>,
	- <literal>i386</literal>, <literal>ia64</literal>,
	- <literal>pc98</literal>, <literal>powerpc</literal>, or
	+ <literal>amd64</literal>, <literal>i386</literal>,
	+ <literal>ia64</literal>, <literal>pc98</literal>,
	+ <literal>powerpc</literal>, or
	<literal>sparc64</literal>.</para>

	<indexterm>
	<primary>kernel options</primary>
	<secondary>cpu</secondary>
	</indexterm>
	<programlisting>cpu I486_CPU
	cpu I586_CPU
	cpu I686_CPU</programlisting>

	- <para>The above option specifies the type of CPU you have in your
	- system. You may have multiple instances of the CPU line (if,
	- for example, you are not sure whether you should use
	- <literal>I586_CPU</literal> or <literal>I686_CPU</literal>),
	- but for a custom kernel it is best to specify only the CPU
	- you have. If you are unsure of your CPU type, you can check
	- the <filename>/var/run/dmesg.boot</filename> file to view your
	- boot messages.</para>
	+ <para>This option specifies the type of CPU. It is fine to have
	+ multiple instances of the CPU entries, but for a custom kernel
	+ it is best to specify the CPU. To determine the CPU type,
	+ review the boot messages in
	+ <filename>/var/run/dmesg.boot</filename>.</para>

	<indexterm>
	<primary>kernel options</primary>
	<secondary>ident</secondary>
	</indexterm>

	<programlisting>ident GENERIC</programlisting>

	- <para>This is the identification of the kernel. You should change
	- this to whatever you named your kernel,
	- i.e., <literal><replaceable>MYKERNEL</replaceable></literal>
	- if you have followed the instructions of the previous examples.
	- The value you put in the <literal>ident</literal> string will
	- print when you boot up the kernel, so it is useful to give the
	- new kernel a different name if you want to keep it separate
	- from your usual kernel (e.g., you want to build an experimental
	- kernel).</para>
	+ <para>This is the identification of the kernel. Change
	+ this to the new kernel name, such as
	+ <literal><replaceable>MYKERNEL</replaceable></literal>.
	+ The value in the <literal>ident</literal> string will
	+ print when the kernel boots.</para>

	<programlisting>#To statically compile in device wiring instead of /boot/device.hints
	#hints "GENERIC.hints" # Default places to look for devices.</programlisting>

	- <para>The &man.device.hints.5; is
	- used to configure options of the device drivers. The default
	- location that &man.loader.8; will check at boot time is
	- <filename>/boot/device.hints</filename>. Using the
	- <literal>hints</literal> option you can compile these hints
	- statically into your kernel. Then there is no need to create a
	- <filename>device.hints</filename> file in
	- <filename>/boot</filename>.</para>
	+ <para>&man.device.hints.5; is used to configure options for device
	+ drivers. The default location is
	+ <filename>/boot/device.hints</filename>. The
	+ <literal>hints</literal> option compiles these hints statically
	+ into the kernel so that there is no need to create
	+ <filename>/boot/device.hints</filename>.</para>

	<!-- XXX: Add a comment here that explains when compiling hints into
	the kernel is a good idea and why. -->

	<programlisting>makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols</programlisting>

	- <para>The normal build process of &os; includes
	- debugging information when building the kernel with the
	- <option>-g</option> option, which enables debugging
	- information when passed to &man.gcc.1;.</para>
	+ <para>This option enables debugging information when passed to
	+ &man.gcc.1;.</para>

	<programlisting>options SCHED_ULE # ULE scheduler</programlisting>

	<para>The default system scheduler for &os;. Keep this.</para>

	<programlisting>options PREEMPTION # Enable kernel thread preemption</programlisting>

	- <para>Allows threads that are in the kernel to be preempted
	- by higher priority threads. It helps with interactivity and
	- allows interrupt threads to run sooner rather than
	- waiting.</para>
	+ <para>Allows kernel threads to be preempted by higher priority
	+ threads. This helps with interactivity and allows interrupt
	+ threads to run sooner rather than waiting.</para>

	<programlisting>options INET # InterNETworking</programlisting>

	- <para>Networking support. Leave this in, even if you do not
	- plan to be connected to a network. Most programs require at
	- least loopback networking (i.e., making network connections
	- within your PC), so this is essentially mandatory.</para>
	+ <para>Networking support. This is mandatory as most programs
	+ require at least loopback networking.</para>

	<programlisting>options INET6 # IPv6 communications protocols</programlisting>

	<para>This enables the IPv6 communication protocols.</para>

	<programlisting>options FFS # Berkeley Fast Filesystem</programlisting>

	<para>This is the basic hard drive file system. Leave it in if
	- you boot from the hard disk.</para>
	+ the system boots from the hard disk.</para>

	<programlisting>options SOFTUPDATES # Enable FFS Soft Updates support</programlisting>

	- <para>This option enables Soft Updates in the kernel, this will
	- help speed up write access on the disks. Even when this
	+ <para>This option enables Soft Updates in the kernel which helps
	+ to speed up write access on the disks. Even when this
	functionality is provided by the kernel, it must be turned on
	- for specific disks. Review the output from &man.mount.8; to
	- see if Soft Updates is enabled for your system disks. If you
	- do not see the <literal>soft-updates</literal> option then you
	- will need to activate it using the &man.tunefs.8; (for existing
	- file systems) or &man.newfs.8; (for new file systems)
	- commands.</para>
	+ for specific disks. Review the output of &man.mount.8; to
	+ determine if Soft Updates is enabled. If the
	+ <literal>soft-updates</literal> option is not in the output, it
	+ can be activated using &man.tunefs.8; for existing file systems
	+ or &man.newfs.8; for new file systems.</para>

	<programlisting>options UFS_ACL # Support for access control lists</programlisting>

	- <para>This option enables kernel support
	- for access control lists. This relies on the use of extended
	+ <para>This option enables kernel support for access control lists
	+ (<acronym>ACL</acronym>s). This relies on the use of extended
	attributes and <acronym>UFS2</acronym>, and the feature is
	- described in detail in <xref linkend="fs-acl"/>.
	- <acronym>ACL</acronym>s are enabled by default and should not
	- be disabled in the kernel if they have been used previously
	- on a file system, as this will remove the access control lists,
	- changing the way files are protected in unpredictable
	- ways.</para>
	+ described in detail in <link linkend="fs-acl"></link>.
	+ <acronym>ACL</acronym>s are enabled by default and should not be
	+ disabled in the kernel if they have been used previously on a
	+ file system, as this will remove the ACLs, changing the way
	+ files are protected in unpredictable ways.</para>

	<programlisting>options UFS_DIRHASH # Improve performance on big directories</programlisting>

	<para>This option includes functionality to speed up disk
	operations on large directories, at the expense of using
	- additional memory. You would normally keep this for a large
	- server, or interactive workstation, and remove it if you are
	- using &os; on a smaller system where memory is at a premium and
	- disk access speed is less important, such as a firewall.</para>
	+ additional memory. Keep this for a large server or interactive
	+ workstation, and remove it from smaller systems where memory is
	+ at a premium and disk access speed is less important, such as a
	+ firewall.</para>

	<programlisting>options MD_ROOT # MD is a potential root device</programlisting>

	<para>This option enables support for a memory backed virtual disk
	used as a root device.</para>

	<indexterm>
	<primary>kernel options</primary>
	<secondary>NFS</secondary>
	</indexterm>
	<indexterm>
	<primary>kernel options</primary>
	<secondary>NFS_ROOT</secondary>
	</indexterm>
	<programlisting>options NFSCLIENT # Network Filesystem Client
	options NFSSERVER # Network Filesystem Server
	options NFS_ROOT # NFS usable as /, requires NFSCLIENT</programlisting>

	- <para>The network file system. Unless you plan to mount
	- partitions from a &unix; file server over TCP/IP, you can
	- comment these out.</para>
	+ <para>The network file system (<acronym>NFS</acronym>). These
	+ lines can be commented unless the system needs to mount
	+ partitions from a <acronym>NFS</acronym> file server over
	+ TCP/IP.</para>

	<indexterm>
	<primary>kernel options</primary>
	<secondary>MSDOSFS</secondary>
	</indexterm>
	<programlisting>options MSDOSFS # MSDOS Filesystem</programlisting>

	- <para>The &ms-dos; file system. Unless you plan to mount a DOS
	- formatted hard drive partition at boot time, you can safely
	- comment this out. It will be automatically loaded the first
	- time you mount a DOS partition, as described above. Also,
	- the excellent
	- <filename role="package">emulators/mtools</filename> software
	- allows you to access DOS floppies without having to mount and
	- unmount them (and does not require <literal>MSDOSFS</literal> at
	- all).</para>
	+ <para>The &ms-dos; file system. Unless the system needs to mount
	+ a DOS formatted hard drive partition at boot time, comment this
	+ out. It will be automatically loaded the first time a DOS
	+ partition is mounted. The <filename
	+ role="package">emulators/mtools</filename> package allows
	+ access to DOS floppies without having to mount and unmount
	+ them and does not require <literal>MSDOSFS</literal>.</para>

	<programlisting>options CD9660 # ISO 9660 Filesystem</programlisting>

	- <para>The ISO 9660 file system for CDROMs. Comment it out if
	- you do not have a CDROM drive or only mount data CDs
	- occasionally (since it will be dynamically loaded the first
	- time you mount a data CD). Audio CDs do not need this file
	+ <para>The ISO 9660 file system for CDROMs. Comment it out if the
	+ system does not have a CDROM drive or only mounts data CDs
	+ occasionally since it will be dynamically loaded the first
	+ time a data CD is mounted. Audio CDs do not need this file
	system.</para>

	<programlisting>options PROCFS # Process filesystem (requires PSEUDOFS)</programlisting>

	<para>The process file system. This is a <quote>pretend</quote>
	- file system mounted on <filename>/proc</filename> which allows
	- programs like &man.ps.1; to give you more information on what
	- processes are running. Use of <literal>PROCFS</literal>
	- is not required under most circumstances, as most
	- debugging and monitoring tools have been adapted to run without
	- <literal>PROCFS</literal>: installs will not mount this file
	- system by default.</para>
	+ file system mounted on <filename
	+ class="directory">/proc</filename> which allows some programs
	+ to provide more information on what processes are running. Use
	+ of <literal>PROCFS</literal> is not required under most
	+ circumstances, as most debugging and monitoring tools have been
	+ adapted to run without <literal>PROCFS</literal>. The default
	+ installation will not mount this file system by default.</para>

	<programlisting>options PSEUDOFS # Pseudo-filesystem framework</programlisting>

	<para>Kernels making use of <literal>PROCFS</literal> must
	also include support for <literal>PSEUDOFS</literal>.</para>

	<programlisting>options GEOM_PART_GPT # GUID Partition Tables.</programlisting>

	<para>Adds support for <ulink
	url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
	- Partition Tables</ulink>. GPT provides the ability to have a
	- large number of partitions per disk, 128 in the standard
	- configuration.</para>
	+ Partition Tables</ulink> (<acronym>GPT</acronym>. GPT
	+ provides the ability to have a large number of partitions per
	+ disk, 128 in the standard configuration.</para>

	<programlisting>options COMPAT_43 # Compatible with BSD 4.3 [KEEP THIS!]</programlisting>

	- <para>Compatibility with 4.3BSD. Leave this in; some programs
	- will act strangely if you comment this out.</para>
	+ <para>Compatibility with 4.3BSD. Leave this in as some programs
	+ will act strangely if this is commented out.</para>

	<programlisting>options COMPAT_FREEBSD4 # Compatible with &os;4</programlisting>

	- <para>This option is required
	- to support applications compiled on older versions of &os;
	- that use older system call interfaces. It is recommended that
	- this option be used on all &i386; systems that may
	- run older applications; platforms that gained support only in
	- 5.X, such as ia64 and &sparc64;, do not require this
	- option.</para>
	+ <para>This option is required to support applications compiled on
	+ older versions of &os; that use older system call interfaces.
	+ It is recommended that this option be used on all &i386; systems
	+ that may run older applications. Platforms that gained support
	+ after &os; 4.X, such as ia64 and &sparc64;, do not require
	+ this option.</para>

	<programlisting>options COMPAT_FREEBSD5 # Compatible with &os;5</programlisting>

	- <para>This option is required to
	- support applications compiled on &os; 5.X versions that
	- use &os; 5.X system call interfaces.</para>
	+ <para>This option is required to support applications compiled on
	+ &os; 5.X versions that use &os; 5.X system call
	+ interfaces.</para>

	<programlisting>options COMPAT_FREEBSD6 # Compatible with &os;6</programlisting>

	- <para>This option is required to
	- support applications compiled on &os; 6.X versions that
	- use &os; 6.X system call interfaces.</para>
	+ <para>This option is required to support applications compiled on
	+ &os; 6.X versions that use &os; 6.X system call
	+ interfaces.</para>

	<programlisting>options COMPAT_FREEBSD7 # Compatible with &os;7</programlisting>

	- <para>This option is required on &os; 8 and above to
	- support applications compiled on &os; 7.X versions that
	- use &os; 7.X system call interfaces.</para>
	+ <para>This option is required on &os; 8 and above to support
	+ applications compiled on &os; 7.X versions that use
	+ &os; 7.X system call interfaces.</para>

	<programlisting>options SCSI_DELAY=5000 # Delay (in ms) before probing SCSI</programlisting>

	<para>This causes the kernel to pause for 5 seconds before probing
	- each SCSI device in your system. If you only have IDE hard
	- drives, you can ignore this, otherwise you can try to lower
	- this number, to speed up booting. Of course, if you do this
	- and &os; has trouble recognizing your SCSI devices, you will
	- have to raise it again.</para>
	+ each SCSI device in the system. If the system only has IDE hard
	+ drives, ignore this or lower the number to speed up booting.
	+ However, if &os; has trouble recognizing the SCSI devices, the
	+ number will have to be raised again.</para>

	<programlisting>options KTRACE # ktrace(1) support</programlisting>

	<para>This enables kernel process tracing, which is useful in
	debugging.</para>

	<programlisting>options SYSVSHM # SYSV-style shared memory</programlisting>

	- <para>This option provides for System V shared memory.
	- The most common use of this is the XSHM extension in X, which
	- many graphics-intensive programs will automatically take
	- advantage of for extra speed. If you use X, you will definitely
	- want to include this.</para>
	+ <para>This option provides for System V shared memory. The
	+ most common use of this is the XSHM extension in X, which many
	+ graphics-intensive programs will automatically take advantage of
	+ for extra speed. If <application>Xorg</application> is
	+ installed, include this.</para>

	<programlisting>options SYSVMSG # SYSV-style message queues</programlisting>

	<para>Support for System V messages. This option only adds
	a few hundred bytes to the kernel.</para>

	<programlisting>options SYSVSEM # SYSV-style semaphores</programlisting>

	- <para>Support for System V semaphores. Less commonly used
	+ <para>Support for System V semaphores. Less commonly used,
	but only adds a few hundred bytes to the kernel.</para>

	<note>
	- <para>The <option>-p</option> option of the &man.ipcs.1;
	- command will list any processes using each of these
	- System V facilities.</para>
	+ <para>Using <option>-p</option> with &man.ipcs.1; will list any
	+ processes using each of these System V facilities.</para>
	</note>

	<programlisting>options _KPOSIX_PRIORITY_SCHEDULING # POSIX P1003_1B real-time extensions</programlisting>

	<para>Real-time extensions added in the 1993 &posix;. Certain
	- applications in the Ports Collection use these
	- (such as <application>&staroffice;</application>).</para>
	+ applications in the Ports Collection use these.</para>

	<programlisting>options KBD_INSTALL_CDEV # install a CDEV entry in /dev</programlisting>

	<para>This option is required to allow the creation of keyboard
	- device nodes in <filename>/dev</filename>.</para>
	+ device nodes in <filename
	+ class="directory">/dev</filename>.</para>

	<programlisting>options ADAPTIVE_GIANT # Giant mutex is adaptive.</programlisting>

	- <para>Giant is the name of a mutual exclusion mechanism (a
	- sleep mutex)that protects a large set of kernel resources.
	+ <para>Giant is the name of a mutual exclusion mechanism, a
	+ sleep mutex, that protects a large set of kernel resources.
	Today, this is an unacceptable performance bottleneck which
	is actively being replaced with locks that protect individual
	resources. The <literal>ADAPTIVE_GIANT</literal> option causes
	Giant to be included in the set of mutexes adaptively spun on.
	- That is, when a thread wants to lock the Giant mutex, but it
	- is already locked by a thread on another CPU, the first thread
	- will keep running and wait for the lock to be released.
	- Normally, the thread would instead go back to sleep and wait
	- for its next chance to run. If you are not sure, leave this
	- in.</para>
	+ When a thread wants to lock the Giant mutex, but it is already
	+ locked by a thread on another CPU, the first thread will keep
	+ running and wait for the lock to be released. Normally, the
	+ thread would instead go back to sleep and wait for its next
	+ chance to run. If unsure, leave this in.</para>

	<note>
	- <para>Note that on &os; 8.0-RELEASE and later versions, all
	- mutexes are adaptive by default, unless explicitly set to
	- non-adaptive by compiling with the
	- <literal>NO_ADAPTIVE_MUTEXES</literal> option. As a result,
	- Giant is adaptive by default now, and the
	+ <para>Beginning with &os; 8.0, all mutexes are adaptive by
	+ default, unless explicitly set to non-adaptive by compiling
	+ with the <literal>NO_ADAPTIVE_MUTEXES</literal> option. As a
	+ result, Giant is adaptive by default now, and the
	<literal>ADAPTIVE_GIANT</literal> option has been removed
	from the kernel configuration.</para>
	</note>

	<indexterm>
	<primary>kernel options</primary>
	<secondary>SMP</secondary>
	</indexterm>
	<programlisting>device apic # I/O APIC</programlisting>

	- <para>The apic device enables the use of the I/O APIC for
	- interrupt delivery. The apic device can be used in both UP
	- and SMP kernels, but is required for SMP kernels. Add
	- <literal>options SMP</literal> to include support for multiple
	+ <para>This device enables the use of the I/O APIC for interrupt
	+ delivery. It can be used in both uni-processor and SMP kernels,
	+ but is required for SMP kernels. Add <literal>options
	+ SMP</literal> to include support for multiple
	processors.</para>

	<note>
	- <para>The apic device exists only on the i386 architecture, this
	+ <para>This device exists only on the i386 architecture and this
	configuration line should not be used on other
	architectures.</para>
	</note>

	<programlisting>device eisa</programlisting>

	- <para>Include this if you have an EISA motherboard. This enables
	- auto-detection and configuration support for all devices on
	- the EISA bus.</para>
	+ <para>Include this for systems with an EISA motherboard. This
	+ enables auto-detection and configuration support for all devices
	+ on the EISA bus.</para>

	<programlisting>device pci</programlisting>

	- <para>Include this if you have a PCI motherboard. This enables
	- auto-detection of PCI cards and gatewaying from the PCI to ISA
	- bus.</para>
	+ <para>Include this for systems with a PCI motherboard. This
	+ enables auto-detection of PCI cards and gatewaying from the PCI
	+ to ISA bus.</para>

	<programlisting># Floppy drives
	device fdc</programlisting>

	<para>This is the floppy drive controller.</para>

	<programlisting># ATA and ATAPI devices
	device ata</programlisting>

	- <para>This driver supports all ATA and ATAPI devices. You only
	- need one <literal>device ata</literal> line for the kernel to
	- detect all PCI ATA/ATAPI devices on modern machines.</para>
	+ <para>This driver supports all ATA and ATAPI devices. Only
	+ one <literal>device ata</literal> line is needed for the kernel
	+ to detect all PCI ATA/ATAPI devices on modern machines.</para>

	<programlisting>device atadisk # ATA disk drives</programlisting>

	- <para>This is needed along with <literal>device ata</literal>
	- for ATA disk drives.</para>
	+ <para>This is needed along with <literal>device ata</literal> for
	+ ATA disk drives.</para>

	<programlisting>device ataraid # ATA RAID drives</programlisting>

	<para>This is needed along with <literal>device ata</literal>
	for ATA RAID drives.</para>

	<programlisting><anchor id="kernelconfig-atapi"/>
	device atapicd # ATAPI CDROM drives</programlisting>

	<para>This is needed along with <literal>device ata</literal>
	for ATAPI CDROM drives.</para>

	<programlisting>device atapifd # ATAPI floppy drives</programlisting>

	- <para>This is needed along with <literal>device ata</literal>
	- for ATAPI floppy drives.</para>
	+ <para>This is needed along with <literal>device ata</literal> for
	+ ATAPI floppy drives.</para>

	<programlisting>device atapist # ATAPI tape drives</programlisting>

	- <para>This is needed along with <literal>device ata</literal>
	- for ATAPI tape drives.</para>
	+ <para>This is needed along with <literal>device ata</literal> for
	+ ATAPI tape drives.</para>

	<programlisting>options ATA_STATIC_ID # Static device numbering</programlisting>

	- <para>This makes the controller number static; without this,
	- the device numbers are dynamically allocated.</para>
	+ <para>This makes the controller number static. Without this, the
	+ device numbers are dynamically allocated.</para>

	<programlisting># SCSI Controllers
	device ahb # EISA AHA1742 family
	device ahc # AHA2940 and onboard AIC7xxx devices
	options AHC_REG_PRETTY_PRINT # Print register bitfields in debug
	# output. Adds ~128k to driver.
	device ahd # AHA39320/29320 and onboard AIC79xx devices
	options AHD_REG_PRETTY_PRINT # Print register bitfields in debug
	# output. Adds ~215k to driver.
	device amd # AMD 53C974 (Teckram DC-390(T))
	device isp # Qlogic family
	#device ispfw # Firmware for QLogic HBAs- normally a module
	device mpt # LSI-Logic MPT-Fusion
	#device ncr # NCR/Symbios Logic
	device sym # NCR/Symbios Logic (newer chipsets + those of `ncr')
	device trm # Tekram DC395U/UW/F DC315U adapters

	device adv # Advansys SCSI adapters
	device adw # Advansys wide SCSI adapters
	device aha # Adaptec 154x SCSI adapters
	device aic # Adaptec 15[012]x SCSI adapters, AIC-6[23]60.
	device bt # Buslogic/Mylex MultiMaster SCSI adapters

	device ncv # NCR 53C500
	device nsp # Workbit Ninja SCSI-3
	device stg # TMC 18C30/18C50</programlisting>

	- <para>SCSI controllers. Comment out any you do not have in your
	- system. If you have an IDE only system, you can remove these
	- altogether. The <literal>*_REG_PRETTY_PRINT</literal> lines are
	+ <para>In this section, comment out any SCSI controllers not on
	+ the system. For an IDE only system, these lines can be removed.
	+ The <literal>*_REG_PRETTY_PRINT</literal> lines are
	debugging options for their respective drivers.</para>

	<programlisting># SCSI peripherals
	device scbus # SCSI bus (required for SCSI)
	device ch # SCSI media changers
	device da # Direct Access (disks)
	device sa # Sequential Access (tape etc)
	device cd # CD
	device pass # Passthrough device (direct SCSI access)
	device ses # SCSI Environmental Services (and SAF-TE)</programlisting>

	- <para>SCSI peripherals. Again, comment out any you do not have,
	- or if you have only IDE hardware, you can remove them
	+ <para>Comment out any SCSI peripherals not on the system. If
	+ the system only has IDE hardware, these lines can be removed
	completely.</para>

	<note>
	<para>The USB &man.umass.4; driver and a few other drivers use
	the SCSI subsystem even though they are not real SCSI devices.
	- Therefore make sure not to remove SCSI support, if any such
	- drivers are included in the kernel configuration.</para>
	+ Do not remove SCSI support if any such drivers are included in
	+ the kernel configuration.</para>
	</note>

	<programlisting># RAID controllers interfaced to the SCSI subsystem
	device amr # AMI MegaRAID
	device arcmsr # Areca SATA II RAID
	device asr # DPT SmartRAID V, VI and Adaptec SCSI RAID
	device ciss # Compaq Smart RAID 5*
	device dpt # DPT Smartcache III, IV - See NOTES for options
	device hptmv # Highpoint RocketRAID 182x
	device hptrr # Highpoint RocketRAID 17xx, 22xx, 23xx, 25xx
	device iir # Intel Integrated RAID
	device ips # IBM (Adaptec) ServeRAID
	device mly # Mylex AcceleRAID/eXtremeRAID
	device twa # 3ware 9000 series PATA/SATA RAID

	# RAID controllers
	device aac # Adaptec FSA RAID
	device aacp # SCSI passthrough for aac (requires CAM)
	device ida # Compaq Smart RAID
	device mfi # LSI MegaRAID SAS
	device mlx # Mylex DAC960 family
	device pst # Promise Supertrak SX6000
	device twe # 3ware ATA RAID</programlisting>

	- <para>Supported RAID controllers. If you do not have any of
	- these, you can comment them out or remove them.</para>
	+ <para>Supported RAID controllers. If the system does not have any
	+ of these, comment them out or remove them.</para>

	<programlisting># atkbdc0 controls both the keyboard and the PS/2 mouse
	device atkbdc # AT keyboard controller</programlisting>

	- <para>The keyboard controller (<literal>atkbdc</literal>)
	- provides I/O services for the AT keyboard and PS/2 style
	- pointing devices. This controller is required by the keyboard
	- driver (<literal>atkbd</literal>) and the PS/2 pointing device
	- driver (<literal>psm</literal>).</para>
	+ <para>The <literal>atkbdc</literal> keyboard controller provides
	+ I/O services for the AT keyboard and PS/2 style pointing
	+ devices. This controller is required by &man.atkbd.4; and
	+ &man.psm.4;.</para>

	<programlisting>device atkbd # AT keyboard</programlisting>

	- <para>The <literal>atkbd</literal> driver, together with
	- <literal>atkbdc</literal> controller, provides access to the
	- AT 84 keyboard or the AT enhanced keyboard which is connected
	- to the AT keyboard controller.</para>
	+ <para>The &man.atkbd.4; driver, together with the &man.atkbdc.4;
	+ controller, provides access to the AT 84 keyboard or the AT
	+ enhanced keyboard which is connected to the AT keyboard
	+ controller.</para>

	<programlisting>device psm # PS/2 mouse</programlisting>

	- <para>Use this device if your mouse plugs into the PS/2 mouse
	+ <para>Use this device if the mouse plugs into the PS/2 mouse
	port.</para>

	<programlisting>device kbdmux # keyboard multiplexer</programlisting>

	- <para>Basic support for keyboard multiplexing. If you do not
	- plan to use more than one keyboard on the system, you can
	- safely remove that line.</para>
	+ <para>Basic support for keyboard multiplexing. If the system
	+ does not use more than one keyboard, this line can be safely
	+ removed.</para>

	<programlisting>device vga # VGA video card driver</programlisting>

	- <para>The video card driver.</para>
	+ <para>The &man.vga.4; video card driver.</para>

	<programlisting>
	device splash # Splash screen and screen saver support</programlisting>

	- <para>Splash screen at start up! Screen savers require this
	- too.</para>
	+ <para>Required by the boot splash screen and screen savers.</para>

	<programlisting># syscons is the default console driver, resembling an SCO console
	device sc</programlisting>

	- <para><literal>sc</literal> is the default console driver and
	- resembles a SCO console. Since most full-screen programs
	- access the console through a terminal database library like
	+ <para>&man.sc.4; is the default console driver and resembles a SCO
	+ console. Since most full-screen programs access the console
	+ through a terminal database library like
	<filename>termcap</filename>, it should not matter whether
	- you use this or <literal>vt</literal>, the
	- <literal>VT220</literal> compatible console driver. When you
	- log in, set your <envar>TERM</envar> variable to
	- <literal>scoansi</literal> if full-screen programs have trouble
	- running under this console.</para>
	+ this or <literal>vt</literal>, the
	+ <literal>VT220</literal> compatible console driver, is used.
	+ When a user logs in, the <envar>TERM</envar> variable can be set
	+ to <literal>scoansi</literal> if full-screen programs have
	+ trouble running under this console.</para>

	<programlisting># Enable this for the pcvt (VT220 compatible) console driver
	#device vt
	#options XSERVER # support for X server on a vt console
	#options FAT_CURSOR # start with block cursor</programlisting>

	<para>This is a VT220-compatible console driver, backward
	compatible to VT100/102. It works well on some laptops which
	have hardware incompatibilities with <literal>sc</literal>.
	- Also set your <envar>TERM</envar> variable to
	- <literal>vt100</literal> or <literal>vt220</literal> when you
	- log in. This driver might also prove useful when connecting
	- to a large number of different machines over the network, where
	+ Users may need to set <envar>TERM</envar> to
	+ <literal>vt100</literal> or <literal>vt220</literal> after
	+ login. This driver is useful when connecting to a large number
	+ of different machines over the network, where
	<filename>termcap</filename> or <filename>terminfo</filename>
	- entries for the <literal>sc</literal> device are often not
	- available — <literal>vt100</literal> should be available
	+ entries for the <literal>sc</literal> device are not
	+ available as <literal>vt100</literal> should be available
	on virtually any platform.</para>

	<programlisting>device agp</programlisting>

	- <para>Include this if you have an AGP card in the system. This
	- will enable support for AGP, and AGP GART for boards which
	- have these features.</para>
	+ <para>Include this if the system has an AGP card. This will
	+ enable support for AGP and AGP GART for boards which have these
	+ features.</para>

	- <indexterm>
	- <primary>APM</primary>
	- </indexterm>
	-
	- <programlisting># Power management support (see NOTES for more options)
	-#device apm</programlisting>
	-
	- <para>Advanced Power Management support. Useful for laptops,
	- although this is disabled in
	- <filename>GENERIC</filename> by default.</para>
	-
	<programlisting># Add suspend/resume support for the i8254.
	device pmtimer</programlisting>

	<para>Timer device driver for power management events, such as
	APM and ACPI.</para>

	<programlisting># PCCARD (PCMCIA) support
	# PCMCIA and cardbus bridge support
	device cbb # cardbus (yenta) bridge
	device pccard # PC Card (16-bit) bus
	device cardbus # CardBus (32-bit) bus</programlisting>

	- <para>PCMCIA support. You want this if you are using a
	- laptop.</para>
	+ <para>PCMCIA support. Keep this on laptop systems.</para>

	<programlisting># Serial (COM) ports
	device sio # 8250, 16[45]50 based serial ports</programlisting>

	<para>These are the serial ports referred to as
	- <devicename>COM</devicename> ports in the &ms-dos;/&windows;
	- world.</para>
	+ <devicename>COM</devicename> ports in &windows;.</para>

	<note>
	- <para>If you have an internal modem on
	+ <para>If the system has an internal modem on
	<devicename>COM4</devicename> and a serial port at
	- <devicename>COM2</devicename>, you will have to change the
	- IRQ of the modem to 2 (for obscure technical reasons,
	- IRQ2 = IRQ 9) in order to access it from &os;. If you have
	- a multiport serial card, check the manual page for &man.sio.4;
	- for more information on the proper values to add to your
	- <filename>/boot/device.hints</filename>. Some video cards
	- (notably those based on S3 chips) use IO addresses in the
	- form of <literal>0x*2e8</literal>, and since many cheap serial
	- cards do not fully decode the 16-bit IO address space, they
	- clash with these cards making the
	+ <devicename>COM2</devicename>, change the IRQ of the modem to
	+ 2. For a multiport serial card, refer to &man.sio.4; for more
	+ information on the proper values to add to
	+ <filename>/boot/device.hints</filename>. Some video cards,
	+ notably those based on S3 chips, use I/O addresses in the
	+ form of <literal>0x*2e8</literal>. Since many cheap serial
	+ cards do not fully decode the 16-bit I/O address space, they
	+ clash with these cards, making the
	<devicename>COM4</devicename> port practically
	unavailable.</para>

	- <para>Each serial port is required to have a unique IRQ
	- (unless you are using one of the multiport cards where shared
	- interrupts are supported), so the default IRQs for
	- <devicename>COM3</devicename> and
	- <devicename>COM4</devicename> cannot be used.</para>
	+ <para>Each serial port is required to have a unique IRQ and the
	+ default IRQs for <devicename>COM3</devicename> and
	+ <devicename>COM4</devicename> cannot be used. The exception
	+ is multiport cards where shared interrupts are
	+ supported.</para>
	</note>

	<programlisting># Parallel port
	device ppc</programlisting>

	- <para>This is the ISA-bus parallel port interface.</para>
	+ <para>This is the ISA bus parallel port interface.</para>

	<programlisting>device ppbus # Parallel port bus (required)</programlisting>

	<para>Provides support for the parallel port bus.</para>

	<programlisting>device lpt # Printer</programlisting>

	- <para>Support for parallel port printers.</para>
	+ <para>Adds support for parallel port printers.</para>

	<note>
	<para>All three of the above are required to enable parallel
	printer support.</para>
	</note>

	<programlisting>device ppi # Parallel port interface device</programlisting>

	<para>The general-purpose I/O (<quote>geek port</quote>) +
	IEEE1284 I/O.</para>

	<programlisting>#device vpo # Requires scbus and da</programlisting>

	<indexterm><primary>zip drive</primary></indexterm>
	<para>This is for an Iomega Zip drive. It requires
	<literal>scbus</literal> and <literal>da</literal> support.
	Best performance is achieved with ports in EPP 1.9 mode.</para>

	<programlisting>#device puc</programlisting>

	- <para>Uncomment this device if you have a <quote>dumb</quote>
	- serial or parallel PCI card that is supported by the &man.puc.4;
	- glue driver.</para>
	+ <para>Uncomment this device if the system has a
	+ <quote>dumb</quote> serial or parallel PCI card that is
	+ supported by the &man.puc.4; glue driver.</para>

	<programlisting># PCI Ethernet NICs.
	device de # DEC/Intel DC21x4x (<quote>Tulip</quote>)
	device em # Intel PRO/1000 adapter Gigabit Ethernet Card
	device ixgb # Intel PRO/10GbE Ethernet Card
	device txp # 3Com 3cR990 (<quote>Typhoon</quote>)
	device vx # 3Com 3c590, 3c595 (<quote>Vortex</quote>)</programlisting>

	<para>Various PCI network card drivers. Comment out or remove
	- any of these not present in your system.</para>
	+ any of these which are not present in the system.</para>

	<programlisting># PCI Ethernet NICs that use the common MII bus controller code.
	# NOTE: Be sure to keep the 'device miibus' line in order to use these NICs!
	device miibus # MII bus support</programlisting>

	<para>MII bus support is required for some PCI 10/100 Ethernet
	NICs, namely those which use MII-compliant transceivers or
	implement transceiver control interfaces that operate like an
	MII. Adding <literal>device miibus</literal> to the kernel
	config pulls in support for the generic miibus API and all of
	the PHY drivers, including a generic one for PHYs that are not
	specifically handled by an individual driver.</para>

	<programlisting>device bce # Broadcom BCM5706/BCM5708 Gigabit Ethernet
	device bfe # Broadcom BCM440x 10/100 Ethernet
	device bge # Broadcom BCM570xx Gigabit Ethernet
	device dc # DEC/Intel 21143 and various workalikes
	device fxp # Intel EtherExpress PRO/100B (82557, 82558)
	device lge # Level 1 LXT1001 gigabit ethernet
	device msk # Marvell/SysKonnect Yukon II Gigabit Ethernet
	device nge # NatSemi DP83820 gigabit ethernet
	device nve # nVidia nForce MCP on-board Ethernet Networking
	device pcn # AMD Am79C97x PCI 10/100 (precedence over 'lnc')
	device re # RealTek 8139C+/8169/8169S/8110S
	device rl # RealTek 8129/8139
	device sf # Adaptec AIC-6915 (<quote>Starfire</quote>)
	device sis # Silicon Integrated Systems SiS 900/SiS 7016
	device sk # SysKonnect SK-984x & SK-982x gigabit Ethernet
	device ste # Sundance ST201 (D-Link DFE-550TX)
	device stge # Sundance/Tamarack TC9021 gigabit Ethernet
	device ti # Alteon Networks Tigon I/II gigabit Ethernet
	device tl # Texas Instruments ThunderLAN
	device tx # SMC EtherPower II (83c170 <quote>EPIC</quote>)
	device vge # VIA VT612x gigabit ethernet
	device vr # VIA Rhine, Rhine II
	device wb # Winbond W89C840F
	device xl # 3Com 3c90x (<quote>Boomerang</quote>, <quote>Cyclone</quote>)</programlisting>

	<para>Drivers that use the MII bus controller code.</para>

	<programlisting># ISA Ethernet NICs. pccard NICs included.
	device cs # Crystal Semiconductor CS89x0 NIC
	# 'device ed' requires 'device miibus'
	device ed # NE[12]000, SMC Ultra, 3c503, DS8390 cards
	device ex # Intel EtherExpress Pro/10 and Pro/10+
	device ep # Etherlink III based cards
	device fe # Fujitsu MB8696x based cards
	device ie # EtherExpress 8/16, 3C507, StarLAN 10 etc.
	device lnc # NE2100, NE32-VL Lance Ethernet cards
	device sn # SMC's 9000 series of Ethernet chips
	device xe # Xircom pccard Ethernet

	# ISA devices that use the old ISA shims
	#device le</programlisting>

	<para>ISA Ethernet drivers. See
	<filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/NOTES</filename>
	for details of which cards are supported by which driver.</para>

	<programlisting># Wireless NIC cards
	device wlan # 802.11 support</programlisting>

	<para>Generic 802.11 support. This line is required for wireless
	networking.</para>

	<programlisting>device wlan_wep # 802.11 WEP support
	device wlan_ccmp # 802.11 CCMP support
	device wlan_tkip # 802.11 TKIP support</programlisting>

	<para>Crypto support for 802.11 devices. These lines are needed
	- if you intend to use encryption and 802.11i security
	+ on systems which use encryption and 802.11i security
	protocols.</para>

	<programlisting>device an # Aironet 4500/4800 802.11 wireless NICs.
	device ath # Atheros pci/cardbus NIC's
	device ath_hal # Atheros HAL (Hardware Access Layer)
	device ath_rate_sample # SampleRate tx rate control for ath
	device awi # BayStack 660 and others
	device ral # Ralink Technology RT2500 wireless NICs.
	device wi # WaveLAN/Intersil/Symbol 802.11 wireless NICs.
	#device wl # Older non 802.11 Wavelan wireless NIC.</programlisting>

	<para>Support for various wireless cards.</para>

	<programlisting># Pseudo devices
	device loop # Network loopback</programlisting>

	- <para>This is the generic loopback device for TCP/IP. If you
	- telnet or FTP to <hostid>localhost</hostid> (aka <hostid
	- role="ipaddr">127.0.0.1</hostid>) it will come back at you
	- through this device. This is
	+ <para>This is the generic loopback device for TCP/IP. This is
	<emphasis>mandatory</emphasis>.</para>

	<programlisting>device random # Entropy device</programlisting>

	<para>Cryptographically secure random number generator.</para>

	<programlisting>device ether # Ethernet support</programlisting>

	- <para><literal>ether</literal> is only needed if you have an
	- Ethernet card. It includes generic Ethernet protocol
	+ <para><literal>ether</literal> is only needed if the system has
	+ an Ethernet card. It includes generic Ethernet protocol
	code.</para>

	<programlisting>device sl # Kernel SLIP</programlisting>

	- <para><literal>sl</literal> is for SLIP support. This has been
	+ <para><literal>sl</literal> provides SLIP support. This has been
	almost entirely supplanted by PPP, which is easier to set up,
	better suited for modem-to-modem connection, and more
	powerful.</para>

	<programlisting>device ppp # Kernel PPP</programlisting>

	<para>This is for kernel PPP support for dial-up connections.
	There is also a version of PPP implemented as a userland
	application that uses <literal>tun</literal> and offers more
	flexibility and features such as demand dialing.</para>

	<programlisting>device tun # Packet tunnel.</programlisting>

	- <para>This is used by the userland PPP software.
	- See
	- the <link linkend="userppp">PPP</link> section of this book
	- for more information.</para>
	+ <para>This is used by the userland PPP software. See the <link
	+ linkend="userppp">PPP</link> section of the Handbook for more
	+ information.</para>

	<programlisting><anchor id="kernelconfig-ptys"/>
	device pty # Pseudo-ttys (telnet etc)</programlisting>

	<para>This is a <quote>pseudo-terminal</quote> or simulated
	login port. It is used by incoming <command>telnet</command>
	and <command>rlogin</command> sessions,
	<application>xterm</application>, and some other applications
	such as <application>Emacs</application>.</para>

	<programlisting>device md # Memory <quote>disks</quote></programlisting>

	<para>Memory disk pseudo-devices.</para>

	<programlisting>device gif # IPv6 and IPv4 tunneling</programlisting>

	<para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6
	tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6
	tunneling. The <literal>gif</literal> device is
	<quote>auto-cloning</quote>, and will create device nodes as
	needed.</para>

	<programlisting>device faith # IPv6-to-IPv4 relaying (translation)</programlisting>

	<para>This pseudo-device captures packets that are sent to it and
	diverts them to the IPv4/IPv6 translation daemon.</para>

	<programlisting># The `bpf' device enables the Berkeley Packet Filter.
	# Be aware of the administrative consequences of enabling this!
	# Note that 'bpf' is required for DHCP.
	device bpf # Berkeley packet filter</programlisting>

	- <para>This is the Berkeley Packet Filter. This pseudo-device
	- allows network interfaces to be placed in promiscuous mode,
	- capturing every packet on a broadcast network (e.g., an
	- Ethernet). These packets can be captured to disk and or
	- examined with the &man.tcpdump.1; program.</para>
	+ <para>The Berkeley Packet Filter pseudo-device allows network
	+ interfaces to be placed in promiscuous mode, capturing every
	+ packet on a broadcast network such as an Ethernet network.
	+ These packets can be captured to disk and or examined using
	+ &man.tcpdump.1;.</para>

	<note>
	- <para>The &man.bpf.4; device is also used by
	- &man.dhclient.8; to obtain the IP address of the default
	- router (gateway) and so on. If you use DHCP, leave this
	- uncommented.</para>
	+ <para>The &man.bpf.4; device is also used by &man.dhclient.8;.
	+ If DHCP is used, leave this uncommented.</para>
	</note>

	<programlisting># USB support
	device uhci # UHCI PCI->USB interface
	device ohci # OHCI PCI->USB interface
	device ehci # EHCI PCI->USB interface (USB 2.0)
	device usb # USB Bus (required)
	#device udbp # USB Double Bulk Pipe devices
	device ugen # Generic
	device uhid # <quote>Human Interface Devices</quote>
	device ukbd # Keyboard
	device ulpt # Printer
	device umass # Disks/Mass storage - Requires scbus and da
	device ums # Mouse
	device ural # Ralink Technology RT2500USB wireless NICs
	device urio # Diamond Rio 500 MP3 player
	device uscanner # Scanners
	# USB Ethernet, requires mii
	device aue # ADMtek USB Ethernet
	device axe # ASIX Electronics USB Ethernet
	device cdce # Generic USB over Ethernet
	device cue # CATC USB Ethernet
	device kue # Kawasaki LSI USB Ethernet
	device rue # RealTek RTL8150 USB Ethernet</programlisting>

	<para>Support for various USB devices.</para>

	<programlisting># FireWire support
	device firewire # FireWire bus code
	device sbp # SCSI over FireWire (Requires scbus and da)
	device fwe # Ethernet over FireWire (non-standard!)</programlisting>

	<para>Support for various Firewire devices.</para>

	<para>For more information and additional devices supported by
	&os;, see
	<filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/NOTES</filename>.</para>

	<sect2>
	- <title>Large Memory Configurations (<acronym>PAE</acronym>)</title>
	+ <title>Large Memory Configurations
	+ (<acronym>PAE</acronym>)</title>

	<indexterm>
	<primary>Physical Address Extensions
	(<acronym>PAE</acronym>)</primary>
	<secondary>large memory</secondary>
	</indexterm>

	- <para>Large memory configuration machines require access to
	- more than the 4 gigabyte limit on User+Kernel Virtual
	- Address (<acronym>KVA</acronym>) space. Due to this
	- limitation, Intel added support for 36-bit physical address
	- space access in the &pentium; Pro and later line of
	- CPUs.</para>
	+ <para>Large memory configuration machines require access to
	+ more than the 4 gigabyte limit on User+Kernel Virtual
	+ Address (<acronym>KVA</acronym>) space. Due to this
	+ limitation, Intel added support for 36-bit physical address
	+ space access in the &pentium; Pro and later line of
	+ CPUs.</para>

	- <para>The Physical Address Extension (<acronym>PAE</acronym>)
	- capability of the &intel; &pentium; Pro and later CPUs
	- allows memory configurations of up to 64 gigabytes.
	- &os; provides support for this capability via the
	- <option>PAE</option> kernel configuration option, available
	- in all current release versions of &os;. Due to
	- the limitations of the Intel memory architecture, no
	- distinction is made for memory above or below 4 gigabytes.
	- Memory allocated above 4 gigabytes is simply added to the
	- pool of available memory.</para>
	+ <para>The Physical Address Extension (<acronym>PAE</acronym>)
	+ capability of the &intel; &pentium; Pro and later CPUs allows
	+ memory configurations of up to 64 gigabytes. &os; provides
	+ support for this capability via the <option>PAE</option>
	+ kernel configuration option, available in all current release
	+ versions of &os;. Due to the limitations of the Intel memory
	+ architecture, no distinction is made for memory above or below
	+ 4 gigabytes. Memory allocated above 4 gigabytes is simply
	+ added to the pool of available memory.</para>

	- <para>To enable <acronym>PAE</acronym> support in the kernel,
	- simply add the following line to your kernel configuration
	- file:</para>
	+ <para>To enable <acronym>PAE</acronym> support in the kernel,
	+ add the following line to the kernel configuration
	+ file:</para>

	- <programlisting>options PAE</programlisting>
	+ <programlisting>options PAE</programlisting>

	<note>
	<para>The <acronym>PAE</acronym> support in &os; is only
	available for &intel; IA-32 processors. It should also be
	- noted, that the <acronym>PAE</acronym> support in &os; has
	+ noted that the <acronym>PAE</acronym> support in &os; has
	not received wide testing, and should be considered beta
	quality compared to other stable features of &os;.</para>
	</note>

	<para><acronym>PAE</acronym> support in &os; has a few
	limitations:</para>

	<itemizedlist>
	<listitem>
	<para>A process is not able to access more than 4
	- gigabytes of VM space.</para>
	+ gigabytes of virtual memory space.</para>
	</listitem>

	<listitem>
	<para>Device drivers that do not use the &man.bus.dma.9;
	interface will cause data corruption in a
	<acronym>PAE</acronym> enabled kernel and are not
	recommended for use. For this reason, a
	- <filename>PAE</filename> kernel
	- configuration file is provided in &os; which
	- excludes all drivers not known to work in a
	- <acronym>PAE</acronym> enabled kernel.</para>
	+ <filename>PAE</filename> kernel configuration file is
	+ provided in &os; which excludes all drivers not known to
	+ work in a <acronym>PAE</acronym> enabled kernel.</para>
	</listitem>

	<listitem>
	<para>Some system tunables determine memory resource usage
	by the amount of available physical memory. Such
	tunables can unnecessarily over-allocate due to the
	large memory nature of a <acronym>PAE</acronym> system.
	- One such example is the <option>kern.maxvnodes</option>
	- sysctl, which controls the maximum number of vnodes
	- allowed in the kernel. It is advised to adjust this
	- and other such tunables to a reasonable value.</para>
	+ One such example is the
	+ <varname>kern.maxvnodes</varname> sysctl, which controls
	+ the maximum number of vnodes allowed in the kernel. It
	+ is advised to adjust this and other such tunables to a
	+ reasonable value.</para>
	</listitem>

	<listitem>
	<para>It might be necessary to increase the kernel virtual
	address (<acronym>KVA</acronym>) space or to reduce the
	amount of specific kernel resource that is heavily used
	- (see above) in order to avoid <acronym>KVA</acronym>
	- exhaustion. The <option>KVA_PAGES</option> kernel
	- option can be used for increasing the
	- <acronym>KVA</acronym> space.</para>
	+ in order to avoid <acronym>KVA</acronym> exhaustion.
	+ The <option>KVA_PAGES</option> kernel option can be used
	+ for increasing the <acronym>KVA</acronym> space.</para>
	</listitem>
	</itemizedlist>

	<para>For performance and stability concerns, it is advised to
	- consult the &man.tuning.7; manual page. The &man.pae.4;
	- manual page contains up-to-date information on &os;'s
	- <acronym>PAE</acronym> support.</para>
	- </sect2>
	- </sect1>
	+ consult &man.tuning.7;. &man.pae.4; contains up-to-date
	+ information on &os;'s <acronym>PAE</acronym> support.</para>
	+ </sect2>
	+ </sect1>

	- <sect1 id="kernelconfig-trouble">
	- <title>If Something Goes Wrong</title>
	+ <sect1 id="kernelconfig-trouble">
	+ <title>If Something Goes Wrong</title>

	- <para>There are four categories of trouble that can occur when
	- building a custom kernel. They are:</para>
	+ <para>There are four categories of trouble that can occur when
	+ building a custom kernel. They are:</para>

	- <variablelist>
	- <varlistentry>
	- <term><command>config</command> fails:</term>
	+ <variablelist>
	+ <varlistentry>
	+ <term><command>config</command> fails:</term>

	- <listitem>
	- <para>If the &man.config.8; command fails when you
	- give it your kernel description, you have probably made a
	- simple error somewhere. Fortunately,
	- &man.config.8; will print the line number that it
	- had trouble with, so that you can quickly locate the line
	- containing the error. For example, if you see:</para>
	+ <listitem>
	+ <para>If &man.config.8; fails, it is probably a simple
	+ error. Fortunately, &man.config.8; will print the line
	+ number that it had trouble with. For example, for
	+ this message:</para>

	<screen>config: line 17: syntax error</screen>

	- <para>Make sure the
	- keyword is typed correctly by comparing it to the
	+ <para>Make sure the keyword on line 17 is typed correctly by
	+ comparing it to the
	<filename>GENERIC</filename> kernel or another
	reference.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>make</command> fails:</term>

	<listitem>
	- <para>If the <command>make</command> command fails, it
	- usually signals an error in your kernel description which
	- is not severe enough for &man.config.8; to catch. Again,
	- look over your configuration, and if you still cannot
	- resolve the problem, send mail to the &a.questions; with
	- your kernel configuration, and it should be diagnosed
	- quickly.</para>
	+ <para>If <command>make</command> fails, it usually signals
	+ an error in the kernel description which is not severe
	+ enough for &man.config.8; to catch. Review the
	+ configuration, and if you still cannot resolve the
	+ problem, send an email to the &a.questions; with the
	+ kernel configuration.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>The kernel does not boot:<anchor
	id="kernelconfig-noboot"/></term>

	<listitem>
	- <para>If your new kernel does not boot, or fails to
	- recognize your devices, do not panic! Fortunately, &os;
	- has an excellent mechanism for recovering from
	- incompatible kernels. Simply choose the kernel you want
	- to boot from at the &os; boot loader. You can access this
	- when the system boot menu appears. Select the
	- <quote>Escape to a loader prompt</quote> option, number
	- six. At the prompt, type
	+ <para>If the new kernel does not boot, or fails to recognize
	+ devices, do not panic! Fortunately, &os; has an excellent
	+ mechanism for recovering from incompatible kernels.
	+ Simply choose the kernel to boot from at the &os; boot
	+ loader. This can be accessed when the system boot menu
	+ appears by selecting the <quote>Escape to a loader
	+ prompt</quote> option. At the prompt, type
	<command>boot
	- <replaceable>kernel.old</replaceable></command>,
	- or the name of any other kernel that will boot properly.
	+ <replaceable>kernel.old</replaceable></command>, or
	+ the name of any other kernel that will boot properly.
	When reconfiguring a kernel, it is always a good idea to
	keep a kernel that is known to work on hand.</para>

	- <para>After booting with a good kernel you can check over
	- your configuration file and try to build it again. One
	- helpful resource is the
	- <filename>/var/log/messages</filename> file which records,
	- among other things, all of the kernel messages from every
	- successful boot. Also, the &man.dmesg.8; command will
	- print the kernel messages from the current boot.</para>
	+ <para>After booting with a good kernel, check over the
	+ configuration file and try to build it again. One helpful
	+ resource is <filename>/var/log/messages</filename> which
	+ records the kernel messages from every successful boot.
	+ Also, &man.dmesg.8; will print the kernel messages from
	+ the current boot.</para>

	<note>
	- <para>If you are having trouble building a kernel, make
	- sure to keep a <filename>GENERIC</filename>, or some
	- other kernel that is known to work on hand as a
	- different name that will not get erased on the next
	- build. You cannot rely on
	+ <para>When troubleshooting a kernel, make sure to keep
	+ <filename>GENERIC</filename>, or some other kernel that
	+ is known to work, on hand as a different name that will
	+ not get erased on the next build. Do not rely on
	<filename>kernel.old</filename> because when installing
	a new kernel, <filename>kernel.old</filename> is
	overwritten with the last installed kernel which may
	- be non-functional. Also, as soon as possible, move
	- the working kernel to the proper <filename
	+ be non-functional. As soon as possible, move the
	+ working kernel to the proper <filename
	class="directory">/boot/kernel</filename>
	location or commands such as &man.ps.1; may not work
	properly. To do this, simply rename the directory
	containing the good kernel:</para>

	<screen>&prompt.root; <userinput>mv /boot/kernel <replaceable>/boot/kernel.bad</replaceable></userinput>
	&prompt.root; <userinput>mv /boot/<replaceable>kernel.good</replaceable> /boot/kernel</userinput></screen>

	</note>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>The kernel works, but &man.ps.1; does not work
	any more:</term>

	<listitem>
	- <para>If you have installed a different version of the
	- kernel from the one that the system utilities have been
	- built with, for example, a -CURRENT kernel on a -RELEASE,
	- many system-status commands like &man.ps.1; and
	- &man.vmstat.8; will not work any more. You should
	- <link linkend="makeworld">recompile and install a
	+ <para>If the kernel version differs from the one that the
	+ system utilities have been built with, for example, a
	+ -CURRENT kernel on a -RELEASE, many system status commands
	+ like &man.ps.1; and &man.vmstat.8; will not work. To fix
	+ this, <link linkend="makeworld">recompile and install a
	world</link> built with the same version of the
	- source tree as your kernel. This is one reason it is
	- not normally a good idea to use a different version of
	- the kernel from the rest of the operating system.</para>
	+ source tree as the kernel. This is one reason why it is
	+ not a good idea to use a different version of the kernel
	+ than the rest of the operating system.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/l10n/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/l10n/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/l10n/chapter.xml (revision 41355)
	@@ -1,1004 +1,975 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="l10n">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Andrey</firstname>
	<surname>Chernov</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Michael C.</firstname>
	<surname>Wu</surname>
	<contrib>Rewritten by </contrib>
	</author>
	<!-- 30 Nv 2000 -->
	</authorgroup>
	</chapterinfo>

	- <title>Localization - I18N/L10N Usage and Setup</title>
	+ <title>Localization -
	+ <acronym>i18n</acronym>/<acronym>L10n</acronym> Usage and
	+ Setup</title>

	<sect1 id="l10n-synopsis">
	<title>Synopsis</title>

	- <para>FreeBSD is a very distributed project with users and
	- contributors located all over the world. This chapter discusses
	- the internationalization and localization features of FreeBSD
	- that allow non-English speaking users to get real work done.
	- There are many aspects of the i18n implementation in both the
	- system and application levels, so where applicable we refer
	- the reader to more specific sources of documentation.</para>
	+ <para>&os; is a distributed project with users and contributors
	+ located all over the world. This chapter discusses the
	+ internationalization and localization features of &os; that
	+ allow non-English speaking users to get real work done. Since
	+ there are many aspects of the <acronym>i18n</acronym>
	+ implementation in both the system and application levels, more
	+ specific sources of documentation are referred to, where
	+ applicable.</para>

	<para>After reading this chapter, you will know:</para>
	<itemizedlist>
	- <listitem><para>How different languages and locales are encoded
	- on modern operating systems.</para></listitem>
	- <listitem><para>How to set the locale for your login
	- shell.</para></listitem>
	- <listitem><para>How to configure your console for non-English
	- languages.</para></listitem>
	- <listitem><para>How to use X Window System effectively with
	- different languages.</para></listitem>
	- <listitem><para>Where to find more information about writing
	- i18n-compliant applications.</para></listitem>
	+ <listitem>
	+ <para>How different languages and locales are encoded on
	+ modern operating systems.</para>
	+ </listitem>
	+ <listitem>
	+ <para>How to set the locale for a login shell.</para>
	+ </listitem>
	+ <listitem>
	+ <para>How to configure the console for non-English
	+ languages.</para>
	+ </listitem>
	+ <listitem>
	+ <para>How to use <application>Xorg</application>effectively
	+ with different languages.</para>
	+ </listitem>
	+ <listitem>
	+ <para>Where to find more information about writing
	+ <acronym>i18n</acronym>-compliant applications.</para>
	+ </listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	- <listitem><para>Know how to install additional third-party
	- applications (<xref linkend="ports"/>).</para></listitem>
	+ <listitem><para>Know how to <link linkend="ports">install
	+ additional third-party
	+ applications</link>.</para></listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="l10n-basics">
	<title>The Basics</title>

	<sect2>
	- <title>What Is I18N/L10N?</title>
	+ <title>What Is
	+ <acronym>i18n</acronym>/<acronym>L10n</acronym>?</title>

	<indexterm>
	<primary>internationalization</primary>
	<see>localization</see>
	</indexterm>
	<indexterm><primary>localization</primary></indexterm>

	- <para>Developers shortened internationalization into the term
	- I18N, counting the number of letters between the first and
	- the last letters of internationalization. L10N uses the
	+ <para>The term internationalization has been shortened to
	+ <acronym>i18n</acronym>, which represents the number of
	+ letters between the first and the last letters of
	+ internationalization. <acronym>L10n</acronym> uses the
	same naming scheme, coming from <quote>localization</quote>.
	- Combined together, I18N/L10N methods, protocols, and
	- applications allow users to use languages of their
	- choice.</para>
	+ Combined together,
	+ <acronym>i18n</acronym>/<acronym>L10n</acronym> methods,
	+ protocols, and applications allow users to use languages of
	+ their choice.</para>

	- <para>I18N applications are programmed using I18N kits under
	- libraries. It allows for developers to write a simple file
	- and translate displayed menus and texts to each language.
	- We strongly encourage programmers to follow this
	- convention.</para>
	+ <para><acronym>i18n</acronym> applications are programmed using
	+ <acronym>i18n</acronym> kits under libraries. These allow
	+ developers to write a simple file and translate displayed
	+ menus and texts to each language.</para>
	</sect2>

	<sect2>
	- <title>Why Should I Use I18N/L10N?</title>
	+ <title>Why Use
	+ <acronym>i18n</acronym>/<acronym>L10n</acronym>?</title>

	- <para>I18N/L10N is used whenever you wish to either view,
	- input, or process data in non-English languages.</para>
	+ <para>Using <acronym>i18n</acronym>/<acronym>L10n</acronym>
	+ allows a user to view, input, or process data in non-English
	+ languages.</para>
	</sect2>

	<sect2>
	- <title>What Languages Are Supported in the I18N Effort?</title>
	+ <title>Which Languages Are Supported?</title>

	- <para>I18N and L10N are not FreeBSD specific. Currently, one
	- can choose from most of the major languages of the World,
	- including but not limited to: Chinese, German, Japanese,
	- Korean, French, Russian, Vietnamese and others.</para>
	+ <para><acronym>i18n</acronym> and <acronym>L10n</acronym> are
	+ not &os; specific. Currently, one can choose from most of the
	+ major languages, including but not limited to: Chinese,
	+ German, Japanese, Korean, French, Russian, and
	+ Vietnamese.</para>
	</sect2>
	</sect1>

	<sect1 id="using-localization">
	<title>Using Localization</title>

	- <para>In all its splendor, I18N is not FreeBSD-specific and is
	- a convention. We encourage you to help FreeBSD in following
	- this convention.</para>
	<indexterm><primary>locale</primary></indexterm>

	<para>Localization settings are based on three main terms:
	Language Code, Country Code, and Encoding. Locale names are
	constructed from these parts as follows:</para>

	<programlisting><replaceable>LanguageCode</replaceable>_<replaceable>CountryCode</replaceable>.<replaceable>Encoding</replaceable></programlisting>

	<sect2>
	<title>Language and Country Codes</title>

	<indexterm><primary>language codes</primary></indexterm>
	<indexterm><primary>country codes</primary></indexterm>

	- <para>In order to localize a FreeBSD system to a specific
	- language (or any other I18N-supporting &unix; like systems),
	- the user needs to find out the codes for the specific country
	- and language (country codes tell applications what variation
	- of given language to use). In addition, web browsers,
	- SMTP/POP servers, web servers, etc. make decisions based on
	- them. The following are examples of language/country
	- codes:</para>
	+ <para>In order to localize a &os; system to a specific language,
	+ the user needs to determine the codes for the specific country
	+ and language as the country code tells applications which
	+ variation of the given language to use. The following are
	+ examples of language/country codes:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Language/Country Code</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>en_US</entry>
	<entry>English - United States</entry>
	</row>

	<row>
	<entry>ru_RU</entry>
	<entry>Russian for Russia</entry>
	</row>

	<row>
	<entry>zh_TW</entry>
	<entry>Traditional Chinese for Taiwan</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>A complete listing of available locales can be found by
	typing:</para>

	<screen>&prompt.user; <userinput>locale -a</userinput></screen>

	</sect2>

	<sect2>
	<title>Encodings</title>

	<indexterm><primary>encodings</primary></indexterm>
	<indexterm><primary>ASCII</primary></indexterm>

	<para>Some languages use non-ASCII encodings that are 8-bit,
	- wide or multibyte characters, see &man.multibyte.3; for more
	- details. Older applications do not recognize them and mistake
	- them for control characters. Newer applications usually do
	- recognize 8-bit characters. Depending on the implementation,
	- users may be required to compile an application with wide or
	- multibyte characters support, or configure it correctly.
	- To be able to input and process wide or multibyte characters,
	- the <ulink
	- url="&url.base;/ports/index.html">FreeBSD Ports
	- Collection</ulink> has provided each language with different
	- programs. Refer to the I18N documentation in the respective
	- FreeBSD Port.</para>
	+ wide, or multibyte characters. For more information on these
	+ encodings, refer to &man.multibyte.3;. Older applications do
	+ not recognize these encodings and mistake them for control
	+ characters. Newer applications usually recognize 8-bit
	+ characters. Depending on the implementation, users may be
	+ required to compile an application with wide or multibyte
	+ character support, or configure it correctly. To provide
	+ application support for wide or multibyte characters, the
	+ <ulink url="&url.base;/ports/index.html">&os; Ports
	+ Collection</ulink> contains programs for several languages.
	+ Refer to the <acronym>i18n</acronym> documentation in the
	+ respective &os; port.</para>

	<para>Specifically, the user needs to look at the application
	- documentation to decide on how to configure it correctly or
	- to pass correct values into the
	- configure/Makefile/compiler.</para>
	+ documentation to decide how to configure it correctly or to
	+ determine which compile options to use when building the
	+ port.</para>

	<para>Some things to keep in mind are:</para>

	<itemizedlist>
	<listitem>
	<para>Language specific single C chars character sets
	- (see &man.multibyte.3;), e.g. ISO8859-1, ISO8859-15,
	- KOI8-R, CP437.</para>
	+ such as ISO8859-1, ISO8859-15, KOI8-R, and CP437. These
	+ are described in &man.multibyte.3;.</para>
	</listitem>

	<listitem>
	- <para>Wide or multibyte encodings, e.g., EUC, Big5.</para>
	+ <para>Wide or multibyte encodings such as EUC and
	+ Big5.</para>
	</listitem>
	</itemizedlist>

	- <para>You can check the active list of character sets at the
	+ <para>The active list of character sets can be found at the
	<ulink
	- url="http://www.iana.org/assignments/character-sets">IANA Registry</ulink>.</para>
	+ url="http://www.iana.org/assignments/character-sets">IANA
	+ Registry</ulink>.</para>

	<note>
	- <para>&os; uses X11-compatible locale encodings
	+ <para>&os; uses Xorg-compatible locale encodings
	instead.</para>
	</note>

	- </sect2>
	-
	- <sect2>
	- <title>I18N Applications</title>
	-
	- <para>In the FreeBSD Ports and Package system, I18N applications
	- have been named with <literal>I18N</literal> in their names
	+ <para>In the &os; Ports Collection, <acronym>i18n</acronym>
	+ applications include <literal>i18n</literal> in their names
	for easy identification. However, they do not always support
	the language needed.</para>
	</sect2>

	<sect2 id="setting-locale">
	<title>Setting Locale</title>

	<para>Usually it is sufficient to export the value of the
	locale name as <envar>LANG</envar> in the login shell. This
	could be done in the user's <filename>~/.login_conf</filename>
	- file or in the startup file of the user's shell
	+ or in the startup file of the user's shell:
	(<filename>~/.profile</filename>,
	- <filename>~/.bashrc</filename>,
	+ <filename>~/.bashrc</filename>, or
	<filename>~/.cshrc</filename>). There is no need to set the
	- locale subsets such as <envar>LC_CTYPE</envar>,
	- <envar>LC_CTIME</envar>. Please refer to language-specific
	- FreeBSD documentation for more information.</para>
	+ locale subsets such as <envar>LC_CTYPE</envar> or
	+ <envar>LC_CTIME</envar>. Refer to language-specific &os;
	+ documentation for more information.</para>

	- <para>You should set the following two environment variables
	- in your configuration files:</para>
	+ <para>Each user should set the following two environment
	+ variables in their configuration files:</para>

	<itemizedlist>
	<indexterm><primary>POSIX</primary></indexterm>
	<listitem>
	<para><envar>LANG</envar> for &posix; &man.setlocale.3;
	family functions</para>
	</listitem>

	<listitem>
	<indexterm><primary>MIME</primary></indexterm>

	<para><envar>MM_CHARSET</envar> for applications' MIME
	character set</para>
	</listitem>
	</itemizedlist>

	- <para>This includes the user shell configuration, the specific
	- application configuration, and the X11 configuration.</para>
	+ <para>These should be set in the user's shell configuration, the
	+ specific application configuration, and the
	+ <application>Xorg</application> configuration.</para>

	<sect3>
	<title>Setting Locale Methods</title>

	<indexterm><primary>locale</primary></indexterm>
	<indexterm><primary>login class</primary></indexterm>

	- <para>There are two methods for setting locale, and both are
	- described below. The first (recommended one) is by
	- assigning the environment variables in
	- <link linkend="login-class">login class</link>, and the
	- second is by adding the environment variable assignments
	- to the system's shell
	- <link linkend="startup-file">startup file</link>.</para>
	+ <para>This section describes the two methods for setting
	+ locale. The first is recommended and assigns the
	+ environment variables in the <link
	+ linkend="login-class">login class</link>. The second
	+ method adds the environment variable assignments to the
	+ system's shell <link linkend="startup-file">startup
	+ file</link>.</para>

	<sect4 id="login-class">
	<title>Login Classes Method</title>

	<para>This method allows environment variables needed for
	locale name and MIME character sets to be assigned once
	for every possible shell instead of adding specific shell
	- assignments to each shell's startup file.
	- <link linkend="usr-setup">User Level Setup</link> can be
	- done by an user himself and
	- <link linkend="adm-setup">Administrator Level Setup</link>
	- require superuser privileges.</para>
	+ assignments to each shell's startup file. <link
	+ linkend="usr-setup">User Level Setup</link> can be
	+ performed by each user while <link
	+ linkend="adm-setup">Administrator Level Setup</link>
	+ requires superuser privileges.</para>

	<sect5 id="usr-setup">
	<title>User Level Setup</title>

	- <para>Here is a minimal example of a
	- <filename>.login_conf</filename> file in user's home
	- directory which has both variables set for Latin-1
	- encoding:</para>
	+ <para>This provides a minimal example of a
	+ <filename>.login_conf</filename> located in a user's
	+ home directory which has both variables set for the
	+ Latin-1 encoding:</para>

	<programlisting>me:\
	:charset=ISO-8859-1:\
	:lang=de_DE.ISO8859-1:</programlisting>

	<indexterm><primary>Traditional Chinese</primary>
	<secondary>BIG-5 encoding</secondary></indexterm>
	- <para>Here is an example of a
	+ <para>Here is an example of a user's
	<filename>.login_conf</filename> that sets the variables
	- for Traditional Chinese in BIG-5 encoding. Notice the
	- many more variables set because some software does not
	- respect locale variables correctly for Chinese,
	+ for Traditional Chinese in BIG-5 encoding. More
	+ variables are set because some applications do not
	+ correctly respect locale variables for Chinese,
	Japanese, and Korean.</para>

	<programlisting>#Users who do not wish to use monetary units or time formats
	#of Taiwan can manually change each variable
	me:\
	:lang=zh_TW.Big5:\
	:setenv=LC_ALL=zh_TW.Big5:\
	:setenv=LC_COLLATE=zh_TW.Big5:\
	:setenv=LC_CTYPE=zh_TW.Big5:\
	:setenv=LC_MESSAGES=zh_TW.Big5:\
	:setenv=LC_MONETARY=zh_TW.Big5:\
	:setenv=LC_NUMERIC=zh_TW.Big5:\
	:setenv=LC_TIME=zh_TW.Big5:\
	:charset=big5:\
	:xmodifiers="@im=gcin": #Set gcin as the XIM Input Server</programlisting>

	<para>See <link linkend="adm-setup">Administrator Level
	Setup</link> and &man.login.conf.5; for more
	details.</para>
	</sect5>

	<sect5 id="adm-setup">
	<title>Administrator Level Setup</title>

	<para>Verify that the user's login class in
	<filename>/etc/login.conf</filename> sets the correct
	- language. Make sure these settings
	- appear in <filename>/etc/login.conf</filename>:</para>
	+ language:</para>

	<programlisting><replaceable>language_name</replaceable>\|<replaceable>Account Type Description</replaceable>:\
	:charset=<replaceable>MIME_charset</replaceable>:\
	:lang=<replaceable>locale_name</replaceable>:\
	:tc=default:</programlisting>

	- <para>So sticking with our previous example using Latin-1,
	- it would look like this:</para>
	+ <para>The previous Latin-1 example would look like
	+ this:</para>

	<programlisting>german\|German Users Accounts:\
	:charset=ISO-8859-1:\
	:lang=de_DE.ISO8859-1:\
	:tc=default:</programlisting>

	- <para>Before changing users Login Classes execute
	- the following command:</para>
	+ <para>Whenever this file is edited, execute the following
	+ command to update the capability database:</para>

	<screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>

	- <para>to make new configuration in
	- <filename>/etc/login.conf</filename> visible to the
	- system.</para>
	-
	<bridgehead renderas="sect4">Changing Login Classes with
	&man.vipw.8;</bridgehead>

	<indexterm>
	<primary><command>vipw</command></primary>
	</indexterm>
	- <para>Use <command>vipw</command> to add new users, and
	- make the entry look like this:</para>
	+ <para>When using <command>vipw</command> to add new users,
	+ use <replaceable>language</replaceable> to set the
	+ language:</para>

	<programlisting>user:password:1111:11:<replaceable>language</replaceable>:0:0:User Name:/home/user:/bin/sh</programlisting>

	<bridgehead renderas="sect4">Changing Login Classes with
	&man.adduser.8;</bridgehead>

	<indexterm>
	<primary><command>adduser</command></primary>
	</indexterm>
	<indexterm><primary>login class</primary></indexterm>
	- <para>Use <command>adduser</command> to add new users,
	- and do the following:</para>
	+ <para>When using <command>adduser</command> to add new
	+ users, configure the language as follows:</para>

	<itemizedlist>
	<listitem>
	- <para>Set <literal>defaultclass =
	+ <para>If all new users use the same language, set
	+ <literal>defaultclass =
	<replaceable>language</replaceable></literal> in
	- <filename>/etc/adduser.conf</filename>. Keep in
	- mind you must enter a <literal>default</literal>
	- class for all users of other languages in this
	- case.</para>
	+ <filename>/etc/adduser.conf</filename>.</para>
	</listitem>

	<listitem>
	- <para>An alternative variant is answering the
	- specified language each time that
	+ <para>Alternatively, input the specified language at
	+ this prompt:

	<screen><prompt>Enter login class: default []:</prompt></screen>

	- appears from &man.adduser.8;.</para>
	+ when creating a new user using
	+ &man.adduser.8;.</para>
	</listitem>

	<listitem>
	- <para>Another alternative is to use the following for
	- each user of a different language that you wish to
	- add:</para>
	+ <para>Another alternative is to use the following
	+ when creating a user that uses a different language
	+ than the one set in
	+ <filename>/etc/adduser.conf</filename>:</para>

	<screen>&prompt.root; <userinput>adduser -class <replaceable>language</replaceable></userinput></screen>
	</listitem>
	</itemizedlist>

	<bridgehead renderas="sect4">Changing Login Classes with
	&man.pw.8;</bridgehead>
	<indexterm>
	<primary><command>pw</command></primary>
	</indexterm>
	- <para>If you use &man.pw.8; for adding new users, call
	+ <para>If &man.pw.8; is used to add new users, call
	it in this form:</para>

	<screen>&prompt.root; <userinput>pw useradd <replaceable>user_name</replaceable> -L <replaceable>language</replaceable></userinput></screen>
	</sect5>
	</sect4>

	<sect4 id="startup-file">
	<title>Shell Startup File Method</title>

	<note>
	<para>This method is not recommended because it requires
	- a different setup for each possible shell program
	- chosen. Use the <link linkend="login-class">Login Class
	- Method</link> instead.</para>
	+ a different setup for each shell. Use the <link
	+ linkend="login-class">Login Class Method</link>
	+ instead.</para>
	</note>

	<indexterm><primary>MIME</primary></indexterm>
	<indexterm><primary>locale</primary></indexterm>
	- <para>To add the locale name and MIME character set, just
	- set the two environment variables shown below in the
	- <filename>/etc/profile</filename> and/or
	+ <para>To add the locale name and MIME character set, set
	+ the two environment variables shown below in the
	+ <filename>/etc/profile</filename> or
	<filename>/etc/csh.login</filename> shell startup files.
	- We will use the German language as an example
	- below:</para>
	+ This example sets the German language:</para>

	<para>In <filename>/etc/profile</filename>:</para>

	<programlisting><envar>LANG=de_DE.ISO8859-1; export LANG</envar>
	<envar>MM_CHARSET=ISO-8859-1; export MM_CHARSET</envar></programlisting>

	<para>Or in <filename>/etc/csh.login</filename>:</para>

	<programlisting><envar>setenv LANG de_DE.ISO8859-1</envar>
	<envar>setenv MM_CHARSET ISO-8859-1</envar></programlisting>

	- <para>Alternatively, you can add the above instructions to
	- <filename>/usr/share/skel/dot.profile</filename> (similar
	- to what was used in <filename>/etc/profile</filename>
	- above), or <filename>/usr/share/skel/dot.login</filename>
	- (similar to what was used in
	- <filename>/etc/csh.login</filename> above).</para>
	+ <para>Alternatively, add the above settings to
	+ <filename>/usr/share/skel/dot.profile</filename> or
	+ <filename>/usr/share/skel/dot.login</filename>.</para>

	- <para>For X11:</para>
	+ <para>To configure <application>Xorg</application>, add
	+ <emphasis>one</emphasis> of the following to
	+ <filename>~/.xinitrc</filename>, depending upon the
	+ shell:</para>

	- <para>In <filename>$HOME/.xinitrc</filename>:</para>
	-
	<programlisting><envar>LANG=de_DE.ISO8859-1; export LANG</envar></programlisting>

	- <para>Or:</para>
	-
	<programlisting><envar>setenv LANG de_DE.ISO8859-1</envar></programlisting>

	- <para>Depending on your shell (see above).</para>
	-
	</sect4>
	</sect3>
	</sect2>

	<sect2 id="setting-console">
	<title>Console Setup</title>

	<para>For all single C chars character sets, set the correct
	console fonts in <filename>/etc/rc.conf</filename> for the
	language in question with:</para>

	<programlisting>font8x16=<replaceable>font_name</replaceable>
	font8x14=<replaceable>font_name</replaceable>
	font8x8=<replaceable>font_name</replaceable></programlisting>

	- <para>The <replaceable>font_name</replaceable> here is taken
	- from the <filename>/usr/share/syscons/fonts</filename>
	- directory, without the <filename>.fnt</filename>
	- suffix.</para>
	+ <para>The <replaceable>font_name</replaceable> is taken from
	+ <filename
	+ class="directory">/usr/share/syscons/fonts</filename>,
	+ without the <filename>.fnt</filename> suffix.</para>

	<indexterm>
	<primary><application>sysinstall</application></primary>
	</indexterm>
	<indexterm><primary>keymap</primary></indexterm>
	<indexterm><primary>screenmap</primary></indexterm>
	- <para>If required, set the keymap and screenmap for your
	- single C chars character set through
	- <command>sysinstall</command>.
	- Once inside <application>sysinstall</application>, choose
	+ <para>The keymap and screenmap for the single C chars character
	+ set can be set using <command>sysinstall</command>. Once
	+ inside <application>sysinstall</application>, choose
	<guimenuitem>Configure</guimenuitem>, then
	- <guimenuitem>Console</guimenuitem>. Alternatively, you can
	+ <guimenuitem>Console</guimenuitem>. Alternatively,
	add the following to <filename>/etc/rc.conf</filename>:</para>

	<programlisting>scrnmap=<replaceable>screenmap_name</replaceable>
	keymap=<replaceable>keymap_name</replaceable>
	keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting>

	- <para>The <replaceable>screenmap_name</replaceable> here is
	- taken from the
	- <filename>/usr/share/syscons/scrnmaps</filename> directory,
	+ <para>The <replaceable>screenmap_name</replaceable> is taken
	+ from <filename
	+ class="directory">/usr/share/syscons/scrnmaps</filename>,
	without the <filename>.scm</filename> suffix. A screenmap
	with a corresponding mapped font is usually needed as a
	workaround for expanding bit 8 to bit 9 on a VGA adapter's
	- font character matrix in pseudographics area, i.e., to move
	- letters out of that area if screen font uses a bit 8
	+ font character matrix. This will move letters out of the
	+ pseudographics area if the screen font uses a bit 8
	column.</para>

	- <para>If you have the <application>moused</application> daemon
	- enabled by setting the following
	- in your <filename>/etc/rc.conf</filename>:</para>
	+ <para>If <application>moused</application> is enabled in
	+ <filename>/etc/rc.conf</filename>, review the mouse cursor
	+ information in the next paragraph.</para>

	-<programlisting>moused_enable="YES"</programlisting>
	-
	- <para>then examine the mouse cursor information in the next
	- paragraph.</para>
	-
	<indexterm>
	<primary><application>moused</application></primary>
	</indexterm>
	- <para>By default the mouse cursor of the &man.syscons.4; driver
	- occupies the 0xd0-0xd3 range in the character set. If your
	- language uses this range, you need to move the cursor's range
	- outside of it. To enable the workaround for &os;, add the
	- following line to <filename>/etc/rc.conf</filename>:</para>
	+ <para>By default, the mouse cursor of the &man.syscons.4; driver
	+ occupies the 0xd0-0xd3 range in the character set. If the
	+ language uses this range, move the cursor's range. To enable
	+ this workaround for &os;, add the following line to
	+ <filename>/etc/rc.conf</filename>:</para>

	<programlisting>mousechar_start=3</programlisting>

	- <para>The <replaceable>keymap_name</replaceable> here is taken
	- from the <filename>/usr/share/syscons/keymaps</filename>
	- directory, without the <filename>.kbd</filename> suffix. If
	- you are uncertain which keymap to use, you use can
	- &man.kbdmap.1; to test keymaps without rebooting.</para>
	+ <para>The <replaceable>keymap_name</replaceable> in the above
	+ example is taken from <filename
	+ class="directory">/usr/share/syscons/keymaps</filename>,
	+ without the <filename>.kbd</filename> suffix. When uncertain
	+ as to which keymap to use, &man.kbdmap.1; can be used to test
	+ keymaps without rebooting.</para>

	<para>The <literal>keychange</literal> is usually needed to
	program function keys to match the selected terminal type
	because function key sequences cannot be defined in the key
	map.</para>

	- <para>Also be sure to set the correct console terminal type
	- in <filename>/etc/ttys</filename> for all
	- <literal>ttyv*</literal> entries. Current pre-defined
	- correspondences are:</para>
	+ <para>Be sure to set the correct console terminal type in
	+ <filename>/etc/ttys</filename> for all virtual terminal
	+ entries. Current pre-defined correspondences are:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Character Set</entry>
	<entry>Terminal Type</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>ISO8859-1 or ISO8859-15</entry>
	<entry><literal>cons25l1</literal></entry>
	</row>

	<row>
	<entry>ISO8859-2</entry>
	<entry><literal>cons25l2</literal></entry>
	</row>

	<row>
	<entry>ISO8859-7</entry>
	<entry><literal>cons25l7</literal></entry>
	</row>

	<row>
	<entry>KOI8-R</entry>
	<entry><literal>cons25r</literal></entry>
	</row>

	<row>
	<entry>KOI8-U</entry>
	<entry><literal>cons25u</literal></entry>
	</row>

	<row>
	<entry>CP437 (VGA default)</entry>
	<entry><literal>cons25</literal></entry>
	</row>

	<row>
	<entry>US-ASCII</entry>
	<entry><literal>cons25w</literal></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	- <para>For wide or multibyte characters languages, use the
	- correct FreeBSD port in your
	- <filename>/usr/ports/<replaceable>language</replaceable></filename>
	- directory. Some ports appear as console while the system
	- sees it as serial vtty's, hence you must reserve enough vtty's
	- for both X11 and the pseudo-serial console. Here is a partial
	- list of applications for using other languages in
	- console:</para>
	+ <para>For languages with wide or multibyte characters, use the
	+ correct &os; port in <filename
	+ class="directory">/usr/ports/<replaceable>language</replaceable></filename>.
	+ Some applications appear as serial terminals to the system.
	+ Reserve enough terminals in <filename>/etc/ttys</filename>
	+ for both <application>Xorg</application> and the pseudo-serial
	+ console. Here is a partial list of applications for using
	+ other languages in the console:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Language</entry>
	<entry>Location</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>Traditional Chinese (BIG-5)</entry>
	<entry><filename
	role="package">chinese/big5con</filename></entry>
	</row>

	<row>
	<entry>Japanese</entry>
	<entry><filename
	role="package">japanese/kon2-16dot</filename> or
	<filename
	role="package">japanese/mule-freewnn</filename></entry>
	</row>

	<row>
	<entry>Korean</entry>
	<entry><filename
	role="package">korean/han</filename></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</sect2>

	<sect2>
	- <title>X11 Setup</title>
	+ <title>Xorg Setup</title>

	- <para>Although X11 is not part of the FreeBSD Project, we have
	- included some information here for FreeBSD users. For more
	- details, refer to the <ulink
	- url="http://www.x.org/">&xorg;
	- web site</ulink> or whichever X11 Server you use.</para>
	+ <para>Although <application>Xorg</application> is not installed
	+ with &os;, it can be installed from the Ports Collection.
	+ Refer to <link linkend="x11"></link> for more information on
	+ how to do this. This section discusses how to localize
	+ <application>Xorg</application> once it is installed.</para>

	- <para>In <filename>~/.Xresources</filename>, you can
	- additionally tune application specific I18N settings (e.g.,
	- fonts, menus, etc.).</para>
	+ <para>Application specific <acronym>i18n</acronym> settings such
	+ as fonts and menus can be tuned in
	+ <filename>~/.Xresources</filename>.</para>

	<sect3>
	<title>Displaying Fonts</title>

	- <indexterm><primary>X11 True Type font
	+ <indexterm><primary>Xorg True Type font
	server</primary></indexterm>
	- <para>Install <application>&xorg;</application> server
	- (<filename
	- role="package">x11-servers/xorg-server</filename>),
	- then install the language &truetype; fonts. Setting the
	- correct locale should allow you to view your selected
	- language in menus and such.</para>
	+ <para>After installing <filename
	+ role="package">x11-servers/xorg-server</filename>, install
	+ the language's &truetype; fonts. Setting the correct locale
	+ should allow users to view their selected language in
	+ graphical application menus.</para>
	</sect3>

	<sect3>
	<title>Inputting Non-English Characters</title>

	- <indexterm><primary>X11 Input Method
	+ <indexterm><primary>X Input Method
	(XIM)</primary></indexterm>
	- <para>The X11 Input Method (XIM) Protocol is a new standard
	- for all X11 clients. All X11 applications should be written
	- as XIM clients that take input from XIM Input servers.
	- There are several XIM servers available for different
	- languages.</para>
	+
	+ <para>The X Input Method (<acronym>XIM</acronym>) protocol
	+ is an input standard for <application>Xorg</application>
	+ clients. All <application>Xorg</application> applications
	+ should be written as XIM clients that take input from XIM
	+ input servers. There are several XIM servers available for
	+ different languages.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Printer Setup</title>

	- <para>Some single C chars character sets are usually hardware
	- coded into printers. Wide or multibyte character sets require
	- special setup and we recommend using
	- <application>apsfilter</application>. You may also convert
	- the document to &postscript; or PDF formats using language
	+ <para>Some single C chars character sets are hardware coded
	+ into printers. Wide or multibyte character sets require
	+ special setup using a utility such as
	+ <application>apsfilter</application>. Documents can be
	+ converted to &postscript; or PDF formats using language
	specific converters.</para>
	</sect2>

	<sect2>
	<title>Kernel and File Systems</title>

	- <para>The FreeBSD fast filesystem (FFS) is 8-bit clean, so it
	- can be used with any single C chars character set (see
	- &man.multibyte.3;), but there is no character set name stored
	- in the filesystem; i.e., it is raw 8-bit and does not know
	- anything about encoding order. Officially, FFS does not
	- support any form of wide or multibyte character sets yet.
	- However, some wide or multibyte character sets have
	- independent patches for FFS enabling such support. They are
	- only temporary unportable solutions or hacks and we have
	- decided to not include them in the source tree. Refer to
	+ <para>The &os; fast filesystem (<acronym>FFS</acronym>) is 8-bit
	+ clean, so it can be used with any single C chars character
	+ set. However, character set names are not stored in the
	+ filesystem as it is raw 8-bit and does not understand encoding
	+ order. Officially, <acronym>FFS</acronym> does not support
	+ any form of wide or multibyte character sets. However, some
	+ wide or multibyte character sets have independent patches for
	+ enabling support on <acronym>FFS</acronym>. Refer to the
	respective languages' web sites for more information and the
	patch files.</para>

	<indexterm><primary>DOS</primary></indexterm>
	<indexterm><primary>Unicode</primary></indexterm>
	- <para>The FreeBSD &ms-dos; filesystem has the configurable
	- ability to convert between &ms-dos;, Unicode character sets
	- and chosen FreeBSD filesystem character sets. See
	- &man.mount.msdosfs.8; for details.</para>
	+ <para>&os;'s support for the &ms-dos; filesystem has the
	+ configurable ability to convert between &ms-dos;, Unicode
	+ character sets, and chosen &os; filesystem character sets.
	+ Refer to &man.mount.msdosfs.8; for details.</para>
	</sect2>
	</sect1>

	<sect1 id="l10n-compiling">
	- <title>Compiling I18N Programs</title>
	+ <title>Compiling <acronym>i18n</acronym> Programs</title>

	- <para>Many FreeBSD Ports have been ported with I18N support.
	- Some of them are marked with -I18N in the port name. These
	- and many other programs have built in support for I18N and
	- need no special consideration.</para>
	+ <para>Many applications in the &os; Ports Collection have been
	+ ported with <acronym>i18n</acronym> support. Some of these
	+ include <literal>-i18n</literal> in the port name. These
	+ and many other programs have built in support for
	+ <acronym>i18n</acronym> and need no special
	+ consideration.</para>

	<indexterm>
	<primary><application>MySQL</application></primary>
	</indexterm>
	<para>However, some applications such as
	<application>MySQL</application> need to have their
	<filename>Makefile</filename> configured with the specific
	- charset. This is usually done in the
	- <filename>Makefile</filename> or done by passing a value to
	+ charset. This is usually done in the port's
	+ <filename>Makefile</filename> or by passing a value to
	<application>configure</application> in the source.</para>
	</sect1>

	<sect1 id="lang-setup">
	- <title>Localizing FreeBSD to Specific Languages</title>
	+ <title>Localizing &os; to Specific Languages</title>

	<sect2 id="ru-localize">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Andrey</firstname>
	<surname>Chernov</surname>
	<contrib>Originally contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>
	<title>Russian Language (KOI8-R Encoding)</title>

	<indexterm>
	<primary>localization</primary>
	<secondary>Russian</secondary>
	</indexterm>

	- <para>For more information about KOI8-R encoding, see the
	+ <para>For more information about KOI8-R encoding, refer to
	<ulink url="http://koi8.pp.ru/">KOI8-R References
	(Russian Net Character Set)</ulink>.</para>

	<sect3>
	<title>Locale Setup</title>

	- <para>Put the following lines into your
	- <filename>~/.login_conf</filename> file:</para>
	+ <para>To set this locale, put the following lines into each
	+ user's <filename>~/.login_conf</filename>:</para>

	<programlisting>me:My Account:\
	:charset=KOI8-R:\
	:lang=ru_RU.KOI8-R:</programlisting>

	- <para>See earlier in this chapter for examples of setting
	- up the <link linkend="setting-locale">locale</link>.</para>
	</sect3>

	<sect3>
	<title>Console Setup</title>

	<itemizedlist>
	<listitem>
	- <para>Add the following line
	- to your <filename>/etc/rc.conf</filename> file:</para>
	-
	- <programlisting>mousechar_start=3</programlisting>
	- </listitem>
	-
	- <listitem>
	- <para>Also, use following settings in
	+ <para>Add the following lines to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>keymap="ru.koi8-r"
	scrnmap="koi8-r2cp866"
	font8x16="cp866b-8x16"
	font8x14="cp866-8x14"
	-font8x8="cp866-8x8"</programlisting>
	+font8x8="cp866-8x8"
	+mousechar_start=3</programlisting>

	</listitem>

	<listitem>
	- <para>For each <literal>ttyv*</literal> entry in
	+ <para>For each <literal>ttyv</literal> entry in
	<filename>/etc/ttys</filename>, use
	<literal>cons25r</literal> as the terminal type.</para>
	</listitem>
	</itemizedlist>
	-
	- <para>See earlier in this chapter for examples of setting up
	- the <link linkend="setting-console">console</link>.</para>
	</sect3>

	<sect3>
	<title>Printer Setup</title>

	<indexterm><primary>printers</primary></indexterm>
	<para>Since most printers with Russian characters come with
	hardware code page CP866, a special output filter is needed
	- to convert from KOI8-R to CP866. Such a filter is installed
	- by default as
	- <filename>/usr/libexec/lpr/ru/koi2alt</filename>. A
	- Russian printer <filename>/etc/printcap</filename> entry
	+ to convert from KOI8-R to CP866. &os; installs a default
	+ filter as <filename>/usr/libexec/lpr/ru/koi2alt</filename>.
	+ A Russian printer <filename>/etc/printcap</filename> entry
	should look like:</para>

	<programlisting>lp\|Russian local line printer:\
	:sh:of=/usr/libexec/lpr/ru/koi2alt:\
	:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:</programlisting>

	- <para>See &man.printcap.5; for a detailed description.</para>
	+ <para>Refer to &man.printcap.5; for a more detailed
	+ description.</para>
	</sect3>

	<sect3>
	- <title>&ms-dos; FS and Russian Filenames</title>
	+ <title>&ms-dos; and Russian Filenames</title>

	<para>The following example &man.fstab.5; entry enables
	support for Russian filenames in mounted &ms-dos;
	filesystems:</para>

	- <programlisting>/dev/ad0s2 /dos/c msdos rw,-Wkoi2dos,-Lru_RU.KOI8-R 0 0</programlisting>
	+ <programlisting>/dev/ad0s2 /dos/c msdos rw,-Lru_RU.KOI8-R 0 0</programlisting>

	- <para>The option <option>-L</option> selects the locale name
	- used, and <option>-W</option> sets the character conversion
	- table. To use the <option>-W</option> option, be sure to
	- mount <filename>/usr</filename> before the &ms-dos;
	- partition because the conversion tables are located in
	- <filename>/usr/libdata/msdosfs</filename>. For more
	- information, see the &man.mount.msdosfs.8; manual
	- page.</para>
	+ <para><option>-L</option> selects the locale name. Refer to
	+ &man.mount.msdosfs.8; for more details.</para>
	</sect3>

	<sect3>
	- <title>X11 Setup</title>
	+ <title><application>Xorg</application> Setup</title>

	<orderedlist>
	<listitem>
	- <para>Do <link linkend="setting-locale">non-X locale
	- setup</link> first as described.</para>
	+ <para>First, configure the <link
	+ linkend="setting-locale">non-X locale
	+ setup</link>.</para>
	</listitem>

	<listitem>
	- <para>If you use <application>&xorg;</application>,
	- install <filename
	+ <para>When using <application>&xorg;</application>,
	+ install the <filename
	role="package">x11-fonts/xorg-fonts-cyrillic</filename>
	package.</para>

	<para>Check the <literal>"Files"</literal> section in
	- your <filename>/etc/X11/xorg.conf</filename> file. The
	+ <filename>/etc/X11/xorg.conf</filename>. The
	following line must be added <emphasis>before</emphasis>
	any other <literal>FontPath</literal> entries:</para>

	<programlisting>FontPath "/usr/local/lib/X11/fonts/cyrillic"</programlisting>

	<note>
	- <para>See ports for more cyrillic fonts.</para>
	+ <para>Search the Ports Collection for more Cyrillic
	+ fonts.</para>
	</note>
	</listitem>

	<listitem>
	<para>To activate a Russian keyboard, add the following
	- to the <literal>"Keyboard"</literal> section of your
	- <filename>xorg.conf</filename> file:</para>
	+ to the <literal>"Keyboard"</literal> section of
	+ <filename>/etc/xorg.conf</filename>:</para>

	<programlisting>Option "XkbLayout" "us,ru"
	Option "XkbOptions" "grp:toggle"</programlisting>

	- <para>Also make sure that <literal>XkbDisable</literal> is
	- turned off (commented out) there.</para>
	+ <para>Make sure that <literal>XkbDisable</literal> is
	+ commented out in that file.</para>

	- <para>For <literal>grp:toggle</literal>
	- the RUS/LAT switch will be <keycap>Right Alt</keycap>,
	- for <literal>grp:ctrl_shift_toggle</literal> switch
	- will be <keycombo
	+ <para>For <literal>grp:toggle</literal> use <keycap>Right
	+ Alt</keycap>, for
	+ <literal>grp:ctrl_shift_toggle</literal> use <keycombo
	action="simul"><keycap>Ctrl</keycap><keycap>Shift</keycap></keycombo>.
	- For <literal>grp:caps_toggle</literal> the RUS/LAT
	- switch will be <keycap>CapsLock</keycap>. The old
	+ For <literal>grp:caps_toggle</literal> use
	+ <keycap>CapsLock</keycap>. The old
	<keycap>CapsLock</keycap> function is still available
	- via <keycombo
	- action="simul"><keycap>Shift</keycap><keycap>CapsLock</keycap></keycombo>
	- (in LAT mode only). <literal>grp:caps_toggle</literal>
	+ in LAT mode only using <keycombo
	+ action="simul"><keycap>Shift</keycap><keycap>CapsLock</keycap></keycombo>.
	+ <literal>grp:caps_toggle</literal>
	does not work in <application>&xorg;</application> for
	- unknown reason.</para>
	+ some unknown reason.</para>

	- <para>If you have <quote>&windows;</quote> keys on your
	- keyboard, and notice that some non-alphabetical keys
	- are mapped incorrectly in RUS mode, add the following
	- line in your <filename>xorg.conf</filename> file:</para>
	+ <para>If the keyboard has <quote>&windows;</quote> keys,
	+ and some non-alphabetical keys are mapped incorrectly,
	+ add the following line to
	+ <filename>/etc/xorg.conf</filename>:</para>

	<programlisting>Option "XkbVariant" ",winkeys"</programlisting>

	<note>
	<para>The Russian XKB keyboard may not work with
	non-localized applications.</para>
	</note>
	</listitem>
	</orderedlist>
	<note>
	- <para>Minimally localized applications
	- should call a <function>XtSetLanguageProc (NULL, NULL,
	- NULL);</function> function early in the program.</para>
	+ <para>Minimally localized applications should call a
	+ <function>XtSetLanguageProc (NULL, NULL, NULL);</function>
	+ function early in the program.</para>

	<para>See <ulink url="http://koi8.pp.ru/xwin.html">
	KOI8-R for X Window</ulink> for more instructions on
	- localizing X11 applications.</para>
	+ localizing <application>Xorg</application>
	+ applications.</para>
	</note>
	</sect3>
	</sect2>

	<sect2>
	<title>Traditional Chinese Localization for Taiwan</title>

	<indexterm>
	<primary>localization</primary>
	<secondary>Traditional Chinese</secondary>
	</indexterm>
	- <para>The FreeBSD-Taiwan Project has an Chinese HOWTO for
	- FreeBSD at <ulink
	+ <para>The &os;-Taiwan Project has a Chinese HOWTO for
	+ &os; at <ulink
	url="http://netlab.cse.yzu.edu.tw/~statue/freebsd/zh-tut/"></ulink>
	- using many Chinese ports. Current editor for the
	- <literal>FreeBSD Chinese HOWTO</literal> is Shen Chuan-Hsing
	+ using many Chinese ports. The current editor for the
	+ <literal>&os; Chinese HOWTO</literal> is Shen Chuan-Hsing
	<email>statue@freebsd.sinica.edu.tw</email>.</para>
	-
	- <para>Chuan-Hsing Shen
	- <email>statue@freebsd.sinica.edu.tw</email> has created the
	- <ulink url="http://netlab.cse.yzu.edu.tw/~statue/cfc/">
	- Chinese FreeBSD Collection (CFC)</ulink> using
	- FreeBSD-Taiwan's <literal>zh-L10N-tut</literal>. The packages
	- and the script files are available at <ulink
	- url="ftp://freebsd.csie.nctu.edu.tw/pub/taiwan/CFC/"></ulink>.</para>
	</sect2>

	<sect2>
	- <title>German Language Localization (for All ISO 8859-1
	- Languages)</title>
	+ <title>German Language Localization for All ISO 8859-1
	+ Languages</title>

	<indexterm>
	<primary>localization</primary>
	<secondary>German</secondary>
	</indexterm>

	<para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a
	- tutorial on using umlauts on a FreeBSD machine. The tutorial
	+ tutorial on using umlauts on &os;. The tutorial
	is written in German and is available at <ulink
	url="http://user.cs.tu-berlin.de/~eserte/FreeBSD/doc/umlaute/umlaute.html"></ulink>.</para>
	</sect2>

	<sect2>
	<title>Greek Language Localization</title>

	<indexterm>
	<primary>localization</primary>
	<secondary>Greek</secondary>
	</indexterm>
	<para>Nikos Kokkalis <email>nickkokkalis@gmail.com</email> has
	written a complete article on Greek support in &os;. It is
	- available as part of the official &os; Greek documentation, in
	- <ulink
	- url="&url.doc.base;/el_GR.ISO8859-7/articles/greek-language-support/index.html">http://www.freebsd.org/doc/el_GR.ISO8859-7/articles/greek-language-support/index.html</ulink>.
	- Please note this is in Greek <emphasis>only</emphasis>.</para>
	+ available <ulink
	+ url="&url.doc.base;/el_GR.ISO8859-7/articles/greek-language-
	+ support/ index.html">here</ulink>, in Greek only, as part of
	+ the official &os; Greek documentation.</para>
	</sect2>

	<sect2>
	<title>Japanese and Korean Language Localization</title>

	<indexterm>
	<primary>localization</primary>
	<secondary>Japanese</secondary>
	</indexterm>
	<indexterm>
	<primary>localization</primary>
	<secondary>Korean</secondary>
	</indexterm>
	<para>For Japanese, refer to
	<ulink url="http://www.jp.FreeBSD.org/"></ulink>,
	and for Korean, refer to
	<ulink url="http://www.kr.FreeBSD.org/"></ulink>.</para>
	</sect2>

	<sect2>
	- <title>Non-English FreeBSD Documentation</title>
	+ <title>Non-English &os; Documentation</title>

	- <para>Some FreeBSD contributors have translated parts of
	- FreeBSD documentation to other languages. They are available
	+ <para>Some &os; contributors have translated parts of the
	+ &os; documentation to other languages. They are available
	through links on the <ulink
	url="&url.base;/index.html">main site</ulink> or in
	- <filename>/usr/share/doc</filename>.</para>
	+ <filename class="directory">/usr/share/doc</filename>.</para>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml (revision 41355)
	@@ -1,1419 +1,1284 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="linuxemu">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Jim</firstname>
	<surname>Mock</surname>
	<contrib>Restructured and parts updated by </contrib>
	</author>
	<!-- 22 Mar 2000 -->
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Brian N.</firstname>
	<surname>Handy</surname>
	<contrib>Originally contributed by </contrib>
	</author>
	<author>
	<firstname>Rich</firstname>
	<surname>Murphey</surname>
	</author>
	</authorgroup>
	</chapterinfo>

	- <title>Linux Binary Compatibility</title>
	+ <title>&linux; Binary Compatibility</title>

	<sect1 id="linuxemu-synopsis">
	<title>Synopsis</title>

	<indexterm><primary>Linux binary
	compatibility</primary></indexterm>
	<indexterm>
	<primary>binary compatibility</primary>
	<secondary>Linux</secondary>
	</indexterm>

	- <para>FreeBSD provides binary compatibility with several other
	- &unix; like operating systems, including Linux. At this point,
	- you may be asking yourself why exactly, does
	- FreeBSD need to be able to run Linux binaries? The answer to
	- that question is quite simple. Many companies and developers
	- develop only for Linux, since it is the latest <quote>hot
	- thing</quote> in the computing world. That leaves the rest
	- of us FreeBSD users bugging these same companies and developers
	- to put out native FreeBSD versions of their applications. The
	- problem is, that most of these companies do not really realize
	- how many people would use their product if there were FreeBSD
	- versions too, and most continue to only develop for Linux.
	- So what is a FreeBSD user to do? This is where the Linux binary
	- compatibility of FreeBSD comes into play.</para>
	+ <para>&os; provides binary compatibility with &linux;, allowing
	+ users to install and run &linux; binaries on a &os; system.
	+ Many companies and developers develop only for &linux;, and
	+ binary compatibility allows &os; users to run about 90% of all
	+ &linux; applications without modification. This includes
	+ productivity applications, games, and more. It has even been
	+ reported that, in some situations, &linux; binaries perform
	+ better on &os; than they do on &linux;.</para>

	- <para>In a nutshell, the compatibility allows FreeBSD users to
	- run about 90% of all Linux applications without modification.
	- This includes applications such as
	- <application>&staroffice;</application>, the Linux version of
	- <application>&adobe; &acrobat;</application>,
	- <application>&realplayer;</application>,
	- <application>&oracle;</application>,
	- <application>Doom</application>,
	- <application>Quake</application>, and more. It is also reported
	- that in some situations, Linux binaries perform better on
	- FreeBSD than they do under Linux.</para>
	-
	- <para>There are, however, some Linux-specific operating system
	- features that are not supported under FreeBSD. Linux binaries
	- will not work on FreeBSD if they overly use &i386; specific
	+ <para>However, some &linux;-specific operating system features
	+ are not supported under &os;. For example, &linux; binaries
	+ will not work on &os; if they overly use &i386; specific
	calls, such as enabling virtual 8086 mode.</para>

	<para>After reading this chapter, you will know:</para>
	<itemizedlist>
	<listitem>
	- <para>How to enable Linux binary compatibility on your
	+ <para>How to enable &linux; binary compatibility on a &os;
	system.</para>
	</listitem>

	<listitem>
	- <para>How to install additional Linux shared
	+ <para>How to install additional &linux; shared
	libraries.</para>
	</listitem>

	<listitem>
	- <para>How to install Linux applications on your FreeBSD
	+ <para>How to install &linux; applications on a &os;
	system.</para>
	</listitem>

	<listitem>
	- <para>The implementation details of Linux compatibility in
	- FreeBSD.</para>
	+ <para>The implementation details of &linux; compatibility in
	+ &os;.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	- <para>Know how to install additional third-party
	- software (<xref linkend="ports"/>).</para>
	+ <para>Know how to install <link linkend="ports">additional
	+ third-party software</link>.</para>
	</listitem>
	</itemizedlist>

	</sect1>

	<sect1 id="linuxemu-lbc-install">
	<title>Installation</title>

	- <indexterm><primary>KLD (kernel loadable
	- object)</primary></indexterm>
	+ <indexterm><primary>Ports Collection</primary></indexterm>

	- <para>Linux binary compatibility is not turned on by default. The
	- easiest way to enable this functionality is to load the
	- <literal>linux</literal> KLD object (<quote>Kernel LoaDable
	- object</quote>). You can load this module by typing the
	- following as <username>root</username>:</para>
	+ <para>&linux; libararies are not installed on &os; by default
	+ and &linux; binary compatibility is not enabled by default.
	+ &linux; libraries can be installed using the &os; Ports
	+ Collection. Alternately, &linux; libraries can be installed
	+ <link linkend="linuxemu-libs-manually">manually</link>.</para>

	- <screen>&prompt.root; <userinput>kldload linux</userinput></screen>
	+ <para>Using the Ports Collection is by far the easiest way to
	+ install &linux; libraries:</para>

	- <para>If you would like Linux compatibility to always be enabled,
	- then you should add the following line to
	+ <screen>&prompt.root; <userinput>cd
	+/usr/ports/emulators/linux_base-f10</userinput> &prompt.root; <userinput>make install distclean</userinput></screen>
	+
	+ <para>Once the port is installed, enable &linux; binary
	+ compatibility by loading the <literal>linux</literal>
	+ module. Type the following as
	+ <username>root</username>:</para>
	+
	+ <screen>&prompt.root; <userinput>kldload linux</userinput></screen>
	+
	+ <para>In order for &linux; compatibility to always be enabled at
	+ boot time, add the following line to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>linux_enable="YES"</programlisting>

	- <para>The &man.kldstat.8; command can be used to verify that the
	- KLD is loaded:</para>
	+ <para>To verify that the module is loaded, use
	+ &man.kldstat.8;:</para>

	<screen>&prompt.user; <userinput>kldstat</userinput>
	Id Refs Address Size Name
	1 2 0xc0100000 16bdb8 kernel
	7 1 0xc24db000 d000 linux.ko</screen>

	<indexterm>
	<primary>kernel options</primary>
	<secondary>COMPAT_LINUX</secondary>
	</indexterm>

	- <para>If for some reason you do not want to or cannot load the
	- KLD, then you may statically link Linux binary compatibility
	- into the kernel by adding <literal>options
	- COMPAT_LINUX</literal> to your kernel configuration file.
	- Then install your new kernel as described in
	- <xref linkend="kernelconfig"/>.</para>
	+ <para>Users who prefer to statically link &linux; binary
	+ compatibility into the kernel should add <literal>options
	+ COMPAT_LINUX</literal> to the custom kernel configuration
	+ file. Compile and install the new kernel as described in <link
	+ linkend="kernelconfig"></link>.</para>

	- <sect2>
	- <title>Installing Linux Runtime Libraries</title>
	+ <sect2 id="linuxemu-libs-manually">
	+ <title>Installing Libraries Manually</title>

	- <indexterm>
	- <primary>Linux</primary>
	- <secondary>installing Linux libraries</secondary>
	- </indexterm>
	+ <para>While using the Ports Collection is recommended, &linux;
	+ libraries can be installed manually. The &linux; shared
	+ libraries required by a program and the runtime linker
	+ should be copied to <filename
	+ class="directory">/compat/linux</filename>. Any shared
	+ libraries opened by &linux; programs run under &os; will
	+ look in this directory first. For example, if a &linux;
	+ program loads <filename>/lib/libc.so</filename>, &os; will
	+ first try to open
	+ <filename>/compat/linux/lib/libc.so</filename>, and if that
	+ does not exist, it will then try
	+ <filename>/lib/libc.so</filename>. Shared libraries should
	+ be installed to <filename
	+ class="directory">/compat/linux/lib</filename> rather than
	+ to the paths that the &linux; <command>ld.so</command>
	+ reports.</para>

	- <para>This can be done one of two ways, either by using the
	- <link linkend="linuxemu-libs-port">linux_base</link> port, or
	- by installing them <link
	- linkend="linuxemu-libs-manually">manually</link>.</para>
	+ <para>Generally, one will need to look for the shared
	+ libraries that &linux; binaries depend on only the first few
	+ times that a &linux; program is installed on &os;. After a
	+ while, there will be a sufficient set of &linux; shared
	+ libraries on the system to be able to run newly imported
	+ &linux; binaries without any extra work.</para>

	- <sect3 id="linuxemu-libs-port">
	- <title>Installing Using the linux_base Port</title>
	-
	- <indexterm><primary>Ports Collection</primary></indexterm>
	-
	- <para>This is by far the easiest method to use when installing
	- the runtime libraries. It is just like installing any other
	- port from the <link linkend="ports">Ports
	- Collection</link>:</para>
	-
	- <screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base-f10</userinput>
	-&prompt.root; <userinput>make install distclean</userinput></screen>
	-
	- <note>
	- <para>On &os; systems prior to &os; 8.0, you will have
	- to use the <filename
	- role="package">emulators/linux_base-fc4</filename> port
	- instead of <filename
	- role="package">emulators/linux_base-f10</filename>.</para>
	- </note>
	-
	- <para>You should now have working Linux binary compatibility.
	- Some programs may complain about incorrect minor versions
	- of the system libraries. In general, however, this does
	- not seem to be a problem.</para>
	-
	- <note><para>There may be multiple versions of the <filename
	- role="package">emulators/linux_base</filename> port
	- available, corresponding to different versions of various
	- Linux distributions. You should install the port most
	- closely resembling the requirements of the Linux
	- applications you would like to install.</para></note>
	-
	- </sect3>
	-
	- <sect3 id="linuxemu-libs-manually">
	- <title>Installing Libraries Manually</title>
	-
	- <para>If you do not have the <quote>ports</quote> collection
	- installed, you can install the libraries by hand instead.
	- You will need the Linux shared libraries that the program
	- depends on and the runtime linker. Also, you will need to
	- create a <quote>shadow root</quote> directory,
	- <filename>/compat/linux</filename>, for Linux libraries
	- on your FreeBSD system. Any shared libraries opened by
	- Linux programs run under FreeBSD will look in this tree
	- first. So, if a Linux program loads, for example,
	- <filename>/lib/libc.so</filename>, FreeBSD will first try
	- to open <filename>/compat/linux/lib/libc.so</filename>,
	- and if that does not exist, it will then try
	- <filename>/lib/libc.so</filename>. Shared libraries should
	- be installed in the shadow tree
	- <filename>/compat/linux/lib</filename> rather than the paths
	- that the Linux <command>ld.so</command> reports.</para>
	-
	- <para>Generally, you will need to look for the shared
	- libraries that Linux binaries depend on only the first few
	- times that you install a Linux program on your FreeBSD
	- system. After a while, you will have a sufficient set of
	- Linux shared libraries on your system to be able to run
	- newly imported Linux binaries without any extra work.</para>
	- </sect3>
	-
	<sect3>
	<title>How to Install Additional Shared Libraries</title>

	<indexterm><primary>shared libraries</primary></indexterm>

	- <para>What if you install the <filename>linux_base</filename>
	- port and your application still complains about missing
	- shared libraries? How do you know which shared libraries
	- Linux binaries need, and where to get them? Basically,
	- there are 2 possibilities (when following these instructions
	- you will need to be <username>root</username> on your
	- FreeBSD system).</para>
	+ <para>If the <literal>linux_base</literal> port is installed
	+ and an application still complains about missing shared
	+ libraries, there are two methods <username>root</username>
	+ can use to determine which shared libraries the &linux;
	+ binaries need.</para>

	- <para>If you have access to a Linux system, see what shared
	- libraries the application needs, and copy them to your
	- FreeBSD system. Look at the following example:</para>
	+ <para>If a &linux; system is available, determine which shared
	+ libraries the application needs, and copy them to the &os;
	+ system.</para>

	<informalexample>
	- <para>Let us assume you used FTP to get the Linux binary
	- of <application>Doom</application>, and put it on a Linux
	- system you have access to. You then can check which
	- shared libraries it needs by running
	- <command>ldd linuxdoom</command>, like so:</para>
	+ <para>In this example, FTP was used to download the &linux;
	+ binary of <application>Doom</application> on a &linux;
	+ system . To check which shared libraries it needs, run
	+ <command>ldd linuxdoom</command>:</para>

	<screen>&prompt.user; <userinput>ldd linuxdoom</userinput>
	libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0
	libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0
	libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29</screen>

	<indexterm><primary>symbolic links</primary></indexterm>
	- <para>You would need to get all the files from the last
	- column, and put them under
	- <filename>/compat/linux</filename>, with the names in
	- the first column as symbolic links pointing to them.
	- This means you eventually have these files on your
	- FreeBSD system:</para>
	+ <para>Copy all the files in the last column into
	+ <filename class="directory">/compat/linux</filename> on
	+ the &os; system, with the names in the first column as
	+ symbolic links pointing to them. This example will result
	+ in the following files on the &os; system:</para>

	<screen>/compat/linux/usr/X11/lib/libXt.so.3.1.0
	/compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0
	/compat/linux/usr/X11/lib/libX11.so.3.1.0
	/compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0
	/compat/linux/lib/libc.so.4.6.29
	/compat/linux/lib/libc.so.4 -> libc.so.4.6.29</screen>

	<blockquote>
	<note>
	- <para>Note that if you already have a Linux shared
	- library with a matching major revision number to the
	- first column of the <command>ldd</command> output,
	- you will not need to copy the file named in the last
	- column to your system, the one you already have should
	- work. It is advisable to copy the shared library
	- anyway if it is a newer version, though. You can
	- remove the old one, as long as you make the symbolic
	- link point to the new one. So, if you have these
	- libraries on your system:</para>
	+ <para>If a &linux; shared library already exists with a
	+ matching major revision number to the first column of
	+ the <command>ldd</command> output, it does not need to
	+ be copied to the file named in the last column, as the
	+ existing library should work. It is advisable to copy
	+ the shared library if it is a newer version, though.
	+ The old one can be removed, as long as the symbolic
	+ link points to the new one. For example, these
	+ libraries exist on the system:</para>

	<screen>/compat/linux/lib/libc.so.4.6.27
	/compat/linux/lib/libc.so.4 -> libc.so.4.6.27</screen>

	- <para>and you find a new binary that claims to require a
	- later version according to the output of
	+ <para>and a binary claims to require a later version
	+ according to the output of
	<command>ldd</command>:</para>

	<screen>libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29</screen>

	<para>If it is only one or two versions out of date
	- in the trailing digit then do not worry about copying
	- <filename>/lib/libc.so.4.6.29</filename> too, because
	+ in the trailing digit, do not worry about copying
	+ <filename>/lib/libc.so.4.6.29</filename>, because
	the program should work fine with the slightly older
	- version. However, if you like, you can decide to
	- replace the <filename>libc.so</filename> anyway, and
	- that should leave you with:</para>
	+ version. However, it is safe to replace the
	+ <filename>libc.so</filename>:</para>

	<screen>/compat/linux/lib/libc.so.4.6.29
	/compat/linux/lib/libc.so.4 -> libc.so.4.6.29</screen>
	</note>
	</blockquote>

	<blockquote>
	<note>
	<para>The symbolic link mechanism is
	- <emphasis>only</emphasis> needed for Linux binaries.
	- The FreeBSD runtime linker takes care of looking for
	- matching major revision numbers itself and you do not
	- need to worry about it.</para>
	+ <emphasis>only</emphasis> needed for &linux; binaries
	+ as the &os; runtime linker takes care of looking for
	+ matching major revision numbers.</para>
	</note>
	</blockquote>
	</informalexample>
	</sect3>
	</sect2>

	<sect2>
	- <title>Installing Linux ELF Binaries</title>
	+ <title>Installing &linux; ELF Binaries</title>

	<indexterm>
	<primary>Linux</primary>
	<secondary>ELF binaries</secondary>
	</indexterm>

	<para>ELF binaries sometimes require an extra step of
	- <quote>branding</quote>. If you attempt to run an unbranded
	- ELF binary, you will get an error message like the
	+ <quote>branding</quote>. If an unbranded ELF binary is
	+ executed, it will generate an error message like the
	following:</para>

	<screen>&prompt.user; <userinput>./my-linux-elf-binary</userinput>
	ELF binary type not known
	Abort</screen>

	- <para>To help the FreeBSD kernel distinguish between a FreeBSD
	- ELF binary and a Linux binary, use the &man.brandelf.1;
	- utility.</para>
	+ <para>To help the &os; kernel distinguish between a &os;
	+ ELF binary and a &linux; binary, use &man.brandelf.1;:</para>

	<screen>&prompt.user; <userinput>brandelf -t Linux my-linux-elf-binary</userinput></screen>

	<indexterm><primary>GNU toolchain</primary></indexterm>
	- <para>The GNU toolchain now places the appropriate branding
	- information into ELF binaries automatically, so this step
	- should become increasingly unnecessary in the future.</para>
	+ <para>Since the GNU toolchain places the appropriate branding
	+ information into ELF binaries automatically, this step is
	+ usually not necessary.</para>
	</sect2>

	<sect2>
	- <title>Installing a Random Linux RPM Based Application</title>
	+ <title>Installing a &linux; RPM Based Application</title>

	- <para>FreeBSD has its own package database and it is used to
	- track all ports (&linux; ports as well). So the &linux; RPM
	- database is not used (not supported).</para>
	+ <para>&os; uses its own package database to track all software
	+ installed from the Ports Collection. However, the &linux; RPM
	+ database is not supported.</para>

	- <para>However if you need to install a random &linux;
	- RPM-based application it can be achieved by:</para>
	+ <para>In order to install a &linux; RPM-based application, first
	+ install the <filename
	+ role="package">archivers/rpm2cpio</filename> package or
	+ port. Once installed, <username>root</username> can use this
	+ command to install a <filename>.rpm</filename> as
	+ follows:</para>

	<screen>&prompt.root; <userinput>cd /compat/linux</userinput>
	&prompt.root; <userinput>rpm2cpio -q < /path/to/linux.archive.rpm \| cpio -id</userinput></screen>

	- <para>Then brandelf installed ELF binaries (not libraries!).
	- You will not be able to do a clean uninstall, but it may
	- help you to do tests.</para>
	+ <para>If necessary, <command>brandelf</command> the installed
	+ ELF binaries, but <emphasis>not</emphasis> the libraries.
	+ Note that this will prevent a clean uninstall.</para>
	</sect2>

	<sect2>
	<title>Configuring the Hostname Resolver</title>

	- <para>If DNS does not work or you get this message:</para>
	+ <para>If DNS does not work or this error appears:</para>

	<screen>resolv+: "bind" is an invalid keyword resolv+:
	"hosts" is an invalid keyword</screen>

	- <para>You will need to configure a
	- <filename>/compat/linux/etc/host.conf</filename> file
	- containing:</para>
	+ <para>Configure
	+ <filename>/compat/linux/etc/host.conf</filename> as
	+ follows:</para>

	<programlisting>order hosts, bind
	multi on</programlisting>

	- <para>The order here specifies that
	+ <para>This order specifies that
	<filename>/etc/hosts</filename> is searched first and DNS
	is searched second. When
	- <filename>/compat/linux/etc/host.conf</filename> is not
	- installed, Linux applications find FreeBSD's
	+ <filename>/compat/linux/etc/host.conf</filename> does not
	+ exist, &linux; applications use
	<filename>/etc/host.conf</filename> and complain about the
	- incompatible FreeBSD syntax. You should remove
	- <literal>bind</literal> if you have not configured a name
	- server using the <filename>/etc/resolv.conf</filename>
	- file.</para>
	+ incompatible &os; syntax. Remove
	+ <literal>bind</literal> if a name server is not configured
	+ using <filename>/etc/resolv.conf</filename>.</para>
	</sect2>
	</sect1>

	<sect1 id="linuxemu-mathematica">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Boris</firstname>
	<surname>Hollas</surname>
	<contrib>Updated for Mathematica 5.X by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Installing &mathematica;</title>

	<indexterm>
	<primary>applications</primary>
	<secondary><application>Mathematica</application></secondary>
	</indexterm>

	- <para>This document describes the process of installing the Linux
	- version of <application>&mathematica; 5.X</application> onto
	- a FreeBSD system.</para>
	+ <para>This section describes the process of installing the
	+ &linux; version of <application>&mathematica; 5.X</application>
	+ onto a &os; system. <application>&mathematica;</application>
	+ is a commercial, computational software program used in
	+ scientific, engineering, and mathematical fields. It is
	+ available from <ulink
	+ url="http://www.wolfram.com/mathematica/">Wolfram
	+ Research</ulink>.</para>

	- <para>The Linux version of
	- <application>&mathematica;</application>
	- or <application>&mathematica; for Students</application> can
	- be ordered directly from Wolfram at
	- <ulink url="http://www.wolfram.com/"></ulink>.</para>
	-
	<sect2>
	<title>Running the &mathematica; Installer</title>

	- <para>First, you have to tell &os; that
	- <application>&mathematica;</application>'s Linux
	- binaries use the Linux ABI. The easiest way to do so is to
	- set the default ELF brand
	- to Linux for all unbranded binaries with the command:</para>
	+ <para>First, tell &os; that
	+ <application>&mathematica;</application>'s &linux;
	+ binaries use the &linux; Application Binary Interface
	+ <acronym>ABI</acronym>. The easiest way to do this is to
	+ set the default ELF brand to &linux; for all unbranded
	+ binaries with the command:</para>

	<screen>&prompt.root; <userinput>sysctl kern.fallback_elf_brand=3</userinput></screen>

	- <para>This will make &os; assume that unbranded ELF binaries
	- use the Linux ABI and so you should be able to run the
	- installer straight from the CDROM.</para>
	+ <para>&os; will now assume that unbranded ELF binaries
	+ use the &linux; <acronym>ABI</acronym> which should allow the
	+ installer to execute from the CDROM.</para>

	- <para>Now, copy the file <filename>MathInstaller</filename> to
	- your hard drive:</para>
	+ <para>Copy the <filename>MathInstaller</filename> to the hard
	+ drive:</para>

	<screen>&prompt.root; <userinput>mount /cdrom</userinput>
	&prompt.root; <userinput>cp /cdrom/Unix/Installers/Linux/MathInstaller /localdir/</userinput></screen>

	- <para>and in this file, replace <literal>/bin/sh</literal> in
	- the first line by <literal>/compat/linux/bin/sh</literal>.
	- This makes sure that the installer is executed by the Linux
	+ <para>In this file, replace <literal>/bin/sh</literal> in
	+ the first line with <literal>/compat/linux/bin/sh</literal>.
	+ This ensures that the installer is executed by the &linux;
	version of &man.sh.1;. Next, replace all occurrences of
	- <literal>Linux)</literal> by <literal>FreeBSD)</literal> with
	- a text editor or the script below in the next section. This
	- tells the <application>&mathematica;</application> installer,
	- who calls <command>uname -s</command> to determine the
	- operating system, to treat &os; as a Linux-like operating
	- system. Invoking <command>MathInstaller</command> will now
	+ <literal>Linux)</literal> with <literal>FreeBSD)</literal>
	+ using a text editor or the script below in the next section.
	+ This tells the <application>&mathematica;</application>
	+ installer, to treat &os; as a &linux;-like operating
	+ system. Invoking <command>MathInstaller</command> should now
	install <application>&mathematica;</application>.</para>
	</sect2>

	<sect2>
	<title>Modifying the &mathematica; Executables</title>

	<para>The shell scripts that
	<application>&mathematica;</application> created during
	- installation have to be modified before you can use them.
	- If you chose <filename
	+ installation have to be modified before use. When using
	+ <filename
	class="directory">/usr/local/bin</filename> as the directory
	- to place the
	- <application>&mathematica;</application> executables in, you
	- will find symlinks in this directory to files called
	- <filename>math</filename>, <filename>mathematica</filename>,
	+ for the <application>&mathematica;</application>
	+ executables, symlinks in this directory will point to files
	+ called <filename>math</filename>,
	+ <filename>mathematica</filename>,
	<filename>Mathematica</filename>, and
	<filename>MathKernel</filename>. In each of these, replace
	- <literal>Linux)</literal> by <literal>FreeBSD)</literal> with
	- a text editor or the following shell script:</para>
	+ <literal>Linux)</literal> with <literal>FreeBSD)</literal>
	+ using a text editor or the following shell script:</para>

	<programlisting>#!/bin/sh
	cd /usr/local/bin
	for i in math mathematica Mathematica MathKernel
	do sed 's/Linux)/FreeBSD)/g' $i > $i.tmp
	sed 's/\/bin\/sh/\/compat\/linux\/bin\/sh/g' $i.tmp > $i
	rm $i.tmp
	chmod a+x $i
	done</programlisting>
	</sect2>

	<sect2>
	- <title>Obtaining Your &mathematica; Password</title>
	+ <title>Obtaining a &mathematica; Password</title>

	<indexterm>
	<primary>Ethernet</primary>
	<secondary>MAC address</secondary>
	</indexterm>

	- <para>When you start <application>&mathematica;</application>
	- for the first time, you will be asked for a password. If you
	- have not yet obtained a password from Wolfram, run the program
	+ <para>When <application>&mathematica;</application> is started
	+ for the first time, it will ask for a password. If a password
	+ had not yet been obtained from Wolfram Research, run
	<command>mathinfo</command> in the installation directory to
	- obtain your <quote>machine ID</quote>. This machine ID is
	- based solely on the MAC address of your first Ethernet card,
	- so you cannot run your copy of
	- <application>&mathematica;</application> on different
	- machines.</para>
	+ obtain the <quote>machine ID</quote>. This machine ID is
	+ based solely on the MAC address of the first Ethernet card,
	+ as the copy of <application>&mathematica;</application> cannot
	+ run on different machines.</para>

	- <para>When you register with Wolfram, either by email, phone
	- or fax, you will give them the <quote>machine ID</quote> and
	- they will respond with a corresponding password consisting
	- of groups of numbers.</para>
	+ <para>When registering with Wolfram Research, provide the
	+ <quote>machine ID</quote> and they will respond with a
	+ corresponding password consisting of groups of numbers.</para>
	</sect2>

	<sect2>
	<title>Running the &mathematica; Frontend over a Network</title>

	<para><application>&mathematica;</application> uses some special
	- fonts to display characters not
	- present in any of the standard font sets (integrals, sums,
	- Greek letters, etc.). The X protocol requires these fonts
	- to be install <emphasis>locally</emphasis>. This means you
	- will have to copy these fonts from the CDROM or from a host
	- with <application>&mathematica;</application> installed to
	- your local machine. These fonts are normally stored in
	- <filename>/cdrom/Unix/Files/SystemFiles/Fonts</filename> on
	- the CDROM, or
	- <filename>/usr/local/mathematica/SystemFiles/Fonts</filename>
	- on your hard drive. The actual fonts are in the
	- subdirectories <filename>Type1</filename> and
	- <filename>X</filename>. There are several ways to use them,
	- as described below.</para>
	+ fonts to display characters not present in any of the standard
	+ font sets. <application>Xorg</application> requires these
	+ fonts to be installed locally. This means that these fonts
	+ need to be copied from the CDROM or from a host with
	+ <application>&mathematica;</application> installed to the
	+ local machine. These fonts are normally stored in
	+ <filename
	+ class="directory">/cdrom/Unix/Files/SystemFiles/Fonts</filename>
	+ on the CDROM, or <filename
	+ class="directory">/usr/local/mathematica/SystemFiles/Fonts</filename>
	+ on the hard drive. The actual fonts are in the subdirectories
	+ <filename class="directory">Type1</filename> and
	+ <filename class="directory">X</filename>. There are several
	+ ways to use them, as described below.</para>

	- <para>The first way is to copy them into one of the existing
	- font directories in
	- <filename>/usr/X11R6/lib/X11/fonts</filename>. This will
	- require editing the <filename>fonts.dir</filename> file,
	- adding the font names to it, and changing the number of fonts
	- on the first line. Alternatively, you should also just be
	- able to run &man.mkfontdir.1; in the directory you have copied
	- them to.</para>
	+ <para>The first way is to copy the fonts into one of the
	+ existing font directories in <filename
	+ class="directory">/usr/local/lib/X11/fonts</filename> then
	+ running &man.mkfontdir.1; within the directory containing the
	+ new fonts.</para>

	<para>The second way to do this is to copy the directories to
	- <filename>/usr/X11R6/lib/X11/fonts</filename>:</para>
	+ <filename
	+ class="directory">/usr/local/lib/X11/fonts</filename>:</para>

	- <screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts</userinput>
	+ <screen>&prompt.root; <userinput>cd /usr/local/lib/X11/fonts</userinput>
	&prompt.root; <userinput>mkdir X</userinput>
	&prompt.root; <userinput>mkdir MathType1</userinput>
	&prompt.root; <userinput>cd /cdrom/Unix/Files/SystemFiles/Fonts</userinput>
	-&prompt.root; <userinput>cp X/* /usr/X11R6/lib/X11/fonts/X</userinput>
	-&prompt.root; <userinput>cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1</userinput>
	-&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/X</userinput>
	+&prompt.root; <userinput>cp X/* /usr/local/lib/X11/fonts/X</userinput>
	+&prompt.root; <userinput>cp Type1/* /usr/local/lib/X11/fonts/MathType1</userinput>
	+&prompt.root; <userinput>cd /usr/local/lib/X11/fonts/X</userinput>
	&prompt.root; <userinput>mkfontdir</userinput>
	&prompt.root; <userinput>cd ../MathType1</userinput>
	&prompt.root; <userinput>mkfontdir</userinput></screen>

	- <para>Now add the new font directories to your font path:</para>
	+ <para>Now add the new font directories to the font path:</para>

	- <screen>&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/X</userinput>
	-&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/MathType1</userinput>
	+ <screen>&prompt.root; <userinput>xset fp+ /usr/local/lib/X11/fonts/X</userinput>
	+&prompt.root; <userinput>xset fp+ /usr/local/lib/X11/fonts/MathType1</userinput>
	&prompt.root; <userinput>xset fp rehash</userinput></screen>

	- <para>If you are using the <application>&xorg;</application>
	- server, you can have these font directories loaded
	- automatically by adding them to your
	- <filename>xorg.conf</filename> file.</para>
	+ <para>When using the <application>&xorg;</application> server,
	+ these font directories can be loaded automatically by adding
	+ them to <filename>/etc/X11/xorg.conf</filename>.</para>

	<indexterm><primary>fonts</primary></indexterm>

	- <para>If you <emphasis>do not</emphasis> already have a
	- directory called
	- <filename>/usr/X11R6/lib/X11/fonts/Type1</filename>, you
	- can change the name of the <filename>MathType1</filename>
	- directory in the example above to
	- <filename>Type1</filename>.</para>
	+ <para>If <filename
	+ class="directory">/usr/local/lib/X11/fonts/Type1</filename>
	+ does not already exist, change the name of the <filename
	+ class="directory">MathType1</filename> directory in the
	+ example above to <filename
	+ class="directory">Type1</filename>.</para>
	</sect2>
	</sect1>

	<sect1 id="linuxemu-maple">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Aaron</firstname>
	<surname>Kaplan</surname>
	<!-- <address><email>aaron@lo-res.org</email></address>-->
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Robert</firstname>
	<surname>Getschmann</surname>
	<!-- <address><email>rob@getschmann.org</email></address>-->
	<contrib>Thanks to </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Installing &maple;</title>

	<indexterm>
	<primary>applications</primary>
	<secondary><application>Maple</application></secondary>
	</indexterm>

	<para><application>&maple;</application> is a commercial
	mathematics program similar to
	- <application>&mathematica;</application>. You must purchase
	- this software from <ulink
	- url="http://www.maplesoft.com/"></ulink> and then register
	- there for a license file. To install this software on FreeBSD,
	- please follow these simple steps.</para>
	+ <application>&mathematica;</application>. This software must be
	+ purchased and licensed from <ulink
	+ url="http://www.maplesoft.com/products/maple/">Maplesoft</ulink>.
	+ To install the &linux; version of this software on &os;, follow
	+ these steps.</para>

	<procedure>
	<step><para>Execute the <filename>INSTALL</filename> shell
	script from the product distribution. Choose the
	<quote>RedHat</quote> option when prompted by the
	installation program. A typical installation directory
	might be <filename
	class="directory">/usr/local/maple</filename>.</para></step>

	- <step><para>If you have not done so, order a license for
	- <application>&maple;</application> from Maple Waterloo
	- Software (<ulink
	- url="http://register.maplesoft.com/"></ulink>) and copy it
	- to
	- <filename>/usr/local/maple/license/license.dat</filename>.</para></step>
	+ <step>
	+ <para>Copy the license to
	+ <filename>/usr/local/maple/license/license.dat</filename>.</para>
	+ </step>

	- <step><para>Install the <application>FLEXlm</application>
	- license manager by running the
	+ <step>
	+ <para>Install the <application>FLEXlm</application> license
	+ manager by running the
	<filename>INSTALL_LIC</filename> install shell script that
	- comes with <application>&maple;</application>. Specify the
	- primary hostname for your machine for the license
	- server.</para></step>
	+ comes with <application>&maple;</application>. Specify
	+ the primary hostname for the machine for the license
	+ server.</para>
	+ </step>

	- <step><para>Patch the
	+ <step>
	+ <para>Patch
	<filename>/usr/local/maple/bin/maple.system.type</filename>
	- file with the following:</para>
	+ with the following:</para>
	+
	<programlisting> ----- snip ------------------
	*** maple.system.type.orig Sun Jul 8 16:35:33 2001
	--- maple.system.type Sun Jul 8 16:35:51 2001
	***************
	* 72,77 **
	--- 72,78 ----
	# the IBM RS/6000 AIX case
	MAPLE_BIN="bin.IBM_RISC_UNIX"
	;;
	+ "FreeBSD"\|\
	"Linux")
	# the Linux/x86 case
	# We have two Linux implementations, one for Red Hat and
	----- snip end of patch -----</programlisting>

	- <para>Please note that after the
	- <literal>"FreeBSD"\|\</literal> no other whitespace should
	- be present.</para>
	+ <para>Note that no whitespace should be present after
	+ <literal>"FreeBSD"\|\</literal>.</para>

	<para>This patch instructs <application>&maple;</application>
	- to recognize <quote>FreeBSD</quote> as a type of Linux
	+ to recognize &os; as a type of &linux;
	system. The <filename>bin/maple</filename> shell script
	calls the <filename>bin/maple.system.type</filename> shell
	script which in turn calls <command>uname -a</command> to
	find out the operating system name. Depending on the OS
	name it will find out which binaries to use.</para></step>

	<step><para>Start the license server.</para>

	<para>The following script, installed as
	<filename>/usr/local/rtc/rc.d/lmgrd</filename> is a
	convenient way to start up <command>lmgrd</command>:</para>

	<programlisting> ----- snip ------------

	#! /bin/sh
	-PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin
	+PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
	PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX
	export PATH

	LICENSE_FILE=/usr/local/maple/license/license.dat
	LOG=/var/log/lmgrd.log

	case "$1" in
	start)
	lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2
	echo -n " lmgrd"
	;;
	stop)
	lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2
	;;
	*)
	echo "Usage: `basename $0` {start\|stop}" 1>&2
	exit 64
	;;
	esac

	exit 0
	----- snip ------------</programlisting></step>


	- <step><para>Test-start
	- <application>&maple;</application>:</para>
	+ <step><para>Test that
	+ <application>&maple;</application> starts:</para>

	<screen>&prompt.user; <userinput>cd /usr/local/maple/bin</userinput>
	&prompt.user; <userinput>./xmaple</userinput></screen>

	- <para>You should be up and running. Make sure to write
	- Maplesoft to let them know you would like a native FreeBSD
	+ <para>Once everything is working, consider writing
	+ Maplesoft to let them know you would like a native &os;
	version!</para></step>
	</procedure>

	<sect2>
	<title>Common Pitfalls</title>

	<itemizedlist>
	- <listitem><para>The <application>FLEXlm</application>
	- license manager can be a difficult tool to work with.
	- Additional documentation on the subject can be found at
	- <ulink
	- url="http://www.globetrotter.com/"></ulink>.</para></listitem>
	-
	- <listitem><para><command>lmgrd</command> is known to be very
	- picky about the license file and to core dump if there
	+ <listitem><para><command>lmgrd</command> is known to be
	+ picky about the license file and to dump core if there
	are any problems. A correct license file should look
	like this:</para>

	<programlisting>#
	=======================================================
	# License File for UNIX Installations ("Pointer File")
	# =======================================================
	SERVER chillig ANY
	#USE_SERVER
	VENDOR maplelmg

	FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \
	PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \
	ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \
	SN=XXXXXXXXX</programlisting>

	- <note><para>Serial number and key 'X''ed out.
	- <hostid>chillig</hostid> is a hostname.</para></note>
	+ <note>
	+ <para>In this example, the serial number and key were
	+ replaced with <literal>X</literal>.
	+ <hostid>chillig</hostid> is the hostname.</para>
	+ </note>

	- <para>Editing the license file works as long as you do not
	- touch the <quote>FEATURE</quote> line (which is protected
	- by the license key).</para></listitem>
	+ <para>Editing the license file works as long as the
	+ <quote>FEATURE</quote> line is not edited. That line is
	+ protected by the license key.</para></listitem>
	</itemizedlist>
	</sect2>
	</sect1>

	<sect1 id="linuxemu-matlab">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Dan</firstname>
	<surname>Pelleg</surname>
	<contrib>Contributed by </contrib>
	</author>
	<!-- daniel+handbook@pelleg.org -->
	</authorgroup>
	</sect1info>
	<title>Installing &matlab;</title>

	<indexterm>
	<primary>applications</primary>
	<secondary><application>MATLAB</application></secondary>
	</indexterm>

	- <para>This document describes the process of installing the Linux
	- version of <application>&matlab; version 6.5</application> onto
	- a &os; system. It works quite well, with the exception of the
	- <application>&java.virtual.machine;</application> (see
	- <xref linkend="matlab-jre"/>).</para>
	+ <para>This document describes the process of installing the
	+ &linux; version of <application>&matlab; version
	+ 6.5</application> onto a &os; system. It works quite well,
	+ with the exception of the
	+ <application>&java.virtual.machine;</application> which is
	+ described further in <link linkend="matlab-jre"></link>.</para>

	- <para>The Linux version of <application>&matlab;</application>
	- can be ordered directly from The MathWorks at <ulink
	- url="http://www.mathworks.com"></ulink>. Make sure you also
	- get the license file or instructions how to create it. While
	- you are there, let them know you would like a native &os;
	- version of their software.</para>
	+ <para>The &linux; version of <application>&matlab;</application>
	+ can be purchased and licensed from <ulink
	+ url="http://www.mathworks.com/products/matlab/">
	+ MathWorks</ulink>. Consider letting the company know that
	+ you would like a native &os; version of this software.</para>

	<sect2>
	<title>Installing &matlab;</title>

	- <para>To install <application>&matlab;</application>, do the
	- following:</para>
	+ <para>To install <application>&matlab;</application>:</para>

	<procedure>
	<step>
	- <para>Insert the installation CD and mount it.
	- Become <username>root</username>, as recommended by the
	- installation script. To start the installation script
	- type:</para>
	+ <para>Become <username>root</username>, as recommended by
	+ the installation script. Insert the installation CD and
	+ mount it. To start the installation script type:</para>

	<screen>&prompt.root; <userinput>/compat/linux/bin/sh /cdrom/install</userinput></screen>

	<tip>
	- <para>The installer is graphical. If you get errors about
	- not being able to open a display, type
	- <command>setenv HOME
	+ <para>The installer is graphical. If it is not able to
	+ open a display, type <command>setenv HOME
	~<replaceable>USER</replaceable></command>,
	- where <replaceable>USER</replaceable> is the user you
	- did a &man.su.1; as.</para>
	+ where <replaceable>USER</replaceable> is the user who
	+ ran &man.su.1;.</para>
	</tip>
	</step>

	<step>
	<para>
	When asked for the <application>&matlab;</application>
	root directory, type:
	<userinput>/compat/linux/usr/local/matlab</userinput>.</para>

	<tip>
	<para>For easier typing on the rest of the installation
	- process, type this at your shell prompt:
	- <command>set
	- MATLAB=/compat/linux/usr/local/matlab</command></para>
	+ process, type this at the shell prompt: <command>set
	+ MATLAB=/compat/linux/usr/local/matlab</command>.</para>
	</tip>
	</step>

	<step>
	- <para>Edit the license file as instructed when
	- obtaining the <application>&matlab;</application>
	- license.</para>
	+ <para>Edit the license file as instructed when obtaining
	+ the <application>&matlab;</application> license.</para>

	<tip>
	- <para>You can prepare this file in advance using your
	- favorite editor, and copy it to
	+ <para>This file can be prepared in advance using an
	+ editor, and copied to
	<filename>$MATLAB/license.dat</filename> before the
	- installer asks you to edit it.</para>
	+ installer asks to edit it.</para>
	</tip>
	</step>

	<step>
	<para>Complete the installation process.</para>
	</step>
	</procedure>

	- <para>At this point your <application>&matlab;</application>
	+ <para>At this point the <application>&matlab;</application>
	installation is complete. The following steps apply
	- <quote>glue</quote> to connect it to your &os; system.</para>
	+ <quote>glue</quote> to connect it to the &os; system.</para>
	</sect2>

	<sect2>
	<title>License Manager Startup</title>

	<procedure>
	<step>
	<para>Create symlinks for the license manager
	scripts:</para>

	<screen>&prompt.root; <userinput>ln -s $MATLAB/etc/lmboot /usr/local/etc/lmboot_TMW</userinput>
	&prompt.root; <userinput>ln -s $MATLAB/etc/lmdown /usr/local/etc/lmdown_TMW</userinput></screen>
	</step>

	<step>
	- <para>Create a startup file at
	+ <para>Create a startup file named
	<filename>/usr/local/etc/rc.d/flexlm</filename>. The
	example below is a modified version of the distributed
	<filename>$MATLAB/etc/rc.lm.glnx86</filename>. The
	- changes are file locations, and startup of the license
	- manager under Linux emulation.</para>
	+ changes are file locations and startup of the license
	+ manager under &linux; emulation.</para>

	<programlisting>#!/bin/sh
	case "$1" in
	start)
	if [ -f /usr/local/etc/lmboot_TMW ]; then
	/compat/linux/bin/sh /usr/local/etc/lmboot_TMW -u <replaceable>username</replaceable> && echo 'MATLAB_lmgrd'
	fi
	;;
	stop)
	if [ -f /usr/local/etc/lmdown_TMW ]; then
	/compat/linux/bin/sh /usr/local/etc/lmdown_TMW > /dev/null 2>&1
	fi
	;;
	*)
	echo "Usage: $0 {start\|stop}"
	exit 1
	;;
	esac

	exit 0</programlisting>

	<important>
	<para>The file must be made executable:</para>

	<screen>&prompt.root; <userinput>chmod +x /usr/local/etc/rc.d/flexlm</userinput></screen>

	- <para>You must also replace
	- <replaceable>username</replaceable> above with the name
	- of a valid user on your system (and not
	- <username>root</username>).</para>
	+ <para>Replace <replaceable>username</replaceable> with the
	+ name of a valid user on the system which is not
	+ <username>root</username>.</para>
	</important>
	</step>

	<step>
	<para>Start the license manager with the command:</para>

	<screen>&prompt.root; <userinput>service flexlm start</userinput></screen>
	</step>
	</procedure>
	</sect2>

	<sect2 id="matlab-jre">
	<title>Linking the &java; Runtime Environment</title>

	<para>Change the <application>&java;</application> Runtime
	- Environment (JRE) link to one working under &os;:</para>
	+ Environment (<acronym>JRE</acronym>) link to one working under
	+ &os;:</para>

	<screen>&prompt.root; <userinput>cd $MATLAB/sys/java/jre/glnx86/</userinput>
	&prompt.root; <userinput>unlink jre; ln -s ./jre1.1.8 ./jre</userinput></screen>
	</sect2>

	<sect2>
	<title>Creating a &matlab; Startup Script</title>

	<procedure>
	<step>
	<para>Place the following startup script in
	- <filename>/usr/local/bin/matlab</filename>:</para>
	+ <filename
	+ class="directory">/usr/local/bin/matlab</filename>:</para>

	<programlisting>#!/bin/sh
	/compat/linux/bin/sh /compat/linux/usr/local/matlab/bin/matlab "$@"</programlisting>
	</step>

	<step>
	- <para>Then type the command
	+ <para>Then, type the command
	<command>chmod +x /usr/local/bin/matlab</command>.</para>
	</step>
	</procedure>

	<tip>
	- <para>Depending on your version of
	- <filename role="package">emulators/linux_base</filename>,
	- you may run into errors when running this script. To avoid
	- that, edit the file
	+ <para>Depending on the version of <filename
	+ role="package">emulators/linux_base</filename>, running
	+ this script may result in errors. To avoid errors, edit
	<filename>/compat/linux/usr/local/matlab/bin/matlab</filename>,
	and change the line that says:</para>

	<programlisting>if [ `expr "$lscmd" : '.->.'` -ne 0 ]; then</programlisting>

	- <para>(in version 13.0.1 it is on line 410) to this
	- line:</para>
	+ <para>to this line:</para>

	<programlisting>if test -L $newbase; then</programlisting>
	</tip>
	</sect2>

	<sect2>
	<title>Creating a &matlab; Shutdown Script</title>

	<para>The following is needed to solve a problem with &matlab;
	not exiting correctly.</para>

	<procedure>
	<step>
	- <para>Create a file
	- <filename>$MATLAB/toolbox/local/finish.m</filename>, and
	- in it put the single line:</para>
	+ <para>Create
	+ <filename>$MATLAB/toolbox/local/finish.m</filename>
	+ containing the single line:</para>

	<programlisting>! $MATLAB/bin/finish.sh</programlisting>

	<note><para>The <literal>$MATLAB</literal> is
	literal.</para></note>

	<tip>
	- <para>In the same directory, you will find the files
	+ <para>The same directory contains
	<filename>finishsav.m</filename> and
	- <filename>finishdlg.m</filename>, which let you save
	- your workspace before quitting. If you use either of
	- them, insert the line above immediately after the
	+ <filename>finishdlg.m</filename>, which allow the
	+ workspace to be saved before quitting. If either file
	+ is used, insert the line above immediately after the
	<literal>save</literal> command.</para></tip>
	</step>

	<step>
	- <para>Create a file
	- <filename>$MATLAB/bin/finish.sh</filename>, which will
	- contain the following:</para>
	+ <para>Create
	+ <filename>$MATLAB/bin/finish.sh</filename> which
	+ contains the following:</para>

	<programlisting>#!/compat/linux/bin/sh
	(sleep 5; killall -1 matlab_helper) &
	exit 0</programlisting>
	</step>

	<step>
	<para>Make the file executable:</para>

	<screen>&prompt.root; <userinput>chmod +x $MATLAB/bin/finish.sh</userinput></screen>
	</step>
	</procedure>
	</sect2>

	<sect2 id="matlab-using">
	<title>Using &matlab;</title>

	- <para>At this point you are ready to type
	- <command>matlab</command> and start using it.</para>
	+ <para>At this point, <command>matlab</command> is ready for
	+ use.</para>
	</sect2>
	</sect1>

	<sect1 id="linuxemu-oracle">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Marcel</firstname>
	<surname>Moolenaar</surname>
	<contrib>Contributed by </contrib>
	</author>
	<!-- marcel@cup.hp.com -->
	</authorgroup>
	</sect1info>
	<title>Installing &oracle;</title>

	<indexterm>
	<primary>applications</primary>
	<secondary><application>Oracle</application></secondary>
	</indexterm>

	- <sect2>
	- <title>Preface</title>
	+ <para>This document describes the process of installing
	+ <application>&oracle; 8.0.5</application> and
	+ <application>&oracle; 8.0.5.1 Enterprise Edition</application>
	+ for &linux; onto a &os; machine.</para>

	- <para>This document describes the process of installing
	- <application>&oracle; 8.0.5</application> and
	- <application>&oracle; 8.0.5.1 Enterprise Edition</application>
	- for Linux onto a FreeBSD machine.</para>
	- </sect2>
	-
	<sect2>
	- <title>Installing the Linux Environment</title>
	+ <title>Installing the &linux; Environment</title>

	- <para>Make sure you have both <filename
	+ <para>Make sure both <filename
	role='package'>emulators/linux_base</filename> and
	<filename role='package'>devel/linux_devtools</filename>
	- from the Ports Collection installed. If you run into
	- difficulties with these ports, you may have to use the
	- packages or older versions available in the Ports
	- Collection.</para>
	+ are installed from the Ports Collection.</para>

	- <para>If you want to run the intelligent agent, you will
	- also need to install the Red Hat Tcl package:
	- <filename>tcl-8.0.3-20.i386.rpm</filename>. The general
	- command for installing packages with the official
	- <application>RPM</application> port (<filename
	- role='package'>archivers/rpm</filename>) is:</para>
	+ <para>To run the intelligent agent, install the Red Hat Tcl
	+ package: <filename>tcl-8.0.3-20.i386.rpm</filename>. The
	+ general command for installing RPMs with the <filename
	+ role='package'>archivers/rpm</filename> port is:</para>

	<screen>&prompt.root; <userinput>rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <replaceable>package</replaceable></userinput></screen>

	- <para>Installation of the <replaceable>package</replaceable>
	- should not generate any errors.</para>
	+ <para>This command should not generate any errors.</para>
	</sect2>

	<sect2>
	<title>Creating the &oracle; Environment</title>

	- <para>Before you can install
	- <application>&oracle;</application>, you need to set up a
	- proper environment. This document only describes what to do
	- <emphasis>specially</emphasis> to run
	- <application>&oracle;</application> for Linux on FreeBSD, not
	- what has been described in the
	+ <para>Before installing <application>&oracle;</application>, set
	+ up a proper environment. This section only describes how to
	+ install <application>&oracle;</application> for &linux; on
	+ &os;, not what has been described in the
	<application>&oracle;</application> installation guide.</para>

	<sect3 id="linuxemu-kernel-tuning">
	<title>Kernel Tuning</title>

	<indexterm><primary>kernel tuning</primary></indexterm>

	<para>As described in the <application>&oracle;</application>
	- installation guide, you need to set the maximum size of
	- shared memory. Do not use <literal>SHMMAX</literal> under
	- FreeBSD. <literal>SHMMAX</literal> is merely calculated
	- out of <literal>SHMMAXPGS</literal> and
	- <literal>PGSIZE</literal>. Therefore define
	+ installation guide, the maximum size of shared memory needs
	+ to be set. Do not use <literal>SHMMAX</literal> under &os;
	+ as it is calculated from <literal>SHMMAXPGS</literal> and
	+ <literal>PGSIZE</literal>. Therefore, define
	<literal>SHMMAXPGS</literal>. All other options can be
	used as described in the guide. For example:</para>

	<programlisting>options SHMMAXPGS=10000
	options SHMMNI=100
	options SHMSEG=10
	options SEMMNS=200
	options SEMMNI=70
	options SEMMSL=61</programlisting>

	- <para>Set these options to suit your intended use of
	+ <para>Set these options to suit the intended use of
	<application>&oracle;</application>.</para>

	- <para>Also, make sure you have the following options in your
	+ <para>Also, make sure the following options are in the
	kernel configuration file:</para>

	<programlisting>options SYSVSHM #SysV shared memory
	options SYSVSEM #SysV semaphores
	options SYSVMSG #SysV interprocess communication</programlisting>
	</sect3>

	<sect3 id="linuxemu-oracle-account">

	<title>&oracle; Account</title>

	- <para>Create an <username>oracle</username> account just as
	- you would create any other account. The
	- <username>oracle</username> account is special only that
	- you need to give it a Linux shell. Add
	+ <para>Create a user account to be used as the
	+ <username>oracle</username> account. Add
	<literal>/compat/linux/bin/bash</literal> to
	<filename>/etc/shells</filename> and set the shell for
	the <username>oracle</username> account to
	<filename>/compat/linux/bin/bash</filename>.</para>
	</sect3>

	<sect3 id="linuxemu-environment">
	<title>Environment</title>

	<para>Besides the normal <application>&oracle;</application>
	variables, such as <envar>ORACLE_HOME</envar> and
	- <envar>ORACLE_SID</envar> you must set the following
	+ <envar>ORACLE_SID</envar> set the following
	environment variables:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<colspec colwidth="1*"/>
	<colspec colwidth="2*"/>
	<thead>
	<row>
	<entry>Variable</entry>

	<entry>Value</entry>
	</row>
	</thead>
	<tbody>
	<row>
	<entry><envar>LD_LIBRARY_PATH</envar></entry>

	<entry><literal>$ORACLE_HOME/lib</literal></entry>
	</row>

	<row>
	<entry><envar>CLASSPATH</envar></entry>

	<entry><literal>$ORACLE_HOME/jdbc/lib/classes111.zip</literal></entry>
	</row>

	<row>
	<entry><envar>PATH</envar></entry>

	<entry><literal>/compat/linux/bin
	/compat/linux/sbin
	/compat/linux/usr/bin
	/compat/linux/usr/sbin
	/bin
	/sbin
	/usr/bin
	/usr/sbin
	/usr/local/bin
	- $ORACLE_HOME/bin</literal></entry>
	+ $ORACLE_HOME/bin</literal></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>It is advised to set all the environment variables in
	- <filename>.profile</filename>. A complete example
	- is:</para>
	+ <filename>~/.profile</filename> as follows:</para>

	<programlisting>ORACLE_BASE=/oracle; export ORACLE_BASE
	ORACLE_HOME=/oracle; export ORACLE_HOME
	LD_LIBRARY_PATH=$ORACLE_HOME/lib
	export LD_LIBRARY_PATH
	ORACLE_SID=ORCL; export ORACLE_SID
	ORACLE_TERM=386x; export ORACLE_TERM
	CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip
	export CLASSPATH
	PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin
	PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin
	PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin
	export PATH</programlisting>
	</sect3>
	</sect2>

	<sect2>
	<title>Installing &oracle;</title>

	- <para>Due to a slight inconsistency in the Linux emulator,
	- you need to create a directory named
	- <filename>.oracle</filename> in <filename>/var/tmp</filename>
	- before you start the installer. Let it be owned by the
	- <username>oracle</username> user. You should be able to
	- install <application>&oracle;</application> without any
	- problems. If you have problems, check your
	- <application>&oracle;</application> distribution and/or
	- configuration first! After you have installed
	- <application>&oracle;</application>, apply the patches
	- described in the next two subsections.</para>
	+ <para>Before starting the installer, create a directory named
	+ <filename class="directory">/var/tmp/.oracle</filename> which
	+ is owned by the <username>oracle</username> user. The
	+ installation of <application>&oracle;</application> should
	+ work without any problems. If errors are encountered, check
	+ the <application>&oracle;</application> distribution and
	+ configuration. Once <application>&oracle;</application> is
	+ installed, apply the patches described in the next two
	+ subsections.</para>

	- <para>A frequent problem is that the TCP protocol adapter is
	- not installed right. As a consequence, you cannot start any
	- TCP listeners. The following actions help solve this
	+ <para>A frequent error is that the TCP protocol adapter is not
	+ installed correctly. As a consequence, no TCP listeners can
	+ be started. The following actions help to solve this
	problem:</para>

	<screen>&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
	&prompt.root; <userinput>make -f ins_network.mk ntcontab.o</userinput>
	&prompt.root; <userinput>cd $ORACLE_HOME/lib</userinput>
	&prompt.root; <userinput>ar r libnetwork.a ntcontab.o</userinput>
	&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
	&prompt.root; <userinput>make -f ins_network.mk install</userinput></screen>

	- <para>Do not forget to run <filename>root.sh</filename>
	- again!</para>
	+ <para>Do not forget to run <filename>root.sh</filename>
	+ again.</para>

	<sect3 id="linuxemu-patch-root">
	- <title>Patching root.sh</title>
	+ <title>Patching <filename>root.sh</filename></title>

	<para>When installing <application>&oracle;</application>,
	some actions, which need to be performed as
	<username>root</username>, are recorded in a shell script
	called <filename>root.sh</filename>. This script is
	- written in the <filename>orainst</filename> directory.
	- Apply the following patch to <filename>root.sh</filename>,
	- to have it use to proper location of
	- <command>chown</command> or alternatively run the script
	- under a Linux native shell.</para>
	+ found in <filename class="directory">orainst</filename>.
	+ Apply the following patch to <filename>root.sh</filename>
	+ so that it can find the &os; location of
	+ <command>chown</command>. Alternatively, run the script
	+ under a &linux; native shell.</para>

	<programlisting>*** orainst/root.sh.orig Tue Oct 6 21:57:33 1998
	--- orainst/root.sh Mon Dec 28 15:58:53 1998
	***************
	* 31,37 **
	# This is the default value for CHOWN
	# It will redefined later in this script for those ports
	# which have it conditionally defined in ss_install.h
	! CHOWN=/bin/chown
	#
	# Define variables to be used in this script
	--- 31,37 ----
	# This is the default value for CHOWN
	# It will redefined later in this script for those ports
	# which have it conditionally defined in ss_install.h
	! CHOWN=/usr/sbin/chown
	#
	# Define variables to be used in this script</programlisting>

	- <para>When you do not install
	- <application>&oracle;</application> from CD, you can patch
	- the source for <filename>root.sh</filename>. It is called
	- <filename>rthd.sh</filename> and is located in the
	- <filename>orainst</filename> directory in the source
	+ <para>If <application>&oracle;</application> is not installed
	+ from CD, patch the source for <filename>root.sh</filename>.
	+ It is called <filename>rthd.sh</filename> and is located in
	+ <filename class="directory">orainst</filename> in the source
	tree.</para>
	</sect3>

	<sect3 id="linuxemu-patch-tcl">
	- <title>Patching genclntsh</title>
	+ <title>Patching <filename>genclntsh</filename></title>

	<para>The script <command>genclntsh</command> is used to
	- create a single shared client library. It is used when
	- building the demos. Apply the following patch to comment
	- out the definition of <envar>PATH</envar>:</para>
	+ create a single shared client library when building the
	+ demos. Apply the following patch to comment out the
	+ definition of <envar>PATH</envar>:</para>

	<programlisting>*** bin/genclntsh.orig Wed Sep 30 07:37:19 1998
	--- bin/genclntsh Tue Dec 22 15:36:49 1998
	***************
	* 32,38 **
	#
	# Explicit path to ensure that we're using the correct commands
	#PATH=/usr/bin:/usr/ccs/bin export PATH
	-! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
	+! PATH=/usr/local/bin:/bin:/usr/bin export PATH
	#
	# each product MUST provide a $PRODUCT/admin/shrept.lst
	--- 32,38 ----
	#
	# Explicit path to ensure that we're using the correct commands
	#PATH=/usr/bin:/usr/ccs/bin export PATH
	-! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
	+! #PATH=/usr/local/bin:/bin:/usr/bin: export PATH
	#
	# each product MUST provide a $PRODUCT/admin/shrept.lst</programlisting>
	</sect3>
	</sect2>

	<sect2>
	<title>Running &oracle;</title>

	- <para>When you have followed the instructions, you should be
	- able to run <application>&oracle;</application> as if it was
	- run on Linux itself.</para>
	+ <para>After following these instructions,
	+ <application>&oracle;</application> should run as if it was
	+ running on &linux;.</para>
	</sect2>
	</sect1>

	<sect1 id="linuxemu-advanced">
	<title>Advanced Topics</title>

	- <para>If you are curious as to how the Linux binary compatibility
	- works, this is the section you want to read. Most of what
	- follows is based heavily on an email written to &a.chat; by
	+ <para>This section describes how &linux; binary compatibility
	+ works and is based on an email written to &a.chat; by
	Terry Lambert <email>tlambert@primenet.com</email> (Message ID:
	<literal><199906020108.SAA07001@usr09.primenet.com></literal>).</para>

	- <sect2>
	- <title>How Does It Work?</title>
	+ <indexterm><primary>execution class loader</primary></indexterm>

	- <indexterm><primary>execution class loader</primary></indexterm>
	+ <para>&os; has an abstraction called an <quote>execution class
	+ loader</quote>. This is a wedge into the &man.execve.2;
	+ system call.</para>

	- <para>FreeBSD has an abstraction called an <quote>execution
	- class loader</quote>. This is a wedge into the
	- &man.execve.2; system call.</para>
	+ <para>Historically, the &unix; loader examined the magic number
	+ (generally the first 4 or 8 bytes of the file) to see if it was
	+ a binary known to the system, and if so, invoked the binary
	+ loader.</para>

	- <para>What happens is that FreeBSD has a list of loaders,
	- instead of a single loader with a fallback to the
	- <literal>#!</literal> loader for running any shell
	- interpreters or shell scripts.</para>
	+ <para>If it was not the binary type for the system, the
	+ &man.execve.2; call returned a failure, and the shell
	+ attempted to start executing it as shell commands. The
	+ assumption was a default of <quote>whatever the current shell
	+ is</quote>.</para>

	- <para>Historically, the only loader on the &unix; platform
	- examined the magic number (generally the first 4 or 8 bytes
	- of the file) to see if it was a binary known to the system,
	- and if so, invoked the binary loader.</para>
	+ <para>Later, a hack was made for &man.sh.1; to examine the first
	+ two characters, and if they were <literal>:\n</literal>, it
	+ invoked the &man.csh.1; shell instead.</para>

	- <para>If it was not the binary type for the system, the
	- &man.execve.2; call returned a failure, and the shell
	- attempted to start executing it as shell commands.</para>
	+ <para>&os; has a list of loaders, instead of a single loader, with
	+ a fallback to the <literal>#!</literal> loader for running shell
	+ interpreters or shell scripts.</para>

	- <para>The assumption was a default of <quote>whatever the
	- current shell is</quote>.</para>
	+ <indexterm><primary>ELF</primary></indexterm>

	- <para>Later, a hack was made for &man.sh.1; to examine the
	- first two characters, and if they were <literal>:\n</literal>,
	- then it invoked the &man.csh.1; shell instead (we believe SCO
	- first made this hack).</para>
	+ <indexterm><primary>Solaris</primary></indexterm>

	- <para>What FreeBSD does now is go through a list of loaders,
	- with a generic <literal>#!</literal> loader that knows about
	- interpreters as the characters which follow to the next
	- whitespace next to last, followed by a fallback to
	- <filename>/bin/sh</filename>.</para>
	- <indexterm><primary>ELF</primary></indexterm>
	+ <para>For the &linux; <acronym>ABI</acronym> support, &os; sees
	+ the magic number as an ELF binary. The ELF loader looks for a
	+ specialized <emphasis>brand</emphasis>, which is a comment
	+ section in the ELF image, and which is not present on
	+ SVR4/&solaris; ELF binaries.</para>

	- <para>For the Linux ABI support, FreeBSD sees the magic number
	- as an ELF binary (it makes no distinction between FreeBSD,
	- &solaris;, Linux, or any other OS which has an ELF image type,
	- at this point).</para>
	- <indexterm><primary>Solaris</primary></indexterm>
	+ <para>For &linux; binaries to function, they must be
	+ <emphasis>branded</emphasis> as type <literal>Linux</literal>
	+ using &man.brandelf.1;:</para>

	- <para>The ELF loader looks for a specialized
	- <emphasis>brand</emphasis>, which is a comment section in
	- the ELF image, and which is not present on SVR4/&solaris;
	- ELF binaries.</para>
	+ <screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen>

	- <para>For Linux binaries to function, they must be
	- <emphasis>branded</emphasis> as type <literal>Linux</literal>
	- from &man.brandelf.1;:</para>
	-
	- <screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen>
	-
	- <para>When this is done, the ELF loader will see the
	- <literal>Linux</literal> brand on the file.</para>
	<indexterm>
	<primary>ELF</primary>
	<secondary>branding</secondary>
	</indexterm>

	<para>When the ELF loader sees the <literal>Linux</literal>
	brand, the loader replaces a pointer in the
	<literal>proc</literal> structure. All system calls are
	- indexed through this pointer (in a traditional &unix; system,
	- this would be the <literal>sysent[]</literal> structure array,
	- containing the system calls). In addition, the process is
	+ indexed through this pointer. In addition, the process is
	flagged for special handling of the trap vector for the signal
	trampoline code, and several other (minor) fix-ups that are
	- handled by the Linux kernel module.</para>
	+ handled by the &linux; kernel module.</para>

	- <para>The Linux system call vector contains, among other
	+ <para>The &linux; system call vector contains, among other
	things, a list of <literal>sysent[]</literal> entries whose
	addresses reside in the kernel module.</para>

	- <para>When a system call is called by the Linux binary, the
	+ <para>When a system call is called by the &linux; binary, the
	trap code dereferences the system call function pointer off
	- the <literal>proc</literal> structure, and gets the Linux,
	- not the FreeBSD, system call entry points.</para>
	+ the <literal>proc</literal> structure, and gets the &linux;,
	+ not the &os;, system call entry points.</para>

	- <para>In addition, the Linux mode dynamically
	- <emphasis>reroots</emphasis> lookups; this is, in effect,
	- what the <option>union</option> option to file system mounts
	- (<emphasis>not</emphasis> the <literal>unionfs</literal>
	- file system type!) does. First, an attempt is made to lookup
	- the file in the
	- <filename>/compat/linux/<replaceable>original-path</replaceable></filename>
	- directory, <emphasis>then</emphasis> only if that fails, the
	- lookup is done in the
	- <filename>/<replaceable>original-path</replaceable></filename>
	- directory. This makes sure that binaries that require other
	- binaries can run (e.g., the Linux toolchain can all run under
	- Linux ABI support). It also means that the Linux binaries
	- can load and execute FreeBSD binaries, if there are no
	- corresponding Linux binaries present, and that you could place
	- a &man.uname.1; command in the
	- <filename>/compat/linux</filename> directory tree to ensure
	- that the Linux binaries could not tell they were not running
	- on Linux.</para>
	+ <para>&linux; mode dynamically <emphasis>reroots</emphasis>
	+ lookups. This is, in effect, equivalent to the
	+ <option>union</option> option to file system mounts. First,
	+ an attempt is made to lookup the file in <filename
	+ class="directory">/compat/linux/<replaceable>original-path</replaceable></filename>.
	+ If that fails, the lookup is done in
	+ <filename
	+ class="directory">/<replaceable>original-path</replaceable></filename>.
	+ This makes sure that binaries that require other binaries can
	+ run. For example, the &linux; toolchain can all run under
	+ &linux; <acronym>ABI</acronym> support. It also means that
	+ the &linux; binaries can load and execute &os; binaries, if
	+ there are no corresponding &linux; binaries present, and that
	+ a &man.uname.1; command can be placed in the
	+ <filename class="directory">/compat/linux</filename> directory
	+ tree to ensure that the &linux; binaries can not tell they are
	+ not running on &linux;.</para>

	- <para>In effect, there is a Linux kernel in the FreeBSD kernel;
	- the various underlying functions that implement all of the
	+ <para>In effect, there is a &linux; kernel in the &os; kernel.
	+ The various underlying functions that implement all of the
	services provided by the kernel are identical to both the
	- FreeBSD system call table entries, and the Linux system call
	+ &os; system call table entries, and the &linux; system call
	table entries: file system operations, virtual memory
	- operations, signal delivery, System V IPC, etc… The
	- only difference is that FreeBSD binaries get the FreeBSD
	- <emphasis>glue</emphasis> functions, and Linux binaries get
	- the Linux <emphasis>glue</emphasis> functions (most older OS's
	- only had their own <emphasis>glue</emphasis> functions:
	- addresses of functions in a static global
	- <literal>sysent[]</literal> structure array, instead of
	- addresses of functions dereferenced off a dynamically
	- initialized pointer in the <literal>proc</literal> structure
	- of the process making the call).</para>
	+ operations, signal delivery, and System V IPC. The only
	+ difference is that &os; binaries get the &os;
	+ <emphasis>glue</emphasis> functions, and &linux; binaries get
	+ the &linux; <emphasis>glue</emphasis> functions. The &os;
	+ <emphasis>glue</emphasis> functions are statically linked into
	+ the kernel, and the &linux; <emphasis>glue</emphasis>
	+ functions can be statically linked, or they can be accessed
	+ via a kernel module.</para>

	- <para>Which one is the native FreeBSD ABI? It does not matter.
	- Basically the only difference is that (currently; this could
	- easily be changed in a future release, and probably will be
	- after this) the FreeBSD <emphasis>glue</emphasis> functions
	- are statically linked into the kernel, and the Linux
	- <emphasis>glue</emphasis> functions can be statically linked,
	- or they can be accessed via a kernel module.</para>
	-
	- <para>Yeah, but is this really emulation? No. It is an ABI
	- implementation, not an emulation. There is no emulator (or
	- simulator, to cut off the next question) involved.</para>
	-
	- <para>So why is it sometimes called <quote>Linux
	- emulation</quote>? To make it hard to sell FreeBSD!
	- Really, it is because the historical implementation was done
	- at a time when there was really no word other than that to
	- describe what was going on; saying that FreeBSD ran Linux
	- binaries was not true, if you did not compile the code in or
	- load a module, and there needed to be a word to describe what
	- was being loaded—hence <quote>the Linux
	- emulator</quote>.</para>
	- </sect2>
	- </sect1>
	-</chapter>
	+ <para>Technically, this is not really emulation, it is an
	+ <acronym>ABI</acronym> implementation. It is sometimes called
	+ <quote>&linux; emulation</quote> because the implementation
	+ was done at a time when there was no other word to describe
	+ what was going on. Saying that &os; ran &linux; binaries was
	+ not true, since the code was not compiled in.</para>
	+ </sect1>
	+ </chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml (revision 41355)
	@@ -1,3347 +1,2689 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<appendix id="mirrors">
	<title>Obtaining &os;</title>

	<sect1 id="mirrors-cdrom">
	<title>CDROM and DVD Publishers</title>

	<sect2>
	<title>CD and DVD Sets</title>

	<para>&os; CD and DVD sets are available from many online
	retailers:</para>

	<itemizedlist>
	<listitem>
	<address>
	<otheraddr>&os; Mall, Inc.</otheraddr>
	<street>2420 Sand Creek Rd C-1 #347</street>
	<city>Brentwood</city>,
	<state>CA</state>
	<postcode>94513</postcode>
	<country>USA</country>
	Phone: <phone>+1 925 240-6652</phone>
	Fax: <fax>+1 925 674-0821</fax>
	Email: <email>info@freebsdmall.com</email>
	WWW: <otheraddr><ulink
	url="http://www.freebsdmall.com/"></ulink></otheraddr>
	</address>
	</listitem>

	<listitem>
	<address>
	<otheraddr>Dr. Hinner EDV</otheraddr>
	<street>Kochelseestr. 11</street>
	<postcode>D-81371</postcode> <city>München</city>
	<country>Germany</country>
	Phone: <phone>(0177) 428 419 0</phone>
	WWW: <otheraddr><ulink
	url="http://www.hinner.de/linux/freebsd.html"></ulink></otheraddr>
	</address>
	</listitem>

	<listitem>
	<address>
	<otheraddr>Linux Distro UK</otheraddr>
	<street>42 Wharfedale Road</street>
	<city>Margate</city>
	<postcode>CT9 2TB</postcode>
	<country>United Kingdom</country>
	WWW: <otheraddr><ulink
	url="https://linux-distro.co.uk/"></ulink></otheraddr>
	</address>
	</listitem>

	<listitem>
	<address>
	<otheraddr>The Linux Emporium</otheraddr>
	<street>The Techno Centre, Puma Way</street>
	<city>Parkside</city>
	<postcode>CV1 2TT</postcode>
	<country>United Kingdom</country>
	Phone: <phone>+44 (0)247 615 8121</phone>
	Fax: <fax>+44 1491 837016</fax>
	WWW: <otheraddr><ulink
	url="http://www.linuxemporium.co.uk/products/bsd/"></ulink></otheraddr>
	</address>
	</listitem>

	<listitem>
	<address>
	<otheraddr>LinuxCenter.Ru</otheraddr>
	<street>Galernaya Street, 55</street>
	<city>Saint-Petersburg</city>
	<postcode>190000</postcode>
	<country>Russia</country>
	Phone: <phone>+7-812-3125208</phone>
	Email: <email>info@linuxcenter.ru</email>
	WWW: <otheraddr><ulink
	url="http://linuxcenter.ru/shop/freebsd"></ulink></otheraddr>
	</address>
	</listitem>
	</itemizedlist>
	</sect2>
	</sect1>

	<sect1 id="mirrors-ftp">
	<title>FTP Sites</title>

	<para>The official sources for &os; are available via anonymous
	FTP from a worldwide set of mirror sites. The site
	<ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/"></ulink> is well
	connected and allows a large number of connections to it, but
	you are probably better off finding a <quote>closer</quote>
	mirror site (especially if you decide to set up some sort of
	mirror site).</para>

	<para>Additionally, &os; is available via anonymous FTP from the
	following mirror sites. If you choose to obtain &os; via
	anonymous FTP, please try to use a site near you. The mirror
	sites listed as <quote>Primary Mirror Sites</quote> typically
	have the entire &os; archive (all the currently available
	versions for each of the architectures) but you will probably
	have faster download times from a site that is in your country
	or region. The regional sites carry the most recent versions
	for the most popular architecture(s) but might not carry the
	entire &os; archive. All sites provide access via anonymous FTP
	but some sites also provide access via other methods. The
	access methods available for each site are provided in
	parentheses after the hostname.</para>

	&chap.mirrors.ftp.inc;
	</sect1>

	<sect1 id="mirrors-bittorrent">
	<title>BitTorrent</title>

	<indexterm>
	<primary>BitTorrent</primary>
	</indexterm>

	<para>The ISO images for the basic release CDs are available via
	BitTorrent. A collection of torrent files to download the
	images is available at <ulink
	url="http://torrents.freebsd.org:8080/">http://torrents.freebsd.org:8080</ulink></para>

	<para>The BitTorrent client software is available from the
	<filename role="package">net-p2p/py-bittorrent</filename> port,
	or a precompiled package.</para>

	<para>After downloading the ISO image with BitTorrent, you may
	burn it to CD or DVD media as described in
	<xref linkend="burncd"/>, burncd.</para>
	</sect1>


	<sect1 id="anoncvs">
	<title>Anonymous CVS (Deprecated)</title>

	<sect2>
	<title>Warning</title>

	<warning>
	<para>CVS has been deprecated by the project, and its use is
	- not recommended. <application>Subversion</application>
	+ not recommended.
	+ <ulink url="&url.books.handbook;/svn.html">Subversion</ulink>
	should be used instead.</para>
	</warning>
	</sect2>
	</sect1>

	<sect1 id="ctm">
	<title>Using CTM</title>

	<indexterm>
	<primary>CTM</primary>
	</indexterm>

	<para><application>CTM</application> is a method for keeping a
	remote directory tree in sync with a central one. It has been
	developed for usage with &os;'s source trees, though other
	people may find it useful for other purposes as time goes by.
	Little, if any, documentation currently exists at this time on
	the process of creating deltas, so contact the
	&a.ctm-users.name; mailing list for more information and if you
	wish to use <application>CTM</application> for other
	things.</para>

	<sect2>
	<title>Why Should I Use <application>CTM</application>?</title>

	<para><application>CTM</application> will give you a local copy
	of the &os; source trees. There are a number of
	<quote>flavors</quote> of the tree available. Whether you
	wish to track the entire CVS tree or just one of the branches,
	<application>CTM</application> can provide you the
	information. If you are an active developer on &os;, but have
	lousy or non-existent TCP/IP connectivity, or simply wish to
	have the changes automatically sent to you,
	<application>CTM</application> was made for you. You will
	need to obtain up to three deltas per day for the most active
	branches. However, you should consider having them sent by
	automatic email. The sizes of the updates are always kept as
	small as possible. This is typically less than 5K, with an
	occasional (one in ten) being 10-50K and every now and then a
	large 100K+ or more coming around.</para>

	<para>You will also need to make yourself aware of the various
	caveats related to working directly from the development
	sources rather than a pre-packaged release. This is
	particularly true if you choose the <quote>current</quote>
	sources. It is recommended that you read <link
	linkend="current">Staying current with &os;</link>.</para>
	</sect2>

	<sect2>
	<title>What Do I Need to Use
	<application>CTM</application>?</title>

	<para>You will need two things: The
	<application>CTM</application> program, and the initial deltas
	to feed it (to get up to <quote>current</quote>
	levels).</para>

	<para>The <application>CTM</application> program has been part
	of &os; ever since version 2.0 was released, and lives in
	<filename>/usr/src/usr.sbin/ctm</filename> if you have a copy
	of the source available.</para>

	<para>The <quote>deltas</quote> you feed
	<application>CTM</application> can be had two ways, FTP or
	email. If you have general FTP access to the Internet then
	the following FTP sites support access to
	<application>CTM</application>:</para>

	<para><ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/"></ulink></para>

	<para>or see section <link
	linkend="mirrors-ctm">mirrors</link>.</para>

	<para>FTP the relevant directory and fetch the
	<filename>README</filename> file, starting from there.</para>

	<para>If you wish to get your deltas via email:</para>

	<para>Subscribe to one of the
	<application>CTM</application> distribution lists.
	&a.ctm-cvs-cur.name; supports the entire CVS tree.
	&a.ctm-src-cur.name; supports the head of the development
	- branch. &a.ctm-src-7.name; supports the 7.X release branch,
	+ branch. &a.ctm-src-9.name; supports the 9.X release branch,
	etc.. (If you do not know how to subscribe yourself to a
	list, click on the list name above or go to
	&a.mailman.lists.link; and click on the list that you wish to
	subscribe to. The list page should contain all of the
	necessary subscription instructions.)</para>

	<para>When you begin receiving your
	<application>CTM</application> updates in the mail, you may
	use the <command>ctm_rmail</command> program to unpack and
	apply them. You can actually use the
	<command>ctm_rmail</command> program directly from a entry in
	<filename>/etc/aliases</filename> if you want to have the
	process run in a fully automated fashion. Check the
	<command>ctm_rmail</command> manual page for more
	details.</para>

	<note>
	<para>No matter what method you use to get the
	<application>CTM</application> deltas, you should subscribe
	to the &a.ctm-announce.name; mailing list. In the future,
	this will be the only place where announcements concerning
	the operations of the <application>CTM</application> system
	will be posted. Click on the list name above and follow the
	instructions to subscribe to the list.</para>
	</note>
	</sect2>

	<sect2>
	<title>Using <application>CTM</application> for the First
	Time</title>

	<para>Before you can start using <application>CTM</application>
	deltas, you will need to get to a starting point for the
	deltas produced subsequently to it.</para>

	<para>First you should determine what you already have.
	Everyone can start from an <quote>empty</quote> directory.
	You must use an initial <quote>Empty</quote> delta to start
	off your <application>CTM</application> supported tree. At
	some point it is intended that one of these
	<quote>started</quote> deltas be distributed on the CD for
	your convenience, however, this does not currently
	happen.</para>

	<para>Since the trees are many tens of megabytes, you should
	prefer to start from something already at hand. If you have a
	-RELEASE CD, you can copy or extract an initial source from
	it. This will save a significant transfer of data.</para>

	<para>You can recognize these <quote>starter</quote> deltas by
	the <literal>X</literal> appended to the number
	(<filename>src-cur.3210XEmpty.gz</filename> for instance).
	The designation following the <literal>X</literal> corresponds
	to the origin of your initial <quote>seed</quote>.
	<filename>Empty</filename> is an empty directory. As a rule a
	base transition from <literal>Empty</literal> is produced
	every 100 deltas. By the way, they are large! 70 to 80
	Megabytes of <command>gzip</command>'d data is common for the
	<filename>XEmpty</filename> deltas.</para>

	<para>Once you have picked a base delta to start from, you will
	also need all deltas with higher numbers following it.</para>
	</sect2>

	<sect2>
	<title>Using <application>CTM</application> in Your Daily
	Life</title>

	<para>To apply the deltas, simply say:</para>

	<screen>&prompt.root; <userinput>cd /where/ever/you/want/the/stuff</userinput>
	&prompt.root; <userinput>ctm -v -v /where/you/store/your/deltas/src-xxx.*</userinput></screen>

	<para><application>CTM</application> understands deltas which
	have been put through <command>gzip</command>, so you do not
	need to <command>gunzip</command> them first, this saves disk
	space.</para>

	<para>Unless it feels very secure about the entire process,
	<application>CTM</application> will not touch your tree. To
	verify a delta you can also use the <option>-c</option> flag
	and <application>CTM</application> will not actually touch
	your tree; it will merely verify the integrity of the delta
	and see if it would apply cleanly to your current tree.</para>

	<para>There are other options to <application>CTM</application>
	as well, see the manual pages or look in the sources for more
	information.</para>

	<para>That is really all there is to it. Every time you get a
	new delta, just run it through <application>CTM</application>
	to keep your sources up to date.</para>

	<para>Do not remove the deltas if they are hard to download
	again. You just might want to keep them around in case
	something bad happens. Even if you only have floppy disks,
	consider using <command>fdwrite</command> to make a
	copy.</para>
	</sect2>

	<sect2>
	<title>Keeping Your Local Changes</title>

	<para>As a developer one would like to experiment with and
	change files in the source tree.
	<application>CTM</application> supports local modifications in
	a limited way: before checking for the presence of a file
	<filename>foo</filename>, it first looks for
	<filename>foo.ctm</filename>. If this file exists,
	<application>CTM</application> will operate on it instead of
	<filename>foo</filename>.</para>

	<para>This behavior gives us a simple way to maintain local
	changes: simply copy the files you plan to modify to the
	corresponding file names with a <filename>.ctm</filename>
	suffix. Then you can freely hack the code, while
	<application>CTM</application> keeps the
	<filename>.ctm</filename> file up-to-date.</para>
	</sect2>

	<sect2>
	<title>Other Interesting <application>CTM</application>
	Options</title>

	<sect3>
	<title>Finding Out Exactly What Would Be Touched by an
	Update</title>

	<para>You can determine the list of changes that
	<application>CTM</application> will make on your source
	repository using the <option>-l</option> option to
	<application>CTM</application>.</para>

	<para>This is useful if you would like to keep logs of the
	changes, pre- or post- process the modified files in any
	manner, or just are feeling a tad paranoid.</para>
	</sect3>

	<sect3>
	<title>Making Backups Before Updating</title>

	<para>Sometimes you may want to backup all the files that
	would be changed by a <application>CTM</application>
	update.</para>

	<para>Specifying the <option>-B backup-file</option> option
	causes <application>CTM</application> to backup all files
	that would be touched by a given
	<application>CTM</application> delta to
	<filename>backup-file</filename>.</para>
	</sect3>

	<sect3>
	<title>Restricting the Files Touched by an Update</title>

	<para>Sometimes you would be interested in restricting the
	scope of a given <application>CTM</application> update, or
	may be interested in extracting just a few files from a
	sequence of deltas.</para>

	<para>You can control the list of files that
	<application>CTM</application> would operate on by
	specifying filtering regular expressions using the
	<option>-e</option> and <option>-x</option> options.</para>

	<para>For example, to extract an up-to-date copy of
	<filename>lib/libc/Makefile</filename> from your collection
	of saved <application>CTM</application> deltas, run the
	commands:</para>

	<screen>&prompt.root; <userinput>cd /where/ever/you/want/to/extract/it/</userinput>
	&prompt.root; <userinput>ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*</userinput></screen>

	<para>For every file specified in a
	<application>CTM</application> delta, the
	<option>-e</option> and <option>-x</option> options are
	applied in the order given on the command line. The file is
	processed by <application>CTM</application> only if it is
	marked as eligible after all the <option>-e</option> and
	<option>-x</option> options are applied to it.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Future Plans for <application>CTM</application></title>

	<para>Tons of them:</para>

	<itemizedlist>
	<listitem>
	<para>Use some kind of authentication into the
	<application>CTM</application> system, so as to allow
	detection of spoofed <application>CTM</application>
	updates.</para>
	</listitem>

	<listitem>
	<para>Clean up the options to
	<application>CTM</application>, they became confusing and
	counter intuitive.</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2>
	<title>Miscellaneous Stuff</title>

	<para>There is a sequence of deltas for the
	<literal>ports</literal> collection too, but interest has not
	been all that high yet.</para>
	</sect2>

	<sect2 id="mirrors-ctm">
	<title>CTM Mirrors</title>

	<para><link linkend="ctm">CTM</link>/&os; is available via
	anonymous FTP from the following mirror sites. If you choose
	to obtain <application>CTM</application> via anonymous FTP,
	please try to use a site near you.</para>

	<para>In case of problems, please contact the &a.ctm-users.name;
	mailing list.</para>

	<variablelist>
	<varlistentry>
	<term>California, Bay Area, official source</term>

	<listitem>
	<itemizedlist>
	<listitem>
	<para><ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>South Africa, backup server for old deltas</term>

	<listitem>
	<itemizedlist>
	<listitem>
	<para><ulink
	url="ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/"></ulink></para>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Taiwan/R.O.C.</term>

	<listitem>
	<itemizedlist>
	<listitem>
	<para><ulink
	url="ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>If you did not find a mirror near to you or the mirror is
	incomplete, try to use a search engine such as <ulink
	url="http://www.alltheweb.com/">alltheweb</ulink>.</para>
	</sect2>
	</sect1>

	<sect1 id="svn">
	<title>Using <application>Subversion</application></title>

	<indexterm>
	<primary>Subversion</primary>
	</indexterm>

	<sect2 id="svn-intro">
	<title>Introduction</title>

	<para>As of July 2012, &os; uses <ulink
	url="http://subversion.apache.org/">Subversion</ulink>
	(<emphasis>svn</emphasis>) as the primary version control
	system for storing all of &os;'s source code, documentation,
	and the Ports Collection.</para>

	<note>
	<para>Subversion is generally a developer tool. Most users
	should use <link
	linkend="updating-upgrading-freebsdupdate">FreeBSD
	Update</link> to update the &os; base system, and <link
	linkend="updating-upgrading-portsnap">Portsnap</link> to
	update the &os; Ports Collection.</para>
	</note>

	<para>In <application>Subversion</application>, URLs are used to
	designate a repository, taking the form of
	<replaceable>protocol://hostname/path</replaceable>. Mirrors
	may support different protocols as specified below. The first
	component of the path is the &os; repository to access. There
	are three different repositories, <literal>base</literal> for
	the &os; base system source code, <literal>ports</literal> for
	the Ports Collection, and <literal>doc</literal> for
	documentation. For example, the URL
	<literal>svn://svn0.us-east.FreeBSD.org/ports/head/</literal>
	specifies the main branch of the ports repository on the
	<hostid role="fqdn">svn0.us-east.FreeBSD.org</hostid> mirror,
	using the <literal>svn</literal> protocol.</para>
	</sect2>

	<sect2 id="svn-install">
	<title>Installation</title>

	<para><application>Subversion</application> must be installed
	before it can be used to check out the contents of any of the
	repositories. If a copy of the ports tree is already present,
	one can install <application>Subversion</application> like
	this:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/devel/subversion</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>If the ports tree is not available,
	<application>Subversion</application> can be installed as a
	package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r subversion</userinput></screen>

	<para>If <application>pkgng</application> is being used to
	manage packages, <application>Subversion</application> can be
	installed with it instead:</para>

	<screen>&prompt.root; <userinput>pkg install devel/subversion</userinput></screen>
	</sect2>

	<sect2 id="svn-usage">
	<title>Running <application>Subversion</application></title>

	<para>The <command>svn</command> command is used to fetch a
	clean copy of the sources into a local directory. The files
	in this directory are called a <emphasis>local working
	copy</emphasis>.</para>

	<warning>
	<para>If the local directory already exists but was not
	created by <command>svn</command>, rename or delete it
	before the checkout. Checkout over an existing
	non-<command>svn</command> directory can cause conflicts
	between the existing files and those brought in from the
	repository.</para>
	</warning>

	<para>A checkout from a given repository is performed with a
	command like this:</para>

	<screen>&prompt.root; <userinput>svn checkout <replaceable>svn-mirror</replaceable>/<replaceable>repository</replaceable>/<replaceable>branch</replaceable> <replaceable>lwcdir</replaceable></userinput></screen>

	<para>where:</para>

	<itemizedlist>
	<listitem>
	<para><replaceable>svn-mirror</replaceable> is a URL for one
	of the <link linkend="svn-mirrors">Subversion mirror
	sites</link>.</para>
	</listitem>

	<listitem>
	<para><replaceable>repository</replaceable> is one of the
	Project repositories, i.e., <literal>base</literal>,
	<literal>ports</literal>, or
	<literal>doc</literal>.</para>
	</listitem>

	<listitem>
	<para><replaceable>branch</replaceable> depends on the
	repository used. <literal>ports</literal> and
	<literal>doc</literal> are mostly updated in the
	<literal>head</literal> branch, while
	<literal>base</literal> maintains the latest version of
	-CURRENT under <literal>head</literal> and the respective
	latest versions of the -STABLE branches under
	<literal>stable/8</literal> (for
	8.<replaceable>x</replaceable>) and
	<literal>stable/9</literal>
	(9.<replaceable>x</replaceable>).</para>
	</listitem>

	<listitem>
	<para><replaceable>lwcdir</replaceable> is the target
	directory where the contents of the specified branch
	should be placed. This is usually
	<filename class="directory">/usr/ports</filename> for
	<literal>ports</literal>,
	<filename class="directory">/usr/src</filename> for
	<literal>base</literal>, and
	<filename class="directory">/usr/doc</filename> for
	<literal>doc</literal>.</para>
	</listitem>
	</itemizedlist>

	<para>This example checks out the Ports Collection from the
	western US repository using the <acronym>HTTPS</acronym>
	protocol, placing the local working copy in
	<filename class="directory">/usr/ports</filename>. If
	<filename class="directory">/usr/ports</filename> is already
	present but was not created by <command>svn</command>,
	remember to rename or delete it before the checkout.</para>

	<screen>&prompt.root; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/ports/head /usr/ports</userinput></screen>

	<para>Because the initial checkout has to download the full
	branch of the remote repository, it can take a while. Please
	be patient.</para>

	<para>After the initial checkout, the local working copy can be
	updated by running:</para>

	<screen>&prompt.root; <userinput>svn update <replaceable>lwcdir</replaceable></userinput></screen>

	<para>To update
	<filename class="directory">/usr/ports</filename> created in
	the example above, use:</para>

	<screen>&prompt.root; <userinput>svn update /usr/ports</userinput></screen>

	<para>The update is much quicker than a checkout, only
	transferring files that have changed.</para>

	<para>An alternate way of updating the local working copy after
	checkout is provided by the <filename>Makefile</filename> in
	the <filename class="directory">/usr/ports</filename>,
	<filename class="directory">/usr/src</filename>, and
	<filename class="directory">/usr/doc</filename> directories.
	Set <makevar>SVN_UPDATE</makevar> and use the
	<maketarget>update</maketarget> target. For example, to
	update <filename class="directory">/usr/src</filename>:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput>
	&prompt.root; <userinput>make update SVN_UPDATE=yes</userinput></screen>
	</sect2>

	<sect2>
	<title>For More Information</title>

	<para>For other information about using
	<application>Subversion</application>, please see the
	<quote>Subversion Book</quote>, titled
	<ulink url="http://svnbook.red-bean.com/">Version Control with
	Subversion</ulink>, or the
	<ulink url="http://subversion.apache.org/docs/">Subversion
	Documentation</ulink>.</para>
	</sect2>
	</sect1>

	<sect1 id="svn-mirrors">
	<title><application>Subversion</application> Mirror Sites</title>

	<indexterm>
	<primary>Subversion Repository</primary>
	<secondary>Mirror Sites</secondary>
	</indexterm>

	<para>All mirrors carry all repositories.</para>

	<para>The master &os; <application>Subversion</application>
	server, <hostid role="fqdn">svn.FreeBSD.org</hostid>, is
	publicly accessible, read-only. That may change in the future,
	so users are encouraged to use one of the official mirrors. To
	view the &os; <application>Subversion</application> repositories
	through a browser, use <ulink
	url="http://svnweb.FreeBSD.org/">http://svnweb.FreeBSD.org/</ulink>.</para>

	<note>
	<para>The &os; svn mirror network is still in its early days,
	and will likely change. Do not count on this list of mirrors
	being static. In particular, the SSL certificates of the
	servers will likely change at some point.</para>
	</note>

	<informaltable>
	<tgroup cols="4">
	<colspec colwidth="3*"/>
	<colspec colwidth="1*"/>
	<colspec colwidth="2*"/>
	<colspec colwidth="10*"/>
	<thead>
	<row>
	<entry>Name</entry>

	<entry>Protocols</entry>

	<entry>Location</entry>

	<entry>SSL fingerprint</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><hostid
	role="fqdn">svn0.us-west.FreeBSD.org</hostid></entry>

	<entry>svn, <ulink
	url="http://svn0.us-west.FreeBSD.org/">http</ulink>,
	<ulink
	url="https://svn0.us-west.FreeBSD.org/">https</ulink></entry>

	<entry>USA, California</entry>

	<entry>SHA1
	<literal>79:35:8F:CA:6D:34:D9:30:44:D1:00:AF:33:4D:E6:11:44:4D:15:EC</literal></entry>
	</row>

	<row>
	<entry><hostid
	role="fqdn">svn0.us-east.FreeBSD.org</hostid></entry>

	<entry>svn, <ulink
	url="http://svn0.us-east.FreeBSD.org/">http</ulink>,
	<ulink
	url="https://svn0.us-east.FreeBSD.org/">https</ulink></entry>

	<entry>USA, New Jersey</entry>

	<entry>SHA1
	<literal>06:D1:23:DE:5E:7A:F7:2B:7A:7E:74:95:5F:54:8D:5C:B0:D6:2E:8F</literal></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para><acronym>HTTPS</acronym> is the preferred protocol,
	providing protection against another computer pretending to be
	the &os; mirror (commonly known as a <quote>man in the
	middle</quote> attack) or otherwise trying to send bad content
	to the end user.</para>

	<para>On the first connection to an <acronym>HTTPS</acronym>
	mirror, the user will be asked to verify the server
	<emphasis>fingerprint</emphasis>:</para>

	<screen>Error validating server certificate for 'https://svn0.us-west.freebsd.org:443':
	- The certificate is not issued by a trusted authority. Use the
	fingerprint to validate the certificate manually!
	Certificate information:
	- Hostname: svnmir.ysv.FreeBSD.org
	- Valid: from Fri, 24 Aug 2012 22:04:04 GMT until Sat, 24 Aug 2013 22:04:04 GMT
	- Issuer: clusteradm, FreeBSD.org, CA, US
	- Fingerprint: 79:35:8f:ca:6d:34:d9:30:44:d1:00:af:33:4d:e6:11:44:4d:15:ec
	(R)eject, accept (t)emporarily or accept (p)ermanently?</screen>

	<para>Compare the fingerprint shown to those listed in the table
	above. If the fingerprint matches, the server security
	certificate can be accepted temporarily or permanently. A
	temporary certificate will expire after a single session with
	the server, and the verification step will be repeated on the
	next connection. Accepting the certificate permanently will
	store the authentication credentials in
	<filename role="directory">~/.subversion/auth/</filename> and
	the user will not be asked to verify the fingerprint again until
	the certificate expires.</para>

	<para>If <acronym>HTTPS</acronym> cannot be used due to firewall
	or other problems, <literal>SVN</literal> is the next choice,
	with slightly faster transfers. When neither can be used, use
	<acronym>HTTP</acronym>.</para>
	</sect1>

	<sect1 id="cvsup">
	<title>Using CVSup (Deprecated)</title>

	<sect2 id="cvsup-intro">
	<title>Introduction</title>

	<warning>
	<para><command>cvsup</command> has been deprecated by the
	project, and its use is not recommended.
	<application>Subversion</application> should be used
	instead.</para>
	</warning>

	<para><application>CVSup</application> is a software package for
	distributing and updating source trees from a master CVS
	repository on a remote server host. The &os; sources are
	maintained in a CVS repository on a central development
	machine in California. With <application>CVSup</application>,
	&os; users can easily keep their own source trees up to
	date.</para>

	<para><application>CVSup</application> uses the so-called
	<emphasis>pull</emphasis> model of updating. Under the pull
	model, each client asks the server for updates, if and when
	they are wanted. The server waits passively for update
	requests from its clients. Thus all updates are instigated by
	the client. The server never sends unsolicited updates.
	Users must either run the <application>CVSup</application>
	client manually to get an update, or they must set up a
	<command>cron</command> job to run it automatically on a
	regular basis.</para>

	<para>The term <application>CVSup</application>, capitalized
	just so, refers to the entire software package. Its main
	components are the client <command>cvsup</command> which runs
	on each user's machine, and the server
	<command>cvsupd</command> which runs at each of the &os;
	mirror sites.</para>

	- <para>As you read the &os; documentation and mailing lists, you
	- may see references to <application>sup</application>.
	- <application>Sup</application> was the predecessor of
	- <application>CVSup</application>, and it served a similar
	- purpose. <application>CVSup</application> is used much in the
	- same way as sup and, in fact, uses configuration files which
	- are backward-compatible with <command>sup</command>'s.
	- <application>Sup</application> is no longer used in the &os;
	- project, because <application>CVSup</application> is both
	- faster and more flexible.</para>
	-
	<note>
	<para>The <application>csup</application> utility is a rewrite
	of the <application>CVSup</application> software in C. Its
	biggest advantage is, that it is faster and does not depend
	on the Modula-3 language, thus you do not need to install it
	as a requirement. Moreover you can use it out-of-the-box,
	since it is included in the base system. If you decided to
	use <application>csup</application>, just skip the steps on
	the installation of <application>CVSup</application> and
	substitute the references of
	<application>CVSup</application> with
	<application>csup</application> while following the
	remainder of this article.</para>
	</note>
	</sect2>

	<sect2 id="cvsup-install">
	<title>Installation</title>

	<para>The easiest way to install
	<application>CVSup</application> is to use the precompiled
	<filename role="package">net/cvsup</filename> package from the
	&os; <link linkend="ports">packages collection</link>. If you
	prefer to build <application>CVSup</application> from source,
	you can use the <filename role="package">net/cvsup</filename>
	port instead. But be forewarned: the <filename
	role="package">net/cvsup</filename> port depends on the
	Modula-3 system, which takes a substantial amount of time and
	disk space to download and build.</para>

	<note>
	<para>If you are going to be using
	<application>CVSup</application> on a machine which will not
	have <application>&xorg;</application> installed, such as a
	server, be sure to use the port which does not include the
	<application>CVSup</application> <acronym>GUI</acronym>,
	<filename
	role="package">net/cvsup-without-gui</filename>.</para>
	</note>
	</sect2>

	<sect2 id="cvsup-config">
	<title>CVSup Configuration</title>

	<para><application>CVSup</application>'s operation is controlled
	by a configuration file called the
	<filename>supfile</filename>. There are some sample
	<filename>supfiles</filename> in the directory <ulink
	type="html"
	url="file://localhost/usr/share/examples/cvsup/"><filename>/usr/share/examples/cvsup/</filename></ulink>.</para>

	<para>The information in a <filename>supfile</filename> answers
	the following questions for
	<application>CVSup</application>:</para>

	<itemizedlist>
	<listitem>
	<para><link linkend="cvsup-config-files">Which files do you
	want to receive?</link></para>
	</listitem>

	<listitem>
	<para><link linkend="cvsup-config-vers">Which versions of
	them do you want?</link></para>
	</listitem>

	<listitem>
	<para><link linkend="cvsup-config-where">Where do you want
	to get them from?</link></para>
	</listitem>

	<listitem>
	<para><link linkend="cvsup-config-dest">Where do you want to
	put them on your own machine?</link></para>
	</listitem>

	<listitem>
	<para><link linkend="cvsup-config-status">Where do you want
	to put your status files?</link></para>
	</listitem>
	</itemizedlist>

	<para>In the following sections, we will construct a typical
	<filename>supfile</filename> by answering each of these
	questions in turn. First, we describe the overall structure
	of a <filename>supfile</filename>.</para>

	<para>A <filename>supfile</filename> is a text file. Comments
	begin with <literal>#</literal> and extend to the end of the
	line. Lines that are blank and lines that contain only
	comments are ignored.</para>

	<para>Each remaining line describes a set of files that the user
	wishes to receive. The line begins with the name of a
	<quote>collection</quote>, a logical grouping of files defined
	by the server. The name of the collection tells the server
	which files you want. After the collection name come zero or
	more fields, separated by white space. These fields answer
	the questions listed above. There are two types of fields:
	flag fields and value fields. A flag field consists of a
	keyword standing alone, e.g., <literal>delete</literal> or
	<literal>compress</literal>. A value field also begins with a
	keyword, but the keyword is followed without intervening white
	space by <literal>=</literal> and a second word. For example,
	<literal>release=cvs</literal> is a value field.</para>

	<para>A <filename>supfile</filename> typically specifies more
	than one collection to receive. One way to structure a
	<filename>supfile</filename> is to specify all of the relevant
	fields explicitly for each collection. However, that tends to
	make the <filename>supfile</filename> lines quite long, and it
	is inconvenient because most fields are the same for all of
	the collections in a <filename>supfile</filename>.
	<application>CVSup</application> provides a defaulting
	mechanism to avoid these problems. Lines beginning with the
	special pseudo-collection name <literal>*default</literal> can
	be used to set flags and values which will be used as defaults
	for the subsequent collections in the
	<filename>supfile</filename>. A default value can be
	overridden for an individual collection, by specifying a
	different value with the collection itself. Defaults can also
	be changed or augmented in mid-supfile by additional
	<literal>*default</literal> lines.</para>

	<para>With this background, we will now proceed to construct a
	<filename>supfile</filename> for receiving and updating the
	main source tree of
	<link linkend="current">&os;-CURRENT</link>.</para>

	<itemizedlist>
	<listitem>
	<para><anchor id="cvsup-config-files"/>Which files do you
	want to receive?</para>

	<para>The files available via
	<application>CVSup</application> are organized into named
	groups called <quote>collections</quote>. The collections
	that are available are described in the
	<link linkend="cvsup-collec">following section</link>. In
	this example, we wish to receive the entire main source
	tree for the &os; system. There is a single large
	collection <literal>src-all</literal> which will give us
	all of that. As a first step toward constructing our
	<filename>supfile</filename>, we simply list the
	collections, one per line (in this case, only one
	line):</para>

	<programlisting>src-all</programlisting>
	</listitem>

	<listitem>
	<para><anchor id="cvsup-config-vers"/>Which version(s) of
	them do you want?</para>

	<para>With <application>CVSup</application>, you can receive
	virtually any version of the sources that ever existed.
	That is possible because the
	<application>cvsupd</application> server works directly
	from the CVS repository, which contains all of the
	versions. You specify which one of them you want using
	the <literal>tag=</literal> and <option>date=</option>
	value fields.</para>

	<warning>
	<para>Be very careful to specify any
	<literal>tag=</literal> fields correctly. Some tags are
	valid only for certain collections of files. If you
	specify an incorrect or misspelled tag,
	<application>CVSup</application> will delete files which
	you probably do not want deleted. In particular, use
	<emphasis>only </emphasis> <literal>tag=.</literal> for
	the <literal>ports-*</literal> collections.</para>
	</warning>

	<para>The <literal>tag=</literal> field names a symbolic tag
	in the repository. There are two kinds of tags, revision
	tags and branch tags. A revision tag refers to a specific
	revision. Its meaning stays the same from day to day. A
	branch tag, on the other hand, refers to the latest
	revision on a given line of development, at any given
	time. Because a branch tag does not refer to a specific
	revision, it may mean something different tomorrow than it
	means today.</para>

	<para><xref linkend="cvs-tags"/> contains branch tags that
	users might be interested in. When specifying a tag in
	<application>CVSup</application>'s configuration file, it
	must be preceded with <literal>tag=</literal>
	(<literal>RELENG_8</literal> will become
	<literal>tag=RELENG_8</literal>).
	Keep in mind that only the <literal>tag=.</literal> is
	relevant for the Ports Collection.</para>

	<warning>
	<para>Be very careful to type the tag name exactly as
	shown. <application>CVSup</application> cannot
	distinguish between valid and invalid tags. If you
	misspell the tag, <application>CVSup</application> will
	behave as though you had specified a valid tag which
	happens to refer to no files at all. It will delete
	your existing sources in that case.</para>
	</warning>

	<para>When you specify a branch tag, you normally receive
	the latest versions of the files on that line of
	development. If you wish to receive some past version,
	you can do so by specifying a date with the
	<option>date=</option> value field. The &man.cvsup.1;
	manual page explains how to do that.</para>

	<para>For our example, we wish to receive &os;-CURRENT. We
	add this line at the beginning of our
	<filename>supfile</filename>:</para>

	<programlisting>*default tag=.</programlisting>

	<para>There is an important special case that comes into
	play if you specify neither a <literal>tag=</literal>
	field nor a <literal>date=</literal> field. In that case,
	you receive the actual RCS files directly from the
	server's CVS repository, rather than receiving a
	particular version. Developers generally prefer this mode
	of operation. By maintaining a copy of the repository
	itself on their systems, they gain the ability to browse
	the revision histories and examine past versions of files.
	This gain is achieved at a large cost in terms of disk
	space, however.</para>
	</listitem>

	<listitem>
	<para><anchor id="cvsup-config-where"/>Where do you want to
	get them from?</para>

	<para>We use the <literal>host=</literal> field to tell
	<command>cvsup</command> where to obtain its updates. Any
	of the
	<link linkend="cvsup-mirrors">CVSup mirror sites</link>
	will do, though you should try to select one that is close
	to you in cyberspace. In this example we will use a
	fictional &os; distribution site,
	<hostid role="fqdn">cvsup99.FreeBSD.org</hostid>:</para>

	<programlisting>*default host=cvsup99.FreeBSD.org</programlisting>

	<para>You will need to change the host to one that actually
	exists before running <application>CVSup</application>.
	On any particular run of <command>cvsup</command>, you can
	override the host setting on the command line, with
	<option>-h
	<replaceable>hostname</replaceable></option>.</para>
	</listitem>

	<listitem>
	<para><anchor id="cvsup-config-dest"/>Where do you want to
	put them on your own machine?</para>

	<para>The <literal>prefix=</literal> field tells
	<command>cvsup</command> where to put the files it
	receives. In this example, we will put the source files
	directly into our main source tree,
	<filename>/usr/src</filename>. The
	<filename>src</filename> directory is already implicit in
	the collections we have chosen to receive, so this is the
	correct specification:</para>

	<programlisting>*default prefix=/usr</programlisting>
	</listitem>

	<listitem>
	<para><anchor id="cvsup-config-status"/>Where should
	<command>cvsup</command> maintain its status files?</para>

	<para>The <application>CVSup</application> client maintains
	certain status files in what is called the
	<quote>base</quote> directory. These files help
	<application>CVSup</application> to work more efficiently,
	by keeping track of which updates you have already
	received. We will use the standard base directory,
	<filename>/var/db</filename>:</para>

	<programlisting>*default base=/var/db</programlisting>

	<para>If your base directory does not already exist, now
	would be a good time to create it. The
	<command>cvsup</command> client will refuse to run if the
	base directory does not exist.</para>
	</listitem>

	<listitem>
	<para>Miscellaneous <filename>supfile</filename>
	settings:</para>

	<para>There is one more line of boiler plate that normally
	needs to be present in the
	<filename>supfile</filename>:</para>

	<programlisting>*default release=cvs delete use-rel-suffix compress</programlisting>

	<para><literal>release=cvs</literal> indicates that the
	server should get its information out of the main &os; CVS
	repository. This is virtually always the case, but there
	are other possibilities which are beyond the scope of this
	discussion.</para>

	<para><literal>delete</literal> gives
	<application>CVSup</application> permission to delete
	files. You should always specify this, so that
	<application>CVSup</application> can keep your source tree
	fully up-to-date. <application>CVSup</application> is
	careful to delete only those files for which it is
	responsible. Any extra files you happen to have will be
	left strictly alone.</para>

	<para><literal>use-rel-suffix</literal> is ... arcane. If
	you really want to know about it, see the &man.cvsup.1;
	manual page. Otherwise, just specify it and do not worry
	about it.</para>

	<para><literal>compress</literal> enables the use of
	gzip-style compression on the communication channel. If
	your network link is T1 speed or faster, you probably
	should not use compression. Otherwise, it helps
	substantially.</para>
	</listitem>

	<listitem>
	<para>Putting it all together:</para>

	<para>Here is the entire <filename>supfile</filename> for
	our example:</para>

	<programlisting>*default tag=.
	*default host=cvsup99.FreeBSD.org
	*default prefix=/usr
	*default base=/var/db
	*default release=cvs delete use-rel-suffix compress

	src-all</programlisting>
	</listitem>
	</itemizedlist>

	<sect3 id="cvsup-refuse-file">
	<title>The <filename>refuse</filename> File</title>

	<para>As mentioned above, <application>CVSup</application>
	uses a <emphasis>pull method</emphasis>. Basically, this
	means that you connect to the
	<application>CVSup</application> server, and it says,
	<quote>Here is what you can download from me...</quote>, and
	your client responds
	<quote>OK, I will take this, this, this, and this.</quote>
	In the default configuration, the
	<application>CVSup</application> client will take every file
	associated with the collection and tag you chose in the
	- configuration file. However, this is not always what you
	- want, especially if you are synching the
	- <filename>doc</filename>, <filename>ports</filename>, or
	- <filename>www</filename> trees — most people cannot
	- read four or five languages, and therefore they do not need
	- to download the language-specific files. If you are
	- <application>CVSup</application>ing the Ports Collection,
	- you can get around this by specifying each collection
	- individually (e.g., <emphasis>ports-astrology</emphasis>,
	- <emphasis>ports-biology</emphasis>, etc instead of simply
	- saying <emphasis>ports-all</emphasis>). However, since the
	- <filename>doc</filename> and <filename>www</filename> trees
	- do not have language-specific collections, you must use one
	- of <application>CVSup</application>'s many nifty features:
	- the <filename>refuse</filename> file.</para>
	+ configuration file. In order to download a partial tree,
	+ use the <filename>refuse</filename> file.</para>

	- <para>The <filename>refuse</filename> file essentially tells
	+ <para>The <filename>refuse</filename> file tells
	<application>CVSup</application> that it should not take
	every single file from a collection; in other words, it
	tells the client to <emphasis>refuse</emphasis> certain
	files from the server. The <filename>refuse</filename> file
	can be found (or, if you do not yet have one, should be
	placed) in
	<filename><replaceable>base</replaceable>/sup/</filename>.
	<replaceable>base</replaceable> is defined in your
	<filename>supfile</filename>; our defined
	<replaceable>base</replaceable> is
	<filename>/var/db</filename>, which means that by default
	the <filename>refuse</filename> file is
	<filename>/var/db/sup/refuse</filename>.</para>

	<para>The <filename>refuse</filename> file has a very simple
	format; it simply contains the names of files or directories
	- that you do not wish to download. For example, if you
	- cannot speak any languages other than English and some
	- German, and you do not feel the need to read the German
	- translation of documentation, you can put the following in
	- your <filename>refuse</filename> file:</para>
	+ that you do not wish to download. For example:</para>

	- <programlisting>doc/bn_*
	-doc/da_*
	-doc/de_*
	-doc/el_*
	-doc/es_*
	-doc/fr_*
	-doc/hu_*
	-doc/it_*
	-doc/ja_*
	-doc/mn_*
	-doc/nl_*
	-doc/no_*
	-doc/pl_*
	-doc/pt_*
	-doc/ru_*
	-doc/sr_*
	-doc/tr_*
	-doc/zh_*</programlisting>
	+ <programlisting>bin/
	+usr.bin/</programlisting>

	- <para>and so forth for the other languages (you can find the
	- full list by browsing the
	- <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/">&os; CVS
	- repository</ulink>).</para>
	-
	- <para>With this very useful feature, those users who are on
	+ <para>Users who are on
	slow links or pay by the minute for their Internet
	- connection will be able to save valuable time as they will
	+ connection will be able to save time as they will
	no longer need to download files that they will never use.
	For more information on <filename>refuse</filename> files
	and other neat features of <application>CVSup</application>,
	please view its manual page.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Running <application>CVSup</application></title>

	<para>You are now ready to try an update. The command line for
	doing this is quite simple:</para>

	<screen>&prompt.root; <userinput>cvsup <replaceable>supfile</replaceable></userinput></screen>

	<para>where
	<filename><replaceable>supfile</replaceable></filename> is of
	course the name of the <filename>supfile</filename> you have
	just created. Assuming you are running under X11,
	<command>cvsup</command> will display a GUI window with some
	buttons to do the usual things. Press the
	<guibutton>go</guibutton> button, and watch it run.</para>

	<para>Since you are updating your actual
	<filename>/usr/src</filename> tree in this example, you will
	need to run the program as <username>root</username> so that
	<command>cvsup</command> has the permissions it needs to
	update your files. Having just created your configuration
	file, and having never used this program before, that might
	understandably make you nervous. There is an easy way to do a
	trial run without touching your precious files. Just create
	an empty directory somewhere convenient, and name it as an
	extra argument on the command line:</para>

	<screen>&prompt.root; <userinput>mkdir /var/tmp/dest</userinput>
	&prompt.root; <userinput>cvsup supfile /var/tmp/dest</userinput></screen>

	<para>The directory you specify will be used as the destination
	directory for all file updates.
	<application>CVSup</application> will examine your usual files
	in <filename>/usr/src</filename>, but it will not modify or
	delete any of them. Any file updates will instead land in
	<filename>/var/tmp/dest/usr/src</filename>.
	<application>CVSup</application> will also leave its base
	directory status files untouched when run this way. The new
	versions of those files will be written into the specified
	directory. As long as you have read access to
	<filename>/usr/src</filename>, you do not even need to be
	<username>root</username> to perform this kind of trial
	run.</para>

	<para>If you are not running X11 or if you just do not like
	GUIs, you should add a couple of options to the command line
	when you run <command>cvsup</command>:</para>

	<screen>&prompt.root; <userinput>cvsup -g -L 2 <replaceable>supfile</replaceable></userinput></screen>

	<para>The <option>-g</option> tells
	<application>CVSup</application> not to use its GUI. This is
	automatic if you are not running X11, but otherwise you have
	to specify it.</para>

	<para>The <option>-L 2</option> tells
	<application>CVSup</application> to print out the
	details of all the file updates it is doing. There are three
	levels of verbosity, from <option>-L 0</option> to
	<option>-L 2</option>. The default is 0, which means total
	silence except for error messages.</para>

	<para>There are plenty of other options available. For a brief
	list of them, type <command>cvsup -H</command>. For more
	detailed descriptions, see the manual page.</para>

	<para>Once you are satisfied with the way updates are working,
	you can arrange for regular runs of
	<application>CVSup</application> using &man.cron.8;.
	Obviously, you should not let <application>CVSup</application>
	use its GUI when running it from &man.cron.8;.</para>
	</sect2>

	<sect2 id="cvsup-collec">
	<title><application>CVSup</application> File Collections</title>

	<para>The file collections available via
	<application>CVSup</application> are organized hierarchically.
	There are a few large collections, and they are divided into
	smaller sub-collections. Receiving a large collection is
	equivalent to receiving each of its sub-collections. The
	hierarchical relationships among collections are reflected by
	the use of indentation in the list below.</para>

	- <para>The most commonly used collections are
	- <literal>src-all</literal>, and
	- <literal>ports-all</literal>. The other collections are used
	- only by small groups of people for specialized purposes, and
	- some mirror sites may not carry all of them.</para>
	+ <para>The most commonly used collection is
	+ <literal>src-all</literal>. </para>

	<variablelist>
	<varlistentry>
	<term><literal>cvs-all release=cvs</literal></term>

	<listitem>
	<para>The main &os; CVS repository, including the
	cryptography code.</para>

	<variablelist>
	<varlistentry>
	<term><literal>distrib release=cvs</literal></term>

	<listitem>
	<para>Files related to the distribution and
	mirroring of &os;.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	- <term><literal>ports-all release=cvs</literal></term>
	-
	- <listitem>
	- <para>The &os; Ports Collection.</para>
	-
	- <important id="cvsup-collec-pbase-warn">
	- <para>If you do not want to update the whole of
	- <literal>ports-all</literal> (the whole ports
	- tree), but use one of the subcollections listed
	- below, make sure that you
	- <emphasis>always</emphasis> update the
	- <literal>ports-base</literal> subcollection!
	- Whenever something changes in the ports build
	- infrastructure represented by
	- <literal>ports-base</literal>, it is virtually
	- certain that those changes will be used by
	- <quote>real</quote> ports real soon. Thus, if
	- you only update the <quote>real</quote> ports
	- and they use some of the new features, there is
	- a very high chance that their build will fail
	- with some mysterious error message. The
	- <emphasis>very first</emphasis> thing to do in
	- this case is to make sure that your
	- <literal>ports-base</literal> subcollection is
	- up to date.</para>
	- </important>
	-
	- <important id="cvsup-collec-index-warn">
	- <para>If you are going to be building your own
	- local copy of <filename>ports/INDEX</filename>,
	- you <emphasis>must</emphasis> accept
	- <literal>ports-all</literal> (the whole ports
	- tree). Building
	- <filename>ports/INDEX</filename> with a partial
	- tree is not supported. See the <ulink
	- url="&url.books.faq;/applications.html#MAKE-INDEX">
	- FAQ</ulink>.</para>
	- </important>
	-
	- <variablelist>
	- <varlistentry>
	- <term><literal>ports-accessibility
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Software to help disabled users.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-arabic
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Arabic language support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-archivers
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Archiving tools.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-astro
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Astronomical ports.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-audio
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Sound support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-base
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>The Ports Collection build
	- infrastructure - various files located in
	- the <filename>Mk/</filename> and
	- <filename>Tools/</filename> subdirectories
	- of <filename>/usr/ports</filename>.</para>
	-
	- <note>
	- <para>Please see the <link
	- linkend="cvsup-collec-pbase-warn">important
	- warning above</link>: you should
	- <emphasis>always</emphasis> update this
	- subcollection, whenever you update any
	- part of the &os; Ports Collection!</para>
	- </note>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-benchmarks
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Benchmarks.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-biology
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Biology.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-cad
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Computer aided design tools.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-chinese
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Chinese language support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-comms
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Communication software.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-converters
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>character code converters.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-databases
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Databases.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-deskutils
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Things that used to be on the desktop
	- before computers were invented.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-devel
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Development utilities.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-dns
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>DNS related software.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-editors
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Editors.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-emulators
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Emulators for other operating
	- systems.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-finance
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Monetary, financial and related
	- applications.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-ftp
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>FTP client and server utilities.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-games
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Games.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-german
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>German language support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-graphics
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Graphics utilities.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-hebrew
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Hebrew language support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-hungarian
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Hungarian language support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-irc
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Internet Relay Chat utilities.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-japanese
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Japanese language support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-java
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>&java; utilities.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-korean
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Korean language support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-lang
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Programming languages.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-mail
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Mail software.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-math
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Numerical computation software.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-misc
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Miscellaneous utilities.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-multimedia
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Multimedia software.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-net
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Networking software.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-net-im
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Instant messaging software.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-net-mgmt
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Network management software.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-net-p2p
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Peer to peer networking.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-news
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>USENET news software.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-palm
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Software support for
	- <trademark class="trade">Palm</trademark>
	- series.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-polish
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Polish language support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-ports-mgmt
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Utilities to manage ports and
	- packages.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-portuguese
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Portuguese language support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-print
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Printing software.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-russian
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Russian language support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-science
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Science.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-security
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Security utilities.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-shells
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Command line shells.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-sysutils
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>System utilities.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-textproc
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>text processing utilities (does not
	- include desktop publishing).</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-ukrainian
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Ukrainian language support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-vietnamese
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Vietnamese language support.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-www
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Software related to the World Wide
	- Web.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-x11
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>Ports to support the X window
	- system.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-x11-clocks
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>X11 clocks.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-x11-drivers
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>X11 drivers.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-x11-fm
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>X11 file managers.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-x11-fonts
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>X11 fonts and font utilities.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-x11-toolkits
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>X11 toolkits.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-x11-servers
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>X11 servers.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-x11-themes
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>X11 themes.</para>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	- <term><literal>ports-x11-wm
	- release=cvs</literal></term>
	-
	- <listitem>
	- <para>X11 window managers.</para>
	- </listitem>
	- </varlistentry>
	- </variablelist>
	- </listitem>
	- </varlistentry>
	-
	- <varlistentry>
	<term>
	<literal>projects-all release=cvs</literal>
	</term>

	<listitem>
	<para>Sources for the &os; projects
	repository.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-all release=cvs</literal></term>

	<listitem>
	<para>The main &os; sources, including the
	cryptography code.</para>

	<variablelist>
	<varlistentry>
	<term><literal>src-base
	release=cvs</literal></term>

	<listitem>
	<para>Miscellaneous files at the top of
	<filename>/usr/src</filename>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-bin
	release=cvs</literal></term>

	<listitem>
	<para>User utilities that may be needed in
	single-user mode
	(<filename>/usr/src/bin</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-cddl
	release=cvs</literal></term>

	<listitem>
	<para>Utilities and libraries covered by the
	CDDL license
	(<filename>/usr/src/cddl</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-contrib
	release=cvs</literal></term>

	<listitem>
	<para>Utilities and libraries from outside the
	&os; project, used relatively unmodified
	(<filename>/usr/src/contrib</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>
	<literal>src-crypto release=cvs</literal>
	</term>

	<listitem>
	<para>Cryptography utilities and libraries
	from outside the &os; project, used
	relatively unmodified

	(<filename>/usr/src/crypto</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>
	<literal>src-eBones release=cvs</literal>
	</term>

	<listitem>
	<para>Kerberos and DES
	(<filename>/usr/src/eBones</filename>). Not
	used in current releases of &os;.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-etc
	release=cvs</literal></term>

	<listitem>
	<para>System configuration files
	(<filename>/usr/src/etc</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-games
	release=cvs</literal></term>

	<listitem>
	<para>Games
	(<filename>/usr/src/games</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-gnu
	release=cvs</literal></term>

	<listitem>
	<para>Utilities covered by the GNU Public
	License
	(<filename>/usr/src/gnu</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-include
	release=cvs</literal></term>

	<listitem>
	<para>Header files
	(<filename>/usr/src/include</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-kerberos5
	release=cvs</literal></term>

	<listitem>
	<para>Kerberos5 security package
	(<filename>/usr/src/kerberos5</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-kerberosIV
	release=cvs</literal></term>

	<listitem>
	<para>KerberosIV security package
	(<filename>/usr/src/kerberosIV</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-lib
	release=cvs</literal></term>

	<listitem>
	<para>Libraries
	(<filename>/usr/src/lib</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-libexec
	release=cvs</literal></term>

	<listitem>
	<para>System programs normally executed by
	other programs
	(<filename>/usr/src/libexec</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-release
	release=cvs</literal></term>

	<listitem>
	<para>Files required to produce a &os;
	release
	(<filename>/usr/src/release</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-rescue
	release=cvs</literal></term>

	<listitem>
	<para>Statically linked programs for emergency
	recovery; see &man.rescue.8;
	(<filename>/usr/src/rescue</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>
	<literal>src-sbin release=cvs</literal>
	</term>

	<listitem>
	<para>System utilities for single-user mode
	(<filename>/usr/src/sbin</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-secure
	release=cvs</literal></term>

	<listitem>
	<para>Cryptographic libraries and commands
	(<filename>/usr/src/secure</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-share
	release=cvs</literal></term>

	<listitem>
	<para>Files that can be shared across multiple
	systems
	(<filename>/usr/src/share</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-sys
	release=cvs</literal></term>

	<listitem>
	<para>The kernel
	(<filename>/usr/src/sys</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-sys-crypto
	release=cvs</literal></term>

	<listitem>
	<para>Kernel cryptography code
	(<filename>/usr/src/sys/crypto</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-tools
	release=cvs</literal></term>

	<listitem>
	<para>Various tools for the maintenance of
	&os;
	(<filename>/usr/src/tools</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-usrbin
	release=cvs</literal></term>

	<listitem>
	<para>User utilities
	(<filename>/usr/src/usr.bin</filename>).</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>src-usrsbin
	release=cvs</literal></term>

	<listitem>
	<para>System utilities
	(<filename>/usr/src/usr.sbin</filename>).</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</listitem>
	</varlistentry>
	</variablelist>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>distrib release=self</literal></term>

	<listitem>
	<para>The <application>CVSup</application> server's own
	configuration files. Used by
	<application>CVSup</application> mirror sites.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>gnats release=current</literal></term>

	<listitem>
	<para>The GNATS bug-tracking database.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>mail-archive release=current</literal></term>

	<listitem>
	<para>&os; mailing list archive.</para>
	</listitem>
	</varlistentry>
	-
	- <varlistentry>
	- <term><literal>www release=current</literal></term>
	-
	- <listitem>
	- <para>The pre-processed &os; WWW site files (not the
	- source files). Used by WWW mirror sites.</para>
	- </listitem>
	- </varlistentry>
	</variablelist>
	</sect2>

	<sect2>
	<title>For More Information</title>

	<para>For the <application>CVSup</application> FAQ and other
	information about <application>CVSup</application>, see
	<ulink url="http://www.cvsup.org">The
	CVSup Home Page</ulink>.</para>

	<para>Most &os;-related discussion of
	<application>CVSup</application> takes place on the
	&a.hackers;. New versions of the software are announced
	there, as well as on the &a.announce;.</para>

	<para>For questions or bug reports about
	<application>CVSup</application> take a look at the
	<ulink url="http://www.cvsup.org/faq.html#bugreports">
	CVSup FAQ</ulink>.</para>
	</sect2>

	<sect2 id="cvsup-mirrors">
	<title>CVSup Sites</title>

	<para><link linkend="cvsup">CVSup</link> servers for &os; are
	running at the following sites:</para>

	&chap.mirrors.cvsup.inc;
	</sect2>
	</sect1>

	<sect1 id="cvs-tags">
	<title>CVS Tags</title>

	<warning>
	<para>CVS has been deprecated by the project, and its use is not
	recommended. <application>Subversion</application> should be
	used instead.</para>
	</warning>

	<para>When obtaining or updating sources using
	<application>cvs</application> or
	<application>CVSup</application>, a revision tag must be
	specified. A revision tag refers to either a particular line of
	&os; development, or a specific point in time. The first type
	are called <quote>branch tags</quote>, and the second type are
	called <quote>release tags</quote>.</para>

	<sect2>
	<title>Branch Tags</title>

	<para>All of these, with the exception of
	<literal>HEAD</literal> (which is always a valid tag), only
	apply to the <filename>src/</filename> tree. The
	<filename>ports/</filename>, <filename>doc/</filename>, and
	<filename>www/</filename> trees are not branched.</para>

	<variablelist>
	<varlistentry>
	<term>HEAD</term>

	<listitem>
	<para>Symbolic name for the main line, or &os;-CURRENT.
	Also the default when no revision is specified.</para>

	<para>In <application>CVSup</application>, this tag is
	represented by a <literal>.</literal> (not punctuation,
	but a literal <literal>.</literal> character).</para>

	<note>
	<para>In CVS, this is the default when no revision tag
	is specified. It is usually <emphasis>not</emphasis>
	a good idea to checkout or update to CURRENT sources
	on a STABLE machine, unless that is your
	intent.</para>
	</note>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_9</term>

	<listitem>
	<para>The line of development for &os;-9.X, also known
	as &os; 9-STABLE</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	+ <term>RELENG_9_1</term>
	+
	+ <listitem>
	+ <para>The release branch for &os;-9.1, used only for
	+ security advisories and other critical fixes.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	<term>RELENG_9_0</term>

	<listitem>
	<para>The release branch for &os;-9.0, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_8</term>

	<listitem>
	<para>The line of development for &os;-8.X, also known
	as &os; 8-STABLE</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	+ <term>RELENG_8_4</term>
	+
	+ <listitem>
	+ <para>The release branch for &os;-8.4, used only for
	+ security advisories and other critical fixes.</para>
	+ </listitem>
	+ </varlistentry>
	+
	+ <varlistentry>
	<term>RELENG_8_3</term>

	<listitem>
	<para>The release branch for &os;-8.3, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_8_2</term>

	<listitem>
	<para>The release branch for &os;-8.2, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_8_1</term>

	<listitem>
	<para>The release branch for &os;-8.1, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_8_0</term>

	<listitem>
	<para>The release branch for &os;-8.0, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_7</term>

	<listitem>
	<para>The line of development for &os;-7.X, also known
	as &os; 7-STABLE</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_7_4</term>

	<listitem>
	<para>The release branch for &os;-7.4, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_7_3</term>

	<listitem>
	<para>The release branch for &os;-7.3, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_7_2</term>

	<listitem>
	<para>The release branch for &os;-7.2, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_7_1</term>

	<listitem>
	<para>The release branch for &os;-7.1, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_7_0</term>

	<listitem>
	<para>The release branch for &os;-7.0, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_6</term>

	<listitem>
	<para>The line of development for &os;-6.X, also known
	as &os; 6-STABLE</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_6_4</term>

	<listitem>
	<para>The release branch for &os;-6.4, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_6_3</term>

	<listitem>
	<para>The release branch for &os;-6.3, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_6_2</term>

	<listitem>
	<para>The release branch for &os;-6.2, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_6_1</term>

	<listitem>
	<para>The release branch for &os;-6.1, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_6_0</term>

	<listitem>
	<para>The release branch for &os;-6.0, used only for
	security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5</term>

	<listitem>
	<para>The line of development for &os;-5.X, also known
	as &os; 5-STABLE.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_5</term>

	<listitem>
	<para>The release branch for &os;-5.5, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_4</term>

	<listitem>
	<para>The release branch for &os;-5.4, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_3</term>

	<listitem>
	<para>The release branch for &os;-5.3, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_2</term>

	<listitem>
	<para>The release branch for &os;-5.2 and
	&os;-5.2.1, used only for security advisories and other
	critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_1</term>

	<listitem>
	<para>The release branch for &os;-5.1, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_0</term>

	<listitem>
	<para>The release branch for &os;-5.0, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4</term>

	<listitem>
	<para>The line of development for &os;-4.X, also known
	as &os; 4-STABLE.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_11</term>

	<listitem>
	<para>The release branch for &os;-4.11, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_10</term>

	<listitem>
	<para>The release branch for &os;-4.10, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_9</term>

	<listitem>
	<para>The release branch for &os;-4.9, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_8</term>

	<listitem>
	<para>The release branch for &os;-4.8, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_7</term>

	<listitem>
	<para>The release branch for &os;-4.7, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_6</term>

	<listitem>
	<para>The release branch for &os;-4.6 and &os;-4.6.2,
	used only for security advisories and other
	critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_5</term>

	<listitem>
	<para>The release branch for &os;-4.5, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_4</term>

	<listitem>
	<para>The release branch for &os;-4.4, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_3</term>

	<listitem>
	<para>The release branch for &os;-4.3, used only
	for security advisories and other critical fixes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_3</term>

	<listitem>
	<para>The line of development for &os;-3.X, also known
	as 3.X-STABLE.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_2_2</term>

	<listitem>
	<para>The line of development for &os;-2.2.X, also known
	as 2.2-STABLE. This branch is mostly obsolete.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect2>

	<sect2>
	<title>Release Tags</title>

	<para>These tags refer to a specific point in time when a
	particular version of &os; was released. The release
	engineering process is documented in more detail by the
	<ulink url="&url.base;/releng/">Release Engineering
	Information</ulink> and
	<ulink url="&url.articles.releng;/release-proc.html">Release
	Process</ulink> documents. The
	<filename class="directory">src</filename> tree uses tag names
	that start with <literal>RELENG_</literal> tags. The
	<filename class="directory">ports</filename> and
	<filename class="directory">doc</filename> trees use tags
	whose names begin with <literal>RELEASE</literal> tags.
	Finally, the <filename class="directory">www</filename> tree
	is not tagged with any special name for releases.</para>

	<variablelist>
	+ <varlistentry>
	+ <term>RELENG_9_1_0_RELEASE</term>
	+
	+ <listitem>
	+ <para>&os; 9.1</para>
	+ </listitem>
	+ </varlistentry>
	+
	<varlistentry>
	<term>RELENG_9_0_0_RELEASE</term>

	<listitem>
	<para>&os; 9.0</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_8_3_0_RELEASE</term>

	<listitem>
	<para>&os; 8.3</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_8_2_0_RELEASE</term>

	<listitem>
	<para>&os; 8.2</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_8_1_0_RELEASE</term>

	<listitem>
	<para>&os; 8.1</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_8_0_0_RELEASE</term>

	<listitem>
	<para>&os; 8.0</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_7_4_0_RELEASE</term>

	<listitem>
	<para>&os; 7.4</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_7_3_0_RELEASE</term>

	<listitem>
	<para>&os; 7.3</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_7_2_0_RELEASE</term>

	<listitem>
	<para>&os; 7.2</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_7_1_0_RELEASE</term>

	<listitem>
	<para>&os; 7.1</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_7_0_0_RELEASE</term>

	<listitem>
	<para>&os; 7.0</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_6_4_0_RELEASE</term>

	<listitem>
	<para>&os; 6.4</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_6_3_0_RELEASE</term>

	<listitem>
	<para>&os; 6.3</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_6_2_0_RELEASE</term>

	<listitem>
	<para>&os; 6.2</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_6_1_0_RELEASE</term>

	<listitem>
	<para>&os; 6.1</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_6_0_0_RELEASE</term>

	<listitem>
	<para>&os; 6.0</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_5_0_RELEASE</term>

	<listitem>
	<para>&os; 5.5</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_4_0_RELEASE</term>

	<listitem>
	<para>&os; 5.4</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_11_0_RELEASE</term>

	<listitem>
	<para>&os; 4.11</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_3_0_RELEASE</term>

	<listitem>
	<para>&os; 5.3</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_10_0_RELEASE</term>

	<listitem>
	<para>&os; 4.10</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_2_1_RELEASE</term>

	<listitem>
	<para>&os; 5.2.1</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_2_0_RELEASE</term>

	<listitem>
	<para>&os; 5.2</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_9_0_RELEASE</term>

	<listitem>
	<para>&os; 4.9</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_1_0_RELEASE</term>

	<listitem>
	<para>&os; 5.1</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_8_0_RELEASE</term>

	<listitem>
	<para>&os; 4.8</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_5_0_0_RELEASE</term>

	<listitem>
	<para>&os; 5.0</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_7_0_RELEASE</term>

	<listitem>
	<para>&os; 4.7</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_6_2_RELEASE</term>

	<listitem>
	<para>&os; 4.6.2</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_6_1_RELEASE</term>

	<listitem>
	<para>&os; 4.6.1</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_6_0_RELEASE</term>

	<listitem>
	<para>&os; 4.6</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_5_0_RELEASE</term>

	<listitem>
	<para>&os; 4.5</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_4_0_RELEASE</term>

	<listitem>
	<para>&os; 4.4</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_3_0_RELEASE</term>

	<listitem>
	<para>&os; 4.3</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_2_0_RELEASE</term>

	<listitem>
	<para>&os; 4.2</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_1_1_RELEASE</term>

	<listitem>
	<para>&os; 4.1.1</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_1_0_RELEASE</term>

	<listitem>
	<para>&os; 4.1</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_4_0_0_RELEASE</term>

	<listitem>
	<para>&os; 4.0</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_3_5_0_RELEASE</term>

	<listitem>
	<para>&os;-3.5</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_3_4_0_RELEASE</term>

	<listitem>
	<para>&os;-3.4</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_3_3_0_RELEASE</term>

	<listitem>
	<para>&os;-3.3</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_3_2_0_RELEASE</term>

	<listitem>
	<para>&os;-3.2</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_3_1_0_RELEASE</term>

	<listitem>
	<para>&os;-3.1</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_3_0_0_RELEASE</term>

	<listitem>
	<para>&os;-3.0</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_2_2_8_RELEASE</term>

	<listitem>
	<para>&os;-2.2.8</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_2_2_7_RELEASE</term>

	<listitem>
	<para>&os;-2.2.7</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_2_2_6_RELEASE</term>

	<listitem>
	<para>&os;-2.2.6</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_2_2_5_RELEASE</term>

	<listitem>
	<para>&os;-2.2.5</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_2_2_2_RELEASE</term>

	<listitem>
	<para>&os;-2.2.2</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_2_2_1_RELEASE</term>

	<listitem>
	<para>&os;-2.2.1</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RELENG_2_2_0_RELEASE</term>

	<listitem>
	<para>&os;-2.2.0</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect2>
	</sect1>

	<sect1 id="mirrors-rsync">
	<title><application>rsync</application> Sites</title>

	<para>The following sites make &os; available through the rsync
	protocol. The <application>rsync</application> utility works in
	much the same way as the &man.rcp.1; command,
	but has more options and uses the rsync remote-update protocol
	which transfers only the differences between two sets of files,
	thus greatly speeding up the synchronization over the network.
	This is most useful if you are a mirror site for the
	&os; FTP server, or the CVS repository. The
	<application>rsync</application> suite is available for many
	operating systems, on &os;, see the
	<filename role="package">net/rsync</filename>
	port or use the package.</para>

	<variablelist>
	<varlistentry>
	<term>Czech Republic</term>

	<listitem>
	<para>rsync://ftp.cz.FreeBSD.org/</para>

	<para>Available collections:</para>
	<itemizedlist>
	<listitem>
	<para>ftp: A partial mirror of the &os; FTP
	server.</para>
	</listitem>

	<listitem>
	<para>&os;: A full mirror of the &os; FTP server.</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Netherlands</term>

	<listitem>
	<para>rsync://ftp.nl.FreeBSD.org/</para>

	<para>Available collections:</para>
	<itemizedlist>
	<listitem>
	<para>&os;: A full mirror of the &os; FTP server.</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Russia</term>

	<listitem>
	<para>rsync://ftp.mtu.ru/</para>

	<para>Available collections:</para>

	<itemizedlist>
	<listitem>
	<para>&os;: A full mirror of the &os; FTP server.</para>
	</listitem>

	<listitem>
	<para>&os;-gnats: The GNATS bug-tracking
	database.</para>
	</listitem>

	<listitem>
	<para>&os;-Archive: The mirror of &os; Archive
	FTP server.</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Sweden</term>

	<listitem>
	<para>rsync://ftp4.se.freebsd.org/</para>

	<para>Available collections:</para>
	<itemizedlist>
	<listitem>
	<para>&os;: A full mirror of the &os; FTP server.</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Taiwan</term>

	<listitem>
	<para>rsync://ftp.tw.FreeBSD.org/</para>

	<para>rsync://ftp2.tw.FreeBSD.org/</para>

	<para>rsync://ftp6.tw.FreeBSD.org/</para>

	<para>Available collections:</para>
	<itemizedlist>
	<listitem>
	<para>&os;: A full mirror of the &os; FTP server.</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>United Kingdom</term>

	<listitem>
	<para>rsync://rsync.mirrorservice.org/</para>

	<para>Available collections:</para>
	<itemizedlist>
	<listitem>
	<para>ftp.freebsd.org: A full mirror of the &os;
	FTP server.</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>United States of America</term>

	<listitem>
	<para>rsync://ftp-master.FreeBSD.org/</para>

	<para>This server may only be used by &os; primary mirror
	sites.</para>
	<para>Available collections:</para>
	<itemizedlist>
	<listitem>
	<para>&os;: The master archive of the &os; FTP
	server.</para>
	</listitem>

	<listitem>
	<para>acl: The &os; master ACL list.</para>
	</listitem>
	</itemizedlist>

	<para>rsync://ftp13.FreeBSD.org/</para>

	<para>Available collections:</para>

	<itemizedlist>
	<listitem>
	<para>&os;: A full mirror of the &os; FTP server.</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect1>
	</appendix>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml (revision 41355)
	@@ -1,2001 +1,1967 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="multimedia">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Ross</firstname>
	<surname>Lippert</surname>
	<contrib>Edited by </contrib>
	</author>
	</authorgroup>
	</chapterinfo>

	<title>Multimedia</title>

	<sect1 id="multimedia-synopsis">
	<title>Synopsis</title>

	<para>FreeBSD supports a wide variety of sound cards, allowing you
	to enjoy high fidelity output from your computer. This includes
	the ability to record and playback audio in the MPEG Audio Layer
	3 (MP3), WAV, and Ogg Vorbis formats as well as many other
	formats. The FreeBSD Ports Collection also contains
	applications allowing you to edit your recorded audio, add sound
	effects, and control attached MIDI devices.</para>

	<para>With some experimentation, &os; can support
	playback of video files and DVDs. The number of applications
	to encode, convert, and playback various video media is more
	limited than the number of sound applications. For example as
	of this writing, there are no good re-encoding applications
	in the FreeBSD Ports Collection that could be used to convert
	between formats, as there is with <filename
	role="package">audio/sox</filename>. However, the software
	landscape in this area is changing rapidly.</para>

	<para>This chapter will describe the necessary steps to configure
	your sound card. The configuration and installation of X11
	(<xref linkend="x11"/>) has already taken care of the
	hardware issues for your video card, though there may be some
	tweaks to apply for better playback.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>How to configure your system so that your sound card
	is recognized.</para>
	</listitem>

	<listitem>
	<para>Methods to test whether your card is working.</para>
	</listitem>

	<listitem>
	<para>How to troubleshoot your sound setup.</para>
	</listitem>

	<listitem>
	<para>How to playback and encode MP3s and other audio.</para>
	</listitem>

	<listitem>
	<para>How video is supported by the X server.</para>
	</listitem>

	<listitem>
	<para>Some video player/encoder ports which give good
	results.</para>
	</listitem>

	<listitem>
	<para>How to playback DVDs, <filename>.mpg</filename> and
	<filename>.avi</filename> files.</para>
	</listitem>

	<listitem>
	<para>How to rip CD and DVD content into files.</para>
	</listitem>

	<listitem>
	<para>How to configure a TV card.</para>
	</listitem>

	<listitem>
	<para>How to configure an image scanner.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem><para>Know how to configure and install a new kernel
	(<xref linkend="kernelconfig"/>).</para></listitem>
	</itemizedlist>

	<warning>
	<para>Trying to mount audio CDs with the &man.mount.8; command
	will result in an error, at least, and a <emphasis>kernel
	panic</emphasis>, at worst. These media have specialized
	encodings which differ from the usual ISO-filesystem.</para>
	</warning>

	</sect1>

	<sect1 id="sound-setup">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Moses</firstname>
	<surname>Moore</surname>
	<contrib>Contributed by </contrib>
	<!-- 20 November 2000 -->
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Marc</firstname>
	<surname>Fonvieille</surname>
	<contrib>Enhanced by </contrib>
	<!-- 13 September 2004 -->
	</author>
	</authorgroup>
	</sect1info>

	<title>Setting Up the Sound Card</title>

	<sect2 id="sound-device">
	<title>Configuring the System</title>

	<indexterm><primary>PCI</primary></indexterm>
	<indexterm><primary>ISA</primary></indexterm>
	<indexterm><primary>sound cards</primary></indexterm>
	<para>Before you begin, you should know the model of the card
	you have, the chip it uses, and whether it is a PCI or ISA
	card. FreeBSD supports a wide variety of both PCI and ISA
	cards. Check the supported audio devices list of the <ulink
	url="&rel.current.hardware;">Hardware Notes</ulink> to
	see if your card is supported. The Hardware Notes will
	also mention which driver supports your card.</para>

	<indexterm>
	<primary>kernel</primary>
	<secondary>configuration</secondary>
	</indexterm>

	<para>To use your sound device, you will need to load the proper
	device driver. This may be accomplished in one of two ways.
	The easiest way is to simply load a kernel module for your
	sound card with &man.kldload.8; which can either be done from
	the command line:</para>

	<screen>&prompt.root; <userinput>kldload snd_emu10k1</userinput></screen>

	<para>or by adding the appropriate line to the file
	<filename>/boot/loader.conf</filename> like this:</para>

	<programlisting>snd_emu10k1_load="YES"</programlisting>

	<para>These examples are for a Creative &soundblaster; Live! sound
	card. Other available loadable sound modules are listed in
	<filename>/boot/defaults/loader.conf</filename>.
	If you are not sure which driver to use, you may try to load
	the <filename>snd_driver</filename> module:</para>

	<screen>&prompt.root; <userinput>kldload snd_driver</userinput></screen>

	<para>This is a metadriver loading the most common device drivers
	at once. This speeds up the search for the correct driver. It
	is also possible to load all sound drivers via the
	<filename>/boot/loader.conf</filename> facility.</para>

	<para>If you wish to find out the driver selected for your
	soundcard after loading the <filename>snd_driver</filename>
	metadriver, you may check the <filename>/dev/sndstat</filename>
	file with the <command>cat /dev/sndstat</command>
	command.</para>

	<para>A second method is to statically
	compile in support for your sound card in your kernel. The
	section below provides the information you need to add support
	for your hardware in this manner. For more information about
	recompiling your kernel, please see <xref
	linkend="kernelconfig"/>.</para>

	<sect3>
	<title>Configuring a Custom Kernel with Sound Support</title>

	<para>The first thing to do is add the audio framework driver
	&man.sound.4; to the kernel; for that you will need to
	add the following line to the kernel configuration file:</para>

	<programlisting>device sound</programlisting>

	<para>Next, you have to add the support for your sound card.
	Therefore, you need to know which driver supports the card.
	Check the supported audio devices list of the <ulink
	url="&rel.current.hardware;">Hardware Notes</ulink>, to
	determine the correct driver for your sound card. For
	example, a Creative &soundblaster; Live! sound card is
	supported by the &man.snd.emu10k1.4; driver. To add the support
	for this card, use the following:</para>

	<programlisting>device snd_emu10k1</programlisting>

	<para>Be sure to read the manual page of the driver for the
	syntax to use. The explicit syntax for the kernel
	configuration of every supported sound driver can also be
	found in the <filename>/usr/src/sys/conf/NOTES</filename>
	file.</para>

	<para>Non-PnP ISA sound cards may require you to provide the
	kernel with information on the card settings (IRQ, I/O port,
	etc), as is true of all non-PnP ISA cards. This is done via
	the <filename>/boot/device.hints</filename> file. During the
	boot process, the &man.loader.8; will read this file and pass
	the settings to the kernel. For example, an old Creative
	&soundblaster; 16 ISA non-PnP card will use the
	&man.snd.sbc.4; driver in conjunction with
	<literal>snd_sb16</literal>. For this card the following
	lines must be added to the kernel configuration file:</para>

	<programlisting>device snd_sbc
	device snd_sb16</programlisting>

	<para>and these to
	<filename>/boot/device.hints</filename>:</para>

	<programlisting>hint.sbc.0.at="isa"
	hint.sbc.0.port="0x220"
	hint.sbc.0.irq="5"
	hint.sbc.0.drq="1"
	hint.sbc.0.flags="0x15"</programlisting>

	<para>In this case, the card uses the <literal>0x220</literal>
	I/O port and the IRQ <literal>5</literal>.</para>

	<para>The syntax used in the
	<filename>/boot/device.hints</filename> file is covered in the
	&man.sound.4; driver manual page and the manual page
	for the driver in question.</para>

	<para>The settings shown above are the defaults. In some
	cases, you may need to change the IRQ or the other settings to
	match your card. See the &man.snd.sbc.4; manual page for more
	information about this card.</para>
	</sect3>
	</sect2>

	<sect2 id="sound-testing">
	<title>Testing the Sound Card</title>

	<para>After rebooting with the modified kernel, or after loading
	the required module, the sound card should appear in your system
	message buffer (&man.dmesg.8;) as something like:</para>

	<screen>pcm0: <Intel ICH3 (82801CA)> port 0xdc80-0xdcbf,0xd800-0xd8ff irq 5 at device 31.5 on pci0
	pcm0: [GIANT-LOCKED]
	pcm0: <Cirrus Logic CS4205 AC97 Codec></screen>

	<para>The status of the sound card may be checked via the
	<filename>/dev/sndstat</filename> file:</para>

	<screen>&prompt.root; <userinput>cat /dev/sndstat</userinput>
	FreeBSD Audio Driver (newpcm)
	Installed devices:
	pcm0: <Intel ICH3 (82801CA)> at io 0xd800, 0xdc80 irq 5 bufsz 16384
	kld snd_ich (1p/2r/0v channels duplex default)</screen>

	<para>The output from your system may vary. If no
	<devicename>pcm</devicename> devices are listed, go back and
	review what was done earlier. Go through your kernel
	configuration file again and make sure the correct
	device driver was chosen. Common problems are listed in <xref
	linkend="troubleshooting"/>.</para>

	<para>If all goes well, you should now have a functioning sound
	card. If your CD-ROM or DVD-ROM drive's audio-out pins are
	properly connected to your sound card, you can put a CD in the
	drive and play it with &man.cdcontrol.1;:</para>

	<screen>&prompt.user; <userinput>cdcontrol -f /dev/acd0 play 1</userinput></screen>

	<para>Various applications, such as <filename
	role="package">audio/workman</filename> can provide a
	friendlier interface. You may want to install an application
	such as <filename role="package">audio/mpg123</filename> to
	listen to MP3 audio files.</para>

	<para>Another quick way to test the card is sending data
	to <filename>/dev/dsp</filename>, like this:</para>

	<screen>&prompt.user; <userinput>cat <replaceable>filename</replaceable> > /dev/dsp</userinput></screen>

	<para>where
	<filename><replaceable>filename</replaceable></filename> can
	be any file. This command line should produce some noise,
	confirming the sound card is actually working.</para>

	<note>
	<para>The device nodes <filename>/dev/dsp*</filename> will be
	created automatically when needed. If they are not used, they
	do not exist and will not appear in the output of
	&man.ls.1;.</para>
	</note>

	<para>Sound card mixer levels can be changed via the &man.mixer.8;
	command. More details can be found in the &man.mixer.8; manual
	page.</para>

	<sect3 id="troubleshooting">
	<title>Common Problems</title>

	<indexterm><primary>device nodes</primary></indexterm>
	<indexterm><primary>I/O port</primary></indexterm>
	<indexterm><primary>IRQ</primary></indexterm>
	<indexterm><primary>DSP</primary></indexterm>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Error</entry>
	<entry>Solution</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><errorname>sb_dspwr(XX) timed
	out</errorname></entry>
	<entry><para>The I/O port is not set
	correctly.</para></entry>
	</row>

	<row>
	<entry><errorname>bad irq XX</errorname></entry>
	<entry><para>The IRQ is set incorrectly. Make sure
	that the set IRQ and the sound IRQ are the
	same.</para></entry>
	</row>

	<row>
	<entry><errorname>xxx: gus pcm not attached, out of
	memory</errorname></entry>
	<entry><para>There is not enough available memory to
	use the device.</para></entry>
	</row>

	<row>
	<entry><errorname>xxx: can't open
	/dev/dsp!</errorname></entry>
	<entry><para>Check with <command>fstat \| grep
	dsp</command>
	if another application is holding the device open.
	Noteworthy troublemakers are
	<application>esound</application> and
	<application>KDE</application>'s sound
	support.</para></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>Another issue is that modern graphics cards often come
	with their own sound driver, for use with
	<acronym>HDMI</acronym> and similar. This sound device will
	sometimes be enumerated before the actual soundcard and the
	soundcard will subsequently not be used as the default
	playback device. To check if this is the case, run
	<application>dmesg</application> and look for
	<literal>pcm</literal>. The output looks something like
	this:</para>

	<programlisting>...
	hdac0: HDA Driver Revision: 20100226_0142
	hdac1: HDA Driver Revision: 20100226_0142
	hdac0: HDA Codec #0: NVidia (Unknown)
	hdac0: HDA Codec #1: NVidia (Unknown)
	hdac0: HDA Codec #2: NVidia (Unknown)
	hdac0: HDA Codec #3: NVidia (Unknown)
	pcm0: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 0 nid 1 on hdac0
	pcm1: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 1 nid 1 on hdac0
	pcm2: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 2 nid 1 on hdac0
	pcm3: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 3 nid 1 on hdac0
	hdac1: HDA Codec #2: Realtek ALC889
	pcm4: <HDA Realtek ALC889 PCM #0 Analog> at cad 2 nid 1 on hdac1
	pcm5: <HDA Realtek ALC889 PCM #1 Analog> at cad 2 nid 1 on hdac1
	pcm6: <HDA Realtek ALC889 PCM #2 Digital> at cad 2 nid 1 on hdac1
	pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1
	...</programlisting>

	<para>Here the graphics card (<literal>NVidia</literal>) has
	been enumerated before the sound card (<literal>Realtek
	ALC889</literal>). To use the sound card as default playback
	device, change <literal>hw.snd.default_unit</literal> to the
	unit that should be used for playback, enter the
	following:</para>

	<screen>&prompt.root; <userinput>sysctl hw.snd.default_unit=<replaceable>n</replaceable></userinput></screen>

	<para>Here, <literal>n</literal> is the number of the sound
	device to use, in this example <literal>4</literal>. You can
	make this change permanent by adding the following line to
	<filename>/etc/sysctl.conf</filename>:</para>

	<programlisting>hw.snd.default_unit=<replaceable>4</replaceable></programlisting>
	</sect3>
	</sect2>

	<sect2 id="sound-multiple-sources">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Munish</firstname>
	<surname>Chopra</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>
	<title>Utilizing Multiple Sound Sources</title>

	<para>It is often desirable to have multiple sources of sound that
	are able to play simultaneously, such as when
	<application>esound</application> or
	<application>artsd</application> do not support sharing of the
	sound device with a certain application.</para>

	<para>FreeBSD lets you do this through <emphasis>Virtual Sound
	Channels</emphasis>, which can be enabled with the
	&man.sysctl.8; facility. Virtual channels allow you to
	multiplex your sound card's playback by mixing sound in the
	kernel.</para>

	<para>To set the number of virtual channels, there are three
	sysctl knobs which, if you are the <username>root</username>
	user, can be set like this:</para>

	<screen>&prompt.root; <userinput>sysctl dev.pcm.0.play.vchans=4</userinput>
	&prompt.root; <userinput>sysctl dev.pcm.0.rec.vchans=4</userinput>
	&prompt.root; <userinput>sysctl hw.snd.maxautovchans=4</userinput></screen>

	<para>The above example allocates four virtual channels, which
	is a practical number for everyday use. Both
	<varname>dev.pcm.0.play.vchans=4</varname> and
	<varname>dev.pcm.0.rec.vchans=4</varname> are the number of
	virtual channels <devicename>pcm0</devicename> has for playback
	and recording, and are configurable once a device has been
	attached. <literal>hw.snd.maxautovchans</literal> is the number
	of virtual channels a new audio device is given when it is
	attached using &man.kldload.8;. Since the
	<devicename>pcm</devicename> module can be loaded independently
	of the hardware drivers, <varname>hw.snd.maxautovchans</varname>
	can store how many virtual channels any devices which are
	attached later will be given. Refer to &man.pcm.4; manual page
	for more information.</para>

	<note>
	<para>You cannot change the number of virtual channels for a
	device while it is in use. First close any programs using
	the device, such as music players or sound daemons.</para>
	</note>

	<para>
	The correct <devicename>pcm</devicename> device will
	automatically be allocated transparently to a program
	that requests <filename>/dev/dsp0</filename>.</para>
	</sect2>

	<sect2>
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Josef</firstname>
	<surname>El-Rayes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>Setting Default Values for Mixer Channels</title>

	<para>The default values for the different mixer channels are
	hardcoded in the sourcecode of the &man.pcm.4; driver. There
	are many different applications and daemons that allow
	you to set values for the mixer that are remembered between
	invocations, but this is not a clean solution. It is possible
	to set default mixer values at the driver level — this
	is accomplished by defining the appropriate values in
	<filename>/boot/device.hints</filename>, e.g.:</para>

	<programlisting>hint.pcm.0.vol="50"</programlisting>

	<para>This will set the volume channel to a default value of
	50 when the &man.pcm.4; module is loaded.</para>
	</sect2>
	</sect1>

	<sect1 id="sound-mp3">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Chern</firstname>
	<surname>Lee</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<!-- 11 Sept 2001 -->
	</sect1info>

	<title>MP3 Audio</title>

	<para>MP3 (MPEG Layer 3 Audio) accomplishes near CD-quality sound,
	leaving no reason to let your FreeBSD workstation fall short of
	its offerings.</para>

	<sect2 id="mp3-players">
	<title>MP3 Players</title>

	<para>By far, the most popular X11 MP3 player is
	<application>XMMS</application> (X Multimedia System).
	<application>Winamp</application>
	skins can be used with <application>XMMS</application> since
	the GUI is almost identical to that of Nullsoft's
	<application>Winamp</application>.
	<application>XMMS</application> also has native plug-in
	support.</para>

	<para><application>XMMS</application> can be installed from
	the <filename role="package">multimedia/xmms</filename> port
	or package.</para>

	<para><application>XMMS</application>'s interface is intuitive,
	with a playlist, graphic equalizer, and more. Those familiar
	with <application>Winamp</application> will find
	<application>XMMS</application> simple to use.</para>

	<para>The <filename role="package">audio/mpg123</filename> port
	is an alternative, command-line MP3 player.</para>

	<para><application>mpg123</application> can be run by specifying
	the sound device and the MP3 file on the command line.
	Assuming your audio device is
	<devicename>/dev/dsp1.0</devicename> and you want to play the
	MP3 file <replaceable>Foobar-GreatestHits.mp3</replaceable>
	you would enter the following:</para>

	<screen>&prompt.root; <userinput>mpg123 -a <devicename>/dev/dsp1.0</devicename> <replaceable>Foobar-GreatestHits.mp3</replaceable></userinput>
	High Performance MPEG 1.0/2.0/2.5 Audio Player for Layer 1, 2 and 3.
	Version 0.59r (1999/Jun/15). Written and copyrights by Michael Hipp.
	Uses code from various people. See 'README' for more!
	THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY! USE AT YOUR OWN RISK!





	Playing MPEG stream from Foobar-GreatestHits.mp3 ...
	MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen>
	</sect2>

	<sect2 id="rip-cd">
	<title>Ripping CD Audio Tracks</title>

	<para>Before encoding a CD or CD track to MP3, the audio data on
	the CD must be ripped onto the hard drive. This is done by
	copying the raw CDDA (CD Digital Audio) data to WAV
	files.</para>

	<para>The <command>cdda2wav</command> tool, which is a part of
	the <filename role="package">sysutils/cdrtools</filename>
	suite, is used for ripping audio information from CDs and the
	information associated with them.</para>

	<para>With the audio CD in the drive, the following command can
	be issued (as <username>root</username>) to rip an entire CD
	into individual (per track) WAV files:</para>

	<screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -B</userinput></screen>

	<para><application>cdda2wav</application> will support
	ATAPI (IDE) CDROM drives. To rip from an IDE drive, specify
	the device name in place of the SCSI unit numbers. For
	example, to rip track 7 from an IDE drive:</para>

	<screen>&prompt.root; <userinput>cdda2wav -D <replaceable>/dev/acd0</replaceable> -t 7</userinput></screen>

	<para>The <option>-D <replaceable>0,1,0</replaceable></option>
	indicates the SCSI device <devicename>0,1,0</devicename>,
	which corresponds to the output of <command>cdrecord
	-scanbus</command>.</para>

	<para>To rip individual tracks, make use of the
	<option>-t</option> option as shown:</para>

	<screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -t 7</userinput></screen>

	<para>This example rips track seven of the audio CDROM. To rip
	a range of tracks, for example, track one to seven, specify a
	range:</para>

	<screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -t 1+7</userinput></screen>

	<para>The utility &man.dd.1; can also be used to extract audio
	tracks on ATAPI drives, read <xref
	linkend="duplicating-audiocds"/> for more information on
	that possibility.</para>

	</sect2>

	<sect2 id="mp3-encoding">
	<title>Encoding MP3s</title>

	<para>Nowadays, the mp3 encoder of choice is
	<application>lame</application>.
	<application>Lame</application> can be found at
	<filename role="package">audio/lame</filename> in the ports
	tree.</para>

	<para>Using the ripped WAV files, the following command will
	convert
	<filename><replaceable>audio01.wav</replaceable></filename>
	to
	<filename><replaceable>audio01.mp3</replaceable></filename>:</para>

	<screen>&prompt.root; <userinput>lame -h -b <replaceable>128</replaceable> \
	--tt "<replaceable>Foo Song Title</replaceable>" \
	--ta "<replaceable>FooBar Artist</replaceable>" \
	--tl "<replaceable>FooBar Album</replaceable>" \
	--ty "<replaceable>2001</replaceable>" \
	--tc "<replaceable>Ripped and encoded by Foo</replaceable>" \
	--tg "<replaceable>Genre</replaceable>" \
	<replaceable>audio01.wav audio01.mp3</replaceable></userinput></screen>

	<para>128 kbits seems to be the standard MP3 bitrate in
	use. Many enjoy the higher quality 160, or 192. The higher
	the bitrate, the more disk space the resulting MP3 will
	consume--but the quality will be higher. The
	<option>-h</option> option turns on the <quote>higher quality
	but a little slower</quote> mode. The options beginning with
	<option>--t</option> indicate ID3 tags, which usually contain
	song information, to be embedded within the MP3 file.
	Additional encoding options can be found by consulting the
	<application>lame</application> man page.</para>
	</sect2>

	<sect2 id="mp3-decoding">
	<title>Decoding MP3s</title>

	<para>In order to burn an audio CD from MP3s, they must be
	converted to a non-compressed WAV format. Both
	<application>XMMS</application> and
	<application>mpg123</application> support the output of MP3
	to an uncompressed file format.</para>

	<para>Writing to Disk in <application>XMMS</application>:</para>

	<procedure>
	<step>
	<para>Launch <application>XMMS</application>.</para>
	</step>

	<step>
	<para>Right-click on the window to bring up the
	<application>XMMS</application> menu.</para>
	</step>

	<step>
	<para>Select <literal>Preference</literal> under
	<literal>Options</literal>.</para>
	</step>

	<step>
	<para>Change the Output Plugin to <quote>Disk Writer
	Plugin</quote>.</para>
	</step>

	<step>
	<para>Press <literal>Configure</literal>.</para>
	</step>

	<step>
	<para>Enter (or choose browse) a directory to write the
	uncompressed files to.</para>
	</step>

	<step>
	<para>Load the MP3 file into <application>XMMS</application>
	as usual, with volume at 100% and EQ settings turned
	off.</para>
	</step>

	<step>
	<para>Press <literal>Play</literal> —
	<application>XMMS</application> will appear as if it is
	playing the MP3, but no music will be heard. It is
	actually playing the MP3 to a file.</para>
	</step>

	<step>
	<para>Be sure to set the default Output Plugin back to what
	it was before in order to listen to MP3s again.</para>
	</step>
	</procedure>

	<para>Writing to stdout in
	<application>mpg123</application>:</para>

	<procedure>
	<step>
	<para>Run <command>mpg123 -s
	<replaceable>audio01.mp3</replaceable> >
	<replaceable>audio01.pcm</replaceable></command></para>
	</step>
	</procedure>

	<para><application>XMMS</application> writes a file in the WAV
	format, while <application>mpg123</application> converts the
	MP3 into raw PCM audio data. Both of these formats can be
	used with <application>cdrecord</application> to create audio
	CDs. You have to use raw PCM with &man.burncd.8;. If you
	use WAV files, you will notice a small tick sound at the
	beginning of each track, this sound is the header of the WAV
	file. You can simply remove the header of a WAV file with
	the utility <application>SoX</application> (it can be
	installed from the <filename
	role="package">audio/sox</filename> port or package):</para>

	<screen>&prompt.user; <userinput>sox -t wav -r 44100 -s -w -c 2 <replaceable>track.wav track.raw</replaceable></userinput></screen>

	<para>Read <xref linkend="creating-cds"/> for more information
	on using a CD burner in FreeBSD.</para>
	</sect2>
	</sect1>

	<sect1 id="video-playback">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Ross</firstname>
	<surname>Lippert</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<!-- 5 June 2002 -->
	</sect1info>

	<title>Video Playback</title>

	<para>Video playback is a very new and rapidly developing
	application area. Be patient. Not everything is going to work
	as smoothly as it did with sound.</para>

	<para>Before you begin, you should know the model of the video
	card you have and the chip it uses. While
	<application>&xorg;</application> supports a wide variety of
	video cards, fewer give good playback performance. To obtain
	a list of extensions supported by the X server using your card
	use the command &man.xdpyinfo.1; while X11 is running.</para>

	<para>It is a good idea to have a short MPEG file which can be
	treated as a test file for evaluating various players and
	options. Since some DVD players will look for DVD media in
	<filename>/dev/dvd</filename> by default, or have this device
	name hardcoded in them, you might find it useful to make
	symbolic links to the proper devices:</para>

	<screen>&prompt.root; <userinput>ln -sf /dev/acd0 /dev/dvd</userinput>
	&prompt.root; <userinput>ln -sf /dev/acd0 /dev/rdvd</userinput></screen>

	<para>Note that due to the nature of &man.devfs.5;,
	manually created links like these will not persist if you reboot
	your system. In order to create the symbolic links
	automatically whenever you boot your system, add the following
	lines to <filename>/etc/devfs.conf</filename>:</para>

	<programlisting>link acd0 dvd
	link acd0 rdvd</programlisting>

	<para>Additionally, DVD decryption, which requires invoking
	special DVD-ROM functions, requires write permission on the DVD
	devices.</para>

	<para>To enhance the shared memory X11 interface, it is
	recommended that the values of some &man.sysctl.8; variables
	should be increased:</para>

	<programlisting>kern.ipc.shmmax=67108864
	kern.ipc.shmall=32768</programlisting>

	<sect2 id="video-interface">
	<title>Determining Video Capabilities</title>

	<indexterm><primary>XVideo</primary></indexterm>
	<indexterm><primary>SDL</primary></indexterm>
	<indexterm><primary>DGA</primary></indexterm>

	<para>There are several possible ways to display video under X11.
	What will really work is largely hardware dependent. Each
	method described below will have varying quality across
	different hardware. Secondly, the rendering of video in X11
	is a topic receiving a lot of attention lately, and with each
	version of <application>&xorg;</application>, there may be
	significant improvement.</para>

	<para>A list of common video interfaces:</para>

	<orderedlist>
	<listitem>
	<para>X11: normal X11 output using shared memory.</para>
	</listitem>

	<listitem>
	<para>XVideo: an extension to the X11 interface which supports
	video in any X11 drawable.</para>
	</listitem>

	<listitem>
	<para>SDL: the Simple Directmedia Layer.</para>
	</listitem>

	<listitem>
	<para>DGA: the Direct Graphics Access.</para>
	</listitem>

	<listitem>
	<para>SVGAlib: low level console graphics layer.</para>
	</listitem>
	</orderedlist>

	<sect3 id="video-interface-xvideo">
	<title>XVideo</title>

	<para><application>&xorg;</application> has an extension called
	<emphasis>XVideo</emphasis> (aka Xvideo, aka Xv, aka xv) which
	allows video to be directly displayed in drawable objects
	through a special acceleration. This extension provides very
	good quality playback even on low-end machines.</para>

	<para>To check whether the extension is running, use
	<command>xvinfo</command>:</para>

	<screen>&prompt.user; <userinput>xvinfo</userinput></screen>

	<para>XVideo is supported for your card if the result looks
	like:</para>

	<screen>X-Video Extension version 2.2
	screen #0
	Adaptor #0: "Savage Streams Engine"
	number of ports: 1
	port base: 43
	operations supported: PutImage
	supported visuals:
	depth 16, visualID 0x22
	depth 16, visualID 0x23
	number of attributes: 5
	"XV_COLORKEY" (range 0 to 16777215)
	client settable attribute
	client gettable attribute (current value is 2110)
	"XV_BRIGHTNESS" (range -128 to 127)
	client settable attribute
	client gettable attribute (current value is 0)
	"XV_CONTRAST" (range 0 to 255)
	client settable attribute
	client gettable attribute (current value is 128)
	"XV_SATURATION" (range 0 to 255)
	client settable attribute
	client gettable attribute (current value is 128)
	"XV_HUE" (range -180 to 180)
	client settable attribute
	client gettable attribute (current value is 0)
	maximum XvImage size: 1024 x 1024
	Number of image formats: 7
	id: 0x32595559 (YUY2)
	guid: 59555932-0000-0010-8000-00aa00389b71
	bits per pixel: 16
	number of planes: 1
	type: YUV (packed)
	id: 0x32315659 (YV12)
	guid: 59563132-0000-0010-8000-00aa00389b71
	bits per pixel: 12
	number of planes: 3
	type: YUV (planar)
	id: 0x30323449 (I420)
	guid: 49343230-0000-0010-8000-00aa00389b71
	bits per pixel: 12
	number of planes: 3
	type: YUV (planar)
	id: 0x36315652 (RV16)
	guid: 52563135-0000-0000-0000-000000000000
	bits per pixel: 16
	number of planes: 1
	type: RGB (packed)
	depth: 0
	red, green, blue masks: 0x1f, 0x3e0, 0x7c00
	id: 0x35315652 (RV15)
	guid: 52563136-0000-0000-0000-000000000000
	bits per pixel: 16
	number of planes: 1
	type: RGB (packed)
	depth: 0
	red, green, blue masks: 0x1f, 0x7e0, 0xf800
	id: 0x31313259 (Y211)
	guid: 59323131-0000-0010-8000-00aa00389b71
	bits per pixel: 6
	number of planes: 3
	type: YUV (packed)
	id: 0x0
	guid: 00000000-0000-0000-0000-000000000000
	bits per pixel: 0
	number of planes: 0
	type: RGB (packed)
	depth: 1
	red, green, blue masks: 0x0, 0x0, 0x0</screen>

	<para>Also note that the formats listed (YUV2, YUV12, etc) are
	not present with every implementation of XVideo and their
	absence may hinder some players.</para>

	<para>If the result looks like:</para>

	<screen>X-Video Extension version 2.2
	screen #0
	no adaptors present</screen>

	<para>Then XVideo is probably not supported for your card.</para>

	<para>If XVideo is not supported for your card, this only means
	that it will be more difficult for your display to meet the
	computational demands of rendering video. Depending on your
	video card and processor, though, you might still be able to
	have a satisfying experience. You should probably read about
	ways of improving performance in the advanced reading <xref
	linkend="video-further-reading"/>.</para>

	</sect3>

	<sect3 id="video-interface-SDL">
	<title>Simple Directmedia Layer</title>

	<para>The Simple Directmedia Layer, SDL, was intended to be a
	porting layer between &microsoft.windows;, BeOS, and &unix;,
	allowing cross-platform applications to be developed which made
	efficient use of sound and graphics. The SDL layer provides a
	low-level abstraction to the hardware which can sometimes be
	more efficient than the X11 interface.</para>

	<para>The SDL can be found at <filename
	role="package">devel/sdl12</filename>.</para>

	</sect3>

	<sect3 id="video-interface-DGA">
	<title>Direct Graphics Access</title>

	<para>Direct Graphics Access is an X11 extension which allows
	a program to bypass the X server and directly alter the
	framebuffer. Because it relies on a low level memory mapping to
	effect this sharing, programs using it must be run as
	<username>root</username>.</para>

	<para>The DGA extension can be tested and benchmarked by
	&man.dga.1;. When <command>dga</command> is running, it
	changes the colors of the display whenever a key is pressed. To
	quit, use <keycap>q</keycap>.</para>

	</sect3>
	</sect2>

	<sect2 id="video-ports">
	<title>Ports and Packages Dealing with Video</title>

	<indexterm><primary>video ports</primary></indexterm>
	<indexterm><primary>video packages</primary></indexterm>

	<para>This section discusses the software available from the
	FreeBSD Ports Collection which can be used for video playback.
	Video playback is a very active area of software development,
	and the capabilities of various applications are bound to
	diverge somewhat from the descriptions given here.</para>

	<para>Firstly, it is important to know that many of the video
	applications which run on FreeBSD were developed as Linux
	applications. Many of these applications are still
	beta-quality. Some of the problems that you may encounter with
	video packages on FreeBSD include:</para>

	<orderedlist>

	<listitem>
	<para>An application cannot playback a file which another
	application produced.</para>
	</listitem>

	<listitem>
	<para>An application cannot playback a file which the
	application itself produced.</para>
	</listitem>

	<listitem>
	<para>The same application on two different machines,
	rebuilt on each machine for that machine, plays back the
	same file differently.</para>
	</listitem>

	<listitem>
	<para>A seemingly trivial filter like rescaling of the image
	size results in very bad artifacts from a buggy rescaling
	routine.</para>
	</listitem>

	<listitem>
	<para>An application frequently dumps core.</para>
	</listitem>

	<listitem>
	<para>Documentation is not installed with the port and can be
	found either on the web or under the port's <filename
	class='directory'>work</filename>
	directory.</para>
	</listitem>

	</orderedlist>

	<para>Many of these applications may also exhibit
	<quote>Linux-isms</quote>. That is, there may be issues
	resulting from the way some standard libraries are
	implemented in the Linux distributions, or some features of
	the Linux kernel which have been assumed by the authors of the
	applications. These issues are not always noticed and worked
	around by the port maintainers, which can lead to problems like
	these:</para>

	<orderedlist>
	<listitem>
	<para>The use of <filename>/proc/cpuinfo</filename> to detect
	processor characteristics.</para>
	</listitem>

	<listitem>
	<para>A misuse of threads which causes a program to hang upon
	completion instead of truly terminating.</para>
	</listitem>

	<listitem>
	<para>Software not yet in the FreeBSD Ports Collection
	which is commonly used in conjunction with the
	application.</para>
	</listitem>
	</orderedlist>

	<para>So far, these application developers have been cooperative
	with port maintainers to minimize the work-arounds needed for
	port-ing.</para>

	<sect3 id="video-mplayer">
	<title>MPlayer</title>

	<para><application>MPlayer</application> is a recently developed
	and rapidly developing video player. The goals of the
	<application>MPlayer</application> team are speed and
	flexibility on Linux and other Unices. The project was
	started when the team founder got fed up with bad playback
	performance on then available players. Some would say that
	the graphical interface has been sacrificed for a streamlined
	design. However, once you get used to the command line
	options and the key-stroke controls, it works very
	well.</para>

	<sect4 id="video-mplayer-building">
	<title>Building MPlayer</title>

	<indexterm><primary>MPlayer</primary>
	<secondary>making</secondary></indexterm>

	<para><application>MPlayer</application> resides in <filename
	role="package">multimedia/mplayer</filename>.
	<application>MPlayer</application> performs a variety of
	hardware checks during the build process, resulting in a
	binary which will not be portable from one system to
	another. Therefore, it is important to build it from
	ports and not to use a binary package. Additionally, a
	number of options can be specified in the
	<command>make</command> command line, as described in the
	<filename>Makefile</filename> and at the start of the
	build:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/multimedia/mplayer</userinput>
	&prompt.root; <userinput>make</userinput>
	N - O - T - E

	Take a careful look into the Makefile in order
	to learn how to tune mplayer towards you personal preferences!
	For example,
	make WITH_GTK1
	builds MPlayer with GTK1-GUI support.
	If you want to use the GUI, you can either install
	/usr/ports/multimedia/mplayer-skins
	or download official skin collections from
	http://www.mplayerhq.hu/homepage/dload.html</screen>

	<para>The default port options should be sufficient for most
	users. However, if you need the XviD codec, you have to
	specify the <makevar>WITH_XVID</makevar> option in the
	command line. The default DVD device can also be defined
	with the <makevar>WITH_DVD_DEVICE</makevar> option, by
	default <filename>/dev/acd0</filename> will be used.</para>

	<para>As of this writing, the
	<application>MPlayer</application> port will build its HTML
	documentation and two executables,
	<command>mplayer</command>, and <command>mencoder</command>,
	which is a tool for re-encoding video.</para>

	<para>The HTML documentation for
	<application>MPlayer</application> is very informative.
	If the reader finds the information on video hardware and
	interfaces in this chapter lacking, the
	<application>MPlayer</application> documentation is a very
	thorough supplement. You should definitely take the time
	to read the <application>MPlayer</application> documentation
	if you are looking for information about video support in
	&unix;.</para>

	</sect4>

	<sect4 id="video-mplayer-using">
	<title>Using MPlayer</title>

	<indexterm><primary>MPlayer</primary>
	<secondary>use</secondary></indexterm>

	<para>Any user of <application>MPlayer</application> must set
	up a <filename>.mplayer</filename> subdirectory of her
	home directory. To create this necessary subdirectory,
	you can type the following:</para>

	<screen>&prompt.user; <userinput>cd /usr/ports/multimedia/mplayer</userinput>
	&prompt.user; <userinput>make install-user</userinput></screen>

	<para>The command options for <command>mplayer</command> are
	listed in the manual page. For even more detail there is
	HTML documentation. In this section, we will describe only
	a few common uses.</para>

	<para>To play a file, such as
	<filename><replaceable>testfile.avi</replaceable></filename>,
	through one of the various video interfaces set the
	<option>-vo</option> option:</para>

	<screen>&prompt.user; <userinput>mplayer -vo xv <replaceable>testfile.avi</replaceable></userinput></screen>

	<screen>&prompt.user; <userinput>mplayer -vo sdl <replaceable>testfile.avi</replaceable></userinput></screen>

	<screen>&prompt.user; <userinput>mplayer -vo x11 <replaceable>testfile.avi</replaceable></userinput></screen>

	<screen>&prompt.root; <userinput>mplayer -vo dga <replaceable>testfile.avi</replaceable></userinput></screen>

	<screen>&prompt.root; <userinput>mplayer -vo 'sdl:dga' <replaceable>testfile.avi</replaceable></userinput></screen>

	<para>It is worth trying all of these options, as their
	relative performance depends on many factors and will vary
	significantly with hardware.</para>

	<para>To play from a DVD, replace the
	<filename><replaceable>testfile.avi</replaceable></filename>
	with <option>dvd://<replaceable>N</replaceable> -dvd-device
	<replaceable>DEVICE</replaceable></option> where
	<replaceable>N</replaceable> is the title number to play
	and <filename><replaceable>DEVICE</replaceable></filename>
	is the device node for the DVD-ROM. For example, to play
	title 3 from <filename>/dev/dvd</filename>:</para>

	<screen>&prompt.root; <userinput>mplayer -vo xv dvd://3 -dvd-device /dev/dvd</userinput></screen>

	<note>
	<para>The default DVD device can be defined during the build
	of the <application>MPlayer</application> port via the
	<makevar>WITH_DVD_DEVICE</makevar> option. By default,
	this device is <filename>/dev/acd0</filename>. More
	details can be found in the port
	<filename>Makefile</filename>.</para>
	</note>

	<para>To stop, pause, advance and so on, consult the
	keybindings, which are output by running <command>mplayer
	-h</command> or read the manual page.</para>

	<para>Additional important options for playback are:
	<option>-fs -zoom</option> which engages the fullscreen mode
	and <option>-framedrop</option> which helps
	performance.</para>

	<para>In order for the mplayer command line to not become too
	large, the user can create a file
	<filename>.mplayer/config</filename> and set default options
	there:</para>
	<programlisting>vo=xv
	fs=yes
	zoom=yes</programlisting>

	<para>Finally, <command>mplayer</command> can be used to rip a
	DVD title into a <filename>.vob</filename> file. To dump
	out the second title from a DVD, type this:</para>

	<screen>&prompt.root; <userinput>mplayer -dumpstream -dumpfile out.vob dvd://2 -dvd-device /dev/dvd</userinput></screen>

	<para>The output file, <filename>out.vob</filename>, will be
	MPEG and can be manipulated by the other packages described
	in this section.</para>

	</sect4>
	<sect4 id="video-mencoder">
	<title>mencoder</title>

	<indexterm>
	<primary>mencoder</primary>
	</indexterm>

	<para>Before using <command>mencoder</command> it is a good
	idea to familiarize yourself with the options from the HTML
	documentation. There is a manual page, but it is not very
	useful without the HTML documentation. There are
	innumerable ways to improve quality, lower bitrate, and
	change formats, and some of these tricks may make the
	difference between good or bad performance. Here are a
	couple of examples to get you going. First a simple
	copy:</para>

	<screen>&prompt.user; <userinput>mencoder <replaceable>input.avi</replaceable> -oac copy -ovc copy -o <replaceable>output.avi</replaceable></userinput></screen>

	<para>Improper combinations of command line options can yield
	output files that are unplayable even by
	<command>mplayer</command>. Thus, if you just want to rip
	to a file, stick to the <option>-dumpfile</option> in
	<command>mplayer</command>.</para>

	<para>To convert
	<filename><replaceable>input.avi</replaceable></filename>
	to the MPEG4 codec with MPEG3 audio encoding (<filename
	role="package">audio/lame</filename> is required):</para>

	<screen>&prompt.user; <userinput>mencoder <replaceable>input.avi</replaceable> -oac mp3lame -lameopts br=192 \
	-ovc lavc -lavcopts vcodec=mpeg4:vhq -o <replaceable>output.avi</replaceable></userinput></screen>

	<para>This has produced output playable by
	<command>mplayer</command> and
	<command>xine</command>.</para>

	<para><filename><replaceable>input.avi</replaceable></filename>
	can be replaced with <option>dvd://1 -dvd-device
	/dev/dvd</option> and run as <username>root</username>
	to re-encode a DVD title directly. Since you are likely
	to be dissatisfied with your results the first time around,
	it is recommended you dump the title to a file and work on
	the file.</para>
	</sect4>

	</sect3>

	<sect3 id="video-xine">
	<title>The xine Video Player</title>

	<para>The <application>xine</application> video player is a
	project of wide scope aiming not only at being an all in one
	video solution, but also in producing a reusable base library
	and a modular executable which can be extended with plugins.
	It comes both as a package and as a port, <filename
	role="package">multimedia/xine</filename>.</para>

	<para>The <application>xine</application> player
	is still very rough around the edges, but it is clearly off
	to a good start. In practice, <application>xine</application>
	requires either a fast CPU with a fast video card, or support
	for the XVideo extension. The GUI is usable, but a bit
	clumsy.</para>

	<para>As of this writing, there is no input module shipped with
	<application>xine</application> which will play CSS encoded
	DVDs. There are third party builds which do have modules for
	this built in them, but none of these are in the FreeBSD Ports
	Collection.</para>

	<para>Compared to <application>MPlayer</application>,
	<application>xine</application> does more for the user, but
	at the same time, takes some of the more fine-grained control
	away from the user. The <application>xine</application> video
	player performs best on XVideo interfaces.</para>

	<para>By default, <application>xine</application> player will
	start up in a graphical user interface. The menus can then
	be used to open a specific file:</para>

	<screen>&prompt.user; <userinput>xine</userinput></screen>

	<para>Alternatively, it may be invoked to play a file
	immediately without the GUI with the command:</para>

	<screen>&prompt.user; <userinput>xine -g -p <replaceable>mymovie.avi</replaceable></userinput></screen>

	</sect3>

	<sect3 id="video-ports-transcode">
	<title>The transcode Utilities</title>

	<para>The software <application>transcode</application> is not a
	player, but a suite of tools for re-encoding video and audio
	files. With <application>transcode</application>, one has the
	ability to merge video files, repair broken files, using
	command line tools with <filename>stdin/stdout</filename>
	stream interfaces.</para>

	<para>A great number of options can be specified during the
	build from the <filename
	role="package">multimedia/transcode</filename> port, we
	recommend the following command line to build
	<application>transcode</application>:</para>

	<screen>&prompt.root; <userinput>make WITH_OPTIMIZED_CFLAGS=yes WITH_LIBA52=yes WITH_LAME=yes WITH_OGG=yes \
	WITH_MJPEG=yes -DWITH_XVID=yes</userinput></screen>

	<para>The proposed settings should be sufficient for most
	users.</para>

	<para>To illustrate <command>transcode</command> capacities, one
	example to show how to convert a DivX file into a PAL MPEG-1
	file (PAL VCD):</para>

	<screen>&prompt.user; <userinput>transcode -i
	<replaceable>input.avi</replaceable> -V --export_prof vcd-pal -o output_vcd</userinput>
	&prompt.user; <userinput>mplex -f 1 -o <replaceable>output_vcd.mpg output_vcd.m1v output_vcd.mpa</replaceable></userinput></screen>

	<para>The resulting MPEG file,
	<filename><replaceable>output_vcd.mpg</replaceable></filename>,
	is ready to be played with <application>MPlayer</application>.
	You could even burn the file on a CD-R media to create a Video
	CD, in this case you will need to install and use both <filename
	role="package">multimedia/vcdimager</filename> and <filename
	role="package">sysutils/cdrdao</filename> programs.</para>

	<para>There is a manual page for <command>transcode</command>, but
	you should also consult the <ulink
	url="http://www.transcoding.org/cgi-bin/transcode">transcode
	wiki</ulink> for further information and examples.</para>
	</sect3>
	</sect2>

	<sect2 id="video-further-reading">
	<title>Further Reading</title>

	<para>The various video software packages for FreeBSD are
	developing rapidly. It is quite possible that in the near
	future many of the problems discussed here will have been
	resolved. In the mean time, those who want to get the very
	most out of FreeBSD's A/V capabilities will have to cobble
	together knowledge from several FAQs and tutorials and use a
	few different applications. This section exists to give the
	reader pointers to such additional information.</para>

	<para>The <ulink url="http://www.mplayerhq.hu/DOCS/">MPlayer
	documentation</ulink> is very technically informative.
	These documents should probably be consulted by anyone wishing
	to obtain a high level of expertise with &unix; video. The
	<application>MPlayer</application> mailing list is hostile to
	anyone who has not bothered to read the documentation, so if
	you plan on making bug reports to them, RTFM.</para>

	<para>The <ulink
	url="http://dvd.sourceforge.net/xine-howto/en_GB/html/howto.html">
	xine HOWTO</ulink> contains a chapter on performance improvement
	which is general to all players.</para>

	<para>Finally, there are some other promising applications which
	the reader may try:</para>

	<itemizedlist>
	<listitem>
	<para><ulink
	url="http://avifile.sourceforge.net/">Avifile</ulink>
	which is also a port <filename
	role='package'>multimedia/avifile</filename>.</para>
	</listitem>

	<listitem>
	<para><ulink
	url="http://www.dtek.chalmers.se/groups/dvd/">Ogle</ulink>
	which is also a port <filename
	role='package'>multimedia/ogle</filename>.</para>
	</listitem>

	<listitem>
	<para><ulink
	url="http://xtheater.sourceforge.net/">Xtheater</ulink></para>
	</listitem>

	<listitem>
	<para><filename
	role="package">multimedia/dvdauthor</filename>, an open
	source package for authoring DVD content.</para>
	</listitem>

	</itemizedlist>

	</sect2>
	</sect1>

	<sect1 id="tvcard">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Josef</firstname>
	<surname>El-Rayes</surname>
	<contrib>Original contribution by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Marc</firstname>
	<surname>Fonvieille</surname>
	<contrib>Enhanced and adapted by </contrib>
	<!-- 02 January 2004 -->
	</author>
	</authorgroup>
	</sect1info>

	<title>Setting Up TV Cards</title>

	<indexterm>
	<primary>TV cards</primary>
	</indexterm>

	<sect2>
	<title>Introduction</title>

	<para>TV cards allow you to watch broadcast or cable TV on your
	computer. Most of them accept composite video via an RCA or
	S-video input and some of these cards come with a FM radio
	tuner.</para>

	<para>&os; provides support for PCI-based TV cards using a
	Brooktree Bt848/849/878/879 or a Conexant CN-878/Fusion 878a
	Video Capture Chip with the &man.bktr.4; driver. You must
	also ensure the board comes with a supported tuner, consult
	the &man.bktr.4; manual page for a list of supported
	tuners.</para>
	</sect2>

	<sect2>
	<title>Adding the Driver</title>

	<para>To use your card, you will need to load the &man.bktr.4;
	driver, this can be done by adding the following line to the
	<filename>/boot/loader.conf</filename> file like this:</para>

	<programlisting>bktr_load="YES"</programlisting>

	<para>Alternatively, you may statically compile the support for
	the TV card in your kernel, in that case add the following
	lines to your kernel configuration:</para>

	<programlisting>device bktr
	device iicbus
	device iicbb
	device smbus</programlisting>

	<para>These additional device drivers are necessary because
	of the card components being interconnected via an I2C bus.
	Then build and install a new kernel.</para>

	<para>Once the support was added to your system, you have to
	reboot your machine. During the boot process, your TV card
	should show up, like this:</para>

	<programlisting>bktr0: <BrookTree 848A> mem 0xd7000000-0xd7000fff irq 10 at device 10.0 on pci0
	iicbb0: <I2C bit-banging driver> on bti2c0
	iicbus0: <Philips I2C bus> on iicbb0 master-only
	iicbus1: <Philips I2C bus> on iicbb0 master-only
	smbus0: <System Management Bus> on bti2c0
	bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting>

	<para>Of course these messages can differ according to your
	hardware. However you should check if the tuner is correctly
	detected; it is still possible to override some of the
	detected parameters with &man.sysctl.8; MIBs and kernel
	configuration file options. For example, if you want to force
	the tuner to a Philips SECAM tuner, you should add the
	following line to your kernel configuration file:</para>

	<programlisting>options OVERRIDE_TUNER=6</programlisting>

	<para>or you can directly use &man.sysctl.8;:</para>

	<screen>&prompt.root; <userinput>sysctl hw.bt848.tuner=6</userinput></screen>

	<para>See the &man.bktr.4; manual page and the
	<filename>/usr/src/sys/conf/NOTES</filename> file for more
	details on the available options.</para>
	</sect2>

	<sect2>
	<title>Useful Applications</title>

	<para>To use your TV card you need to install one of the
	following applications:</para>

	<itemizedlist>
	<listitem>
	<para><filename role="package">multimedia/fxtv</filename>
	provides TV-in-a-window and image/audio/video capture
	capabilities.</para>
	</listitem>
	<listitem>
	<para><filename role="package">multimedia/xawtv</filename>
	is also a TV application, with the same features as
	<application>fxtv</application>.</para>
	</listitem>
	<listitem>
	<para><filename role="package">misc/alevt</filename> decodes
	and displays Videotext/Teletext.</para>
	</listitem>
	<listitem>
	<para><filename role="package">audio/xmradio</filename>, an
	application to use the FM radio tuner coming with some
	TV cards.</para>
	</listitem>
	<listitem>
	<para><filename role="package">audio/wmtune</filename>, a
	handy desktop application for radio tuners.</para>
	</listitem>
	</itemizedlist>

	<para>More applications are available in the &os; Ports
	Collection.</para>
	</sect2>

	<sect2>
	<title>Troubleshooting</title>

	<para>If you encounter any problem with your TV card, you should
	check at first if the video capture chip and the tuner are
	really supported by the &man.bktr.4; driver and if you used
	the right configuration options. For more support and various
	questions about your TV card you may want to contact and use
	the archives of the &a.multimedia.name; mailing list.</para>
	</sect2>
	</sect1>

	<sect1 id="mythtv">
	<title>MythTV</title>

	<para>MythTV is an open source <acronym
	role="Personal Video Recorder">PVR</acronym> software
	project.</para>

	<para>It is well-known in the &linux; world as a complex
	application with many dependencies, and therefore difficult to
	install. The &os; ports system simplifies much of the process,
	but some components must be set up manually. This section is
	intended to help and guide in setting up MythTV.</para>

	<sect2>
	<title>Hardware</title>

	<para>MythTV is designed to utilise <acronym
	role="Video for Linux">V4L</acronym> to access video input
	devices such as encoders and tuners. At this time, MythTV
	works best with <acronym role="Universal Serial
	Bus">USB</acronym> DVB-S/C/T cards supported by <filename
	role="package">multimedia/webcamd</filename> because
	<application>webcamd</application> provides a <acronym
	role="Video for Linux">V4L</acronym> userland application.
	Any <acronym role="Digital Video Broadcasting">DVB</acronym>
	card supported by <application>webcamd</application> should
	work with MythTV, but a list of known working cards can be
	found <ulink
	url="http://wiki.freebsd.org/WebcamCompat">here</ulink>.
	There are also drivers available for Hauppauge cards in the
	following packages: <filename
	role="package">multimedia/pvr250</filename> and <filename
	role="package">multimedia/pvrxxx</filename>, but they
	provide a non-standard driver interface that does not work
	with versions of MythTV greater than 0.23.</para>

	<para><ulink url="http://wiki.freebsd.org/HTPC">HTPC</ulink>
	contains a list of all available <acronym
	role="Digital Video Broadcasting">DVB</acronym>
	drivers.</para>
	</sect2>

	<sect2>
	<title>Dependencies</title>

	<para>Being flexible and modular, MythTV allows the user to
	have the frontend and backend on different machines.</para>

	<para>For the frontend, <filename
	role="package">multimedia/mythtv-frontend</filename> is
	required, as well as an X server, which can be found in
	<filename role="package">x11/xorg</filename>. Ideally, the
	frontend computer also has a video card that supports <acronym
	role="X-Video Motion Compensation">XvMC</acronym> and,
	optionally, a <acronym
	role="Linux Infrared Remote
	Control">LIRC</acronym>-compatible
	remote.</para>

	<para>For the backend, <filename
	role="package">multimedia/mythtv</filename> is required,
	as well as a &mysql; database, and optionally a tuner and
	storage for recordings. The &mysql; package should be
	automatically installed as a dependency when installing
	<filename role="package">multimedia/mythtv</filename>.</para>
	</sect2>

	<sect2>
	<title>Setting up MythTV</title>

	<para>To install MythTV, use the following steps. First,
	install MythTV from the &os; Ports collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/multimedia/mythtv</userinput>
	&prompt.root; <userinput>make install</userinput></screen>

	<para>Set up the MythTV database:</para>

	<screen>&prompt.root; <userinput>mysql -uroot -p < /usr/local/share/mythtv/database/mc.sql</userinput></screen>

	<para>Configure the backend:</para>

	<screen>&prompt.root; <userinput>mythtv-setup</userinput></screen>

	<para>Start the backend:</para>

	<screen>&prompt.root; <userinput>echo 'mythbackend_enable="YES"' >> /etc/rc.conf</userinput>
	&prompt.root; <userinput>service mythbackend start</userinput></screen>
	</sect2>
	</sect1>

	<sect1 id="scanners">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Marc</firstname>
	<surname>Fonvieille</surname>
	<contrib>Written by </contrib>
	<!-- 04 August 2004 -->
	</author>
	</authorgroup>
	</sect1info>

	<title>Image Scanners</title>

	<indexterm>
	<primary>image scanners</primary>
	</indexterm>

	<sect2>
	<title>Introduction</title>

	<para>In &os;, access to image scanners is provided
	by the <application>SANE</application> (Scanner Access Now
	Easy) <acronym role="Application Programming
	Interface">API</acronym> available through the &os; Ports
	Collection. <application>SANE</application> will also use
	some &os; device drivers to access to the scanner
	hardware.</para>

	<para>&os; supports both SCSI and USB scanners. Be sure your
	scanner is supported by <application>SANE</application> prior
	to performing any configuration.
	<application>SANE</application> has a <ulink
	url="http://www.sane-project.org/sane-supported-devices.html">supported
	devices</ulink> list that can provide you with information
	- about the support for a scanner and its status. On systems
	- prior to &os; 8.X the
	- &man.uscanner.4; manual page also provides a list of supported
	- USB scanners.</para>
	+ about the support for a scanner and its status.</para>
	</sect2>

	<sect2>
	<title>Kernel Configuration</title>

	<para>As mentioned above both SCSI and USB interfaces are
	supported. According to your scanner interface, different
	device drivers are required.</para>

	<sect3 id="scanners-kernel-usb">
	<title>USB Interface</title>

	<para>The <filename>GENERIC</filename> kernel by default
	includes the device drivers needed to support USB scanners.
	Should you decide to use a custom kernel, be sure that the
	following lines are present in your kernel configuration
	file:</para>

	<programlisting>device usb
	device uhci
	device ohci
	device ehci</programlisting>

	- <para>On systems prior to &os; 8.X, the following line is
	- also needed:</para>
	-
	- <programlisting>device uscanner</programlisting>
	-
	- <para>On these versions of &os;, the &man.uscanner.4; device
	- driver provides support for the USB scanners. Since
	- &os; 8.0, this support is directly provided by
	- the &man.libusb.3; library.</para>
	-
	<para>After rebooting with the correct kernel,
	plug in your USB scanner. A
	line showing the detection of your
	scanner should appear in the system message buffer
	(&man.dmesg.8;):</para>

	<screen>ugen0.2: <EPSON> at usbus0</screen>

	- <para>or on a &os; 7.X system:</para>
	-
	- <screen>uscanner0: EPSON EPSON Scanner, rev 1.10/3.02, addr 2</screen>
	-
	<para>These messages show that our scanner is using
	- either <filename>/dev/ugen0.2</filename> or
	- <filename>/dev/uscanner0</filename> as device node according
	- to the &os; version we run. For this example, a
	+ either <filename>/dev/ugen0.2</filename>
	+ as device node. For this example, a
	&epson.perfection; 1650 USB scanner was used.</para>
	</sect3>

	<sect3>
	<title>SCSI Interface</title>

	<para>If your scanner comes with a SCSI interface, it is
	important to know which SCSI controller board you will use.
	According to the SCSI chipset used, you will have to tune
	your kernel configuration file. The
	<filename>GENERIC</filename> kernel supports the most common
	SCSI controllers. Be sure to read the
	<filename>NOTES</filename> file
	and add the correct line to your kernel
	configuration file. In addition to the SCSI adapter driver,
	you need to have the following lines in your kernel
	configuration file:</para>

	<programlisting>device scbus
	device pass</programlisting>

	<para>Once your kernel has been properly compiled and
	installed, you should be able to see the devices in the
	system message buffer, when booting:</para>

	<screen>pass2 at aic0 bus 0 target 2 lun 0
	pass2: <AGFA SNAPSCAN 600 1.10> Fixed Scanner SCSI-2 device
	pass2: 3.300MB/s transfers</screen>

	<para>If your scanner was not powered-on at system boot, it
	is still possible to manually force the detection by
	performing a SCSI bus scan with the &man.camcontrol.8;
	command:</para>

	<screen>&prompt.root; <userinput>camcontrol rescan all</userinput>
	Re-scan of bus 0 was successful
	Re-scan of bus 1 was successful
	Re-scan of bus 2 was successful
	Re-scan of bus 3 was successful</screen>

	<para>Then the scanner will appear in the SCSI devices
	list:</para>

	<screen>&prompt.root; <userinput>camcontrol devlist</userinput>
	<IBM DDRS-34560 S97B> at scbus0 target 5 lun 0 (pass0,da0)
	<IBM DDRS-34560 S97B> at scbus0 target 6 lun 0 (pass1,da1)
	<AGFA SNAPSCAN 600 1.10> at scbus1 target 2 lun 0 (pass3)
	<PHILIPS CDD3610 CD-R/RW 1.00> at scbus2 target 0 lun 0 (pass2,cd0)</screen>

	<para>More details about SCSI devices are available in the
	&man.scsi.4; and &man.camcontrol.8; manual pages.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>SANE Configuration</title>

	<para>The <application>SANE</application> system is
	split in two parts: the backends (<filename
	role="package">graphics/sane-backends</filename>) and the
	frontends (<filename
	role="package">graphics/sane-frontends</filename>). The
	backends part provides access to the scanner itself. The
	<application>SANE</application>'s <ulink
	url="http://www.sane-project.org/sane-supported-devices.html">supported
	devices</ulink> list specifies which backend will support your
	image scanner. It is mandatory to determine the correct
	backend for your scanner if you want to be able to use your
	device. The frontends part provides the graphical scanning
	interface (<application>xscanimage</application>).</para>

	<para>The first step is to install the <filename
	role="package">graphics/sane-backends</filename> port or
	package. Then, use the <command>sane-find-scanner</command>
	command to check the scanner detection by the
	<application>SANE</application> system:</para>

	<screen>&prompt.root; <userinput>sane-find-scanner -q</userinput>
	found SCSI scanner "AGFA SNAPSCAN 600 1.10" at /dev/pass3</screen>

	<para>The output will show the interface type of the scanner and
	the device node used to attach the scanner to the system. The
	vendor and the product model may not appear, it is not
	important.</para>

	<note>
	<para>Some USB scanners require you to load a firmware, this
	is explained in the backend manual page. You should also
	read &man.sane-find-scanner.1; and &man.sane.7; manual
	pages.</para>
	</note>

	<para>Now we have to check if the scanner will be identified
	by a scanning frontend. By default, the
	<application>SANE</application> backends comes with a command
	line tool called &man.scanimage.1;. This command allows you
	to list the devices and to perform an image acquisition from
	the command line. The <option>-L</option> option is used to
	list the scanner devices:</para>

	<screen>&prompt.root; <userinput>scanimage -L</userinput>
	device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner</screen>

	<para>Or, for example with the USB scanner used in the <xref
	linkend="scanners-kernel-usb"/>:</para>

	<screen>&prompt.root; <userinput>scanimage -L</userinput>
	device 'epson2:libusb:/dev/usb:/dev/ugen0.2' is a Epson GT-8200 flatbed scanner</screen>

	<para>This output comes from a &os; 8.X system, the
	<literal>'epson2:libusb:/dev/usb:/dev/ugen0.2'</literal> item
	gives us the backend name (<literal>epson2</literal>) and the
	device node (<literal>/dev/ugen0.2</literal>) used by our
	scanner.</para>

	<note>
	<para>No output or a message saying that no scanners were
	identified indicates that &man.scanimage.1; is unable to
	identify the scanner. If this happens, you will need to
	edit the backend configuration file and define the scanner
	device used. The <filename
	class="directory">/usr/local/etc/sane.d/</filename>
	directory contains all backend configuration files. This
	identification problem does appear with certain USB
	scanners.</para>

	<para>For example, with the USB scanner used in the <xref
	linkend="scanners-kernel-usb"/>, under &os; 8.X the
	scanner is perfectly detected and working but under prior
	versions of &os; (where &man.uscanner.4; driver is used)
	<command>sane-find-scanner</command> gives us the following
	information:</para>

	<screen>&prompt.root; <userinput>sane-find-scanner -q</userinput>
	found USB scanner (UNKNOWN vendor and product) at device /dev/uscanner0</screen>

	<para>The scanner is correctly detected, it uses the USB
	interface and is attached to the
	<filename>/dev/uscanner0</filename> device node. We can
	now check if the scanner is correctly identified:</para>

	<screen>&prompt.root; <userinput>scanimage -L</userinput>

	No scanners were identified. If you were expecting something different,
	check that the scanner is plugged in, turned on and detected by the
	sane-find-scanner tool (if appropriate). Please read the documentation
	which came with this software (README, FAQ, manpages).</screen>

	<para>Since the scanner is not identified, we will need to edit
	the <filename>/usr/local/etc/sane.d/epson2.conf</filename>
	file. The scanner model used was the
	&epson.perfection; 1650, so we know the scanner will use
	the <literal>epson2</literal> backend. Be sure to read the
	help comments in the backends configuration files. Line
	changes are quite simple: comment out all lines that have the
	wrong interface for your scanner (in our case, we will comment
	out all lines starting with the word <literal>scsi</literal>
	as our scanner uses the USB interface), then add at the end
	of the file a line specifying the interface and the device
	node used. In this case, we add the following line:</para>

	<programlisting>usb /dev/uscanner0</programlisting>

	<para>Please be sure to read the comments provided in the
	backend configuration file as well as the backend manual page
	for more details and correct syntax to use. We can now verify
	if the scanner is identified:</para>

	<screen>&prompt.root; <userinput>scanimage -L</userinput>
	device `epson:/dev/uscanner0' is a Epson GT-8200 flatbed scanner</screen>

	<para>Our USB scanner has been identified. It is not important
	if the brand and the model do not match the scanner. The
	key item to be concerned with is the
	<literal>`epson:/dev/uscanner0'</literal> field, which give
	us the right backend name and the right device node.</para>
	</note>

	<para>Once the <command>scanimage -L</command> command is able
	to see the scanner, the configuration is complete. The device
	is now ready to scan.</para>

	<para>While &man.scanimage.1; does allow us to perform an
	image acquisition from the command line, it is preferable to
	use a graphical user interface to perform image scanning.
	<application>SANE</application> offers a simple but efficient
	graphical interface: <application>xscanimage</application>
	(<filename
	role="package">graphics/sane-frontends</filename>).</para>

	<para><application>Xsane</application> (<filename
	role="package">graphics/xsane</filename>) is another popular
	graphical scanning frontend. This frontend offers advanced
	features such as various scanning mode (photocopy, fax, etc.),
	color correction, batch scans, etc. Both of these applications
	are usable as a <application>GIMP</application> plugin.</para>
	</sect2>

	<sect2>
	<title>Giving Other Users Access to the Scanner</title>

	<para>All previous operations have been done with
	<username>root</username> privileges. You may however, need
	other users to have access to the scanner. The user will need
	read and write permissions to the device node used by the
	scanner. As an example, our USB scanner uses the device node
	<filename>/dev/ugen0.2</filename> which is in fact just a
	symlink to the real device node called
	<filename>/dev/usb/0.2.0</filename> (a quick look at the
	contents of the <filename class="directory">/dev</filename>
	directory will confirm it). Both, the symlink and the
	device node, are owned respectively by the
	<groupname>wheel</groupname> and the
	<groupname>operator</groupname> groups. Adding the user
	<username><replaceable>joe</replaceable></username> to these
	groups will allow him to use the scanner but, for obvious
	security reasons, you should think twice before adding a user
	to any group, especially the <groupname>wheel</groupname> group.
	A better solution would be creating a specific group for using
	the USB devices and make the scanner device accessible to
	members of this group.</para>

	<para>So we will use, for example, a group called
	<groupname><replaceable>usb</replaceable></groupname>. The
	first step is the creation of this group with the help of the
	&man.pw.8; command:</para>

	<screen>&prompt.root; <userinput>pw groupadd usb</userinput></screen>

	<para>Then we have to make the <filename>/dev/ugen0.2</filename>
	symlink and the <filename>/dev/usb/0.2.0</filename> device
	node accessible to the <groupname>usb</groupname> group
	with the correct write permissions (<literal>0660</literal> or
	<literal>0664</literal>), because by default only the owner of
	these files (<username>root</username>) can write to them.
	All of this is done by adding the following
	lines to the <filename>/etc/devfs.rules</filename>
	file:</para>

	<programlisting>[system=5]
	add path ugen0.2 mode 0660 group usb
	add path usb/0.2.0 mode 0666 group usb</programlisting>
	-
	- <para>&os; 7.X users will probably need the following
	- lines with the correct device node
	- <filename>/dev/uscanner0</filename>:</para>
	-
	- <programlisting>[system=5]
	-add path uscanner0 mode 660 group usb</programlisting>
	-
	- <para>Then add the following to
	- <filename>/etc/rc.conf</filename> and reboot the
	- machine:</para>
	-
	- <programlisting>devfs_system_ruleset="system"</programlisting>
	-
	- <para>More information regarding these lines can be found in the
	- &man.devfs.8; manual page.</para>

	<para>Now, one will just have to add users to the
	<groupname><replaceable>usb</replaceable></groupname> group to
	allow the access to the scanner:</para>

	<screen>&prompt.root; <userinput>pw groupmod usb -m <replaceable>joe</replaceable></userinput></screen>

	<para>For more details read the &man.pw.8; manual page.</para>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/ports/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/ports/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/ports/chapter.xml (revision 41355)
	@@ -1,1926 +1,1920 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="ports">
	<title>Installing Applications: Packages and Ports</title>

	<sect1 id="ports-synopsis">
	<title>Synopsis</title>

	<indexterm><primary>ports</primary></indexterm>
	<indexterm><primary>packages</primary></indexterm>
	<para>&os; is bundled with a rich collection of system tools as
	part of the base system. However, there is only so much one can
	do before needing to install an additional third-party
	application to get real work done. &os; provides two
	complementary technologies for installing third-party software:
	the &os; Ports Collection (for installing from source), and
	packages (for installing from pre-built binaries). Either
	method may be used to install software from local media or
	from the network.</para>

	<para>After reading this chapter, you will know how to:</para>

	<itemizedlist>
	<listitem>
	<para>Install third-party binary software packages.</para>
	</listitem>

	<listitem>
	<para>Build third-party software from source by using the
	Ports Collection.</para>
	</listitem>

	<listitem>
	<para>Remove previously installed packages or ports.</para>
	</listitem>

	<listitem>
	<para>Override the default values used by the Ports
	Collection.</para>
	</listitem>

	<listitem>
	<para>Find the appropriate software package.</para>
	</listitem>

	<listitem>
	<para>Upgrade installed software.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="ports-overview">
	<title>Overview of Software Installation</title>

	<para>The typical steps for installing third-party software on a
	&unix; system include:</para>

	<procedure>
	<step>
	<para>Download the software, which might be distributed in
	source code format, or as a binary.</para>
	</step>

	<step>
	<para>Unpack the software from its distribution format
	(typically a tarball compressed with &man.compress.1;,
	&man.gzip.1;, or &man.bzip2.1;).</para>
	</step>

	<step>
	<para>Locate the documentation in
	<filename>INSTALL</filename>, <filename>README</filename>
	or some file in a <filename>doc/</filename> subdirectory and
	read up on how to install the software.</para>
	</step>

	<step>
	<para>If the software was distributed in source format,
	compile it. This may involve editing a
	<filename>Makefile</filename>, or running a
	<command>configure</command> script, and other work.</para>
	</step>

	<step>
	<para>Test and install the software.</para>
	</step>
	</procedure>

	<para>If you are installing a software package that was not
	deliberately ported to &os; you may even have to go in and edit
	the code to make it work properly.</para>

	<para>&os; provides two technologies which perform these steps for
	you. At the time of writing, over &os.numports; third-party
	applications are available.</para>

	<para>A &os; package contains pre-compiled copies of all the
	commands for an application, as well as any configuration files
	and documentation. A package can be manipulated with &os;
	package management commands, such as &man.pkg.add.1;,
	&man.pkg.delete.1;, and &man.pkg.info.1;.</para>

	<para>A &os; port is a collection of files designed to automate
	the process of compiling an application from source code. The
	files that comprise a port contain all the necessary information
	to automatically download, extract, patch, compile, and install
	the application.</para>

	<para>The ports system can also be used to generate packages which
	can be manipulated with the &os; package management
	commands.</para>

	<para>Both packages and ports understand
	<emphasis>dependencies</emphasis>. If &man.pkg.add.1; or the
	Ports Collection is used to install an application and a
	dependent library is not already installed, the library will
	- automatically be installaed first.</para>
	+ automatically be installed first.</para>

	<para>While the two technologies are quite similar, packages and
	ports each have their own strengths. Select the technology that
	meets your requirements for installing a particular
	application.</para>

	<itemizedlist>
	<title>Package Benefits</title>

	<listitem>
	<para>A compressed package tarball is typically smaller than
	the compressed tarball containing the source code for the
	application.</para>
	</listitem>

	<listitem>
	<para>Packages do not require compilation time. For large
	applications, such as
	<application>Mozilla</application>,
	<application>KDE</application>, or
	<application>GNOME</application> this can be important,
	on a slow system.</para>
	</listitem>

	<listitem>
	<para>Packages do not require any understanding of the process
	involved in compiling software on &os;.</para>
	</listitem>
	</itemizedlist>

	<itemizedlist>
	<title>Ports Benefits</title>

	<listitem>
	<para>Packages are normally compiled with conservative
	options because they have to run on the maximum number of
	systems. By compiling from the port, one can change the
	compilation options.</para>
	</listitem>

	<listitem>
	<para>Some applications have compile-time options relating to
	which features are installed. For example,
	<application>Apache</application> can be configured with a
	wide variety of different built-in options.</para>

	<para>In some cases, multiple packages will exist for the same
	application to specify certain settings. For example,
	<application>Ghostscript</application> is available as a
	<filename>ghostscript</filename> package and a
	<filename>ghostscript-nox11</filename> package, depending on
	whether or not <application>Xorg</application> is installed.
	Creating multiple packages rapidly becomes impossible if an
	application has more than one or two different compile-time
	options.</para>
	</listitem>

	<listitem>
	<para>The licensing conditions of some software forbid binary
	distribution. These must be distributed as source code
	which must be compiled by the end-user.</para>
	</listitem>

	<listitem>
	<para>Some people do not trust binary distributions or prefer
	to read through source code in order to look for potential
	problems.</para>
	</listitem>

	<listitem>
	<para>If you have local patches, you will need the source in
	order to apply them.</para>
	</listitem>
	</itemizedlist>

	<para>To keep track of updated ports, subscribe to the
	&a.ports; and the &a.ports-bugs;.</para>

	<warning>
	<para>Before installing any application, check <ulink
	url="http://vuxml.freebsd.org/"></ulink> for security issues
	related to the application or install <filename
	role="package">ports-mgmt/portaudit</filename>. Once
	installed, type <command>portaudit -F -a</command> to check
	- all installed applications for known vulnerabilities</para>
	+ all installed applications for known vulnerabilities.</para>
	</warning>

	<para>The remainder of this chapter explains how to use packages
	and ports to install and manage third-party software on
	&os;.</para>
	</sect1>

	<sect1 id="ports-finding-applications">
	<title>Finding Software</title>

	<para>&os;'s list of available applications is growing all the
	time. There are a number of ways to find software to
	install:</para>

	<itemizedlist>
	<listitem>
	<para>The &os; web site maintains an up-to-date searchable
	list of all the available applications, at <ulink
	url="&url.base;/ports/index.html">http://www.FreeBSD.org/ports/</ulink>.
	The ports can be searched by application name or by
	software category.</para>
	</listitem>

	<listitem>
	<indexterm><primary>FreshPorts</primary></indexterm>

	<para>Dan Langille maintains <ulink
	url="http://www.FreshPorts.org/">FreshPorts</ulink> which
	provides a comprehensive search utility and also tracks
	changes to the applications in the Ports Collection.
	Registered users can create a customized watch list in order
	to receive an automated email when their watched ports are
	updated.</para>
	</listitem>

	<listitem>
	<indexterm><primary>Freecode</primary></indexterm>

	<para>If you do not know the name of the application you want,
	try using a site like Freecode (<ulink
	url="http://www.freecode.com/"></ulink>) to find an
	application, then check back at the &os; site to see if
	the application has been ported yet.</para>
	</listitem>

	<listitem>
	<para>To find out which category a port is in, type
	<command>whereis <replaceable>file</replaceable></command>,
	where <replaceable>file</replaceable> is the program to be
	installed:</para>

	<screen>&prompt.root; <userinput>whereis lsof</userinput>
	lsof: /usr/ports/sysutils/lsof</screen>

	- <para>Alternately, a &man.echo.1; statement can be
	+ <para>Alternately, an &man.echo.1; statement can be
	used:</para>

	<screen>&prompt.root; <userinput>echo /usr/ports//lsof*</userinput>
	/usr/ports/sysutils/lsof</screen>

	<para>Note that this will return any matched files downloaded
	into the <filename
	class="directory">/usr/ports/distfiles</filename>
	directory.</para>
	</listitem>

	<listitem>
	<para>Another way to find software is by using the Ports
	Collection's built-in search mechanism. To use
	the search feature, <application>cd</application> to
	<filename>/usr/ports</filename> then run <command>make
	<maketarget>search</maketarget>
	name=<replaceable>program-name</replaceable></command>
	where <replaceable>program-name</replaceable> is the name of
	- the software. For example,to search for
	+ the software. For example, to search for
	<command>lsof</command>:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
	&prompt.root; <userinput>make search name=lsof</userinput>
	Port: lsof-4.56.4
	Path: /usr/ports/sysutils/lsof
	Info: Lists information about open files (similar to fstat(1))
	Maint: obrien@FreeBSD.org
	Index: sysutils
	B-deps:
	R-deps: </screen>

	<para>The <quote>Path:</quote> line indicates where to find
	the port.</para>

	<para>To receive less information, use the
	<command>quicksearch</command> feature:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports</userinput>
	&prompt.root; <userinput>make quicksearch name=lsof</userinput>
	Port: lsof-4.87.a,7
	Path: /usr/ports/sysutils/lsof
	Info: Lists information about open files (similar to fstat(1))</screen>

	<para>For more in-depth searching, use
	<command>make <maketarget>search</maketarget>
	key=<replaceable>string</replaceable></command> or
	<command>make <maketarget>quicksearch</maketarget>
	key=<replaceable>string</replaceable></command>, where
	<replaceable>string</replaceable> is some text to search
	for. The text can be comments, descriptions or dependencies
	in order to find ports which relate to a particular subject
	when the name of the program is unknown.</para>

	<para>When using (<maketarget>search</maketarget> and
	<maketarget>quicksearch</maketarget>), the search string
	is case-insensitive. Searching for <quote>LSOF</quote> will
	yield the same results as searching for
	<quote>lsof</quote>.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="packages-using">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Chern</firstname>
	<surname>Lee</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<!-- 30 Mar 2001 -->
	</sect1info>

	<title>Using Binary Packages</title>

	<para>There are several different tools used to manage packages on
	&os;:</para>

	<itemizedlist>
	<listitem>
	<para>The <command>sysinstall</command> utility can be invoked
	on a running system to install, delete, and list available
	and installed packages. For more information, see
	<xref linkend="packages"/>.</para>
	</listitem>

	<listitem>
	<para>The package management command line tools, which are
	the subject of the rest of this section.</para>
	</listitem>
	</itemizedlist>

	<sect2>
	<title>Installing a Package</title>

	<indexterm>
	<primary>packages</primary>
	<secondary>installing</secondary>
	</indexterm>

	<indexterm>
	<primary><command>pkg_add</command></primary>
	</indexterm>
	<para>Use &man.pkg.add.1; to install a &os; binary package from
	a local file or from a server on the network.</para>

	<example>
	<title>Downloading a Package Manually and Installing It
	Locally</title>

	<screen>&prompt.root; <userinput>ftp -a <replaceable>ftp2.FreeBSD.org</replaceable></userinput>
	Connected to ftp2.FreeBSD.org.
	220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready.
	331 Guest login ok, send your email address as password.
	230-
	230- This machine is in Vienna, VA, USA, hosted by Verio.
	230- Questions? E-mail freebsd@vienna.verio.net.
	230-
	230-
	230 Guest login ok, access restrictions apply.
	Remote system type is UNIX.
	Using binary mode to transfer files.
	<prompt>ftp></prompt> <userinput>cd /pub/FreeBSD/ports/packages/sysutils/</userinput>
	250 CWD command successful.
	<prompt>ftp></prompt> <userinput>get lsof-4.56.4.tgz</userinput>
	local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
	200 PORT command successful.
	150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes).
	100% \|**************************************************\| 92375 00:00 ETA
	226 Transfer complete.
	92375 bytes received in 5.60 seconds (16.11 KB/s)
	<prompt>ftp></prompt> <userinput>exit</userinput>
	&prompt.root; <userinput>pkg_add <replaceable>lsof-4.56.4.tgz</replaceable></userinput></screen>
	</example>

	<para>If you do not have a source of local packages, such as a
	&os; CD-ROM set, include <option>-r</option> with
	&man.pkg.add.1;. This automatically determines the correct
	object format and release, and then fetches and installs the
	package from an FTP site without any further user
	intervention.</para>

	<indexterm>
	<primary><command>pkg_add</command></primary>
	</indexterm>
	<screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof</replaceable></userinput></screen>

	<para>To specify an alternative &os; FTP mirror, specify the
	mirror in the <envar>PACKAGESITE</envar> environment variable.
	&man.pkg.add.1; uses &man.fetch.3; to download files, which
	uses various environment variables, including
	<envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, and
	<envar>FTP_PASSWORD</envar>. You may need to set one or more
	of these if you are behind a firewall, or need to use an
	FTP/HTTP proxy. See &man.fetch.3; for the complete list.
	Note that in the example above <literal>lsof</literal> is used
	instead of <literal>lsof-4.56.4</literal>. When the remote
	fetching feature is used, the version number of the package
	must be removed.</para>

	<note>
	<para>&man.pkg.add.1; will automatically download the latest
	version of the application if you are using &os.current; or
	&os.stable;. If you run a -RELEASE version, it instead
	installs the version of the package that was built with that
	release. It is possible to change this behavior by
	overriding <envar>PACKAGESITE</envar>. For example, on a
	&os; 8.1-RELEASE system, by default &man.pkg.add.1;
	will try to fetch packages from
	<literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8.1-release/Latest/</literal>.
	To force &man.pkg.add.1; to download &os; 8-STABLE
	packages, set <envar>PACKAGESITE</envar> to
	<literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8-stable/Latest/</literal>.</para>
	</note>

	<para>Package files are distributed in <filename>.tgz</filename>
	and <filename>.tbz</filename> formats. Packages are
	available from <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/"></ulink>,
	or the <filename>/packages</filename> directory of the &os;
	DVD distribution. The layout of the packages is similar to
	that of the <filename>/usr/ports</filename> tree. Each
	category has its own directory, and every package can be found
	within the <filename>All</filename> directory.</para>
	</sect2>

	<sect2>
	<title>Managing Packages</title>

	<indexterm>
	<primary>packages</primary>
	<secondary>managing</secondary>
	</indexterm>

	<para>&man.pkg.info.1; can be used to list and describe
	installed packages:</para>

	<indexterm>
	<primary><command>pkg_info</command></primary>
	</indexterm>

	<screen>&prompt.root; <userinput>pkg_info</userinput>
	colordiff-1.0.13 A tool to colorize diff output
	docbook-1.2 Meta-port for the different versions of the DocBook DTD
	...</screen>

	<para>&man.pkg.version.1; summarizes the versions of all
	installed packages and compares the package version to the
	current version found in the ports tree.</para>

	<indexterm>
	<primary><command>pkg_version</command></primary>
	</indexterm>
	<screen>&prompt.root; <userinput>pkg_version</userinput>
	colordiff =
	docbook =
	...</screen>

	<para>The symbols in the second column indicate the relative age
	of the installed version and the version available in the
	local ports tree.</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Symbol</entry>
	<entry>Meaning</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>=</entry>
	<entry>The version of the installed package matches the
	one found in the local ports tree.</entry>
	</row>

	<row>
	<entry><</entry>
	<entry>The installed version is older than the one
	available in the local ports tree.</entry>
	</row>

	<row>
	<entry>></entry><entry>The installed version is newer
	than the one found in the local ports tree, meaning
	that the local ports tree is probably out of
	date.</entry>
	</row>

	<row>
	<entry>?</entry>
	<entry>The installed package cannot be found in the
	ports index. This can happen when an installed port
	is removed from the Ports Collection or is
	renamed.</entry>
	</row>

	<row>
	<entry>*</entry>
	<entry>There are multiple versions of the
	package.</entry>
	</row>

	<row>
	<entry>!</entry>

	<entry>The installed package exists in the index but for
	some reason, <command>pkg_version</command> was unable
	to compare the version number of the installed package
	with the corresponding entry in the index.</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</sect2>

	<sect2>
	<title>Deleting a Package</title>

	<indexterm>
	<primary><command>pkg_delete</command></primary>
	</indexterm>

	<indexterm>
	<primary>packages</primary>
	<secondary>deleting</secondary>
	</indexterm>

	<para>To remove a previously installed software package, use
	&man.pkg.delete.1;:</para>

	<screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen>

	<para>Note that &man.pkg.delete.1; requires the full package
	name and number; the above command would not work if
	<replaceable>xchat</replaceable> was given instead of
	<replaceable>xchat-1.7.1</replaceable>. Use
	&man.pkg.version.1; to find the version of the
	installed package, or use a wildcard:</para>

	<screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat\*</replaceable></userinput></screen>

	<para>in this case, all packages whose names start with
	<literal>xchat</literal> will be deleted.</para>
	</sect2>

	<sect2>
	<title>Miscellaneous</title>

	<para>All package information, including the file list and
	descriptions of each installed package is stored within the
	<filename>/var/db/pkg</filename> directory.</para>
	</sect2>
	</sect1>

	<sect1 id="pkgng-intro">
	<title>Using <application>pkgng</application> for Binary Package
	Management</title>

	<para><application>pkgng</application> is an improved replacement
	for the traditional &os; package management tools, offering
	many features that make dealing with binary packages faster and
	easier. The first release of <application>pkgng</application>
	was in August, 2012.</para>

	<para><application>pkgng</application> is not a replacement for
	port management tools like <filename
	role="package">ports-mgmt/portmaster</filename> or <filename
	role="package">ports-mgmt/portupgrade</filename>. While
	<filename role="package">ports-mgmt/portmaster</filename> and
	<filename role="package">ports-mgmt/portupgrade</filename> can
	install third-party software from both binary packages and the
	Ports Collection, <application>pkgng</application> installs
	only binary packages.</para>

	<sect2 id="pkgng-initial-setup">
	<title>Getting Started with
	<application>pkgng</application></title>

	<para>&os; 9.1 and later includes a "bootstrap"
	utility for <application>pkgng</application>. The bootstrap
	utility will download and install
	<application>pkgng</application>.</para>

	<para>To bootstrap the system, run:</para>

	<screen>&prompt.root; <userinput>/usr/sbin/pkg</userinput></screen>

	<para>For earlier &os; versions,
	<application>pkgng</application> must be installed from the
	Ports Collection, or as a binary package.</para>

	<para>To install the <application>pkgng</application> port,
	run:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/pkg</userinput>
	&prompt.root; <userinput>make</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>To install the binary package, run:</para>

	<screen>&prompt.root; <userinput>pkg_add -r pkg</userinput></screen>

	- <note>
	- <para>The <application>pkgng</application> package management
	- utility is not supported on
	- &os; 7.<replaceable>X</replaceable> or
	- &os; 8.0.</para>
	- </note>
	-
	<para>Existing &os; installations require conversion of the
	<application>pkg_install</application> package database to the
	new format. To convert the package database, run:</para>

	<screen>&prompt.root; <userinput>pkg2ng</userinput></screen>

	<para>This step is not required for new installations that do
	not have third-party software installed.</para>

	<important>
	<para>This step is not reversible. Once the package database
	has been converted to the <application>pkgng</application>
	format, the <application>pkg_install</application> tools
	should not be used.</para>
	</important>

	<note>
	<para>The package database conversion may emit errors as the
	contents are converted to the new version. Generally, these
	errors can be safely ignored, however a list of third-party
	software that was not successfully converted will be listed
	after <command>pkg2ng</command> has finished. These must be
	fixed by hand.</para>
	</note>

	<para>To ensure the &os; Ports Collection registers new
	software with <application>pkgng</application>, and not
	<application>pkg_install</application>, &os; versions earlier
	than 10.<replaceable>X</replaceable> require this line in
	<filename>/etc/make.conf</filename>:</para>

	<programlisting>WITH_PKGNG= yes</programlisting>
	</sect2>

	<sect2 id="pkgng-pkg-conf">
	<title>Configuring the <application>pkgng</application>
	Environment</title>

	<para>The <application>pkgng</application> package management
	system uses a package repository for most operations. The
	default package repository location is defined in
	<filename>/usr/local/etc/pkg.conf</filename> or the
	<envar>PACKAGESITE</envar> environment variable, which
	overrides the configuration file.</para>

	<para>Additional <application>pkgng</application>
	configuration options are described in
	pkg.conf(5).</para>
	</sect2>

	<sect2 id="pkgng-basic-usage">
	<title>Basic <application>pkgng</application> Operations</title>

	<para>Usage information for <application>pkgng</application> is
	available in the pkg(8) manual page, or by running
	<command>pkg</command> without additional arguments.</para>

	<para>Each <application>pkgng</application> command argument is
	documented in a command-specific manual page. To read the
	manual page for <command>pkg install</command>, for example,
	run either:</para>

	<screen>&prompt.root; <userinput>pkg help install</userinput></screen>

	<screen>&prompt.root; <userinput>man pkg-install</userinput></screen>

	<sect3 id="pkgng-pkg-info">
	<title>Obtaining Information About Installed Packages with
	<application>pkgng</application></title>

	<para>Information about the packages installed on a system can
	be viewed by running <command>pkg info</command>. Similar
	to &man.pkg.info.1;, the package version and
	description for all packages will be listed.</para>

	<para>Information about a specific package is available by
	running:</para>

	<screen>&prompt.root; <userinput>pkg info <replaceable>packagename</replaceable></userinput></screen>

	<para>For example, to see which version of
	<application>pkgng</application> is installed on the system,
	run:</para>

	<screen>&prompt.root; <userinput>pkg info pkg</userinput>
	pkg-1.0.2 New generation package manager</screen>
	</sect3>

	<sect3 id="pkgng-installing-deinstalling">
	<title>Installing and Removing Packages with
	<application>pkgng</application></title>

	<para>In general, most &os; users will install binary packages
	by running:</para>

	<screen>&prompt.root; <userinput>pkg install <replaceable>packagename</replaceable></userinput></screen>

	<para><command>pkg install</command> uses repository data, as
	mentioned in <xref linkend="pkgng-pkg-conf"/>. Conversely,
	pkg-add(8) does not use repository data, nor does it use the
	defined <envar>PACKAGESITE</envar>, so dependencies may not
	be properly tracked, and missing dependencies will not be
	fetched from a remote source. This section covers usage of
	<command>pkg install</command>. For information on usage of
	<command>pkg add</command>, see pkg-add(8).</para>

	<para>Additional binary packages can be installed with
	<command>pkg install</command>. For example, to install
	<application>curl</application>:</para>

	<screen>&prompt.root; <userinput>pkg install curl</userinput>
	Updating repository catalogue
	Repository catalogue is up-to-date, no need to fetch fresh copy
	The following packages will be installed:

	Installing ca_root_nss: 3.13.5
	Installing curl: 7.24.0

	The installation will require 4 MB more space

	1 MB to be downloaded

	Proceed with installing packages [y/N]: <userinput>y</userinput>
	ca_root_nss-3.13.5.txz 100% 255KB 255.1KB/s 255.1KB/s 00:00
	curl-7.24.0.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00
	Checking integrity... done
	Installing ca_root_nss-3.13.5... done
	Installing curl-7.24.0... done</screen>

	<para>The new package and any additional packages that were
	installed as dependencies can be seen in the installed
	packages list:</para>

	<screen>&prompt.root; <userinput>pkg info</userinput>
	ca_root_nss-3.13.5 The root certificate bundle from the Mozilla Project
	curl-7.24.0 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers
	pkg-1.0.2 New generation package manager</screen>

	<para>Packages that are no longer needed can be removed with
	<command>pkg delete</command>. For example, if it turns out
	that <application>curl</application> is not needed after
	all:</para>

	<screen>&prompt.root; <userinput>pkg delete curl</userinput>
	The following packages will be deleted:

	curl-7.24.0_1

	The deletion will free 3 MB

	Proceed with deleting packages [y/N]: <userinput>y</userinput>
	Deleting curl-7.24.0_1... done</screen>
	</sect3>

	<sect3 id="pkgng-upgrading">
	<title>Upgrading Installed Packages with
	<application>pkgng</application></title>

	<para>Packages that are outdated can be found with
	<command>pkg version</command>. If a local ports tree
	does not exist, pkg-version(8) will use the remote
	repository catalogue, otherwise the local ports tree will
	be used to identify package versions.</para>

	<para>Packages can be upgraded to newer versions with
	<application>pkgng</application>. Suppose a new version of
	<application>curl</application> has been released. The
	local package can be upgraded to the new version:</para>

	<screen>&prompt.root; <userinput>pkg upgrade</userinput>
	Updating repository catalogue
	repo.txz 100% 297KB 296.5KB/s 296.5KB/s 00:00
	The following packages will be upgraded:

	Upgrading curl: 7.24.0 -> 7.24.0_1

	1 MB to be downloaded

	Proceed with upgrading packages [y/N]: <userinput>y</userinput>
	curl-7.24.0_1.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00
	Checking integrity... done
	Upgrading curl from 7.24.0 to 7.24.0_1... done</screen>
	</sect3>

	<sect3 id="pkgng-auditing">
	<title>Auditing Installed Packages with
	<application>pkgng</application></title>

	<para>Occasionally, software vulnerabilities may be discovered
	in software within the Ports Collection.
	<application>pkgng</application> includes built-in auditing,
	similar to the <filename
	role="package">ports-mgmt/portaudit</filename> package.
	To audit the software installed on the system, run:</para>

	<screen>&prompt.root; <userinput>pkg audit -F</userinput></screen>
	</sect3>
	</sect2>

	<sect2 id="pkgng-advanced-usage">
	<title>Advanced <application>pkgng</application>
	Operations</title>

	<sect3 id="pkgng-autoremove">
	<title>Automatically Removing Leaf Dependencies with
	<application>pkgng</application></title>

	<para>Removing a package may leave behind unnecessary
	dependencies, like <filename
	role="package">security/ca_root_nss</filename> in the
	example above. Such packages are still installed, but
	nothing depends on them any more. Unneeded packages that
	were installed as dependencies can be automatically detected
	and removed:</para>

	<screen>&prompt.root; <userinput>pkg autoremove</userinput>
	Packages to be autoremoved:
	ca_root_nss-3.13.5

	The autoremoval will free 723 kB

	Proceed with autoremoval of packages [y/N]: <userinput>y</userinput>
	Deinstalling ca_root_nss-3.13.5... done</screen>
	</sect3>

	<sect3 id="pkgng-backup">
	<title>Backing Up the <application>pkgng</application> Package
	Database</title>

	<para>Unlike the traditional package management system,
	<application>pkgng</application> includes its own package
	database backup mechanism. To manually back up the package
	database contents, run:</para>

	<screen>&prompt.root; <userinput>pkg backup -d <replaceable>pkgng.db</replaceable></userinput></screen>

	<note>
	<para>Replace the file name
	<replaceable>pkgng.db</replaceable> to a suitable file
	name.</para>
	</note>

	<para>Additionally, <application>pkgng</application> includes
	a &man.periodic.8; script to automatically back up the
	package database daily if
	<literal>daily_backup_pkgng_enable</literal> is set to
	<literal>YES</literal> in &man.periodic.conf.5;.</para>

	<tip>
	<para>To prevent the <application>pkg_install</application>
	periodic script from also backing up the package database,
	set <literal>daily_backup_pkgdb_enable</literal> to
	<literal>NO</literal> in &man.periodic.conf.5;.</para>
	</tip>

	<para>To restore the contents of a previous package database
	backup, run:</para>

	<screen>&prompt.root; <userinput>pkg backup -r <replaceable>/path/to/pkgng.db</replaceable></userinput></screen>
	</sect3>

	<sect3 id="pkgng-clean">
	<title>Removing Stale <application>pkgng</application>
	Packages</title>

	<para>By default, <application>pkgng</application> stores
	binary packages in a cache directory as defined by
	<envar>PKG_CACHEDIR</envar> in pkg.conf(5). When
	upgrading packages with <command>pkg upgrade</command>, old
	versions of the upgraded packages are not automatically
	removed.</para>

	<para>To remove the outdated binary packages, run:</para>

	<screen>&prompt.root; <userinput>pkg clean</userinput></screen>
	</sect3>

	<sect3 id="pkgng-set">
	<title>Modifying <application>pkgng</application> Package
	Metadata</title>

	<para>Historically, software within the &os; Ports
	Collection can undergo major version number changes. Unlike
	<application>pkg_install</application>,
	<application>pkgng</application> has a built-in command to
	update package origins. For example, if <filename
	role="package">lang/php5</filename> was originally at
	version <literal>5.3</literal>, but has been renamed to
	<filename role="package">lang/php53</filename> for the
	inclusion of version <literal>5.4</literal>,
	<application>pkg_install</application> would require the use
	of additional software such as <filename
	role="package">ports-mgmt/portmaster</filename> to update
	the package database, reflecting from which port the
	installation originated.</para>

	<para>Unlike the <filename
	role="package">ports-mgmt/portmaster</filename> and
	<filename role="package">ports-mgmt/portupgrade</filename>
	ports, the order in which the new and old versions are
	listed differ. For <application>pkgng</application>, the
	syntax is:</para>

	<screen>&prompt.root; <userinput>pkg set -o <replaceable>category/oldport</replaceable>:<replaceable>category/newport</replaceable></userinput></screen>

	<para>For example, to change the package origin for the above
	example, run:</para>

	<screen>&prompt.root; <userinput>pkg set -o lang/php5:lang/php53</userinput></screen>

	<para>As another example, to update <filename
	role="package">lang/ruby18</filename> to <filename
	role="package">lang/ruby19</filename>, run:</para>

	<screen>&prompt.root; <userinput>pkg set -o lang/ruby18:lang/ruby19</userinput></screen>

	<para>As a final example, to change the origin of the
	<filename>libglut</filename> shared libraries from <filename
	role="package">graphics/libglut</filename> to <filename
	role="package">graphics/freeglut</filename>, run:</para>

	<screen>&prompt.root; <userinput>pkg set -o graphics/libglut:graphics/freeglut</userinput></screen>

	<note>
	<para>When changing package origins, in most cases it is
	important to reinstall packages that are dependent on the
	package that has had the origin changed. To force a
	reinstallation of dependent packages, run:</para>

	<screen>&prompt.root; <userinput>pkg install -Rf <replaceable>graphics/freeglut</replaceable></userinput></screen>
	</note>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="ports-using">
	<title>Using the Ports Collection</title>

	<para>This section provides basic instructions on using the Ports
	Collection to install or remove software. The detailed
	description of available <command>make</command> targets and
	environment variables is available in &man.ports.7;.</para>

	<warning>
	<para>As of mid 2012, the &os; Ports Project has migrated
	revision control systems from CVS to Subversion. The
	preferred method for obtaining and maintaining the ports tree
	is <application>Portsnap</application>. Users requiring local
	customization of ports (that is, maintaining additional local
	patches) will probably prefer to use Subversion directly. The
	- <application>CVSup</application> service is being phased out
	- as of February 28, 2013, and further use is
	- discouraged.</para>
	+ <application>CVSup</application> service was phased out
	+ as of February 28, 2013.</para>
	</warning>

	<sect2 id="ports-tree">
	<title>Obtaining the Ports Collection</title>

	<para>The Ports Collection is a set of
	<filename>Makefiles</filename>, patches, and description files
	stored in <filename>/usr/ports</filename>. This set of files
	is used to compile and install applications on &os;. The
	instructions below show several methods of obtaining the Ports
	Collection if it was not installed during initial &os;
	setup.</para>

	<procedure>
	<title>Portsnap Method</title>

	<para><application>Portsnap</application> is a fast and
	user-friendly tool for retrieving the Ports Collection, the
	preferred choice for most users. See
	<link linkend="updating-upgrading-portsnap">Using
	Portsnap</link> for a detailed description of
	<application>Portsnap</application>.</para>

	<step>
	<para>Download a compressed snapshot of the Ports Collection
	into <filename
	class="directory">/var/db/portsnap</filename>.</para>

	<screen>&prompt.root; <userinput>portsnap fetch</userinput></screen>
	</step>

	<step>
	<para>When running <application>Portsnap</application>
	for the first time, extract the snapshot into
	<filename class="directory">/usr/ports</filename>:</para>

	<screen>&prompt.root; <userinput>portsnap extract</userinput></screen>
	+ </step>

	+ <step>
	<para>After the first use of
	<application>Portsnap</application> has been completed as
	shown above,
	<filename class="directory">/usr/ports</filename> can be
	updated with:</para>

	- <screen>&prompt.root; <userinput>portsnap update</userinput></screen>
	+ <screen>&prompt.root; <userinput>portsnap fetch</userinput>
	+&prompt.root; <userinput>portsnap update</userinput></screen>
	</step>
	</procedure>

	<procedure>
	<title>Subversion Method</title>

	<para>If more control over the ports tree is needed (for
	example, for maintaining local changes),
	<application>Subversion</application> can be used to
	obtain the Ports Collection. Refer to <ulink
	url="&url.articles.committers-guide;/subversion-primer.html">the
	Subversion Primer</ulink> for a detailed description of
	<application>Subversion</application>.</para>

	<step>
	<para><application>Subversion</application> must be
	installed before it can be used to check out the ports
	tree. If a copy of the ports tree is already present,
	install <application>Subversion</application> like
	this:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/devel/subversion</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>If the ports tree is not available,
	<application>Subversion</application> can be installed as
	a package:</para>

	<screen>&prompt.root; <userinput>pkg_add -r subversion</userinput></screen>

	<para>If <application>pkgng</application> is being used to
	manage packages, <application>Subversion</application> can
	be installed with it instead:</para>

	<screen>&prompt.root; <userinput>pkg install subversion</userinput></screen>
	</step>

	<step>
	<para>Check out a copy of the ports tree. Use a specific
	<ulink
	- url="&url.books.handbook;/mirrors-svn.html">Subversion
	+ url="&url.books.handbook;/svn-mirrors.html">Subversion
	mirror</ulink> close to your geographic location instead
	- of <replaceable>svn.FreeBSD.org</replaceable> in the
	+ of <replaceable>svn0.us-east.FreeBSD.org</replaceable> in the
	command below for better performance. Committers should
	read the <ulink
	url="&url.articles.committers-guide;/subversion-primer.html">Subversion
	Primer</ulink> first to be sure the correct protocol is
	chosen.</para>

	- <screen>&prompt.root; <userinput>svn checkout svn://<replaceable>svn.FreeBSD.org</replaceable>/ports/head /usr/ports</userinput></screen>
	+ <screen>&prompt.root; <userinput>svn checkout https://<replaceable>svn0.us-east.FreeBSD.org</replaceable>/ports/head /usr/ports</userinput></screen>
	</step>

	<step>
	<para>To update
	<filename class="directory">/usr/ports</filename> after
	the initial <application>Subversion</application>
	checkout:</para>

	<screen>&prompt.root; <userinput>svn update /usr/ports</userinput></screen>
	</step>
	</procedure>

	<procedure>
	<title>Sysinstall Method</title>

	<para>This method involves using
	<application>sysinstall</application> to install the Ports
	Collection from the installation media. Note that the old
	copy of Ports Collection from the date of the release will
	be installed. If you have Internet access, you should
	always use one of the methods mentioned above.</para>

	<step>
	<para>As <username>root</username>, run
	<command>sysinstall</command> as shown below:</para>

	<screen>&prompt.root; <userinput>sysinstall</userinput></screen>
	</step>

	<step>
	<para>Scroll down and select
	<guimenuitem>Configure</guimenuitem>, press
	<keycap>Enter</keycap>.</para>
	</step>

	<step>
	<para>Scroll down and select
	<guimenuitem>Distributions</guimenuitem>, press
	<keycap>Enter</keycap>.</para>
	</step>

	<step>
	<para>Scroll down to <guimenuitem>ports</guimenuitem>, press
	<keycap>Space</keycap>.</para>
	</step>

	<step>
	<para>Scroll up to <guimenuitem>Exit</guimenuitem>, press
	<keycap>Enter</keycap>.</para>
	</step>

	<step>
	<para>Select your desired installation media, such as CDROM,
	FTP, and so on.</para>
	</step>

	<step>
	<para>Scroll up to <guimenuitem>Exit</guimenuitem> and press
	<keycap>Enter</keycap>.</para>
	</step>

	<step>
	<para>Press <keycap>X</keycap> to exit
	<application>sysinstall</application>.</para>
	</step>
	</procedure>
	</sect2>

	<sect2 id="cvsup-migration">
	<title>Migrating from
	<application>CVSup</application>/<application>csup</application>
	to <application>portsnap</application></title>

	<warning>
	<para>By February 28, 2013, the ports tree will no longer be
	exported to <application>CVS</application> and therefore
	<application>CVSup</application> and
	<application>csup</application> will no longer provide
	updates for the ports tree.</para>
	</warning>

	<procedure>
	<title>Migration to Portsnap</title>

	<para>The migration will require about 1 GB of disk space
	on <filename class="directory">/usr</filename>, plus
	<application>Portsnap</application> requires about
	150 MB disk space on <filename
	class="directory">/var</filename>.</para>

	<step>
	<para>Disable any automated ports updates you may use, such
	as a &man.cron.8; job calling
	<application>CVSup</application> or
	<application>csup</application>.</para>
	</step>

	<step>
	<para>Move the existing ports tree to a temporary
	location:</para>

	<screen>&prompt.root; <userinput>mv /usr/ports /usr/ports.old</userinput></screen>
	</step>

	<step>
	<para>Fetch the new ports tree with
	<application>Portsnap</application> and extract it to
	<filename class="directory">/usr/ports</filename>:</para>

	<screen>&prompt.root; <userinput>portsnap fetch extract</userinput></screen>
	</step>

	<step>
	<para>Move distfiles and saved packages to the new ports
	tree:</para>

	<screen>&prompt.root; <userinput>mv /usr/ports.old/distfiles /usr/ports</userinput>
	&prompt.root; <userinput>mv /usr/ports.old/packages /usr/ports</userinput></screen>
	</step>

	<step>
	<para>Delete the old ports tree:</para>

	<screen>&prompt.root; <userinput>rm -rf /usr/ports.old</userinput></screen>
	</step>

	<step>
	<para>If <application>CVSup</application> was used before,
	it can now be uninstalled:</para>

	<screen>&prompt.root; <userinput>pkg_delete -r -v cvsup-without-gui-\*</userinput></screen>

	<para>Users of <application>pkgng</application> can use the
	following command:</para>

	<screen>&prompt.root; <userinput>pkg delete cvsup-without-gui</userinput></screen>
	</step>
	</procedure>

	<para>See <link linkend="updating-upgrading-portsnap">Using
	Portsnap</link> for a detailed description of
	<application>Portsnap</application> and how to update the
	ports tree with <application>Portsnap</application>.</para>
	</sect2>

	<sect2 id="ports-skeleton">
	<title>Installing Ports</title>

	<indexterm>
	<primary>ports</primary>
	<secondary>installing</secondary>
	</indexterm>

	<para>A port skeleton is a set of files that tell &os; system
	how to compile and install a program. Each port skeleton
	includes:</para>

	<itemizedlist>
	<listitem>
	<para><filename>Makefile</filename>: The
	<filename>Makefile</filename> contains statements that
	specify how the application should be compiled and where
	its components should be installed.</para>
	</listitem>

	<listitem>
	<para><filename>distinfo</filename>: This file contains
	information about the files that must be downloaded to
	build the port, and their checksums (using
	&man.sha256.1;), to verify that files have not been
	corrupted during the download.</para>
	</listitem>

	<listitem>
	<para><filename>files/</filename>: This directory contains
	any patches needed for the program to compile and install
	on &os;. This directory may also contain other files used
	to build the port.</para>
	</listitem>

	<listitem>
	<para><filename>pkg-descr</filename>: This file provides a
	more detailed description of the program.</para>
	</listitem>

	<listitem>
	<para><filename>pkg-plist</filename>: This is a list
	of all the files that will be installed by the port. It
	also tells the ports system what files to remove upon
	deinstallation.</para>
	</listitem>
	</itemizedlist>

	<para>Some ports include other files, such as
	<filename>pkg-message</filename>. The ports system uses these
	files to handle special situations. If you want more details
	on these files, and on ports in general, refer to the
	<ulink url="&url.books.porters-handbook;/index.html">&os;
	Porter's Handbook</ulink>.</para>

	<para>The port does not include the actual source code, also
	known as a <quote>distfile</quote>. Source code is distributed
	in whatever manner the software author desires. The two
	methods for installing a &os; port are described below.</para>

	<note>
	<para>You must be logged in as <username>root</username> to
	install ports.</para>
	</note>

	<warning>
	<para>Before compiling any port, be sure to have an
	up-to-date Ports Collection and check <ulink
	url="http://vuxml.freebsd.org/"></ulink> for security
	issues related to your port. If <filename
	- role="package">ports-mgmt/portaudit</filename>) is
	+ role="package">ports-mgmt/portaudit</filename> is
	installed, run <command>portaudit -F</command> before
	installing a new port, to fetch the current vulnerabilities
	database. A security audit and an update of the database
	will be performed during the daily security system check.
	For more information read the &man.portaudit.1; and
	&man.periodic.8; manual pages.</para>
	</warning>

	<para>Using the Ports Collection assumes a working Internet
	connection. Otherwise, manually obtain and place a copy of
	the distfile into
	<filename>/usr/ports/distfiles</filename>.</para>

	<para>To begin, change to the directory of the port to
	be installed:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput></screen>

	<para>To compile, or <quote>build</quote>, the port, type
	<command>make</command> at the prompt. You should see
	messages similar to the ones in this example:</para>

	<screen>&prompt.root; <userinput>make</userinput>
	>> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
	>> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.
	===> Extracting for lsof-4.57
	...
	[extraction output snipped]
	...
	>> Checksum OK for lsof_4.57D.freebsd.tar.gz.
	===> Patching for lsof-4.57
	===> Applying FreeBSD patches for lsof-4.57
	===> Configuring for lsof-4.57
	...
	[configure output snipped]
	...
	===> Building for lsof-4.57
	...
	[compilation output snipped]
	...
	&prompt.root;</screen>

	<para>Once the compile is complete, you are returned to the
	prompt. The next step is to install the port using
	<maketarget>make install</maketarget>:</para>

	<screen>&prompt.root; <userinput>make install</userinput>
	===> Installing for lsof-4.57
	...
	[installation output snipped]
	...
	===> Generating temporary packing list
	===> Compressing manual pages for lsof-4.57
	===> Registering installation for lsof-4.57
	===> SECURITY NOTE:
	This port has installed the following binaries which execute with
	increased privileges.
	&prompt.root;</screen>

	<para>Once you are returned to the prompt, you should be able
	to run the installed application. Since
	<command>lsof</command> is a program that runs with increased
	privileges, a security warning is shown. During the building
	and installation of ports, take heed of any other warnings
	that may appear.</para>

	<para>It is a good idea to delete the working subdirectory,
	which contains all the temporary files used during
	compilation. Doing so saves disk space and minimizes the
	chance of problems later when upgrading to the newer version
	of the port.</para>

	<screen>&prompt.root; <userinput>make clean</userinput>
	===> Cleaning for lsof-4.57
	&prompt.root;</screen>

	<note>
	<para>You can save two extra steps by just running
	<command>make
	<maketarget>install clean</maketarget></command>
	instead of <command>make</command>,
	<command>make <maketarget>install</maketarget></command>
	and <command>make <maketarget>clean</maketarget></command>
	as three separate steps.</para>
	</note>

	<note>
	<para>Using only
	<command>make <maketarget>install</maketarget></command>
	means there will potentially be many
	waiting periods between user interaction as the default
	behaviour is to prompt the user for options. To avoid this
	when there are many dependencies, first run <command>make
	<maketarget>config-recursive</maketarget></command> to do
	the configuration in one batch. Then run <command>make
	<maketarget>install [clean]</maketarget></command>
	afterwards.</para>
	</note>

	<tip>
	<para>When using <maketarget>config-recursive</maketarget>,
	the list of ports to configure are gathered by the
	<maketarget>all-depends-list</maketarget> &man.make.1;
	target. It is often recommended to run <command>make
	<maketarget>config-recursive</maketarget></command>
	until all dependent ports options have been defined, and
	ports options &man.dialog.1; screens no longer
	appear, to be certain all ports options have been
	configured as intended.</para>
	</tip>

	<note>
	<para>Some shells keep a cache of the commands that are
	available in the directories listed in the
	<envar>PATH</envar> environment variable, to speed up lookup
	operations for the executable file of these commands. If
	you are using <command>tcsh</command>, you might have to
	type <command>rehash</command> so that a newly installed
	command can be used without specifying its full path. Use
	<command>hash -r</command> instead for the
	<command>sh</command> shell. Refer to the documentation for
	the shell for more information.</para>
	</note>

	<para>Some third-party DVD products such as the &os;
	Toolkit from the <ulink url="http://www.freebsdmall.com/">&os;
	Mall</ulink> contain distfiles. They can be used with the
	Ports Collection. Mount the DVD on
	<filename>/cdrom</filename>. If you use a different mount
	point, set <makevar>CD_MOUNTPTS</makevar> make variable. The
	needed distfiles will be automatically used if they are
	present on the disk.</para>

	<note>
	<para>The licenses of a few ports do not allow their inclusion
	on the DVD. This could be because a registration form
	needs to be filled out before downloading or redistribution
	is not allowed. If you wish to install a port not included
	on the DVD, you will need to be connected to the
	Internet.</para>
	</note>

	<para>The ports system uses &man.fetch.1; to download the
	files, which honors various environment variables, including
	<envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, and
	<envar>FTP_PASSWORD</envar>. You may need to set one or more
	of these if you are behind a firewall, or need to use an
	FTP/HTTP proxy. See &man.fetch.3; for the complete
	list.</para>

	<para>For users which cannot be connected all the time, the
	<command>make <maketarget>fetch</maketarget></command> option
	is provided. Run this command within
	<filename>/usr/ports</filename> and the required files will
	be downloaded. This command also works in the
	lower level categories, such as
	<filename>/usr/ports/net</filename>. Note that if a port
	depends on libraries or other ports, this will
	<emphasis>not</emphasis> fetch the distfiles of ports
	from another category. Use
	- <command>make<maketarget>fetch-recursive</maketarget>
	- <maketarget>fetch</maketarget></command> to fetch
	+ <command>make
	+ <maketarget>fetch-recursive</maketarget></command>
	+ to fetch
	all the dependencies of a port.</para>

	<note>
	<para>You can build all the ports in a category or as a
	whole by running <command>make</command> in the top level
	directory. This is dangerous, however, as some ports cannot
	co-exist. In other cases, some ports can install two
	different files with the same filename.</para>
	</note>

	<para>In some rare cases, users may need to acquire the
	tarballs from a site other than the default
	<makevar>MASTER_SITES</makevar>. You can override the
	<makevar>MASTER_SITES</makevar> option with the following
	command:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
	&prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
	ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen>

	<para>In this example, <makevar>MASTER_SITES</makevar> is
	changed to <hostid
	role="fqdn">ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</hostid>.</para>

	<note>
	<para>Some ports provide build options which can be used to
	enable/disable parts of the application which are unneeded,
	provide security options, or allow for other customizations.
	Examples include
	<filename role="package">www/firefox</filename>,
	<filename role="package">security/gpgme</filename>, and
	<filename role="package">mail/sylpheed-claws</filename>. A
	menu will be displayed at the beginning of a port
	compile when compile options are available.</para>
	</note>

	<sect3>
	<title>Overriding the Default Ports Directories</title>

	<para>The <makevar>WRKDIRPREFIX</makevar> and
	<makevar>PREFIX</makevar> variables can override the default
	working and target directories. For example:</para>

	<screen>&prompt.root; <userinput>make WRKDIRPREFIX=/usr/home/example/ports install</userinput></screen>

	<para>will compile the port in
	<filename>/usr/home/example/ports</filename> and install
	everything under <filename>/usr/local</filename>.</para>

	<screen>&prompt.root; <userinput>make PREFIX=/usr/home/example/local install</userinput></screen>

	<para>will compile the port in <filename>/usr/ports</filename>
	and install it in
	<filename>/usr/home/example/local</filename>.</para>

	<para>And</para>

	<screen>&prompt.root; <userinput>make WRKDIRPREFIX=../ports PREFIX=../local install</userinput></screen>

	<para>will combine the two.</para>

	<para>Alternatively, these can be set as environmental
	variables. Refer to the manual page for your shell
	for instructions on how to set an environmental
	variable.</para>
	</sect3>

	<sect3>
	<title>Reconfiguring Ports</title>

	<para>Certain ports provide an ncurses-based menu containing
	build options. There are several ways to revisit this menu
	in order to add, remove, or change these options after a
	port has been built. One method is to
	<command>cd</command> into the directory containing the
	port and type
	<command>make <maketarget>config</maketarget></command>.
	Another option is to use
	<command>make <maketarget>showconfig</maketarget></command>.
	Another option is to execute
	<command>make <maketarget>rmconfig</maketarget></command>
	which will remove all selected options and allow you to
	start over. All of these options, and others, are explained
	in great detail in the manual page for &man.ports.7;.</para>
	</sect3>
	</sect2>

	<sect2 id="ports-removing">
	<title>Removing Installed Ports</title>

	<indexterm>
	<primary>ports</primary>
	<secondary>removing</secondary>
	</indexterm>

	<para>Installed ports and packages are uninstalled using
	the &man.pkg.delete.1; command:</para>

	<screen>&prompt.root; <userinput>pkg_delete lsof-4.57</userinput></screen>
	</sect2>

	<sect2 id="ports-upgrading">
	<title>Upgrading Ports</title>

	<indexterm>
	<primary>ports</primary>
	<secondary>upgrading</secondary>
	</indexterm>

	<para>First, list outdated ports that have a newer version
	available in the Ports Collection with the &man.pkg.version.1;
	command:</para>

	<screen>&prompt.root; <userinput>pkg_version -v</userinput></screen>

	<sect3 id="ports-file-updating">
	<title>Read <filename>/usr/ports/UPDATING</filename></title>

	<para>Once you have updated your Ports Collection, before
	attempting a port upgrade, you should check
	<filename>/usr/ports/UPDATING</filename>. This file
	describes various issues and additional steps users may
	encounter and need to perform when updating a port,
	including such things as file format changes, changes in
	locations of configuration files, or other such
	incompatibilities with previous versions.</para>

	<para>If <filename>UPDATING</filename> contradicts something
	you read here, <filename>UPDATING</filename> takes
	precedence.</para>
	</sect3>

	<sect3 id="portupgrade">
	<title>Upgrading Ports Using Portupgrade</title>

	<indexterm>
	<primary>portupgrade</primary>
	</indexterm>

	<para>The <application>portupgrade</application> utility is
	designed to easily upgrade installed ports. It is available
	from the
	<filename role="package">ports-mgmt/portupgrade</filename>
	port. Install it like any other port, using
	<command>make <maketarget>install
	clean</maketarget></command>:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portupgrade</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>Scan the list of installed ports using
	<command>pkgdb -F</command> and fix all the inconsistencies
	it reports. It is a good idea to do this regularly, before
	every upgrade.</para>

	<para>Use <command>portupgrade -a</command> to upgrade all the
	outdated ports installed on the system. Include
	<option>-i</option> to be asked for confirmation of every
	individual upgrade.</para>

	<screen>&prompt.root; <userinput>portupgrade -ai</userinput></screen>

	<para>To upgrade only a specified application instead of all
	available ports, use <command>portupgrade
	<replaceable>pkgname</replaceable></command>. Include
	<option>-R</option> to first upgrade all the ports required
	by the given application.</para>

	<screen>&prompt.root; <userinput>portupgrade -R firefox</userinput></screen>

	<para>To use packages instead of ports, include the
	<option>-P</option> flag. With this option,
	<application>portupgrade</application> searches the local
	directories listed in <envar>PKG_PATH</envar>, then fetches
	packages from a remote site if not found locally. If
	packages can not be found locally or fetched remotely,
	<application>portupgrade</application> will use ports. To
	avoid using ports, specify <option>-PP</option>.</para>

	<screen>&prompt.root; <userinput>portupgrade -PP gnome2</userinput></screen>

	<para>To just fetch distfiles (or packages, if
	<option>-P</option> is specified) without building or
	installing anything, use <option>-F</option>. For further
	information see &man.portupgrade.1;.</para>
	</sect3>

	<sect3 id="portmaster">
	<title>Upgrading Ports Using
	<application>portmaster</application></title>

	<indexterm>
	<primary>portmaster</primary>
	</indexterm>

	<para><filename
	role="package">ports-mgmt/portmaster</filename> is another
	utility for upgrading installed ports.
	<application>portmaster</application> was designed to
	use the tools found in the <quote>base</quote> system
	without depending upon other ports. It uses the information
	in <filename class="directory">/var/db/pkg/</filename> to
	determine which ports to upgrade. To install the
	port:</para>

	<screen>&prompt.root; <userinput>cd <filename class="directory">/usr/ports/ports-mgmt/portmaster</filename></userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para><application>Portmaster</application> groups ports into
	four categories:</para>

	<itemizedlist>
	<listitem>
	<para>Root ports: no dependencies and is not depended on
	by other ports</para>
	</listitem>

	<listitem>
	<para>Trunk ports: no dependencies, but other ports depend
	upon it</para>
	</listitem>

	<listitem>
	<para>Branch ports: have dependencies and are depended
	upon by other ports</para>
	</listitem>

	<listitem>
	<para>Leaf ports: have dependencies but are not depended
	upon by other ports</para>
	</listitem>
	</itemizedlist>

	<para>To list all installed software and search for updates,
	use <option>-L</option>:</para>

	<screen>&prompt.root; <userinput>portmaster -L</userinput>
	===>>> Root ports (No dependencies, not depended on)
	===>>> ispell-3.2.06_18
	===>>> screen-4.0.3
	===>>> New version available: screen-4.0.3_1
	===>>> tcpflow-0.21_1
	===>>> 7 root ports
	...
	===>>> Branch ports (Have dependencies, are depended on)
	===>>> apache-2.2.3
	===>>> New version available: apache-2.2.8
	...
	===>>> Leaf ports (Have dependencies, not depended on)
	===>>> automake-1.9.6_2
	===>>> bash-3.1.17
	===>>> New version available: bash-3.2.33
	...
	===>>> 32 leaf ports

	===>>> 137 total installed ports
	===>>> 83 have new versions available</screen>

	<para>All the installed ports can be upgraded using this
	command:</para>

	<screen>&prompt.root; <userinput>portmaster -a</userinput></screen>

	<note>
	<para>By default, <application>portmaster</application> will
	make a backup package before deleting the existing port.
	If the installation of the new version is successful,
	<application>portmaster</application> will delete the
	backup. Using <option>-b</option> will instruct
	<application>portmaster</application> not to automatically
	delete the backup. Adding <option>-i</option> will start
	<application>portmaster</application> in interactive mode,
	prompting for confirmation before upgrading each
	port.</para>
	</note>

	<para>If you encounter errors during the upgrade process, use
	<option>-f</option> to upgrade/rebuild all ports:</para>

	<screen>&prompt.root; <userinput>portmaster -af</userinput></screen>

	<para>You can also use <application>portmaster</application>
	to install new ports on the system, upgrading all
	dependencies before building and installing the new
	port:</para>

	<screen>&prompt.root; <userinput>portmaster <replaceable>shells/bash</replaceable></userinput></screen>

	<para>Refer to &man.portmaster.8; for more information.</para>
	</sect3>
	</sect2>

	<sect2 id="ports-disk-space">
	<title>Ports and Disk Space</title>

	<indexterm>
	<primary>ports</primary>
	<secondary>disk-space</secondary>
	</indexterm>

	<para>Using the Ports Collection will use up disk space over
	time. After building and installing a port, <command>make
	<maketarget>clean</maketarget></command> will clean up the
	temporary <filename class="directory">work</filename>
	directory. To sweep the whole Ports Collection:</para>

	<screen>&prompt.root; <userinput>portsclean -C</userinput></screen>

	<para>A lot of out-dated source distribution files will collect
	in <filename class="directory">distfiles</filename> over time.
	The following command will delete all the distfiles that are
	no longer referenced by any ports:</para>

	<screen>&prompt.root; <userinput>portsclean -D</userinput></screen>

	<para>To remove all distfiles not referenced by any port
	currently installed on the system:</para>

	<screen>&prompt.root; <userinput>portsclean -DD</userinput></screen>

	<note>
	<para>The <command>portsclean</command> utility is part of the
	<application>portupgrade</application> suite.</para>
	</note>

	<para><filename
	role="package">ports-mgmt/pkg_cutleaves</filename> automates
	the task of removing installed ports that are no longer
	- needed.
	-
	- port.</para>
	+ needed.</para>
	</sect2>
	</sect1>

	<sect1 id="ports-nextsteps">
	<title>Post-installation Activities</title>

	<para>After installing a new application you will normally want to
	read any documentation it may have included, edit any
	required configuration files, and ensure that the
	application's service starts at boot time.</para>

	<para>The exact steps you need to take to configure each
	application will obviously be different. However, if you have
	just installed a new application and are wondering
	<quote>What now?</quote> these tips might help:</para>

	<itemizedlist>
	<listitem>
	<para>Use &man.pkg.info.1; to find out which files were
	installed, and where. For example, if you have just
	installed FooPackage version 1.0.0, then this command</para>

	<screen>&prompt.root; <userinput>pkg_info -L foopackage-1.0.0 \| less</userinput></screen>

	<para>will show all the files installed by the package. Pay
	special attention to files located in
	<filename>man/</filename>, which will be manual pages,
	<filename>etc/</filename>, which will be configuration
	files, and <filename>doc/</filename>, which will be more
	comprehensive documentation.</para>

	<para>To determine which version of the application was
	installed:</para>

	<screen>&prompt.root; <userinput>pkg_info \| grep -i <replaceable>foopackage</replaceable></userinput></screen>

	<para>will find all the installed packages that have
	<replaceable>foopackage</replaceable> in the package name.
	Replace <replaceable>foopackage</replaceable> as
	necessary.</para>
	</listitem>

	<listitem>
	<para>Once you have identified where the application's manual
	pages have been installed, review them using &man.man.1;.
	Review the sample configuration files and any additional
	documentation that may have been provided.</para>
	</listitem>

	<listitem>
	<para>If the application has a web site, check it for
	additional documentation, frequently asked questions, and so
	forth. If you are not sure of the web site address it may
	be listed in the output from</para>

	<screen>&prompt.root; <userinput>pkg_info <replaceable>foopackage-1.0.0</replaceable></userinput></screen>

	<para>A <literal>WWW:</literal> line, if present, should
	provide a URL for the application's web site.</para>
	</listitem>

	<listitem>
	<para>Ports that should start at boot time usually install a
	startup script in <filename>/usr/local/etc/rc.d</filename>.
	Review this script for correctness and edit or rename it if
	needed. See <link
	linkend="configtuning-starting-services">Starting
	Services</link> for more information.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="ports-broken">
	<title>Dealing with Broken Ports</title>

	<para>If you come across a port that does not compile:</para>

	<orderedlist>
	<listitem>
	<para>Find out if there is a fix pending for the port in
	the <ulink url="&url.base;/support.html#gnats">Problem
	Report database</ulink>. If so, you may be able to use
	the proposed fix.</para>
	</listitem>

	<listitem>
	<para>Ask the maintainer of the port for help. Type
	<command>make <maketarget>maintainer</maketarget></command>
	or read the <filename>Makefile</filename> to find the
	maintainer's email address. Remember to include the name
	and version of the port (send the
	<literal>&dollar;FreeBSD:</literal> line from the
	<filename>Makefile</filename>) and the output leading up to
	the error when you email the maintainer.</para>

	<note>
	<para>Some ports are not maintained by an individual but
	instead by a <ulink
	url="&url.articles.mailing-list-faq;/article.html">mailing
	list</ulink>. Many, but not all, of these addresses look
	like <email
	role="nolink">freebsd-listname@FreeBSD.org</email>.
	Please take this into account when phrasing your
	questions.</para>

	<para>In particular, ports shown as maintained by
	<email role="nolink">ports@FreeBSD.org</email> are
	actually not maintained by anyone. Fixes and support, if
	any, come from the general community who subscribe to that
	mailing list. More volunteers are always needed!</para>
	</note>

	<para>If you do not get a response, use &man.send-pr.1; to
	submit a bug report (see <ulink
	url="&url.articles.problem-reports;/article.html">Writing
	&os; Problem Reports</ulink>).</para>
	</listitem>

	<listitem>
	<para>Fix it! The <ulink
	url="&url.books.porters-handbook;/index.html">Porter's
	Handbook</ulink> includes detailed information on the
	<quote>Ports</quote> infrastructure so that you can fix the
	occasional broken port or even submit your own!</para>
	</listitem>

	<listitem>
	<para>Use &man.pkg.add.1; to instead install the
	package.</para>
	</listitem>
	</orderedlist>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml (revision 41355)
	@@ -1,3343 +1,3318 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="ppp-and-slip">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Jim</firstname>
	<surname>Mock</surname>
	<contrib>Restructured, reorganized, and updated by </contrib>
	<!-- 1 Mar 2000 -->
	</author>
	</authorgroup>
	</chapterinfo>

	<title>PPP and SLIP</title>

	<sect1 id="ppp-and-slip-synopsis">
	<title>Synopsis</title>

	<indexterm id="ppp-ppp">
	<primary>PPP</primary>
	</indexterm>
	<indexterm id="ppp-slip">
	<primary>SLIP</primary>
	</indexterm>

	<para>FreeBSD has a number of ways to link one computer to
	another. To establish a network or Internet connection through
	a dial-up modem, or to allow others to do so through you,
	requires the use of PPP or SLIP. This chapter describes setting
	up these modem-based communication services in detail.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>How to set up user PPP.</para>
	</listitem>
	<listitem>
	<para>How to set up kernel PPP (&os; 7.X only).</para>
	</listitem>
	<listitem>
	<para>How to set up <acronym>PPPoE</acronym> (PPP over
	Ethernet).</para>
	</listitem>
	<listitem>
	<para>How to set up <acronym>PPPoA</acronym> (PPP over
	ATM).</para>
	</listitem>
	<listitem>
	<para>How to configure and set up a SLIP client and
	server (&os; 7.X only).</para>
	</listitem>
	</itemizedlist>

	<indexterm id="ppp-ppp-user">
	<primary>PPP</primary>
	<secondary>user PPP</secondary>
	</indexterm>
	<indexterm id="ppp-ppp-kernel">
	<primary>PPP</primary>
	<secondary>kernel PPP</secondary>
	</indexterm>
	<indexterm id="ppp-ppp-ethernet">
	<primary>PPP</primary>
	<secondary>over Ethernet</secondary>
	</indexterm>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	<para>Be familiar with basic network terminology.</para>
	</listitem>
	<listitem>
	<para>Understand the basics and purpose of a dialup connection
	and PPP and/or SLIP.</para>
	</listitem>
	</itemizedlist>

	<para>You may be wondering what the main difference is between
	user PPP and kernel PPP. The answer is simple: user PPP
	processes the inbound and outbound data in userland rather than
	in the kernel. This is expensive in terms of copying the data
	between the kernel and userland, but allows a far more
	feature-rich PPP implementation. User PPP uses the
	<devicename>tun</devicename> device to communicate with the
	outside world whereas kernel PPP uses the
	<devicename>ppp</devicename> device.</para>

	<note>
	<para>Throughout in this chapter, user PPP will simply be
	referred to as <application>ppp</application> unless a
	distinction needs to be made between it and any other PPP
	software such as <application>pppd</application>
	(&os; 7.X only). Unless otherwise stated, all of the
	commands explained in this chapter should be executed as
	<username>root</username>.</para>
	</note>
	</sect1>

	<sect1 id="userppp">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Updated and enhanced by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Brian</firstname>
	<surname>Somers</surname>
	<contrib>Originally contributed by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Nik</firstname>
	<surname>Clayton</surname>
	<contrib>With input from </contrib>
	</author>
	<author>
	<firstname>Dirk</firstname>
	<surname>Frömberg</surname>
	</author>
	<author>
	<firstname>Peter</firstname>
	<surname>Childs</surname>
	</author>
	</authorgroup>
	</sect1info>

	<title>Using User PPP</title>

	- <warning>
	- <para>As of &os; 8.0, device nodes for serial ports have been
	- renamed from
	- <filename>/dev/cuad<replaceable>N</replaceable></filename> to
	- <filename>/dev/cuau<replaceable>N</replaceable></filename> and
	- from
	- <filename>/dev/ttyd<replaceable>N</replaceable></filename> to
	- <filename>/dev/ttyu<replaceable>N</replaceable></filename>.
	- &os; 7.X users will have to adapt the following
	- documentation according to these changes.</para>
	- </warning>
	-
	<sect2>
	<title>User PPP</title>

	<sect3>
	<title>Assumptions</title>

	<para>This document assumes you have the following:</para>

	<itemizedlist>
	<indexterm id="ppp-isp">
	<primary>ISP</primary>
	</indexterm>
	<indexterm id="ppp-ppp2">
	<primary>PPP</primary>
	</indexterm>
	<listitem>
	<para>An account with an Internet Service Provider (ISP)
	which you connect to using PPP.</para>
	</listitem>

	<listitem>
	<para>A modem or
	other device connected to your system and properly
	configured to allow you to connect to your ISP.</para>
	</listitem>

	<listitem>
	<para>The dial-up number(s) of your ISP.</para>
	</listitem>

	<listitem>
	<indexterm id="ppp-pap">
	<primary>PAP</primary>
	</indexterm>
	<indexterm id="ppp-chap">
	<primary>CHAP</primary>
	</indexterm>
	<indexterm id="ppp-unix">
	<primary>UNIX</primary>
	</indexterm>
	<indexterm id="ppp-login">
	<primary>login name</primary>
	</indexterm>
	<indexterm id="ppp-password">
	<primary>password</primary>
	</indexterm>
	<para>Your login name and password. (Either a
	regular &unix; style login and password pair, or a PAP
	or CHAP login and password pair).</para>
	</listitem>

	<listitem>
	<indexterm id="ppp-nameserver">
	<primary>nameserver</primary>
	</indexterm>

	<para>The IP address of one or more name servers.
	Normally, you will be given two IP addresses by your
	ISP to use for this. If they have not given you at
	least one, then you can use the <command>enable
	dns</command> command in <filename>ppp.conf</filename>
	and <application>ppp</application> will set the name
	servers for you. This feature depends on your ISPs
	PPP implementation supporting DNS negotiation.</para>
	</listitem>
	</itemizedlist>

	<para>The following information may be supplied by your ISP,
	but is not completely necessary:</para>

	<itemizedlist>
	<listitem>
	<para>The IP address of your ISP's gateway. The gateway
	is the machine to which you will connect and will be
	set up as your <emphasis>default route</emphasis>. If
	you do not have this information, we can make one up
	and your ISP's PPP server will tell us the correct value
	when we connect.</para>

	<para>This IP number is referred to as
	<literal>HISADDR</literal> by
	<application>ppp</application>.</para>
	</listitem>

	<listitem>
	<para>The netmask you should use. If your ISP has not
	provided you with one, you can safely use <hostid
	role="netmask">255.255.255.255</hostid>.</para>
	</listitem>

	<listitem>
	<indexterm id="ppp-static-ip">
	<primary>static IP address</primary>
	</indexterm>

	<para>If your ISP provides you with a static IP address
	and hostname, you can enter it. Otherwise, we simply
	let the peer assign whatever IP address it sees
	fit.</para>
	</listitem>
	</itemizedlist>

	<para>If you do not have any of the required information,
	contact your ISP.</para>

	<note>
	<para>Throughout this section, many of the examples showing
	the contents of configuration files are numbered by line.
	These numbers serve to aid in the presentation and
	discussion only and are not meant to be placed in the
	actual file. Proper indentation with tab and space
	characters is also important.</para>
	</note>

	</sect3>

	<sect3>
	<title>Automatic <application>PPP</application>
	Configuration</title>

	<indexterm>
	<primary>PPP</primary>
	<secondary>configuration</secondary>
	</indexterm>

	<para>Both <command>ppp</command> and <command>pppd</command>
	(the kernel level implementation of PPP, &os; 7.X only)
	use the configuration files located in the <filename
	class="directory">/etc/ppp</filename> directory.
	Examples for user ppp can be found in <filename
	class="directory">/usr/share/examples/ppp/</filename>.</para>

	<para>Configuring <command>ppp</command> requires that you
	edit a number of files, depending on your requirements.
	What you put in them depends to some extent on whether your
	ISP allocates IP addresses statically (i.e., you get given
	one IP address, and always use that one) or dynamically
	(i.e., your IP address changes each time you connect to
	your ISP).</para>

	<sect4 id="userppp-staticIP">
	<title>PPP and Static IP Addresses</title>

	<indexterm>
	<primary>PPP</primary>
	<secondary>with static IP addresses</secondary>
	</indexterm>

	<para>You will need to edit the
	<filename>/etc/ppp/ppp.conf</filename> configuration file.
	It should look similar to the example below.</para>

	<note>
	<para>Lines that end in a <literal>:</literal> start in
	the first column (beginning of the line)— all
	other lines should be indented as shown using spaces
	or tabs.</para>
	</note>

	<programlisting>1 default:
	2 set log Phase Chat LCP IPCP CCP tun command
	3 ident user-ppp VERSION (built COMPILATIONDATE)
	4 set device /dev/cuau0
	5 set speed 115200
	6 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \
	7 \"\" AT OK-AT-OK ATE1Q0 OK \\dATDT\\T TIMEOUT 40 CONNECT"
	8 set timeout 180
	9 enable dns
	10
	11 provider:
	12 set phone "(123) 456 7890"
	13 set authname foo
	14 set authkey bar
	15 set login "TIMEOUT 10 \"\" \"\" gin:--gin: \\U word: \\P col: ppp"
	16 set timeout 300
	17 set ifaddr <replaceable>x.x.x.x</replaceable> <replaceable>y.y.y.y</replaceable> 255.255.255.255 0.0.0.0
	18 add default HISADDR</programlisting>

	<variablelist>
	<varlistentry>
	<term>Line 1:</term>

	<listitem>
	<para>Identifies the default entry. Commands in this
	entry are executed automatically when ppp is
	run.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 2:</term>

	<listitem>
	<para>Enables logging parameters. When the
	configuration is working satisfactorily, this line
	should be reduced to saying:</para>

	<programlisting>set log phase tun</programlisting>

	<para>in order to avoid excessive log file
	sizes.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 3:</term>

	<listitem>
	<para>Tells PPP how to identify itself to the peer.
	PPP identifies itself to the peer if it has any
	trouble negotiating and setting up the link,
	providing information that the peers administrator
	may find useful when investigating such
	problems.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 4:</term>

	<listitem>
	<para>Identifies the device to which the modem is
	connected. <devicename>COM1</devicename> is
	<filename class="devicefile">/dev/cuau0</filename>
	and
	<devicename>COM2</devicename> is
	<filename
	class="devicefile">/dev/cuau1</filename>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 5:</term>

	<listitem>
	<para>Sets the speed you want to connect at. If
	115200 does not work (it should with any reasonably
	new modem), try 38400 instead.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 6 & 7:</term>

	<listitem>
	<indexterm>
	<primary>PPP</primary>
	<secondary>user PPP</secondary>
	</indexterm>

	<para>The dial string. User PPP uses an expect-send
	syntax similar to the &man.chat.8; program. Refer
	to the manual page for information on the features
	of this language.</para>

	<para>Note that this command continues onto the next
	line for readability. Any command in
	<filename>ppp.conf</filename> may do this if the
	last character on the line is a <literal>\</literal>
	character.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 8:</term>

	<listitem>
	<para>Sets the idle timeout for the link. 180 seconds
	is the default, so this line is purely
	cosmetic.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 9:</term>

	<listitem>
	<para>Tells PPP to ask the peer to confirm the local
	resolver settings. If you run a local name server,
	this line should be commented out or removed.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 10:</term>

	<listitem>
	<para>A blank line for readability. Blank lines are
	ignored by PPP.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 11:</term>

	<listitem>
	<para>Identifies an entry for a provider called
	<quote>provider</quote>. This could be changed
	to the name of your <acronym>ISP</acronym> so
	that later you can use the <option>load
	<replaceable>ISP</replaceable></option> to start
	the connection.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 12:</term>

	<listitem>
	<para>Sets the phone number for this provider.
	Multiple phone numbers may be specified using the
	colon (<literal>:</literal>) or pipe character
	(<literal>\|</literal>) as a separator. The
	difference between the two separators is described
	in &man.ppp.8;. To summarize, if you want to rotate
	through the numbers, use a colon. If you want to
	always attempt to dial the first number first and
	only use the other numbers if the first number
	fails, use the pipe character. Always quote the
	entire set of phone numbers as shown.</para>

	<para>You must enclose the phone number in quotation
	marks (<literal>"</literal>) if there is any
	intention on using spaces in the phone number.
	This can cause a simple, yet subtle error.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 13 & 14:</term>

	<listitem>
	<para>Identifies the user name and password. When
	connecting using a &unix; style login prompt, these
	values are referred to by the <command>set
	login</command> command using the \U and \P
	variables. When connecting using PAP or CHAP, these
	values are used at authentication time.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 15:</term>

	<listitem>
	<indexterm><primary>PAP</primary></indexterm>
	<indexterm><primary>CHAP</primary></indexterm>
	<para>If you are using PAP or CHAP, there will be no
	login at this point, and this line should be
	commented out or removed. See <link
	linkend="userppp-PAPnCHAP">PAP and CHAP
	authentication</link> for further details.</para>

	<para>The login string is of the same chat-like
	syntax as the dial string. In this example, the
	string works for a service whose login session looks
	like this:</para>

	<screen>J. Random Provider
	login: <replaceable>foo</replaceable>
	password: <replaceable>bar</replaceable>
	protocol: ppp</screen>

	<para>You will need to alter this script to suit your
	own needs. When you write this script for the first
	time, you should ensure that you have enabled
	<quote>chat</quote> logging so you can determine if
	the conversation is going as expected.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 16:</term>

	<listitem>
	<indexterm><primary>timeout</primary></indexterm>

	<para>Sets the default idle timeout (in seconds) for
	the connection. Here, the connection will be closed
	automatically after 300 seconds of inactivity. If
	you never want to timeout, set this value to zero
	or use the <option>-ddial</option> command line
	switch.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 17:</term>
	<listitem>
	<indexterm><primary>ISP</primary></indexterm>

	<para>Sets the interface addresses. The string
	<replaceable>x.x.x.x</replaceable> should be
	replaced by the IP address that your provider has
	allocated to you. The string
	<replaceable>y.y.y.y</replaceable> should be
	replaced by the IP address that your ISP indicated
	for their gateway (the machine to which you
	connect). If your ISP has not given you a gateway
	address, use <hostid
	role="netmask">10.0.0.2/0</hostid>. If you need to
	use a <quote>guessed</quote> address, make sure that
	you create an entry in
	<filename>/etc/ppp/ppp.linkup</filename> as per the
	instructions for <link
	linkend="userppp-dynamicIP">PPP and Dynamic IP
	addresses</link>. If this line is omitted,
	<command>ppp</command> cannot run in
	<option>-auto</option> mode.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 18:</term>

	<listitem>
	<para>Adds a default route to your ISP's gateway. The
	special word <literal>HISADDR</literal> is replaced
	with the gateway address specified on line 17. It
	is important that this line appears after line 17,
	otherwise <literal>HISADDR</literal> will not yet
	be initialized.</para>

	<para>If you do not wish to run ppp in
	<option>-auto</option>, this line should be moved
	to the <filename>ppp.linkup</filename> file.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>It is not necessary to add an entry to
	<filename>ppp.linkup</filename> when you have a static
	IP address and are running ppp in <option>-auto</option>
	mode as your routing table entries are already correct
	before you connect. You may however wish to create an
	entry to invoke programs after connection. This is
	explained later with the sendmail example.</para>

	<para>Example configuration files can be found in the
	<filename
	class="directory">/usr/share/examples/ppp/</filename>
	directory.</para>
	</sect4>

	<sect4 id="userppp-dynamicIP">
	<title>PPP and Dynamic IP Addresses</title>

	<indexterm>
	<primary>PPP</primary>
	<secondary>with dynamic IP addresses</secondary>
	</indexterm>

	<indexterm>
	<primary>IPCP</primary>
	</indexterm>

	<para>If your service provider does not assign static IP
	addresses, <command>ppp</command> can be configured to
	negotiate the local and remote addresses. This is done by
	<quote>guessing</quote> an IP address and allowing
	<command>ppp</command> to set it up correctly using the IP
	Configuration Protocol (IPCP) after connecting. The
	<filename>ppp.conf</filename> configuration is the same as
	<link linkend="userppp-staticIP">PPP and Static IP
	Addresses</link>, with the following change:</para>

	<programlisting>17 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.255 0.0.0.0</programlisting>

	<para>Again, do not include the line number, it is just for
	reference. Indentation of at least one space is
	required.</para>

	<variablelist>
	<varlistentry>
	<term>Line 17:</term>

	<listitem>
	<para>The number after the <literal>/</literal>
	character is the number of bits of the address that
	ppp will insist on. You may wish to use IP numbers
	more appropriate to your circumstances, but the
	above example will always work.</para>

	<para>The last argument (<literal>0.0.0.0</literal>)
	tells PPP to start negotiations using address
	<hostid role="ipaddr">0.0.0.0</hostid> rather than
	<hostid role="ipaddr">10.0.0.1</hostid> and is
	necessary for some ISPs. Do not use
	<literal>0.0.0.0</literal> as the first argument
	to <command>set ifaddr</command> as it prevents
	PPP from setting up an initial route in
	<option>-auto</option> mode.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>If you are not running in <option>-auto</option> mode,
	you will need to create an entry in
	<filename>/etc/ppp/ppp.linkup</filename>.
	<filename>ppp.linkup</filename> is used after a connection
	has been established. At this point,
	<command>ppp</command> will have assigned the interface
	addresses and it will now be possible to add the routing
	table entries:</para>

	<programlisting>1 provider:
	2 add default HISADDR</programlisting>

	<variablelist>
	<varlistentry>
	<term>Line 1:</term>

	<listitem>
	<para>On establishing a connection,
	<command>ppp</command> will look for an entry in
	<filename>ppp.linkup</filename> according to the
	following rules: First, try to match the same label
	as we used in <filename>ppp.conf</filename>. If
	that fails, look for an entry for the IP address of
	our gateway. This entry is a four-octet IP style
	label. If we still have not found an entry, look
	for the <literal>MYADDR</literal> entry.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 2:</term>

	<listitem>
	<para>This line tells <command>ppp</command> to add a
	default route that points to
	<literal>HISADDR</literal>.
	<literal>HISADDR</literal> will be replaced with the
	IP number of the gateway as negotiated by the
	IPCP.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>See the <literal>pmdemand</literal> entry in the files
	<filename>/usr/share/examples/ppp/ppp.conf.sample</filename>
	and
	<filename>/usr/share/examples/ppp/ppp.linkup.sample</filename>
	for a detailed example.</para>
	</sect4>

	<sect4>
	<title>Receiving Incoming Calls</title>

	<indexterm>
	<primary>PPP</primary>
	<secondary>receiving incoming calls</secondary>
	</indexterm>

	<para>When you configure <application>ppp</application> to
	receive incoming calls on a machine connected to a LAN,
	you must decide if you wish to forward packets to the LAN.
	If you do, you should allocate the peer an IP number from
	your LAN's subnet, and use the command <command>enable
	proxy</command> in your
	<filename>/etc/ppp/ppp.conf</filename> file. You should
	also confirm that the <filename>/etc/rc.conf</filename>
	file contains the following:</para>

	<programlisting>gateway_enable="YES"</programlisting>
	</sect4>

	<sect4>
	<title>Which getty?</title>

	<para><link linkend="dialup">Configuring FreeBSD for
	Dial-up Services</link> provides a good description
	on enabling dial-up services using &man.getty.8;.</para>

	<para>An alternative to <command>getty</command> is <ulink
	url="http://mgetty.greenie.net/">mgetty</ulink> (from
	<filename role="package">comms/mgetty+sendfax</filename>
	port), a smarter version of <command>getty</command>
	designed with dial-up lines in mind.</para>

	<para>The advantages of using <command>mgetty</command> is
	that it actively <emphasis>talks</emphasis> to modems,
	meaning if port is turned off in
	<filename>/etc/ttys</filename> then your modem will not
	answer the phone.</para>

	<para>Later versions of <command>mgetty</command> (from
	0.99beta onwards) also support the automatic detection of
	PPP streams, allowing your clients script-less access to
	your server.</para>

	<para>Refer to <link linkend="userppp-mgetty">Mgetty and
	AutoPPP</link> for more information on
	<command>mgetty</command>.</para>
	</sect4>

	<sect4>
	<title><application>PPP</application> Permissions</title>

	<para>The <command>ppp</command> command must normally be
	run as the <username>root</username> user. If however,
	you wish to allow <command>ppp</command> to run in
	server mode as a normal user by executing
	<command>ppp</command> as described below, that user
	must be given permission to run <command>ppp</command>
	by adding them to the <groupname>network</groupname>
	group in <filename>/etc/group</filename>.</para>

	<para>You will also need to give them access to one or more
	sections of the configuration file using the
	<command>allow</command> command:</para>

	<programlisting>allow users fred mary</programlisting>

	<para>If this command is used in the
	<literal>default</literal> section, it gives the specified
	users access to everything.</para>
	</sect4>

	<sect4>
	<title>PPP Shells for Dynamic-IP Users</title>

	<indexterm>
	<primary>PPP shells</primary>
	</indexterm>

	<para>Create a file called
	<filename>/etc/ppp/ppp-shell</filename> containing the
	following:</para>

	<programlisting>#!/bin/sh
	IDENT=`echo $0 \| sed -e 's/^.-$.$$/\1/'`
	CALLEDAS="$IDENT"
	TTY=`tty`

	if [ x$IDENT = xdialup ]; then
	IDENT=`basename $TTY`
	fi

	echo "PPP for $CALLEDAS on $TTY"
	echo "Starting PPP for $IDENT"

	exec /usr/sbin/ppp -direct $IDENT</programlisting>

	<para>This script should be executable. Now make a
	symbolic link called <filename>ppp-dialup</filename> to
	this script using the following commands:</para>

	<screen>&prompt.root; <userinput>ln -s ppp-shell /etc/ppp/ppp-dialup</userinput></screen>

	<para>You should use this script as the
	<emphasis>shell</emphasis> for all of your dialup users.
	This is an example from <filename>/etc/passwd</filename>
	for a dialup PPP user with username
	<username>pchilds</username> (remember do not directly
	edit the password file, use &man.vipw.8;).</para>

	<programlisting>pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup</programlisting>

	<para>Create a <filename
	class="directory">/home/ppp</filename> directory that
	is world readable containing the following 0 byte
	files:</para>

	<screen>-r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin
	-r--r--r-- 1 root wheel 0 May 27 02:22 .rhosts</screen>

	<para>which prevents <filename>/etc/motd</filename> from
	being displayed.</para>
	</sect4>

	<sect4>
	<title>PPP Shells for Static-IP Users</title>

	<indexterm>
	<primary>PPP shells</primary>
	</indexterm>

	<para>Create the <filename>ppp-shell</filename> file as
	above, and for each account with statically assigned
	IPs create a symbolic link to
	<filename>ppp-shell</filename>.</para>

	<para>For example, if you have three dialup customers,
	<username>fred</username>, <username>sam</username>,
	and <username>mary</username>, that you route /24 CIDR
	networks for, you would type the following:</para>

	<screen>&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred</userinput>
	&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam</userinput>
	&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary</userinput></screen>

	<para>Each of these users dialup accounts should have
	their shell set to the symbolic link created above (for
	example, <username>mary</username>'s shell should be
	<filename>/etc/ppp/ppp-mary</filename>).</para>
	</sect4>

	<sect4>
	<title>Setting Up <filename>ppp.conf</filename> for
	Dynamic-IP Users</title>

	<para>The <filename>/etc/ppp/ppp.conf</filename> file
	should contain something along the lines of:</para>

	<programlisting>default:
	set debug phase lcp chat
	set timeout 0

	ttyu0:
	set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255
	enable proxy

	ttyu1:
	set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255
	enable proxy</programlisting>

	<note>
	<para>The indenting is important.</para>
	</note>

	<para>The <literal>default:</literal> section is loaded
	for each session. For each dialup line enabled in
	<filename>/etc/ttys</filename> create an entry similar
	to the one for <literal>ttyu0:</literal> above. Each
	line should get a unique IP address from your pool of
	IP addresses for dynamic users.</para>
	</sect4>

	<sect4>
	<title>Setting Up <filename>ppp.conf</filename> for
	Static-IP Users</title>

	<para>Along with the contents of the sample
	<filename>/usr/share/examples/ppp/ppp.conf</filename>
	above you should add a section for each of the
	statically assigned dialup users. We will continue with
	our <username>fred</username>, <username>sam</username>,
	and <username>mary</username> example.</para>

	<programlisting>fred:
	set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255

	sam:
	set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255

	mary:
	set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255</programlisting>

	<para>The file <filename>/etc/ppp/ppp.linkup</filename>
	should also contain routing information for each static
	IP user if required. The line below would add a route
	for the <hostid role="ipaddr">203.14.101.0/24</hostid>
	network via the client's ppp link.</para>

	<programlisting>fred:
	add 203.14.101.0 netmask 255.255.255.0 HISADDR

	sam:
	add 203.14.102.0 netmask 255.255.255.0 HISADDR

	mary:
	add 203.14.103.0 netmask 255.255.255.0 HISADDR</programlisting>
	</sect4>

	<sect4 id="userppp-mgetty">
	<title><command>mgetty</command> and AutoPPP</title>

	<indexterm>
	<primary><command>mgetty</command></primary>
	</indexterm>

	<indexterm>
	<primary>AutoPPP</primary>
	</indexterm>

	<indexterm>
	<primary>LCP</primary>
	</indexterm>

	<para>By default the <filename
	role="package">comms/mgetty+sendfax</filename> port
	comes with the <literal>AUTO_PPP</literal> option enabled
	allowing <command>mgetty</command> to detect the LCP
	phase of PPP connections and automatically spawn off a
	ppp shell. However, since the default login/password
	sequence does not occur it is necessary to authenticate
	users using either PAP or CHAP.</para>

	<para>This section assumes the user has successfully
	compiled, and installed the <filename
	role="package">comms/mgetty+sendfax</filename> port on
	his system.</para>

	<para>Make sure your
	<filename>/usr/local/etc/mgetty+sendfax/login.config</filename>
	file has the following in it:</para>

	<programlisting>/AutoPPP/ - - /etc/ppp/ppp-pap-dialup</programlisting>

	<para>This will tell <command>mgetty</command> to run the
	<filename>ppp-pap-dialup</filename> script for detected
	PPP connections.</para>

	<para>Create a file called
	<filename>/etc/ppp/ppp-pap-dialup</filename> containing
	the following (the file should be executable):</para>

	<programlisting>#!/bin/sh
	exec /usr/sbin/ppp -direct pap$IDENT</programlisting>

	<para>For each dialup line enabled in
	<filename>/etc/ttys</filename>, create a corresponding
	entry in <filename>/etc/ppp/ppp.conf</filename>. This
	will happily co-exist with the definitions we created
	above.</para>

	<programlisting>pap:
	enable pap
	set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40
	enable proxy</programlisting>

	<para>Each user logging in with this method will need to
	have a username/password in
	<filename>/etc/ppp/ppp.secret</filename> file, or
	alternatively add the following option to authenticate
	users via PAP from the <filename>/etc/passwd</filename>
	file.</para>

	<programlisting>enable passwdauth</programlisting>

	<para>If you wish to assign some users a static IP number,
	you can specify the number as the third argument in
	<filename>/etc/ppp/ppp.secret</filename>. See
	<filename>/usr/share/examples/ppp/ppp.secret.sample</filename>
	for examples.</para>
	</sect4>

	<sect4>
	<title>MS Extensions</title>

	<indexterm>
	<primary>DNS</primary>
	</indexterm>

	<indexterm>
	<primary>NetBIOS</primary>
	</indexterm>

	<indexterm>
	<primary>PPP</primary>
	<secondary>Microsoft extensions</secondary>
	</indexterm>

	<para>It is possible to configure PPP to supply DNS and
	NetBIOS nameserver addresses on demand.</para>

	<para>To enable these extensions with PPP version 1.x, the
	following lines might be added to the relevant section
	of <filename>/etc/ppp/ppp.conf</filename>.</para>

	<programlisting>enable msext
	set ns 203.14.100.1 203.14.100.2
	set nbns 203.14.100.5</programlisting>

	<para>And for PPP version 2 and above:</para>

	<programlisting>accept dns
	set dns 203.14.100.1 203.14.100.2
	set nbns 203.14.100.5</programlisting>

	<para>This will tell the clients the primary and secondary
	name server addresses, and a NetBIOS nameserver
	host.</para>

	<para>In version 2 and above, if the
	<literal>set dns</literal> line is omitted, PPP will
	use the values found in
	<filename>/etc/resolv.conf</filename>.</para>
	</sect4>

	<sect4 id="userppp-PAPnCHAP">
	<title>PAP and CHAP Authentication</title>

	<indexterm><primary>PAP</primary></indexterm>
	<indexterm><primary>CHAP</primary></indexterm>
	<para>Some ISPs set their system up so that the
	authentication part of your connection is done using
	either of the PAP or CHAP authentication mechanisms. If
	this is the case, your ISP will not give a
	<prompt>login:</prompt> prompt when you connect, but will
	start talking PPP immediately.</para>

	<para>PAP is less secure than CHAP, but security is not
	normally an issue here as passwords, although being sent
	as plain text with PAP, are being transmitted down a
	serial line only. There is not much room for crackers
	to <quote>eavesdrop</quote>.</para>

	<para>Referring back to the <link
	linkend="userppp-staticIP">PPP and Static IP
	addresses</link> or <link
	linkend="userppp-dynamicIP">PPP and Dynamic IP
	addresses</link> sections, the following alterations must
	be made:</para>

	<programlisting>13 set authname <replaceable>MyUserName</replaceable>
	14 set authkey <replaceable>MyPassword</replaceable>
	15 set login</programlisting>

	<variablelist>
	<varlistentry>
	<term>Line 13:</term>

	<listitem>
	<para>This line specifies your PAP/CHAP user name.
	You will need to insert the correct value for
	<replaceable>MyUserName</replaceable>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 14:</term>
	<listitem>
	<indexterm><primary>password</primary></indexterm>

	<para>This line specifies your PAP/CHAP password.
	You will need to insert the correct value for
	<replaceable>MyPassword</replaceable>. You may
	want to add an additional line, such as:</para>

	<programlisting>16 accept PAP</programlisting>

	<para>or</para>

	<programlisting>16 accept CHAP</programlisting>

	<para>to make it obvious that this is the intention,
	but PAP and CHAP are both accepted by
	default.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Line 15:</term>

	<listitem>
	<para>Your ISP will not normally require that you log
	into the server if you are using PAP or CHAP. You
	must therefore disable your <quote>set login</quote>
	string.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect4>

	<sect4>
	<title>Changing Your <command>ppp</command> Configuration
	on the Fly</title>

	<para>It is possible to talk to the <command>ppp</command>
	program while it is running in the background, but only
	if a suitable diagnostic port has been set up. To do
	this, add the following line to your configuration:</para>

	<programlisting>set server /var/run/ppp-tun<replaceable>%d</replaceable> DiagnosticPassword 0177</programlisting>

	<para>This will tell PPP to listen to the specified
	&unix; domain socket, asking clients for the specified
	password before allowing access. The
	<literal>%d</literal> in the name is replaced with the
	<devicename>tun</devicename> device number that is in
	use.</para>

	<para>Once a socket has been set up, the &man.pppctl.8;
	program may be used in scripts that wish to manipulate
	the running program.</para>
	</sect4>
	</sect3>

	<sect3 id="userppp-nat">
	<title>Using PPP Network Address Translation
	Capability</title>

	<indexterm>
	<primary>PPP</primary><secondary>NAT</secondary>
	</indexterm>

	<para>PPP has ability to use internal NAT without kernel
	diverting capabilities. This functionality may be enabled
	by the following line in
	<filename>/etc/ppp/ppp.conf</filename>:</para>

	<programlisting>nat enable yes</programlisting>

	<para>Alternatively, PPP NAT may be enabled by command-line
	option <literal>-nat</literal>. There is also
	<filename>/etc/rc.conf</filename> knob named
	<literal>ppp_nat</literal>, which is enabled by
	default.</para>

	<para>If you use this feature, you may also find useful
	the following <filename>/etc/ppp/ppp.conf</filename> options
	to enable incoming connections forwarding:</para>

	<programlisting>nat port tcp 10.0.0.2:ftp ftp
	nat port tcp 10.0.0.2:http http</programlisting>

	<para>or do not trust the outside at all</para>

	<programlisting>nat deny_incoming yes</programlisting>
	</sect3>

	<sect3 id="userppp-final">
	<title>Final System Configuration</title>

	<indexterm>
	<primary>PPP</primary><secondary>configuration</secondary>
	</indexterm>

	<para>You now have <command>ppp</command> configured, but
	there are a few more things to do before it is ready to
	work. They all involve editing the
	<filename>/etc/rc.conf</filename> file.</para>

	<para>Working from the top down in this file, make sure the
	<literal>hostname=</literal> line is set, e.g.:</para>

	<programlisting>hostname="foo.example.com"</programlisting>

	<para>If your ISP has supplied you with a static IP address
	and name, it is probably best that you use this name as your
	host name.</para>

	<para>Look for the <literal>network_interfaces</literal>
	variable. If you want to configure your system to dial your
	ISP on demand, make sure the <devicename>tun0</devicename>
	device is added to the list, otherwise remove it.</para>

	<programlisting>network_interfaces="lo0 tun0"
	ifconfig_tun0=</programlisting>

	<note>
	<para>The <literal>ifconfig_tun0</literal> variable should
	be empty, and a file called
	<filename>/etc/start_if.tun0</filename> should be created.
	This file should contain the line:</para>

	<programlisting>ppp -auto mysystem</programlisting>

	<para>This script is executed at network configuration time,
	starting your ppp daemon in automatic mode. If you have
	a LAN for which this machine is a gateway, you may also
	wish to use the <option>-alias</option> switch. Refer
	to the manual page for further details.</para>
	</note>

	<para>Make sure that the router program is set to
	<literal>NO</literal> with the following line in your
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>router_enable="NO"</programlisting>

	<indexterm>
	<primary><application>routed</application></primary>
	</indexterm>

	<para>It is important that the <command>routed</command>
	daemon is not started, as <command>routed</command> tends
	to delete the default routing table entries created by
	<command>ppp</command>.</para>

	<para>It is probably a good idea to ensure that the
	<literal>sendmail_flags</literal> line does not include the
	<option>-q</option> option, otherwise
	<command>sendmail</command> will attempt to do a network
	lookup every now and then, possibly causing your machine
	to dial out. You may try:</para>

	<programlisting>sendmail_flags="-bd"</programlisting>

	<indexterm>
	<primary><application>sendmail</application></primary>
	</indexterm>
	<para>The downside of this is that you must force
	<command>sendmail</command> to re-examine the mail queue
	whenever the ppp link is up by typing:</para>

	<screen>&prompt.root; <userinput>/usr/sbin/sendmail -q</userinput></screen>

	<para>You may wish to use the <command>!bg</command> command
	in <filename>ppp.linkup</filename> to do this
	automatically:</para>

	<programlisting>1 provider:
	2 delete ALL
	3 add 0 0 HISADDR
	4 !bg sendmail -bd -q30m</programlisting>

	<indexterm>
	<primary>SMTP</primary>
	</indexterm>

	<para>If you do not like this, it is possible to set up a
	<quote>dfilter</quote> to block SMTP traffic. Refer to the
	sample files for further details.</para>

	<para>All that is left is to reboot the machine. After
	rebooting, you can now either type:</para>

	<screen>&prompt.root; <userinput>ppp</userinput></screen>

	<para>and then <command>dial provider</command> to start the
	PPP session, or, if you want <command>ppp</command> to
	establish sessions automatically when there is outbound
	traffic (and you have not created the
	<filename>start_if.tun0</filename> script), type:</para>

	<screen>&prompt.root; <userinput>ppp -auto provider</userinput></screen>
	</sect3>

	<sect3>
	<title>Summary</title>

	<para>To recap, the following steps are necessary when setting
	up ppp for the first time:</para>

	<para>Client side:</para>

	<procedure>
	<step>
	<para>Ensure that the <devicename>tun</devicename> device
	is built into your kernel.</para>
	</step>

	<step>
	<para>Ensure that the <filename
	class="devicefile">tun<replaceable>N</replaceable></filename>
	device file is available in the <filename
	class="directory">/dev</filename> directory.</para>
	</step>

	<step>
	<para>Create an entry in
	<filename>/etc/ppp/ppp.conf</filename>. The
	<filename>pmdemand</filename> example should suffice
	for most ISPs.</para>
	</step>

	<step>
	<para>If you have a dynamic IP address, create an entry in
	<filename>/etc/ppp/ppp.linkup</filename>.</para>
	</step>

	<step>
	<para>Update your <filename>/etc/rc.conf</filename>
	file.</para>
	</step>

	<step>
	<para>Create a <filename>start_if.tun0</filename> script
	if you require demand dialing.</para>
	</step>
	</procedure>

	<para>Server side:</para>

	<procedure>
	<step>
	<para>Ensure that the <devicename>tun</devicename> device
	is built into your kernel.</para>
	</step>

	<step>
	<para>Ensure that the
	<filename
	class="devicefile">tun<replaceable>N</replaceable></filename>
	device file is available in the <filename
	class="directory">/dev</filename> directory.</para>
	</step>

	<step>
	<para>Create an entry in <filename>/etc/passwd</filename>
	(using the &man.vipw.8; program).</para>
	</step>

	<step>
	<para>Create a profile in this users home directory that
	runs <command>ppp -direct direct-server</command> or
	similar.</para>
	</step>

	<step>
	<para>Create an entry in
	<filename>/etc/ppp/ppp.conf</filename>. The
	<filename>direct-server</filename> example should
	suffice.</para>
	</step>

	<step>
	<para>Create an entry in
	<filename>/etc/ppp/ppp.linkup</filename>.</para>
	</step>

	<step>
	<para>Update your <filename>/etc/rc.conf</filename>
	file.</para>
	</step>
	</procedure>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="ppp">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Gennady B.</firstname>
	<surname>Sorokopud</surname>
	<contrib>Parts originally contributed by </contrib>
	</author>
	<author>
	<firstname>Robert</firstname>
	<surname>Huff</surname>
	</author>
	</authorgroup>
	</sect1info>

	<title>Using Kernel PPP</title>

	<warning>
	<para>This section applies and is valid only for
	&os; 7.X.</para>
	</warning>

	<sect2>
	<title>Setting Up Kernel PPP</title>

	<indexterm>
	<primary>PPP</primary>
	<secondary>kernel PPP</secondary>
	</indexterm>

	<para>Before you start setting up PPP on your machine, make sure
	that <command>pppd</command> is located in
	<filename class="directory">/usr/sbin</filename> and the
	directory <filename class="directory">/etc/ppp</filename>
	exists.</para>

	<para><command>pppd</command> can work in two modes:</para>

	<orderedlist>
	<listitem>
	<para>As a <quote>client</quote> — you want to connect
	your machine to the outside world via a PPP serial
	connection or modem line.</para>
	</listitem>

	<listitem>
	<indexterm>
	<primary>PPP</primary>
	<secondary>server</secondary>
	</indexterm>

	<para>As a <quote>server</quote> — your machine is
	located on the network, and is used to connect other
	computers using PPP.</para>
	</listitem>
	</orderedlist>

	<para>In both cases you will need to set up an options file
	(<filename>/etc/ppp/options</filename> or
	<filename>~/.ppprc</filename> if you have more than one user
	on your machine that uses PPP).</para>

	<para>You will also need some modem/serial software (preferably
	<filename role="package">comms/kermit</filename>), so you
	can dial and establish a connection with the remote
	host.</para>
	</sect2>

	<sect2>
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Trev</firstname>
	<surname>Roydhouse</surname>
	<contrib>Based on information provided by </contrib>
	<!-- Trev.Roydhouse@f401.n711.z3.fidonet.org -->
	</author>
	</authorgroup>
	</sect2info>

	<title>Using <command>pppd</command> as a Client</title>

	<indexterm>
	<primary>PPP</primary>
	<secondary>client</secondary>
	</indexterm>

	<indexterm>
	<primary>Cisco</primary>
	</indexterm>

	<para>The following <filename>/etc/ppp/options</filename> might
	be used to connect to a Cisco terminal server PPP line.</para>

	<programlisting>crtscts # enable hardware flow control
	modem # modem control line
	noipdefault # remote PPP server must supply your IP address
	# if the remote host does not send your IP during IPCP
	# negotiation, remove this option
	passive # wait for LCP packets
	domain ppp.foo.com # put your domain name here

	:<replaceable>remote_ip</replaceable> # put the IP of remote PPP host here
	# it will be used to route packets via PPP link
	# if you didn't specified the noipdefault option
	# change this line to <replaceable>local_ip</replaceable>:<replaceable>remote_ip</replaceable>

	defaultroute # put this if you want that PPP server will be your
	# default router</programlisting>

	<para>To connect:</para>

	<indexterm><primary>Kermit</primary></indexterm>
	<indexterm><primary>modem</primary></indexterm>
	<procedure>
	<step>
	<para>Dial to the remote host using
	<application>Kermit</application> (or some other modem
	program), and enter your user name and password (or
	whatever is needed to enable PPP on the remote
	host).</para>
	</step>

	<step>
	<para>Exit <application>Kermit</application> (without
	hanging up the line).</para>
	</step>

	<step>
	<para>Enter the following:</para>

	<screen>&prompt.root; <userinput>/usr/sbin/pppd <replaceable>/dev/tty01</replaceable> <replaceable>19200</replaceable></userinput></screen>

	<para>Be sure to use the appropriate speed and device
	name.</para>
	</step>
	</procedure>

	<para>Now your computer is connected with PPP. If the
	connection fails, you can add the <option>debug</option>
	option to the <filename>/etc/ppp/options</filename> file,
	and check console messages to track the problem.</para>

	<para>Following <filename>/etc/ppp/pppup</filename> script will
	make all 3 stages automatic:</para>

	<programlisting>#!/bin/sh
	pgrep -l pppd
	pid=`pgrep pppd`
	if [ "X${pid}" != "X" ] ; then
	echo 'killing pppd, PID=' ${pid}
	kill ${pid}
	fi
	pgrep -l kermit
	pid=`pgrep kermit`
	if [ "X${pid}" != "X" ] ; then
	echo 'killing kermit, PID=' ${pid}
	kill -9 ${pid}
	fi

	ifconfig ppp0 down
	ifconfig ppp0 delete

	kermit -y /etc/ppp/kermit.dial
	pppd /dev/tty01 19200</programlisting>

	<indexterm>
	<primary>Kermit</primary>
	</indexterm>

	<para><filename>/etc/ppp/kermit.dial</filename> is a
	<application>Kermit</application> script that dials and makes
	all necessary authorization on the remote host (an example
	of such a script is attached to the end of this
	document).</para>

	<para>Use the following <filename>/etc/ppp/pppdown</filename>
	script to disconnect the PPP line:</para>

	<programlisting>#!/bin/sh
	pid=`pgrep pppd`
	if [ X${pid} != "X" ] ; then
	echo 'killing pppd, PID=' ${pid}
	kill -TERM ${pid}
	fi

	pgrep -l kermit
	pid=`pgrep kermit`
	if [ "X${pid}" != "X" ] ; then
	echo 'killing kermit, PID=' ${pid}
	kill -9 ${pid}
	fi

	/sbin/ifconfig ppp0 down
	/sbin/ifconfig ppp0 delete
	kermit -y /etc/ppp/kermit.hup
	/etc/ppp/ppptest</programlisting>

	<para>Check to see if <command>pppd</command> is still running
	by executing <filename>/usr/etc/ppp/ppptest</filename>, which
	should look like this:</para>

	<programlisting>#!/bin/sh
	pid=`pgrep pppd`
	if [ X${pid} != "X" ] ; then
	echo 'pppd running: PID=' ${pid-NONE}
	else
	echo 'No pppd running.'
	fi
	set -x
	netstat -n -I ppp0
	ifconfig ppp0</programlisting>

	<para>To hang up the modem, execute
	<filename>/etc/ppp/kermit.hup</filename>, which should
	contain:</para>

	<programlisting>set line /dev/tty01 ; put your modem device here
	set speed 19200
	set file type binary
	set file names literal
	set win 8
	set rec pack 1024
	set send pack 1024
	set block 3
	set term bytesize 8
	set command bytesize 8
	set flow none

	pau 1
	out +++
	inp 5 OK
	out ATH0\13
	echo \13
	exit</programlisting>

	<para>Here is an alternate method using <command>chat</command>
	instead of <command>kermit</command>:</para>

	<para>The following two files are sufficient to accomplish a
	<command>pppd</command> connection.</para>

	<para><filename>/etc/ppp/options</filename>:</para>

	<programlisting>/dev/cuad1 115200

	crtscts # enable hardware flow control
	modem # modem control line
	connect "/usr/bin/chat -f /etc/ppp/login.chat.script"
	noipdefault # remote PPP serve must supply your IP address
	# if the remote host doesn't send your IP during
	# IPCP negotiation, remove this option
	passive # wait for LCP packets
	domain <replaceable>your.domain</replaceable> # put your domain name here

	: # put the IP of remote PPP host here
	# it will be used to route packets via PPP link
	# if you didn't specified the noipdefault option
	# change this line to <replaceable>local_ip</replaceable>:<replaceable>remote_ip</replaceable>

	defaultroute # put this if you want that PPP server will be
	# your default router</programlisting>

	<para><filename>/etc/ppp/login.chat.script</filename>:</para>

	<note>
	<para>The following should go on a single line.</para>
	</note>

	<programlisting>ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT<replaceable>phone.number</replaceable>
	CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: <replaceable>login-id</replaceable>
	TIMEOUT 5 sword: <replaceable>password</replaceable></programlisting>

	<para>Once these are installed and modified correctly, all
	you need to do is run <command>pppd</command>, like so:</para>

	<screen>&prompt.root; <userinput>pppd</userinput></screen>
	</sect2>

	<sect2>
	<title>Using <command>pppd</command> as a Server</title>

	<para><filename>/etc/ppp/options</filename> should contain
	something similar to the following:</para>

	<programlisting>crtscts # Hardware flow control
	netmask 255.255.255.0 # netmask (not required)
	192.114.208.20:192.114.208.165 # IP's of local and remote hosts
	# local ip must be different from one
	# you assigned to the Ethernet (or other)
	# interface on your machine.
	# remote IP is IP address that will be
	# assigned to the remote machine
	domain ppp.foo.com # your domain
	passive # wait for LCP
	modem # modem line</programlisting>

	<para>The following <filename>/etc/ppp/pppserv</filename> script
	will tell <application>pppd</application> to behave as a
	server:</para>

	<programlisting>#!/bin/sh
	pgrep -l pppd
	pid=`pgrep pppd`
	if [ "X${pid}" != "X" ] ; then
	echo 'killing pppd, PID=' ${pid}
	kill ${pid}
	fi
	pgrep -l kermit
	pid=`pgrep kermit`
	if [ "X${pid}" != "X" ] ; then
	echo 'killing kermit, PID=' ${pid}
	kill -9 ${pid}
	fi

	# reset ppp interface
	ifconfig ppp0 down
	ifconfig ppp0 delete

	# enable autoanswer mode
	kermit -y /etc/ppp/kermit.ans

	# run ppp
	pppd /dev/tty01 19200</programlisting>

	<para>Use this <filename>/etc/ppp/pppservdown</filename> script
	to stop the server:</para>

	<programlisting>#!/bin/sh
	pgrep -l pppd
	pid=`pgrep pppd`
	if [ "X${pid}" != "X" ] ; then
	echo 'killing pppd, PID=' ${pid}
	kill ${pid}
	fi
	pgrep -l kermit
	pid=`pgrep kermit`
	if [ "X${pid}" != "X" ] ; then
	echo 'killing kermit, PID=' ${pid}
	kill -9 ${pid}
	fi
	ifconfig ppp0 down
	ifconfig ppp0 delete

	kermit -y /etc/ppp/kermit.noans</programlisting>

	<para>The following <application>Kermit</application> script
	(<filename>/etc/ppp/kermit.ans</filename>) will enable/disable
	autoanswer mode on your modem. It should look like
	this:</para>

	<programlisting>set line /dev/tty01
	set speed 19200
	set file type binary
	set file names literal
	set win 8
	set rec pack 1024
	set send pack 1024
	set block 3
	set term bytesize 8
	set command bytesize 8
	set flow none

	pau 1
	out +++
	inp 5 OK
	out ATH0\13
	inp 5 OK
	echo \13
	out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable
	; autoanswer mode
	inp 5 OK
	echo \13
	exit</programlisting>

	<para>A script named <filename>/etc/ppp/kermit.dial</filename>
	is used for dialing and authenticating on the remote host.
	You will need to customize it for your needs. Put your login
	and password in this script; you will also need to change the
	input statement depending on responses from your modem and
	remote host.</para>

	<programlisting>;
	; put the com line attached to the modem here:
	;
	set line /dev/tty01
	;
	; put the modem speed here:
	;
	set speed 19200
	set file type binary ; full 8 bit file xfer
	set file names literal
	set win 8
	set rec pack 1024
	set send pack 1024
	set block 3
	set term bytesize 8
	set command bytesize 8
	set flow none
	set modem hayes
	set dial hangup off
	set carrier auto ; Then SET CARRIER if necessary,
	set dial display on ; Then SET DIAL if necessary,
	set input echo on
	set input timeout proceed
	set input case ignore
	def \%x 0 ; login prompt counter
	goto slhup

	:slcmd ; put the modem in command mode
	echo Put the modem in command mode.
	clear ; Clear unread characters from input buffer
	pause 1
	output +++ ; hayes escape sequence
	input 1 OK\13\10 ; wait for OK
	if success goto slhup
	output \13
	pause 1
	output at\13
	input 1 OK\13\10
	if fail goto slcmd ; if modem doesn't answer OK, try again

	:slhup ; hang up the phone
	clear ; Clear unread characters from input buffer
	pause 1
	echo Hanging up the phone.
	output ath0\13 ; hayes command for on hook
	input 2 OK\13\10
	if fail goto slcmd ; if no OK answer, put modem in command mode

	:sldial ; dial the number
	pause 1
	echo Dialing.
	output atdt9,550311\13\10 ; put phone number here
	assign \%x 0 ; zero the time counter

	:look
	clear ; Clear unread characters from input buffer
	increment \%x ; Count the seconds
	input 1 {CONNECT }
	if success goto sllogin
	reinput 1 {NO CARRIER\13\10}
	if success goto sldial
	reinput 1 {NO DIALTONE\13\10}
	if success goto slnodial
	reinput 1 {\255}
	if success goto slhup
	reinput 1 {\127}
	if success goto slhup
	if < \%x 60 goto look
	else goto slhup

	:sllogin ; login
	assign \%x 0 ; zero the time counter
	pause 1
	echo Looking for login prompt.

	:slloop
	increment \%x ; Count the seconds
	clear ; Clear unread characters from input buffer
	output \13
	;
	; put your expected login prompt here:
	;
	input 1 {Username: }
	if success goto sluid
	reinput 1 {\255}
	if success goto slhup
	reinput 1 {\127}
	if success goto slhup
	if < \%x 10 goto slloop ; try 10 times to get a login prompt
	else goto slhup ; hang up and start again if 10 failures

	:sluid
	;
	; put your userid here:
	;
	output ppp-login\13
	input 1 {Password: }
	;
	; put your password here:
	;
	output ppp-password\13
	input 1 {Entering SLIP mode.}
	echo
	quit

	:slnodial
	echo \7No dialtone. Check the telephone line!\7
	exit 1

	; local variables:
	; mode: csh
	; comment-start: "; "
	; comment-start-skip: "; "
	; end:</programlisting>
	</sect2>
	</sect1>

	<sect1 id="ppp-troubleshoot">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<!-- 13 June 2003 -->
	</sect1info>
	<title>Troubleshooting <acronym>PPP</acronym> Connections</title>

	<indexterm>
	<primary>PPP</primary>
	<secondary>troubleshooting</secondary>
	</indexterm>
	-
	- <warning>
	- <para>As of &os; 8.0, the &man.uart.4; driver replaces the
	- &man.sio.4; driver. Device nodes for serial ports have been
	- renamed from
	- <filename>/dev/cuad<replaceable>N</replaceable></filename> to
	- <filename>/dev/cuau<replaceable>N</replaceable></filename> and
	- from
	- <filename>/dev/ttyd<replaceable>N</replaceable></filename> to
	- <filename>/dev/ttyu<replaceable>N</replaceable></filename>.
	- &os; 7.X users will have to adapt the following
	- documentation according to these changes.</para>
	- </warning>

	<para>This section covers a few issues which may arise when
	using PPP over a modem connection. For instance, perhaps you
	need to know exactly what prompts the system you are dialing
	into will present. Some <acronym>ISP</acronym>s present the
	<literal>ssword</literal> prompt, and others will present
	<literal>password</literal>; if the <command>ppp</command>
	script is not written accordingly, the login attempt will
	fail. The most common way to debug <command>ppp</command>
	connections is by connecting manually. The following
	information will walk you through a manual connection step by
	step.</para>

	<sect2>
	<title>Check the Device Nodes</title>

	<para>When using a custom kernel, make sure to include the
	following line in your kernel configuration file:</para>

	<programlisting>device uart</programlisting>

	<para>The <devicename>uart</devicename> device is already
	included in the <literal>GENERIC</literal> kernel, so no
	additional steps are necessary in this case. Just
	check the <command>dmesg</command> output for the modem
	device with:</para>

	<screen>&prompt.root; <userinput>dmesg \| grep uart</userinput></screen>

	<para>You should get some pertinent output about the
	<devicename>uart</devicename> devices. These are the COM
	ports we need. If your modem acts like a standard serial
	port then you should see it listed on
	<devicename>uart1</devicename>, or
	<devicename>COM2</devicename>. If so, you are not required
	to rebuild the kernel. When matching up sio modem is on
	<devicename>uart1</devicename> or
	<devicename>COM2</devicename> if you are in DOS, then your
	modem device would be <filename
	class="devicefile">/dev/cuau1</filename>.</para>
	</sect2>

	<sect2>
	<title>Connecting Manually</title>

	<para>Connecting to the Internet by manually controlling
	<command>ppp</command> is quick, easy, and a great way to
	debug a connection or just get information on how your
	<acronym>ISP</acronym> treats <command>ppp</command> client
	connections. Lets start <application>PPP</application> from
	the command line. Note that in all of our examples we will
	use <emphasis>example</emphasis> as the hostname of the
	machine running <application>PPP</application>. You start
	<command>ppp</command> by just typing
	<command>ppp</command>:</para>

	<screen>&prompt.root; <userinput>ppp</userinput></screen>

	<para>We have now started <command>ppp</command>.</para>

	<screen>ppp ON example> <userinput>set device <filename class="devicefile">/dev/cuau1</filename></userinput></screen>

	<para>We set our modem device, in this case it is
	<devicename>cuau1</devicename>.</para>

	<screen>ppp ON example> <userinput>set speed 115200</userinput></screen>

	<para>Set the connection speed, in this case we
	are using 115,200 <acronym>kbps</acronym>.</para>

	<screen>ppp ON example> <userinput>enable dns</userinput></screen>

	<para>Tell <command>ppp</command> to configure our
	resolver and add the nameserver lines to
	<filename>/etc/resolv.conf</filename>. If
	<command>ppp</command> cannot determine our hostname, we can
	set one manually later.</para>

	<screen>ppp ON example> <userinput>term</userinput></screen>

	<para>Switch to <quote>terminal</quote> mode so that we can
	manually control the modem.</para>

	<programlisting>deflink: Entering terminal mode on <filename class="devicefile">/dev/cuau1</filename>
	type '~h' for help</programlisting>

	<screen><userinput>at</userinput>
	OK
	<userinput>atdt<replaceable>123456789</replaceable></userinput></screen>

	<para>Use <command>at</command> to initialize the modem,
	then use <command>atdt</command> and the number for your
	<acronym>ISP</acronym> to begin the dial in process.</para>

	<screen>CONNECT</screen>

	<para>Confirmation of the connection, if we are going to have
	any connection problems, unrelated to hardware, here is where
	we will attempt to resolve them.</para>

	<screen>ISP Login:<userinput>myusername</userinput></screen>

	<para>Here you are prompted for a username, return the
	prompt with the username that was provided by the
	<acronym>ISP</acronym>.</para>

	<screen>ISP Pass:<userinput>mypassword</userinput></screen>

	<para>This time we are prompted for a password, just
	reply with the password that was provided by the
	<acronym>ISP</acronym>. Just like logging into
	&os;, the password will not echo.</para>

	<screen>Shell or PPP:<userinput>ppp</userinput></screen>

	<para>Depending on your <acronym>ISP</acronym> this prompt
	may never appear. Here we are being asked if we wish to
	use a shell on the provider, or to start
	<command>ppp</command>. In this example, we have chosen
	to use <command>ppp</command> as we want an Internet
	connection.</para>

	<screen>Ppp ON example></screen>

	<para>Notice that in this example the first <option>p</option>
	has been capitalized. This shows that we have successfully
	connected to the <acronym>ISP</acronym>.</para>

	<screen>PPp ON example></screen>

	<para>We have successfully authenticated with our
	<acronym>ISP</acronym> and are waiting for the
	assigned <acronym>IP</acronym> address.</para>

	<screen>PPP ON example></screen>

	<para>We have made an agreement on an <acronym>IP</acronym>
	address and successfully completed our connection.</para>

	<screen>PPP ON example><userinput>add default HISADDR</userinput></screen>

	<para>Here we add our default route, we need to do this before
	we can talk to the outside world as currently the only
	established connection is with the peer. If this fails due to
	existing routes you can put a bang character
	<literal>!</literal> in front of the <option>add</option>.
	Alternatively, you can set this before making the actual
	connection and it will negotiate a new route
	accordingly.</para>

	<para>If everything went good we should now have an active
	connection to the Internet, which could be thrown into the
	background using <keycombo
	action="simul"><keycap>CTRL</keycap>
	<keycap>z</keycap></keycombo> If you notice the
	<command>PPP</command> return to <command>ppp</command> then
	we have lost our connection. This is good to know because it
	shows our connection status. Capital P's show that we have a
	connection to the <acronym>ISP</acronym> and lowercase p's
	show that the connection has been lost for whatever reason.
	<command>ppp</command> only has these 2 states.</para>

	<sect3>
	<title>Debugging</title>

	<para>If you have a direct line and cannot seem to make a
	connection, then turn hardware flow
	<acronym>CTS/RTS</acronym> to off with the <option>set
	ctsrts off</option>. This is mainly the case if you are
	connected to some <application>PPP</application> capable
	terminal servers, where <application>PPP</application> hangs
	when it tries to write data to your communication link, so
	it would be waiting for a <acronym>CTS</acronym>, or Clear
	To Send signal which may never come. If you use this option
	however, you should also use the <option>set accmap</option>
	option, which may be required to defeat hardware dependent
	on passing certain characters from end to end, most of the
	time XON/XOFF. See the &man.ppp.8; manual page for more
	information on this option, and how it is used.</para>

	<para>If you have an older modem, you may need to use the
	<option>set parity even</option>. Parity is set at none
	be default, but is used for error checking (with a large
	increase in traffic) on older modems and some
	<acronym>ISP</acronym>s. You may need this option for
	the Compuserve <acronym>ISP</acronym>.</para>

	<para><application>PPP</application> may not return to the
	command mode, which is usually a negotiation error where
	the <acronym>ISP</acronym> is waiting for your side to start
	negotiating. At this point, using the <command>~p</command>
	command will force ppp to start sending the configuration
	information.</para>

	<para>If you never obtain a login prompt, then most likely you
	need to use <acronym>PAP</acronym> or
	<acronym>CHAP</acronym> authentication instead of the
	&unix; style in the example above. To use
	<acronym>PAP</acronym> or <acronym>CHAP</acronym> just add
	the following options to <application>PPP</application>
	before going into terminal mode:</para>

	<screen>ppp ON example> <userinput>set authname <replaceable>myusername</replaceable></userinput></screen>

	<para>Where <replaceable>myusername</replaceable> should be
	replaced with the username that was assigned by the
	<acronym>ISP</acronym>.</para>

	<screen>ppp ON example> <userinput>set authkey <replaceable>mypassword</replaceable></userinput></screen>

	<para>Where <replaceable>mypassword</replaceable> should be
	replaced with the password that was assigned by the
	<acronym>ISP</acronym>.</para>

	<para>If you connect fine, but cannot seem to find any domain
	name, try to use &man.ping.8; with an <acronym>IP</acronym>
	address and see if you can get any return information. If
	you experience 100 percent (100%) packet loss, then it is
	most likely that you were not assigned a default route.
	Double check that the option <option>add default
	HISADDR</option> was set during the connection. If you
	can connect to a remote <acronym>IP</acronym> address then
	it is possible that a resolver address has not been added
	to the <filename>/etc/resolv.conf</filename>. This file
	should look like:</para>

	<programlisting>domain <replaceable>example.com</replaceable>
	nameserver <replaceable>x.x.x.x</replaceable>
	nameserver <replaceable>y.y.y.y</replaceable></programlisting>

	<para>Where <replaceable>x.x.x.x</replaceable> and
	<replaceable>y.y.y.y</replaceable> should be replaced with
	the <acronym>IP</acronym> address of your
	<acronym>ISP</acronym>'s DNS servers. This information may
	or may not have been provided when you signed up, but a
	quick call to your <acronym>ISP</acronym> should remedy
	that.</para>

	<para>You could also have &man.syslog.3; provide a logging
	function for your <application>PPP</application> connection.
	Just add:</para>

	<programlisting>!ppp
	. /var/log/ppp.log</programlisting>

	<para>to <filename>/etc/syslog.conf</filename>. In most
	cases, this functionality already exists.</para>

	</sect3>
	</sect2>
	</sect1>




	<sect1 id="pppoe">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Jim</firstname>
	<surname>Mock</surname>
	<contrib>Contributed (from
	http://node.to/freebsd/how-tos/how-to-freebsd-pppoe.html)
	by </contrib>
	</author>
	</authorgroup>
	<!-- 10 Jan 2000 -->
	</sect1info>

	<title>Using PPP over Ethernet (PPPoE)</title>

	<indexterm>
	<primary>PPP</primary>
	<secondary>over Ethernet</secondary>
	</indexterm>

	<indexterm>
	<primary>PPPoE</primary>
	<see>PPP, over Ethernet</see>
	</indexterm>

	<para>This section describes how to set up PPP over Ethernet
	(<acronym>PPPoE</acronym>).</para>

	<sect2>
	<title>Configuring the Kernel</title>

	<para>No kernel configuration is necessary for PPPoE any longer.
	If the necessary netgraph support is not built into the
	kernel, it will be dynamically loaded by
	<application>ppp</application>.</para>
	</sect2>

	<sect2>
	<title>Setting Up <filename>ppp.conf</filename></title>

	<para>Here is an example of a working
	<filename>ppp.conf</filename>:</para>

	<programlisting>default:
	set log Phase tun command # you can add more detailed logging if you wish
	set ifaddr 10.0.0.1/0 10.0.0.2/0

	name_of_service_provider:
	set device PPPoE:<replaceable>xl1</replaceable> # replace xl1 with your Ethernet device
	set authname YOURLOGINNAME
	set authkey YOURPASSWORD
	set dial
	set login
	add default HISADDR</programlisting>

	</sect2>

	<sect2>
	<title>Running <application>ppp</application></title>

	<para>As <username>root</username>, you can run:</para>

	<screen>&prompt.root; <userinput>ppp -ddial name_of_service_provider</userinput></screen>

	</sect2>

	<sect2>
	<title>Starting <application>ppp</application> at Boot</title>

	<para>Add the following to your
	<filename>/etc/rc.conf</filename> file:</para>

	<programlisting>ppp_enable="YES"
	ppp_mode="ddial"
	ppp_nat="YES" # if you want to enable nat for your local network, otherwise NO
	ppp_profile="name_of_service_provider"</programlisting>
	</sect2>

	<sect2>
	<title>Using a PPPoE Service Tag</title>

	<para>Sometimes it will be necessary to use a service tag to
	establish your connection. Service tags are used to
	distinguish between different PPPoE servers attached to a
	given network.</para>

	<para>You should have been given any required service tag
	information in the documentation provided by your ISP. If
	you cannot locate it there, ask your ISP's tech support
	personnel.</para>

	<para>As a last resort, you could try the method suggested by
	the <ulink url="http://www.roaringpenguin.com/pppoe/">Roaring
	Penguin PPPoE</ulink> program which can be found in the <link
	linkend="ports">Ports Collection</link>. Bear in mind
	however, this may de-program your modem and render it useless,
	so think twice before doing it. Simply install the program
	shipped with the modem by your provider. Then, access the
	<guimenu>System</guimenu> menu from the program. The name
	of your profile should be listed there. It is usually
	<emphasis>ISP</emphasis>.</para>

	<para>The profile name (service tag) will be used in the PPPoE
	configuration entry in <filename>ppp.conf</filename> as the
	provider part of the <command>set device</command> command
	(see the &man.ppp.8; manual page for full details). It should
	look like this:</para>

	<programlisting>set device PPPoE:<replaceable>xl1</replaceable>:<replaceable>ISP</replaceable></programlisting>

	<para>Do not forget to change <replaceable>xl1</replaceable>
	to the proper device for your Ethernet card.</para>
	<para>Do not forget to change <replaceable>ISP</replaceable>
	to the profile you have just found above.</para>

	<para>For additional information, see:</para>

	<itemizedlist>
	<listitem>
	<para><ulink
	url="http://renaud.waldura.com/doc/freebsd/pppoe/">Cheaper
	Broadband with FreeBSD on DSL</ulink> by Renaud
	Waldura.</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2 id="ppp-3com">

	<title>PPPoE with a &tm.3com;
	<trademark class="registered">HomeConnect</trademark> ADSL
	Modem Dual Link</title>

	<para>This modem does not follow <ulink
	url="http://www.faqs.org/rfcs/rfc2516.html">RFC 2516</ulink>
	(<emphasis>A Method for transmitting PPP over Ethernet
	(PPPoE)</emphasis>, written by L. Mamakos, K. Lidl, J. Evarts,
	D. Carrel, D. Simone, and R. Wheeler). Instead, different
	packet type codes have been used for the Ethernet frames.
	Please complain to <ulink
	url="http://www.3com.com/">3Com</ulink> if you think it
	should comply with the PPPoE specification.</para>

	<para>In order to make FreeBSD capable of communicating with
	this device, a sysctl must be set. This can be done
	automatically at boot time by updating
	<filename>/etc/sysctl.conf</filename>:</para>

	<programlisting>net.graph.nonstandard_pppoe=1</programlisting>

	<para>or can be done immediately with the command:</para>

	<screen>&prompt.root; <userinput>sysctl net.graph.nonstandard_pppoe=1</userinput></screen>

	<para>Unfortunately, because this is a system-wide setting,
	it is not possible to talk to a normal PPPoE client or server
	and a &tm.3com; <trademark
	class="registered">HomeConnect</trademark> ADSL Modem at
	the same time.</para>

	</sect2>
	</sect1>

	<sect1 id="pppoa">
	<title>Using <application>PPP</application> over ATM
	(PPPoA)</title>

	<indexterm>
	<primary>PPP</primary>
	<secondary>over ATM</secondary>
	</indexterm>

	<indexterm>
	<primary>PPPoA</primary>
	<see>PPP, over ATM</see>
	</indexterm>

	<para>The following describes how to set up PPP over ATM (PPPoA).
	PPPoA is a popular choice among European DSL providers.</para>

	<sect2>
	<title>Using PPPoA with the Alcatel &speedtouch; USB</title>

	<para>PPPoA support for this device is supplied as a port in
	FreeBSD because the firmware is distributed under <ulink
	url="http://www.speedtouchdsl.com/disclaimer_lx.htm">Alcatel's
	license agreement</ulink> and can not be redistributed freely
	with the base system of FreeBSD.</para>

	<para>To install the software, simply use the <link
	linkend="ports">Ports Collection</link>. Install the
	<filename role="package">net/pppoa</filename> port and follow
	the instructions provided with it.</para>

	<para>Like many USB devices, the Alcatel &speedtouch; USB needs
	to download firmware from the host computer to operate
	properly. It is possible to automate this process in &os;
	so that this transfer takes place whenever the device is
	plugged into a USB port. The following information can be
	added to the <filename>/etc/usbd.conf</filename> file to
	enable this automatic firmware transfer. This file must be
	edited as the <username>root</username> user.</para>

	<programlisting>device "Alcatel SpeedTouch USB"
	devname "ugen[0-9]+"
	vendor 0x06b9
	product 0x4061
	attach "/usr/local/sbin/modem_run -f /usr/local/libdata/mgmt.o"</programlisting>

	<para>To enable the USB daemon, <application>usbd</application>,
	put the following the line into
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>usbd_enable="YES"</programlisting>

	<para>It is also possible to set up
	<application>ppp</application> to dial up at startup. To do
	this add the following lines to
	<filename>/etc/rc.conf</filename>. Again, for this procedure
	you will need to be logged in as the <username>root</username>
	user.</para>

	<programlisting>ppp_enable="YES"
	ppp_mode="ddial"
	ppp_profile="adsl"</programlisting>

	<para>For this to work correctly you will need to have used the
	sample <filename>ppp.conf</filename> which is supplied with
	the <filename role="package">net/pppoa</filename> port.</para>

	</sect2>

	<sect2>
	<title>Using mpd</title>

	<para>You can use <application>mpd</application> to connect to a
	variety of services, in particular PPTP services. You can
	find <application>mpd</application> in the Ports Collection,
	<filename role="package">net/mpd</filename>. Many ADSL modems
	require that a PPTP tunnel is created between the modem and
	computer, one such modem is the Alcatel &speedtouch;
	Home.</para>

	<para>First you must install the port, and then you can
	configure <application>mpd</application> to suit your
	requirements and provider settings. The port places a set
	of sample configuration files which are well documented in
	<filename
	class="directory"><replaceable>PREFIX</replaceable>/etc/mpd/</filename>.
	Note here that <replaceable>PREFIX</replaceable> means the
	directory into which your ports are installed, this defaults
	to <filename class="directory">/usr/local/</filename>. A
	complete guide to configure <application>mpd</application>
	is available in HTML format once the port has been installed.
	It is placed in <filename
	class="directory"><replaceable>PREFIX</replaceable>/share/doc/mpd/</filename>.
	Here is a sample configuration for connecting to an ADSL
	service with <application>mpd</application>. The configuration
	is spread over two files, first the
	<filename>mpd.conf</filename>:</para>

	<note>
	<para>This example of the <filename>mpd.conf</filename> file
	only works with <application>mpd</application> 4.x.</para>
	</note>

	<programlisting>default:
	load adsl

	adsl:
	new -i ng0 adsl adsl
	set bundle authname <replaceable>username</replaceable> <co
	id="co-mpd-ex-user"/>
	set bundle password <replaceable>password</replaceable> <co
	id="co-mpd-ex-pass"/>
	set bundle disable multilink

	set link no pap acfcomp protocomp
	set link disable chap
	set link accept chap
	set link keep-alive 30 10

	set ipcp no vjcomp
	set ipcp ranges 0.0.0.0/0 0.0.0.0/0

	set iface route default
	set iface disable on-demand
	set iface enable proxy-arp
	set iface idle 0

	open</programlisting>

	<calloutlist>
	<callout arearefs="co-mpd-ex-user">
	<para>The username used to authenticate with your ISP.</para>
	</callout>
	<callout arearefs="co-mpd-ex-pass">
	<para>The password used to authenticate with your ISP.</para>
	</callout>
	</calloutlist>

	<para>The <filename>mpd.links</filename> file contains information
	about the link, or links, you wish to establish. An example
	<filename>mpd.links</filename> to accompany the above example
	is given beneath:</para>

	<programlisting>adsl:
	set link type pptp
	set pptp mode active
	set pptp enable originate outcall
	set pptp self <replaceable>10.0.0.1</replaceable> <co
	id="co-mpd-ex-self"/>
	set pptp peer <replaceable>10.0.0.138</replaceable> <co
	id="co-mpd-ex-peer"/></programlisting>

	<calloutlist>
	<callout arearefs="co-mpd-ex-self">
	<para>The IP address of your &os; computer which you will be
	using <application>mpd</application> from.</para>
	</callout>
	<callout arearefs="co-mpd-ex-peer">
	<para>The IP address of your ADSL modem. For the Alcatel
	&speedtouch; Home this address defaults to <hostid
	role="ipaddr">10.0.0.138</hostid>.</para>
	</callout>
	</calloutlist>

	<para>It is possible to initialize the connection easily by
	issuing the following command as
	<username>root</username>:</para>

	<screen>&prompt.root; <userinput>mpd -b <replaceable>adsl</replaceable></userinput></screen>

	<para>You can see the status of the connection with the following
	command:</para>

	<screen>&prompt.user; <userinput>ifconfig <replaceable>ng0</replaceable></userinput>
	ng0: flags=88d1<UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST> mtu 1500
	inet 216.136.204.117 --> 204.152.186.171 netmask 0xffffffff</screen>

	<para>Using <application>mpd</application> is the recommended
	way to connect to an ADSL service with &os;.</para>

	</sect2>

	<sect2>
	<title>Using pptpclient</title>

	<para>It is also possible to use FreeBSD to connect to other
	PPPoA services using <filename
	role="package">net/pptpclient</filename>.</para>

	<para>To use <filename role="package">net/pptpclient</filename>
	to connect to a DSL service, install the port or package and
	edit your <filename>/etc/ppp/ppp.conf</filename>. You will
	need to be <username>root</username> to perform both of these
	operations. An example section of <filename>ppp.conf</filename>
	is given below. For further information on
	<filename>ppp.conf</filename> options consult the
	<application>ppp</application> manual page, &man.ppp.8;.</para>

	<programlisting>adsl:
	set log phase chat lcp ipcp ccp tun command
	set timeout 0
	enable dns
	set authname <replaceable>username</replaceable> <co id="co-pptp-ex-user"/>
	set authkey <replaceable>password</replaceable> <co id="co-pptp-ex-pass"/>
	set ifaddr 0 0
	add default HISADDR</programlisting>

	<calloutlist>
	<callout arearefs="co-pptp-ex-user">
	<para>The username of your account with the DSL
	provider.</para>
	</callout>

	<callout arearefs="co-pptp-ex-pass">
	<para>The password for your account.</para>
	</callout>
	</calloutlist>

	<warning>
	<para>Because you must put your account's password in the
	<filename>ppp.conf</filename> file in plain text form you
	should make sure than nobody can read the contents of this
	file. The following series of commands will make sure the
	file is only readable by the <username>root</username>
	account. Refer to the manual pages for &man.chmod.1; and
	&man.chown.8; for further information.</para>

	<screen>&prompt.root; <userinput>chown root:wheel /etc/ppp/ppp.conf</userinput>
	&prompt.root; <userinput>chmod 600 /etc/ppp/ppp.conf</userinput></screen>

	</warning>

	<para>This will open a tunnel for a PPP session to your DSL
	router. Ethernet DSL modems have a preconfigured LAN IP
	address which you connect to. In the case of the Alcatel
	&speedtouch; Home this address is <hostid
	role="ipaddr">10.0.0.138</hostid>. Your router
	documentation should tell you which address your device
	uses. To open the tunnel and start a PPP session execute
	the following command:</para>

	<screen>&prompt.root; <userinput>pptp <replaceable>address</replaceable> <replaceable>adsl</replaceable></userinput></screen>

	<tip>
	<para>You may wish to add an ampersand (<quote>&</quote>)
	to the end of the previous command because
	<application>pptp</application> will not return your prompt
	to you otherwise.</para>
	</tip>

	<para>A <devicename>tun</devicename> virtual tunnel device
	will be created for interaction between the
	<application>pptp</application> and
	<application>ppp</application> processes. Once you have been
	returned to your prompt, or the
	<application>pptp</application> process has confirmed a
	connection you can examine the tunnel like so:</para>

	<screen>&prompt.user; <userinput>ifconfig <replaceable>tun0</replaceable></userinput>
	tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
	inet 216.136.204.21 --> 204.152.186.171 netmask 0xffffff00
	Opened by PID 918</screen>

	<para>If you are unable to connect, check the configuration of
	your router, which is usually accessible via
	<application>telnet</application> or with a web browser. If
	you still cannot connect you should examine the output of the
	<command>pptp</command> command and the contents of the
	<application>ppp</application> log file,
	<filename>/var/log/ppp.log</filename> for clues.</para>
	</sect2>
	</sect1>

	<sect1 id="slip">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Satoshi</firstname>
	<surname>Asami</surname>
	<contrib>Originally contributed by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Guy</firstname>
	<surname>Helmer</surname>
	<contrib>With input from </contrib>
	</author>
	<author>
	<firstname>Piero</firstname>
	<surname>Serini</surname>
	</author>
	</authorgroup>
	</sect1info>

	<title>Using SLIP</title>

	<indexterm><primary>SLIP</primary></indexterm>

	<warning>
	<para>This section applies and is valid only for
	&os; 7.X.</para>
	</warning>

	<sect2 id="slipc">
	<title>Setting Up a SLIP Client</title>

	<indexterm>
	<primary>SLIP</primary>
	<secondary>client</secondary>
	</indexterm>

	<para>The following is one way to set up a FreeBSD machine for
	SLIP on a static host network. For dynamic hostname
	assignments (your address changes each time you dial up), you
	probably need to have a more complex setup.</para>

	<para>First, determine which serial port your modem is connected
	to. Many people set up a symbolic link, such as
	<filename class="devicefile">/dev/modem</filename>, to point
	to the real device name, <filename
	class="devicefile">/dev/cuad<replaceable>N</replaceable></filename>.
	This allows you to abstract the actual device name should you
	ever need to move the modem to a different port. It can
	become quite cumbersome when you need to fix a bunch of files
	in <filename class="directory">/etc</filename> and
	<filename>.kermrc</filename> files all over the system!</para>

	<note>
	<para><filename class="devicefile">/dev/cuad0</filename>
	is <devicename>COM1</devicename>, <filename
	class="devicefile">/dev/cuad1</filename> is
	<devicename>COM2</devicename>, etc.</para>
	</note>

	<para>Make sure you have the following in your kernel
	configuration file:</para>

	<programlisting>device sl</programlisting>

	<para>It is included in the <filename>GENERIC</filename> kernel,
	so this should not be a problem unless you have deleted
	it.</para>

	<sect3>
	<title>Things You Have to Do Only Once</title>

	<procedure>
	<step>
	<para>Add your home machine, the gateway and nameservers
	to your <filename>/etc/hosts</filename> file. Ours
	looks like this:</para>

	<programlisting>127.0.0.1 localhost loghost
	136.152.64.181 water.CS.Example.EDU water.CS water
	136.152.64.1 inr-3.CS.Example.EDU inr-3 slip-gateway
	128.32.136.9 ns1.Example.EDU ns1
	128.32.136.12 ns2.Example.EDU ns2</programlisting>
	</step>

	<step>
	<para>Make sure you have <literal>files</literal> before
	<literal>dns</literal> in the <literal>hosts:</literal>
	section of your <filename>/etc/nsswitch.conf</filename>
	file. Without these parameters funny things may
	happen.</para>
	</step>

	<step>
	<para>Edit the <filename>/etc/rc.conf</filename>
	file.</para>

	<orderedlist>
	<listitem>
	<para>Set your hostname by editing the line that
	says:</para>

	<programlisting>hostname="myname.my.domain"</programlisting>

	<para>Your machine's full Internet hostname should be
	placed here.</para>
	</listitem>

	<listitem>
	<indexterm><primary>default
	route</primary></indexterm>

	<para>Designate the default router by changing the
	line:</para>

	<programlisting>defaultrouter="NO"</programlisting>

	<para>to:</para>

	<programlisting>defaultrouter="slip-gateway"</programlisting>
	</listitem>
	</orderedlist>
	</step>

	<step>
	<para>Make a file <filename>/etc/resolv.conf</filename>
	which contains:</para>

	<programlisting>domain CS.Example.EDU
	nameserver 128.32.136.9
	nameserver 128.32.136.12</programlisting>

	<indexterm><primary>nameserver</primary></indexterm>
	<indexterm><primary>domain name</primary></indexterm>
	<para>As you can see, these set up the nameserver hosts.
	Of course, the actual domain names and addresses depend
	on your environment.</para>
	</step>

	<step>
	<para>Set the password for <username>root</username> and
	<username>toor</username> (and any other
	accounts that do not have a password).</para>
	</step>

	<step>
	<para>Reboot your machine and make sure it comes up with
	the correct hostname.</para>
	</step>
	</procedure>
	</sect3>

	<sect3>
	<title>Making a SLIP Connection</title>

	<indexterm>
	<primary>SLIP</primary>
	<secondary>connecting with</secondary>
	</indexterm>

	<procedure>
	<step>
	<para>Dial up, type <command>slip</command> at the prompt,
	enter your machine name and password. What is required
	to be entered depends on your environment. If you use
	<application>Kermit</application>, you can try a script
	like this:</para>

	<programlisting># kermit setup
	set modem hayes
	set line /dev/modem
	set speed 115200
	set parity none
	set flow rts/cts
	set terminal bytesize 8
	set file type binary
	# The next macro will dial up and login
	define slip dial 643-9600, input 10 =>, if failure stop, -
	output slip\x0d, input 10 Username:, if failure stop, -
	output silvia\x0d, input 10 Password:, if failure stop, -
	output ***\x0d, echo \x0aCONNECTED\x0a</programlisting>

	<para>Of course, you have to change the username and
	password to fit yours. After doing so, you can just
	type <command>slip</command> from the
	<application>Kermit</application> prompt to
	connect.</para>

	<note>
	<para>Leaving your password in plain text anywhere in
	the filesystem is generally a <emphasis>bad</emphasis>
	idea. Do it at your own risk.</para>
	</note>
	</step>

	<step>
	<para>Leave the <application>Kermit</application> there
	(you can suspend it by
	<keycombo>
	<keycap>Ctrl</keycap>
	<keycap>z</keycap>
	</keycombo>) and as <username>root</username>,
	type:</para>

	<screen>&prompt.root; <userinput>slattach -h -c -s 115200 /dev/modem</userinput></screen>

	<para>If you are able to <command>ping</command> hosts
	on the other side of the router, you are connected!
	If it does not work, you might want to try
	<option>-a</option> instead of <option>-c</option> as
	an argument to <command>slattach</command>.</para>
	</step>
	</procedure>
	</sect3>

	<sect3>
	<title>How to Shutdown the Connection</title>

	<para>Do the following:</para>

	<screen>&prompt.root; <userinput>kill -INT `cat /var/run/slattach.modem.pid`</userinput></screen>

	<para>to kill <command>slattach</command>. Keep in mind you
	must be <username>root</username> to do the above. Then
	go back to <command>kermit</command> (by running
	<command>fg</command> if you suspended it) and exit from
	it (<keycap>q</keycap>).</para>

	<para>The &man.slattach.8; manual page says you have to use
	<command>ifconfig sl0 down</command> to mark the interface
	down, but this does not seem to make any difference.
	(<command>ifconfig sl0</command> reports the same
	thing.)</para>

	<para>Some times, your modem might refuse to drop the carrier.
	In that case, simply start <command>kermit</command> and
	quit it again. It usually goes out on the second
	try.</para>
	</sect3>

	<sect3>
	<title>Troubleshooting</title>

	<para>If it does not work, feel free to ask on &a.net.name;
	mailing list. The things that people tripped over so
	far:</para>

	<itemizedlist>
	<listitem>
	<para>Not using <option>-c</option> or <option>-a</option>
	in <command>slattach</command> (This should not be
	fatal, but some users have reported that this solves
	their problems.)</para>
	</listitem>

	<listitem>
	<para>Using <option>s10</option> instead of
	<option>sl0</option> (might be hard to see the
	difference on some fonts).</para>
	</listitem>

	<listitem>
	<para>Try <command>ifconfig sl0</command> to see your
	interface status. For example, you might get:</para>

	<screen>&prompt.root; <userinput>ifconfig sl0</userinput>
	sl0: flags=10<POINTOPOINT>
	inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00</screen>
	</listitem>

	<listitem>
	<para>If you get <errorname>no route to host</errorname>
	messages from &man.ping.8;, there may be a problem
	with your routing table. You can use the
	<command>netstat -r</command> command to display the
	current routes :</para>

	<screen>&prompt.root; <userinput>netstat -r</userinput>
	Routing tables
	Destination Gateway Flags Refs Use IfaceMTU Rtt Netmasks:

	(root node)
	(root node)

	Route Tree for Protocol Family inet:
	(root node) =>
	default inr-3.Example.EDU UG 8 224515 sl0 - -
	localhost.Exampl localhost.Example. UH 5 42127 lo0 - 0.438
	inr-3.Example.ED water.CS.Example.E UH 1 0 sl0 - -
	water.CS.Example localhost.Example. UGH 34 47641234 lo0 - 0.438
	(root node)</screen>

	<para>The preceding examples are from a relatively busy
	system. The numbers on your system will vary depending
	on network activity.</para>

	</listitem>
	</itemizedlist>
	</sect3>
	</sect2>

	<sect2 id="slips">
	<title>Setting Up a SLIP Server</title>

	<indexterm>
	<primary>SLIP</primary>
	<secondary>server</secondary>
	</indexterm>

	<para>This document provides suggestions for setting up SLIP
	Server services on a FreeBSD system, which typically means
	configuring your system to automatically start up connections
	upon login for remote SLIP clients.</para>

	<!-- Disclaimer is not necessarily relevant
	<para> The author has written this document based
	on his experience; however, as your system and needs may be
	different, this document may not answer all of your questions, and
	the author cannot be responsible if you damage your system or lose
	data due to attempting to follow the suggestions here.</para>
	-->

	<sect3 id="slips-prereqs">
	<title>Prerequisites</title>

	<indexterm><primary>TCP/IP networking</primary></indexterm>
	<para>This section is very technical in nature, so background
	knowledge is required. It is assumed that you are familiar
	with the TCP/IP network protocol, and in particular, network
	and node addressing, network address masks, subnetting,
	routing, and routing protocols, such as RIP. Configuring
	SLIP services on a dial-up server requires a knowledge of
	these concepts, and if you are not familiar with them,
	please read a copy of either Craig Hunt's <emphasis>TCP/IP
	Network Administration</emphasis> published by O'Reilly
	& Associates, Inc. (ISBN Number 0-937175-82-X), or
	Douglas Comer's books on the TCP/IP protocol.</para>

	<indexterm><primary>modem</primary></indexterm>
	<para>It is further assumed that you have already set up your
	modem(s) and configured the appropriate system files to
	allow logins through your modems. If you have not prepared
	your system for this yet, please see <xref
	linkend="dialup"/> for details on dialup services
	configuration. You may also want to check the manual pages
	or &man.sio.4; for information on the serial port device
	driver and &man.ttys.5;, &man.gettytab.5;, &man.getty.8;,
	& &man.init.8; for information relevant to configuring
	the system to accept logins on modems, and perhaps
	&man.stty.1; for information on setting serial port
	parameters (such as <literal>clocal</literal> for
	directly-connected serial interfaces).</para>
	</sect3>

	<sect3>
	<title>Quick Overview</title>

	<para>In its typical configuration, using FreeBSD as a SLIP
	server works as follows: a SLIP user dials up your FreeBSD
	SLIP Server system and logs in with a special SLIP login
	ID that uses <filename>/usr/sbin/sliplogin</filename> as
	the special user's shell. The <command>sliplogin</command>
	program browses the file
	<filename>/etc/sliphome/slip.hosts</filename> to find a
	matching line for the special user, and if it finds a match,
	connects the serial line to an available SLIP interface and
	then runs the shell script
	<filename>/etc/sliphome/slip.login</filename> to configure
	the SLIP interface.</para>

	<sect4>
	<title>An Example of a SLIP Server Login</title>

	<para>For example, if a SLIP user ID were
	<username>Shelmerg</username>,
	<username>Shelmerg</username>'s entry in
	<filename>/etc/master.passwd</filename> would look
	something like this:</para>

	<programlisting>Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliplogin</programlisting>

	<para>When <username>Shelmerg</username> logs in,
	<command>sliplogin</command> will search
	<filename>/etc/sliphome/slip.hosts</filename> for a line
	that had a matching user ID; for example, there may be
	a line in <filename>/etc/sliphome/slip.hosts</filename>
	that reads:</para>

	<programlisting>Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp</programlisting>

	<para><command>sliplogin</command> will find that matching
	line, hook the serial line into the next available SLIP
	interface, and then execute
	<filename>/etc/sliphome/slip.login</filename> like
	this:</para>

	<programlisting>/etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp</programlisting>

	<para>If all goes well,
	<filename>/etc/sliphome/slip.login</filename> will issue
	an <command>ifconfig</command> for the SLIP interface to
	which <command>sliplogin</command> attached itself (SLIP
	interface 0, in the above example, which was the first
	parameter in the list given to
	<filename>slip.login</filename>) to set the local IP
	address (<hostid>dc-slip</hostid>), remote IP address
	(<hostid>sl-helmer</hostid>), network mask for the SLIP
	interface (<hostid role="netmask">0xfffffc00</hostid>),
	and any additional flags (<literal>autocomp</literal>).
	If something goes wrong, <command>sliplogin</command>
	usually logs good informational messages via the
	<application>syslogd</application> daemon facility, which
	usually logs to <filename>/var/log/messages</filename>
	(see the manual pages for &man.syslogd.8; and
	&man.syslog.conf.5; and perhaps check
	<filename>/etc/syslog.conf</filename> to see to what
	<application>syslogd</application> is logging and where
	it is logging to).</para>
	</sect4>
	</sect3>

	<sect3>
	<title>Kernel Configuration</title>

	<indexterm>
	<primary>kernel</primary>
	<secondary>configuration</secondary>
	</indexterm>

	<indexterm>
	<primary>SLIP</primary>
	</indexterm>

	<para>&os;'s default kernel (<filename>GENERIC</filename>)
	comes with SLIP (&man.sl.4;) support; in case of a custom
	kernel, you have to add the following line to your kernel
	configuration file:</para>

	<programlisting>device sl</programlisting>

	<para>By default, your &os; machine will not forward packets.
	If you want your FreeBSD SLIP Server to act as a router, you
	will have to edit the <filename>/etc/rc.conf</filename>
	file and change the setting of the
	<literal>gateway_enable</literal> variable to
	<option>YES</option>. This will make sure that setting the
	routing option will be persistent after a reboot.</para>

	<para>To apply the settings immediately you can execute the
	following command as <username>root</username>:</para>

	<screen>&prompt.root; service routing start</screen>

	<para>Please refer to <xref linkend="kernelconfig"/> on
	Configuring the FreeBSD Kernel for help in
	reconfiguring your kernel.</para>
	</sect3>

	<sect3>
	<title>Sliplogin Configuration</title>

	<para>As mentioned earlier, there are three files in the
	<filename class="directory">/etc/sliphome</filename>
	directory that are part of the configuration for
	<filename>/usr/sbin/sliplogin</filename> (see
	&man.sliplogin.8; for the actual manual page for
	<command>sliplogin</command>):
	<filename>slip.hosts</filename>, which defines the SLIP
	users and their associated IP addresses;
	<filename>slip.login</filename>, which usually just
	configures the SLIP interface; and (optionally)
	<filename>slip.logout</filename>, which undoes
	<filename>slip.login</filename>'s effects when the serial
	connection is terminated.</para>

	<sect4>
	<title><filename>slip.hosts</filename> Configuration</title>

	<para><filename>/etc/sliphome/slip.hosts</filename> contains
	lines which have at least four items separated by
	whitespace:</para>

	<itemizedlist>
	<listitem>
	<para>SLIP user's login ID</para>
	</listitem>

	<listitem>
	<para>Local address (local to the SLIP server) of the
	SLIP link</para>
	</listitem>

	<listitem>
	<para>Remote address of the SLIP link</para>
	</listitem>

	<listitem>
	<para>Network mask</para>
	</listitem>
	</itemizedlist>

	<para>The local and remote addresses may be host names
	(resolved to IP addresses by
	<filename>/etc/hosts</filename> or by the domain name
	service, depending on your specifications in the file
	<filename>/etc/nsswitch.conf</filename>), and the network
	mask may be a name that can be resolved by a lookup into
	<filename>/etc/networks</filename>. On a sample system,
	<filename>/etc/sliphome/slip.hosts</filename> looks like
	this:</para>

	<programlisting>#
	# login local-addr remote-addr mask opt1 opt2
	# (normal,compress,noicmp)
	#
	Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp</programlisting>

	<para>At the end of the line is one or more of the
	options:</para>

	<itemizedlist>
	<listitem>
	<para><option>normal</option> — no header
	compression</para>
	</listitem>

	<listitem>
	<para><option>compress</option> — compress
	headers</para>
	</listitem>

	<listitem>
	<para><option>autocomp</option> — compress headers
	if the remote end allows it</para>
	</listitem>

	<listitem>
	<para><option>noicmp</option> — disable ICMP
	packets (so any <quote>ping</quote> packets will be
	dropped instead of using up your bandwidth)</para>
	</listitem>
	</itemizedlist>

	<indexterm><primary>SLIP</primary></indexterm>
	<indexterm><primary>TCP/IP networking</primary></indexterm>
	<para>Your choice of local and remote addresses for your
	SLIP links depends on whether you are going to dedicate
	a TCP/IP subnet or if you are going to use <quote>proxy
	ARP</quote> on your SLIP server (it is not
	<quote>true</quote> proxy ARP, but that is the terminology
	used in this section to describe it). If you are not sure
	which method to select or how to assign IP addresses,
	please refer to the TCP/IP books referenced in the SLIP
	Prerequisites (<xref linkend="slips-prereqs"/>) and/or
	consult your IP network manager.</para>

	<para>If you are going to use a separate subnet for your
	SLIP clients, you will need to allocate the subnet number
	out of your assigned IP network number and assign each
	of your SLIP client's IP numbers out of that subnet.
	Then, you will probably need to configure a static route
	to the SLIP subnet via your SLIP server on your nearest
	IP router.</para>

	<indexterm><primary>Ethernet</primary></indexterm>
	<para>Otherwise, if you will use the <quote>proxy
	ARP</quote> method, you will need to assign your SLIP
	client's IP addresses out of your SLIP server's Ethernet
	subnet, and you will also need to adjust your
	<filename>/etc/sliphome/slip.login</filename> and
	<filename>/etc/sliphome/slip.logout</filename> scripts
	to use &man.arp.8; to manage the <quote>proxy ARP</quote>
	entries in the SLIP server's ARP table.</para>
	</sect4>

	<sect4>
	<title><filename>slip.login</filename> Configuration</title>

	<para>The typical
	<filename>/etc/sliphome/slip.login</filename> file looks
	like this:</para>

	<programlisting>#!/bin/sh -
	#
	# @(#)slip.login 5.1 (Berkeley) 7/1/90

	#
	# generic login file for a slip line. sliplogin invokes this with
	# the parameters:
	# 1 2 3 4 5 6 7-n
	# slipunit ttyspeed loginname local-addr remote-addr mask opt-args
	#
	/sbin/ifconfig sl$1 inet $4 $5 netmask $6</programlisting>

	<para>This <filename>slip.login</filename> file merely runs
	<command>ifconfig</command> for the appropriate SLIP
	interface with the local and remote addresses and network
	mask of the SLIP interface.</para>

	<para>If you have decided to use the <quote>proxy
	ARP</quote> method (instead of using a separate subnet
	for your SLIP clients), your
	<filename>/etc/sliphome/slip.login</filename> file will
	need to look something like this:</para>

	<programlisting>#!/bin/sh -
	#
	# @(#)slip.login 5.1 (Berkeley) 7/1/90

	#
	# generic login file for a slip line. sliplogin invokes this with
	# the parameters:
	# 1 2 3 4 5 6 7-n
	# slipunit ttyspeed loginname local-addr remote-addr mask opt-args
	#
	/sbin/ifconfig sl$1 inet $4 $5 netmask $6
	# Answer ARP requests for the SLIP client with our Ethernet addr
	/usr/sbin/arp -s $5 00:11:22:33:44:55 pub</programlisting>

	<para>The additional line in this
	<filename>slip.login</filename>, <command>arp -s
	$5 00:11:22:33:44:55 pub</command>, creates an ARP
	entry in the SLIP server's ARP table. This ARP entry
	causes the SLIP server to respond with the SLIP server's
	Ethernet MAC address whenever another IP node on the
	Ethernet asks to speak to the SLIP client's IP
	address.</para>

	<indexterm>
	<primary>Ethernet</primary>
	<secondary>MAC address</secondary>
	</indexterm>

	<para>When using the example above, be sure to replace the
	Ethernet MAC address (<hostid
	role="mac">00:11:22:33:44:55</hostid>) with the MAC
	address of your system's Ethernet card, or your
	<quote>proxy ARP</quote> will definitely not work! You
	can discover your SLIP server's Ethernet MAC address by
	looking at the results of running <command>netstat
	-i</command>; the second line of the output should look
	something like:</para>

	<screen>ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116</screen>

	<para>This indicates that this particular system's Ethernet
	MAC address is <hostid
	role="mac">00:02:c1:28:5f:4a</hostid> — the
	periods in the Ethernet MAC address given by
	<command>netstat -i</command> must be changed to colons
	and leading zeros should be added to each single-digit
	hexadecimal number to convert the address into the form
	that &man.arp.8; desires; see the manual page on
	&man.arp.8; for complete information on usage.</para>

	<note>
	<para>When you create
	<filename>/etc/sliphome/slip.login</filename> and
	<filename>/etc/sliphome/slip.logout</filename>, the
	<quote>execute</quote> bit (i.e., <command>chmod 755
	/etc/sliphome/slip.login
	/etc/sliphome/slip.logout</command>) must be set, or
	<command>sliplogin</command> will be unable to execute
	it.</para>
	</note>
	</sect4>

	<sect4>
	<title><filename>slip.logout</filename>
	Configuration</title>

	<para><filename>/etc/sliphome/slip.logout</filename> is not
	strictly needed (unless you are implementing <quote>proxy
	ARP</quote>), but if you decide to create it, this is an
	example of a basic
	<filename>slip.logout</filename> script:</para>

	<programlisting>#!/bin/sh -
	#
	# slip.logout

	#
	# logout file for a slip line. sliplogin invokes this with
	# the parameters:
	# 1 2 3 4 5 6 7-n
	# slipunit ttyspeed loginname local-addr remote-addr mask opt-args
	#
	/sbin/ifconfig sl$1 down</programlisting>

	<para>If you are using <quote>proxy ARP</quote>, you will
	want to have
	<filename>/etc/sliphome/slip.logout</filename> remove the
	ARP entry for the SLIP client:</para>

	<programlisting>#!/bin/sh -
	#
	# @(#)slip.logout

	#
	# logout file for a slip line. sliplogin invokes this with
	# the parameters:
	# 1 2 3 4 5 6 7-n
	# slipunit ttyspeed loginname local-addr remote-addr mask opt-args
	#
	/sbin/ifconfig sl$1 down
	# Quit answering ARP requests for the SLIP client
	/usr/sbin/arp -d $5</programlisting>

	<para>The <command>arp -d $5</command> removes the ARP
	entry that the <quote>proxy ARP</quote>
	<filename>slip.login</filename> added when the SLIP client
	logged in.</para>

	<para>It bears repeating: make sure
	<filename>/etc/sliphome/slip.logout</filename> has the
	execute bit set after you create it (i.e., <command>chmod
	755 /etc/sliphome/slip.logout</command>).</para>
	</sect4>
	</sect3>

	<sect3>
	<title>Routing Considerations</title>

	<indexterm>
	<primary>SLIP</primary>
	<secondary>routing</secondary>
	</indexterm>
	<para>If you are not using the <quote>proxy ARP</quote> method
	for routing packets between your SLIP clients and the rest
	of your network (and perhaps the Internet), you will
	probably have to add static routes to your closest default
	router(s) to route your SLIP clients subnet via your SLIP
	server.</para>

	<sect4>
	<title>Static Routes</title>

	<indexterm><primary>static routes</primary></indexterm>

	<para>Adding static routes to your nearest default routers
	can be troublesome (or impossible if you do not have
	authority to do so...). If you have a multiple-router
	network in your organization, some routers, such as those
	made by Cisco and Proteon, may not only need to be
	configured with the static route to the SLIP subnet, but
	also need to be told which static routes to tell other
	routers about, so some expertise and
	troubleshooting/tweaking may be necessary to get
	static-route-based routing to work.</para>
	</sect4>
	</sect3>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/printing/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/printing/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/printing/chapter.xml (revision 41355)
	@@ -1,5189 +1,5171 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="printing">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Sean</firstname>
	<surname>Kelly</surname>
	<contrib>Contributed by </contrib>
	</author>
	<!-- 30 Sept 1995 -->
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Jim</firstname>
	<surname>Mock</surname>
	<contrib>Restructured and updated by </contrib>
	<!-- Mar 2000 -->
	</author>
	</authorgroup>
	</chapterinfo>

	<title>Printing</title>

	<sect1 id="printing-synopsis">
	<title>Synopsis</title>

	<indexterm><primary>LPD spooling system</primary></indexterm>
	<indexterm><primary>printing</primary></indexterm>

	<para>&os; can be used to print with a wide variety of printers,
	from the oldest impact printer to the latest laser printers,
	and everything in between, allowing you to produce high-quality
	printed output from the applications you run.</para>

	<para>&os; can also be configured to act as a print server on a
	network; in this capacity &os; can receive print jobs from a
	varietyof other computers, including other &os; computers,
	&windows; and &macos; hosts. &os; will ensure that one job
	at a time is printed, and can keep statistics on which users
	and machines are doing the most printing, produce
	<quote>banner</quote> pages showing whose printout is whose,
	and more.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>How to configure the &os; print spooler.</para>
	</listitem>

	<listitem>
	<para>How to install print filters, to handle special print
	jobs differently, including converting incoming documents
	to print formats that your printers understand.</para>
	</listitem>

	<listitem>
	<para>How to enable header, or banner pages on your
	printout.</para>
	</listitem>

	<listitem>
	<para>How to print with printers connected to other
	computers.</para>
	</listitem>

	<listitem>
	<para>How to print with printers connected directly to the
	network.</para>
	</listitem>

	<listitem>
	<para>How to control printer restrictions, including limiting
	the size of print jobs, and preventing certain users from
	printing.</para>
	</listitem>

	<listitem>
	<para>How to keep printer statistics, and account for printer
	usage.</para>
	</listitem>

	<listitem>
	<para>How to troubleshoot printing problems.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	<para>Know how to configure and install a new kernel
	(<xref linkend="kernelconfig"/>).</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="printing-intro-spooler">
	<title>Introduction</title>

	<para>In order to use printers with &os; you may set them up to
	work with the Berkeley line printer spooling system, also known
	as the <application>LPD</application> spooling system, or just
	<application>LPD</application>. It is the standard printer
	control system in &os;. This chapter introduces
	<application>LPD</application> and will guide you through its
	configuration.</para>

	<para>If you are already familiar with
	<application>LPD</application> or another printer spooling
	system, you may wish to skip to section <link
	linkend="printing-intro-setup">Basic Setup</link>.</para>

	<para><application>LPD</application> controls everything about
	a host's printers. It is responsible for a number of
	things:</para>

	<itemizedlist>
	<listitem>
	<para>It controls access to attached printers and printers
	attached to other hosts on the network.</para>
	</listitem>

	<listitem>
	<indexterm><primary>print jobs</primary></indexterm>

	<para>It enables users to submit files to be printed; these
	submissions are known as <emphasis>jobs</emphasis>.</para>
	</listitem>

	<listitem>
	<para>It prevents multiple users from accessing a printer at
	the same time by maintaining a <emphasis>queue</emphasis>
	for each printer.</para>
	</listitem>

	<listitem>
	<para>It can print <emphasis>header pages</emphasis> (also
	known as <emphasis>banner</emphasis> or
	<emphasis>burst</emphasis> pages) so users can easily find
	jobs they have printed in a stack of printouts.</para>
	</listitem>

	<listitem>
	<para>It takes care of communications parameters for printers
	connected on serial ports.</para>
	</listitem>

	<listitem>
	<para>It can send jobs over the network to a
	<application>LPD</application> spooler on another
	host.</para>
	</listitem>

	<listitem>
	<para>It can run special filters to format jobs to be printed
	for various printer languages or printer
	capabilities.</para>
	</listitem>

	<listitem>
	<para>It can account for printer usage.</para>
	</listitem>
	</itemizedlist>

	<para>Through a configuration file
	(<filename>/etc/printcap</filename>), and by providing the
	special filter programs, you can enable the
	<application>LPD</application> system to do all or some subset
	of the above for a great variety of printer hardware.</para>

	<sect2 id="printing-intro-why">
	<title>Why You Should Use the Spooler</title>

	<para>The spooler still provides benefit on a single-user system
	- and should be used because:</para>
	+ and should be used because:</para>

	<itemizedlist>
	<listitem>
	<para><application>LPD</application> prints jobs in the
	background; you do not have to wait for data to be copied
	to the printer.</para>
	</listitem>

	<listitem>
	<indexterm><primary>&tex;</primary></indexterm>

	<para><application>LPD</application> can conveniently run
	a job to be printed through filters to add date/time
	headers or convert a special file format (such as a &tex;
	DVI file) into a format the printer will understand.
	You will not have to do these steps manually.</para>
	</listitem>

	<listitem>
	<para>Many free and commercial programs that provide a print
	feature usually expect to talk to the spooler on your
	system. By setting up the spooling system, you will more
	easily support other software you may later add or already
	have.</para>
	</listitem>
	</itemizedlist>
	</sect2>
	</sect1>

	<sect1 id="printing-intro-setup">
	<title>Basic Setup</title>

	- <warning>
	- <para>As of &os; 8.0, device nodes for serial ports have been
	- renamed from
	- <filename>/dev/ttyd<replaceable>N</replaceable></filename> to
	- <filename>/dev/ttyu<replaceable>N</replaceable></filename>.
	- &os; 7.X users will have to adapt the following
	- documentation according to these changes.</para>
	- </warning>
	-
	<para>To use printers with the <application>LPD</application>
	spooling system, you will need to set up both your printer
	hardware and the <application>LPD</application> software. This
	document describes two levels of setup:</para>

	<itemizedlist>
	<listitem>
	<para>See section <link linkend="printing-simple">Simple
	Printer Setup</link> to learn how to connect a printer,
	tell <application>LPD</application> how to communicate with
	it, and print plain text files to the printer.</para>
	</listitem>

	<listitem>
	<para>See section <link linkend="printing-advanced">Advanced
	Printer Setup</link> to learn how to print a variety of
	special file formats, to print header pages, to print across
	a network, to control access to printers, and to do printer
	accounting.</para>
	</listitem>
	</itemizedlist>

	<sect2 id="printing-simple">
	<title>Simple Printer Setup</title>

	<para>This section tells how to configure printer hardware
	and the <application>LPD</application> software to use the
	printer. It teaches the basics:</para>

	<itemizedlist>
	<listitem>
	<para>Section <link linkend="printing-hardware">Hardware
	Setup</link> gives some hints on connecting the printer
	to a port on your computer.</para>
	</listitem>

	<listitem>
	<para>Section <link linkend="printing-software">Software
	Setup</link> shows how to set up the
	<application>LPD</application> spooler configuration
	file (<filename>/etc/printcap</filename>).</para>
	</listitem>
	</itemizedlist>

	<para>If you are setting up a printer that uses a network
	protocol to accept data to print instead of a computer's local
	interfaces, see <link
	linkend="printing-advanced-network-net-if">Printers With
	Networked Data Stream Interfaces</link>.</para>

	<para>Although this section is called <quote>Simple Printer
	Setup</quote>, it is actually fairly complex. Getting the
	printer to work with your computer and the
	<application>LPD</application> spooler is the hardest part.
	The advanced options like header pages and accounting are
	fairly easy once you get the printer working.</para>

	<sect3 id="printing-hardware">
	<title>Hardware Setup</title>

	<para>This section tells about the various ways you can
	connect a printer to your PC. It talks about the kinds of
	ports and cables, and also the kernel configuration you may
	need to enable &os; to speak to the printer.</para>

	<para>If you have already connected your printer and have
	successfully printed with it under another operating system,
	you can probably skip to section <link
	linkend="printing-software">Software Setup</link>.</para>

	<sect4 id="printing-ports">
	<title>Ports and Cables</title>

	<para>Printers sold for use on PC's today generally come
	with one or more of the following three interfaces:</para>

	<itemizedlist>
	<listitem>
	<indexterm>
	<primary>printers</primary>
	<secondary>serial</secondary>
	</indexterm>

	<para><emphasis>Serial</emphasis> interfaces, also known
	as RS-232 or COM ports, use a serial port
	on your computer to send data to the printer. Serial
	interfaces are common in the computer industry and
	cables are readily available and also easy to
	construct. Serial interfaces sometimes need special
	cables and might require you to configure somewhat
	complex communications options. Most PC serial ports
	have a maximum transmission rate of 115200 bps,
	which makes printing large graphic print jobs with
	them impractical.</para>
	</listitem>

	<listitem>
	<indexterm>
	<primary>printers</primary>
	<secondary>parallel</secondary>
	</indexterm>

	<para><emphasis>Parallel</emphasis> interfaces use a
	parallel port on your computer to send data to the
	printer. Parallel interfaces are common in the PC
	market and are faster than RS-232 serial. Cables are
	readily available but more difficult to construct by
	hand. There are usually no communications options
	with parallel interfaces, making their configuration
	exceedingly simple.</para>

	<indexterm>
	<primary>centronics</primary>
	<see>parallel printers</see>
	</indexterm>
	<para>Parallel interfaces are sometimes known as
	<quote>Centronics</quote> interfaces, named after the
	connector type on the printer.</para>
	</listitem>

	<listitem>
	<indexterm>
	<primary>printers</primary>
	<secondary>USB</secondary>
	</indexterm>

	<para>USB interfaces, named for the Universal Serial
	Bus, can run at even faster speeds than parallel or
	RS-232 serial interfaces. Cables are simple and
	cheap. USB is superior to RS-232 Serial and to
	Parallel for printing, but it is not as well supported
	under &unix; systems. A way to avoid this problem is
	to purchase a printer that has both a USB interface
	and a Parallel interface, as many printers do.</para>
	</listitem>
	</itemizedlist>

	<para>In general, Parallel interfaces usually offer just
	one-way communication (computer to printer) while serial
	and USB gives you two-way. Newer parallel ports (EPP and
	ECP) and printers can communicate in both directions under
	&os; when a IEEE-1284-compliant cable is used.</para>

	<indexterm><primary>PostScript</primary></indexterm>

	<para>Two-way communication to the printer over a parallel
	port is generally done in one of two ways. The first
	method uses a custom-built printer driver for &os; that
	speaks the proprietary language used by the printer. This
	is common with inkjet printers and can be used for
	reporting ink levels and other status information. The
	second method is used when the printer supports
	&postscript;.</para>

	<para>&postscript; jobs are actually programs sent to the
	printer; they need not produce paper at all and may return
	results directly to the computer. &postscript; also uses
	two-way communication to tell the computer about problems,
	such as errors in the &postscript; program or paper jams.
	Your users may be appreciative of such information.
	Furthermore, the best way to do effective accounting with
	a &postscript; printer requires two-way communication:
	you ask the printer for its page count (how many pages
	it has printed in its lifetime), then send the user's job,
	then ask again for its page count. Subtract the two
	values and you know how much paper to charge to the
	user.</para>
	</sect4>

	<sect4 id="printing-parallel">
	<title>Parallel Ports</title>

	<para>To hook up a printer using a parallel interface,
	connect the Centronics cable between the printer and the
	computer. The instructions that came with the printer,
	the computer, or both should give you complete
	guidance.</para>

	<para>Remember which parallel port you used on the computer.
	The first parallel port is
	<filename class="devicefile">ppc0</filename> to &os;;
	the second is <filename
	class="devicefile">ppc1</filename>, and so on. The
	printer device name uses the same scheme:
	<filename class="devicefile">/dev/lpt0</filename> for
	the printer on the first parallel ports etc.</para>
	</sect4>

	<sect4 id="printing-serial">
	<title>Serial Ports</title>

	<para>To hook up a printer using a serial interface, connect
	the proper serial cable between the printer and the
	computer. The instructions that came with the printer,
	the computer, or both should give you complete
	guidance.</para>

	<para>If you are unsure what the <quote>proper serial
	cable</quote> is, you may wish to try one of the
	following alternatives:</para>

	<itemizedlist>
	<listitem>
	<para>A <emphasis>modem</emphasis> cable connects each
	pin of the connector on one end of the cable straight
	through to its corresponding pin of the connector on
	the other end. This type of cable is also known as a
	<quote>DTE-to-DCE</quote> cable.</para>
	</listitem>

	<listitem>
	<indexterm><primary>null-modem
	cable</primary></indexterm>

	<para>A <emphasis>null-modem</emphasis> cable connects
	some pins straight through, swaps others (send data to
	receive data, for example), and shorts some internally
	in each connector hood. This type of cable is also
	known as a <quote>DTE-to-DTE</quote> cable.</para>
	</listitem>

	<listitem>
	<para>A <emphasis>serial printer</emphasis> cable,
	required for some unusual printers, is like the
	null-modem cable, but sends some signals to their
	counterparts instead of being internally
	shorted.</para>
	</listitem>
	</itemizedlist>

	<indexterm><primary>baud rate</primary></indexterm>
	<indexterm><primary>parity</primary></indexterm>
	<indexterm><primary>flow control
	protocol</primary></indexterm>
	<para>You should also set up the communications parameters
	for the printer, usually through front-panel controls or
	DIP switches on the printer. Choose the highest
	<literal>bps</literal> (bits per second, sometimes
	<emphasis>baud rate</emphasis>) that both your computer
	and the printer can support. Choose 7 or 8 data bits;
	none, even, or odd parity; and 1 or 2 stop bits. Also
	choose a flow control protocol: either none, or XON/XOFF
	(also known as <quote>in-band</quote> or
	<quote>software</quote>) flow control. Remember these
	settings for the software configuration that
	follows.</para>
	</sect4>
	</sect3>

	<sect3 id="printing-software">
	<title>Software Setup</title>

	<para>This section describes the software setup necessary
	to print with the <application>LPD</application> spooling
	system in &os;.</para>

	<para>Here is an outline of the steps involved:</para>

	<procedure>
	<step>
	<para>Configure your kernel, if necessary, for the port
	you are using for the printer; section <link
	linkend="printing-kernel">Kernel Configuration</link>
	tells you what you need to do.</para>
	</step>

	<step>
	<para>Set the communications mode for the parallel port,
	if you are using a parallel port; section <link
	linkend="printing-parallel-port-mode">Setting the
	Communication Mode for the Parallel Port</link> gives
	details.</para>
	</step>

	<step>
	<para>Test if the operating system can send data to the
	printer. Section <link
	linkend="printing-testing">Checking Printer
	Communications</link> gives some suggestions on how to
	do this.</para>
	</step>

	<step>
	<para>Set up <application>LPD</application> for the
	printer by modifying the file
	<filename>/etc/printcap</filename>. You will find out
	how to do this later in this chapter.</para>
	</step>
	</procedure>

	<sect4 id="printing-kernel">
	<title>Kernel Configuration</title>

	<para>The operating system kernel is compiled to work with
	a specific set of devices. The serial or parallel
	interface for your printer is a part of that set.
	Therefore, it might be necessary to add support for an
	additional serial or parallel port if your kernel is not
	already configured for one.</para>

	<para>To find out if the kernel you are currently using
	supports a serial interface, type:</para>

	<screen>&prompt.root; <userinput><command>grep sio<replaceable>N</replaceable> <filename>/var/run/dmesg.boot</filename></command></userinput></screen>

	<para>Where <replaceable>N</replaceable> is the number of
	the serial port, starting from zero. If you see output
	similar to the following:</para>

	<screen>sio2 at port 0x3e8-0x3ef irq 5 on isa
	sio2: type 16550A</screen>

	<para>then the kernel supports the port.</para>

	<para>To find out if the kernel supports a parallel
	interface, type:</para>

	<screen>&prompt.root; <userinput><command>grep ppc<replaceable>N</replaceable> /var/run/dmesg.boot</command></userinput></screen>

	<para>Where <replaceable>N</replaceable> is the number of
	the parallel port, starting from zero. If you see output
	similar to the following:</para>

	<screen>ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0
	ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode
	ppc0: FIFO with 16/16/8 bytes threshold</screen>

	<para>then the kernel supports the port.</para>

	<para>You might have to reconfigure your kernel in order
	for the operating system to recognize and use the parallel
	or serial port you are using for the printer.</para>

	<para>To add support for a serial port, see the section on
	kernel configuration. To add support for a parallel port,
	see that section <emphasis>and</emphasis> the section that
	follows.</para>
	</sect4>
	</sect3>

	<sect3 id="printing-parallel-port-mode">
	<title>Setting the Communication Mode for the Parallel
	Port</title>

	<para>When you are using the parallel interface, you can
	choose whether &os; should use interrupt-driven or polled
	communication with the printer. The generic printer
	device driver (&man.lpt.4;) on &os;
	uses the &man.ppbus.4; system, which controls the port
	chipset with the &man.ppc.4; driver.</para>

	<itemizedlist>
	<listitem>
	<para>The <emphasis>interrupt-driven</emphasis> method
	is the default with the GENERIC kernel. With this
	method, the operating system uses an IRQ line to
	determine when the printer is ready for data.</para>
	</listitem>

	<listitem>
	<para>The <emphasis>polled</emphasis> method directs the
	operating system to repeatedly ask the printer if it is
	ready for more data. When it responds ready, the kernel
	sends more data.</para>
	</listitem>
	</itemizedlist>

	<para>The interrupt-driven method is usually somewhat faster
	but uses up a precious IRQ line. Some newer HP printers
	are claimed not to work correctly in interrupt mode,
	apparently due to some (not yet exactly understood) timing
	problem. These printers need polled mode. You should use
	whichever one works. Some printers will work in both
	modes, but are painfully slow in interrupt mode.</para>

	<para>You can set the communications mode in two ways: by
	configuring the kernel or by using the &man.lptcontrol.8;
	program.</para>

	<para><emphasis>To set the communications mode by configuring
	the kernel:</emphasis></para>

	<procedure>
	<step>
	<para>Edit your kernel configuration file. Look for
	an <literal>ppc0</literal> entry. If you are setting up
	the second parallel port, use <literal>ppc1</literal>
	instead. Use <literal>ppc2</literal> for the third
	port, and so on.</para>

	<itemizedlist>
	<listitem>
	<para>If you want interrupt-driven mode, edit the
	following line:</para>

	<programlisting>hint.ppc.0.irq="<replaceable>N</replaceable>"</programlisting>

	<para>in the <filename>/boot/device.hints</filename>
	file and replace <replaceable>N</replaceable> with
	the right IRQ number. The kernel configuration file
	must also contain the &man.ppc.4; driver:</para>

	<screen>device ppc</screen>
	</listitem>

	<listitem>
	<para>If you want polled mode, remove in your
	<filename>/boot/device.hints</filename> file, the
	following line:</para>

	<programlisting>hint.ppc.0.irq="<replaceable>N</replaceable>"</programlisting>

	<para>In some cases, this is not enough to put the
	port in polled mode under &os;. Most of
	time it comes from &man.acpi.4; driver, this latter
	is able to probe and attach devices, and therefore,
	control the access mode to the printer port. You
	should check your &man.acpi.4; configuration to
	correct this problem.</para>
	</listitem>
	</itemizedlist>
	</step>

	<step>
	<para>Save the file. Then configure, build, and install
	the kernel, then reboot. See <link
	linkend="kernelconfig">kernel configuration</link>
	for more details.</para>
	</step>
	</procedure>

	<para><emphasis>To set the communications mode with</emphasis>
	&man.lptcontrol.8;:</para>

	<procedure>
	<step>
	<para>Type:</para>

	<screen>&prompt.root; <userinput><command>lptcontrol <option>-i</option> <option>-d</option> <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen>

	<para>to set interrupt-driven mode for
	<literal>lpt<replaceable>N</replaceable></literal>.</para>
	</step>

	<step>
	<para>Type:</para>

	<screen>&prompt.root; <userinput><command>lptcontrol <option>-p</option> <option>-d</option> <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen>

	<para>to set polled-mode for
	<literal>lpt<replaceable>N</replaceable></literal>.</para>
	</step>
	</procedure>

	<para>You could put these commands in your
	<filename>/etc/rc.local</filename> file to set the mode each
	time your system boots. See &man.lptcontrol.8; for more
	information.</para>
	</sect3>

	<sect3 id="printing-testing">
	<title>Checking Printer Communications</title>

	<para>Before proceeding to configure the spooling system, you
	should make sure the operating system can successfully send
	data to your printer. It is a lot easier to debug printer
	communication and the spooling system separately.</para>

	<para>To test the printer, we will send some text to it. For
	printers that can immediately print characters sent to them,
	the program &man.lptest.1; is perfect: it generates all 96
	printable ASCII characters in 96 lines.</para>

	<indexterm><primary>PostScript</primary></indexterm>
	<para>For a &postscript; (or other language-based) printer, we
	will need a more sophisticated test. A small &postscript;
	program, such as the following, will suffice:</para>

	<programlisting>%!PS
	100 100 moveto 300 300 lineto stroke
	310 310 moveto /Helvetica findfont 12 scalefont setfont
	(Is this thing working?) show
	showpage</programlisting>

	<para>The above &postscript; code can be placed into a file
	and used as shown in the examples appearing in the following
	sections.</para>

	<indexterm><primary>PCL</primary></indexterm>
	<note>
	<para>When this document refers to a printer language, it
	is assuming a language like &postscript;, and not Hewlett
	Packard's PCL. Although PCL has great functionality, you
	can intermingle plain text with its escape sequences.
	&postscript; cannot directly print plain text, and that
	is the kind of printer language for which we must make
	special accommodations.</para>
	</note>

	<sect4 id="printing-checking-parallel">
	<title>Checking a Parallel Printer</title>

	<indexterm>
	<primary>printers</primary>
	<secondary>parallel</secondary>
	</indexterm>
	<para>This section tells you how to check if &os; can
	communicate with a printer connected to a parallel
	port.</para>

	<para><emphasis>To test a printer on a parallel
	port:</emphasis></para>

	<procedure>
	<step>
	<para>Become <username>root</username> with
	&man.su.1;.</para>
	</step>

	<step>
	<para>Send data to the printer.</para>

	<itemizedlist>
	<listitem>
	<para>If the printer can print plain text, then use
	&man.lptest.1;. Type:</para>

	<screen>&prompt.root; <userinput><command>lptest > <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen>

	<para>Where <replaceable>N</replaceable> is the
	number of the parallel port, starting from
	zero.</para>
	</listitem>

	<listitem>
	<para>If the printer understands &postscript; or
	other printer language, then send a small program
	to the printer. Type:</para>

	<screen>&prompt.root; <userinput><command>cat > <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen>

	<para>Then, line by line, type the program
	<emphasis>carefully</emphasis> as you cannot edit
	a line once you have pressed
	<literal>RETURN</literal> or
	<literal>ENTER</literal>. When you have finished
	entering the program, press
	<literal>CONTROL+D</literal>, or whatever your
	end of file key is.</para>

	<para>Alternatively, you can put the program in a
	file and type:</para>

	<screen>&prompt.root; <userinput><command>cat <filename><replaceable>file</replaceable></filename> > <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen>

	<para>Where <replaceable>file</replaceable> is the
	name of the file containing the program you want
	to send to the printer.</para>
	</listitem>
	</itemizedlist>
	</step>
	</procedure>

	<para>You should see something print. Do not worry if the
	text does not look right; we will fix such things
	later.</para>
	</sect4>

	<sect4 id="printing-checking-serial">
	<title>Checking a Serial Printer</title>

	<indexterm>
	<primary>printers</primary>
	<secondary>serial</secondary>
	</indexterm>
	<para>This section tells you how to check if &os; can
	communicate with a printer on a serial port.</para>

	<para><emphasis>To test a printer on a serial
	port:</emphasis></para>

	<procedure>
	<step>
	<para>Become <username>root</username> with
	&man.su.1;.</para>
	</step>

	<step>
	<para>Edit the file <filename>/etc/remote</filename>.
	Add the following entry:</para>

	<programlisting>printer:dv=<filename class="devicefile">/dev/<replaceable>port</replaceable></filename>:br#<replaceable>bps-rate</replaceable>:pa=<replaceable>parity</replaceable></programlisting>

	<indexterm><primary>bits-per-second</primary></indexterm>
	<indexterm><primary>serial port</primary></indexterm>
	<indexterm><primary>parity</primary></indexterm>
	<para>Where <replaceable>port</replaceable> is the
	device entry for the serial port
	(<literal>ttyu0</literal>, <literal>ttyu1</literal>,
	etc.), <replaceable>bps-rate</replaceable> is the
	bits-per-second rate at which the printer
	communicates, and <replaceable>parity</replaceable>
	is the parity required by the printer (either
	<literal>even</literal>, <literal>odd</literal>,
	<literal>none</literal>, or
	<literal>zero</literal>).</para>

	<para>Here is a sample entry for a printer connected via
	a serial line to the third serial port at
	19200 bps with no parity:</para>

	<programlisting>printer:dv=<filename class="devicefile">/dev/ttyu2</filename>:br#19200:pa=none</programlisting>
	</step>

	<step>
	<para>Connect to the printer with &man.tip.1;.
	Type:</para>

	<screen>&prompt.root; <userinput><command>tip</command> printer</userinput></screen>

	<para>If this step does not work, edit the file
	<filename>/etc/remote</filename> again and try using
	<filename
	class="devicefile">/dev/cuaa<replaceable>N</replaceable></filename>
	instead of
	<filename
	class="devicefile">/dev/ttyu<replaceable>N</replaceable></filename>.</para>
	</step>

	<step>
	<para>Send data to the printer.</para>

	<itemizedlist>
	<listitem>
	<para>If the printer can print plain text, then use
	&man.lptest.1;. Type:</para>

	<screen>&prompt.user; <userinput>$lptest</userinput></screen>
	</listitem>

	<listitem>
	<para>If the printer understands &postscript; or
	other printer language, then send a small program
	to the printer. Type the program, line by line,
	<emphasis>very carefully</emphasis> as backspacing
	or other editing keys may be significant to the
	printer. You may also need to type a special
	end-of-file key for the printer so it knows it
	received the whole program. For &postscript;
	printers, press
	<literal>CONTROL+D</literal>.</para>

	<para>Alternatively, you can put the program in a
	file and type:</para>

	<screen>&prompt.user; <userinput>><replaceable>file</replaceable></userinput></screen>

	<para>Where <replaceable>file</replaceable> is the
	name of the file containing the program. After
	&man.tip.1; sends the file, press any required
	end-of-file key.</para>
	</listitem>
	</itemizedlist>
	</step>
	</procedure>

	<para>You should see something print. Do not worry if the
	text does not look right; we will fix that later.</para>
	</sect4>
	</sect3>

	<sect3 id="printing-printcap">
	<title>Enabling the Spooler: the
	<filename>/etc/printcap</filename> File</title>

	<para>At this point, your printer should be hooked up, your
	kernel configured to communicate with it (if necessary),
	and you have been able to send some simple data to the
	printer. Now, we are ready to configure
	<application>LPD</application> to control access to your
	printer.</para>

	<para>You configure <application>LPD</application> by editing
	the file <filename>/etc/printcap</filename>. The
	<application>LPD</application> spooling system reads this
	file each time the spooler is used, so updates to the
	file take immediate effect.</para>

	<indexterm>
	<primary>printers</primary>
	<secondary>capabilities</secondary>
	</indexterm>
	<para>The format of the &man.printcap.5; file is
	straightforward. Use your favorite text editor to make
	changes to <filename>/etc/printcap</filename>. The format
	is identical to other capability files like
	<filename>/usr/share/misc/termcap</filename> and
	<filename>/etc/remote</filename>. For complete information
	about the format, see the &man.cgetent.3;.</para>

	<para>The simple spooler configuration consists of the
	following steps:</para>

	<procedure>
	<step>
	<para>Pick a name (and a few convenient aliases) for the
	printer, and put them in the
	<filename>/etc/printcap</filename> file; see the
	<link linkend="printing-naming">Naming the
	Printer</link> section for more information on
	naming.</para>
	</step>

	<step>
	<indexterm><primary>header pages</primary></indexterm>

	<para>Turn off header pages (which are on by default) by
	inserting the <literal>sh</literal> capability; see the
	<link linkend="printing-no-header-pages">Suppressing
	Header Pages</link> section for more
	information.</para>
	</step>

	<step>
	<para>Make a spooling directory, and specify its location
	with the <literal>sd</literal> capability; see the <link
	linkend="printing-spooldir">Making the Spooling
	Directory</link> section for more information.</para>
	</step>

	<step>
	<para>Set the <filename class="directory">/dev</filename>
	entry to use for the printer, and note it in
	<filename>/etc/printcap</filename> with the
	<literal>lp</literal> capability; see the <link
	linkend="printing-device">Identifying the Printer
	Device</link> for more information. Also, if the
	printer is on a serial port, set up the communication
	parameters with the <literal>ms#</literal> capability
	which is discussed in the <link
	linkend="printing-commparam">Configuring Spooler
	Communications Parameters</link> section.</para>
	</step>

	<step>
	<para>Install a plain text input filter; see the <link
	linkend="printing-textfilter">Installing the Text
	Filter</link> section for details.</para>
	</step>

	<step>
	<para>Test the setup by printing something with the
	&man.lpr.1; command. More details are available in the
	<link linkend="printing-trying">Trying It Out</link> and
	<link
	linkend="printing-troubleshooting">Troubleshooting</link>
	sections.</para>
	</step>
	</procedure>

	<note>
	<para>Language-based printers, such as &postscript;
	printers, cannot directly print plain text. The simple
	setup outlined above and described in the following
	sections assumes that if you are installing such a printer
	you will print only files that the printer can
	understand.</para>
	</note>

	<para>Users often expect that they can print plain text to
	any of the printers installed on your system. Programs
	that interface to <application>LPD</application> to do their
	printing usually make the same assumption. If you are
	installing such a printer and want to be able to print jobs
	in the printer language <emphasis>and</emphasis> print plain
	text jobs, you are strongly urged to add an additional step
	to the simple setup outlined above: install an automatic
	plain-text-to-&postscript; (or other printer language)
	conversion program. The section entitled <link
	linkend="printing-advanced-if-conversion">Accommodating
	Plain Text Jobs on &postscript; Printers</link> tells how
	to do this.</para>

	<sect4 id="printing-naming">
	<title>Naming the Printer</title>

	<para>The first (easy) step is to pick a name for your
	printer. It really does not matter whether you choose
	functional or whimsical names since you can also provide
	a number of aliases for the printer.</para>

	<para>At least one of the printers specified in the
	<filename>/etc/printcap</filename> should have the alias
	<literal>lp</literal>. This is the default printer's
	name. If users do not have the <envar>PRINTER</envar>
	environment variable nor specify a printer name on the
	command line of any of the <application>LPD</application>
	commands, then <literal>lp</literal> will be the default
	printer they get to use.</para>

	<para>Also, it is common practice to make the last alias
	for a printer be a full description of the printer,
	including make and model.</para>

	<para>Once you have picked a name and some common aliases,
	put them in the <filename>/etc/printcap</filename> file.
	The name of the printer should start in the leftmost
	column. Separate each alias with a vertical bar and put
	a colon after the last alias.</para>

	<para>In the following example, we start with a skeletal
	<filename>/etc/printcap</filename> that defines two
	printers (a Diablo 630 line printer and a Panasonic
	KX-P4455 &postscript; laser printer):</para>

	<programlisting>#
	# /etc/printcap for host rose
	#
	rattan\|line\|diablo\|lp\|Diablo 630 Line Printer:

	bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:</programlisting>

	<para>In this example, the first printer is named
	<literal>rattan</literal> and has as aliases
	<literal>line</literal>, <literal>diablo</literal>,
	<literal>lp</literal>, and <literal>Diablo 630 Line
	Printer</literal>. Since it has the alias
	<literal>lp</literal>, it is also the default printer.
	The second is named <literal>bamboo</literal>, and has
	as aliases <literal>ps</literal>, <literal>PS</literal>,
	<literal>S</literal>, <literal>panasonic</literal>, and
	<literal>Panasonic KX-P4455 PostScript
	v51.4</literal>.</para>
	</sect4>

	<sect4 id="printing-no-header-pages">
	<title>Suppressing Header Pages</title>

	<indexterm>
	<primary>printing</primary>
	<secondary>header pages</secondary>
	</indexterm>

	<para>The <application>LPD</application> spooling system
	will by default print a <emphasis>header page</emphasis>
	for each job. The header page contains the user name who
	requested the job, the host from which the job came, and
	the name of the job, in nice large letters.
	Unfortunately, all this extra text gets in the way of
	debugging the simple printer setup, so we will suppress
	header pages.</para>

	<para>To suppress header pages, add the
	<literal>sh</literal> capability to the entry for the
	printer in <filename>/etc/printcap</filename>. Here is
	an example <filename>/etc/printcap</filename> with
	<literal>sh</literal> added:</para>

	<programlisting>#
	# /etc/printcap for host rose - no header pages anywhere
	#
	rattan\|line\|diablo\|lp\|Diablo 630 Line Printer:\
	:sh:

	bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:\
	:sh:</programlisting>

	<para>Note how we used the correct format: the first line
	starts in the leftmost column, and subsequent lines are
	indented. Every line in an entry except the last ends
	in a backslash character.</para>
	</sect4>

	<sect4 id="printing-spooldir">
	<title>Making the Spooling Directory</title>

	<indexterm><primary>printer spool</primary></indexterm>
	<indexterm><primary>print jobs</primary></indexterm>

	<para>The next step in the simple spooler setup is to make
	a <emphasis>spooling directory</emphasis>, a directory
	where print jobs reside until they are printed, and where
	a number of other spooler support files live.</para>

	<para>Because of the variable nature of spooling
	directories, it is customary to put these directories
	under <filename class="directory">/var/spool</filename>.
	It is not necessary to backup the contents of spooling
	directories, either. Recreating them is as simple as
	running &man.mkdir.1;.</para>

	<para>It is also customary to make the directory with a name
	that is identical to the name of the printer, as shown
	below:</para>

	<screen>&prompt.root; <userinput><command>mkdir <filename class="directory">/var/spool/<replaceable>printer-name</replaceable></filename></command></userinput></screen>

	<para>However, if you have a lot of printers on your
	network, you might want to put the spooling directories
	under a single directory that you reserve just for
	printing with <application>LPD</application>. We
	will do this for our two example printers
	<literal>rattan</literal> and
	<literal>bamboo</literal>:</para>

	<screen>&prompt.root; <userinput><command>mkdir <filename class="directory">/var/spool/lpd</filename></command></userinput>
	&prompt.root; <userinput><command>mkdir <filename class="directory">/var/spool/lpd/rattan</filename></command></userinput>
	&prompt.root; <userinput><command>mkdir <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput></screen>

	<note>
	<para>If you are concerned about the privacy of jobs that
	users print, you might want to protect the spooling
	directory so it is not publicly accessible. Spooling
	directories should be owned and be readable, writable,
	and searchable by user <username>daemon</username> and
	group <groupname>daemon</groupname>, and no one else.
	We will do this for our example printers:</para>

	<screen>&prompt.root; <userinput><command>chown daemon:daemon <filename class="directory">/var/spool/lpd/rattan</filename></command></userinput>
	&prompt.root; <userinput><command>chown daemon:daemon <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput>
	&prompt.root; <userinput><command>chmod 770 <filename class="directory">/var/spool/lpd/rattan</filename></command></userinput>
	&prompt.root; <userinput><command>chmod 770 <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput></screen>
	</note>

	<para>Finally, you need to tell
	<application>LPD</application> about these directories
	using the <filename>/etc/printcap</filename> file. You
	specify the pathname of the spooling directory with the
	<literal>sd</literal> capability:</para>

	<programlisting>#
	# /etc/printcap for host rose - added spooling directories
	#
	rattan\|line\|diablo\|lp\|Diablo 630 Line Printer:\
	:sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:

	bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:\
	:sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:</programlisting>

	<para>Note that the name of the printer starts in the first
	column but all other entries describing the printer should
	be indented and each line end escaped with a
	backslash.</para>

	<para>If you do not specify a spooling directory with
	<literal>sd</literal>, the spooling system will use
	<filename class="directory">/var/spool/lpd</filename> as
	a default.</para>
	</sect4>

	<sect4 id="printing-device">
	<title>Identifying the Printer Device</title>

	<para>In the <link linkend="printing-hardware">Hardware
	Setup</link> section, we identified the port and the
	relevant <filename class="directory">/dev</filename>
	directory entry that &os; will use to communicate with
	the printer. Now, we tell <application>LPD</application>
	that information. When the spooling system has a job to
	print, it will open the specified device on behalf of the
	filter program (which is responsible for passing data to
	the printer).</para>

	<para>List the <filename class="directory">/dev</filename>
	entry pathname in the <filename>/etc/printcap</filename>
	file using the <literal>lp</literal> capability.</para>

	<para>In our running example, let us assume that
	<literal>rattan</literal> is on the first parallel port,
	and <literal>bamboo</literal> is on a sixth serial port;
	here are the additions to
	<filename>/etc/printcap</filename>:</para>

	<programlisting>#
	# /etc/printcap for host rose - identified what devices to use
	#
	rattan\|line\|diablo\|lp\|Diablo 630 Line Printer:\
	:sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\
	:lp=<filename class="devicefile">/dev/lpt0</filename>:

	bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:\
	:sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:\
	:lp=<filename class="devicefile">/dev/ttyu5</filename>:</programlisting>

	<para>If you do not specify the <literal>lp</literal>
	capability for a printer in your
	<filename>/etc/printcap</filename> file,
	<application>LPD</application> uses
	<filename class="devicefile">/dev/lp</filename> as a
	default. <filename class="devicefile">/dev/lp</filename>
	currently does not exist in &os;.</para>

	<para>If the printer you are installing is connected to a
	parallel port, skip to the section entitled, <link
	linkend="printing-textfilter">Installing the Text
	Filter</link>. Otherwise, be sure to follow the
	instructions in the next section.</para>
	</sect4>

	<sect4 id="printing-commparam">
	<title>Configuring Spooler Communication Parameters</title>

	<indexterm>
	<primary>printers</primary>
	<secondary>serial</secondary>
	</indexterm>

	<para>For printers on serial ports,
	<application>LPD</application> can set up the bps rate,
	parity, and other serial communication parameters on
	behalf of the filter program that sends data to the
	printer. This is advantageous since:</para>

	<itemizedlist>
	<listitem>
	<para>It lets you try different communication parameters
	by simply editing the
	<filename>/etc/printcap</filename> file; you do not
	have to recompile the filter program.</para>
	</listitem>

	<listitem>
	<para>It enables the spooling system to use the same
	filter program for multiple printers which may have
	different serial communication settings.</para>
	</listitem>
	</itemizedlist>

	<para>The following <filename>/etc/printcap</filename>
	capabilities control serial communication parameters of
	the device listed in the <literal>lp</literal>
	capability:</para>

	<variablelist>
	<varlistentry>
	<term><literal>br#<replaceable>bps-rate</replaceable></literal></term>

	<listitem>
	<para>Sets the communications speed of the device to
	<replaceable>bps-rate</replaceable>, where
	<replaceable>bps-rate</replaceable> can be 50, 75,
	110, 134, 150, 200, 300, 600, 1200, 1800, 2400,
	4800, 9600, 19200, 38400, 57600, or 115200
	bits-per-second.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>ms#<replaceable>stty-mode</replaceable></literal></term>

	<listitem>
	<para>Sets the options for the terminal device after
	opening the device. &man.stty.1; explains the
	available options.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>When <application>LPD</application> opens the device
	specified by the <literal>lp</literal> capability, it sets
	the characteristics of the device to those specified with
	the <literal>ms#</literal> capability. Of particular
	interest will be the <literal>parenb</literal>,
	<literal>parodd</literal>, <literal>cs5</literal>,
	<literal>cs6</literal>, <literal>cs7</literal>,
	<literal>cs8</literal>, <literal>cstopb</literal>,
	<literal>crtscts</literal>, and <literal>ixon</literal>
	modes, which are explained in the &man.stty.1;
	manual page.</para>

	<para>Let us add to our example printer on the sixth serial
	port. We will set the bps rate to 38400. For the mode,
	we will set no parity with <literal>-parenb</literal>,
	8-bit characters with <literal>cs8</literal>,
	no modem control with <literal>clocal</literal> and
	hardware flow control with
	<literal>crtscts</literal>:</para>

	<programlisting>bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:\
	:sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:\
	:lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:</programlisting>
	</sect4>

	<sect4 id="printing-textfilter">
	<title>Installing the Text Filter</title>

	<indexterm>
	<primary>printing</primary>
	<secondary>filters</secondary>
	</indexterm>

	<para>We are now ready to tell
	<application>LPD</application> what text filter to use
	to send jobs to the printer. A <emphasis>text
	filter</emphasis>, also known as an <emphasis>input
	filter</emphasis>, is a program that
	<application>LPD</application> runs when it has a job to
	print. When <application>LPD</application> runs the text
	filter for a printer, it sets the filter's standard input
	to the job to print, and its standard output to the
	printer device specified with the <literal>lp</literal>
	capability. The filter is expected to read the job from
	standard input, perform any necessary translation for the
	printer, and write the results to standard output, which
	will get printed. For more information on the text
	filter, see the <link
	linkend="printing-advanced-filters">Filters</link>
	section.</para>

	<para>For our simple printer setup, the text filter can be a
	small shell script that just executes
	<command>/bin/cat</command> to send the job to the
	printer. &os; comes with another filter called
	<filename>lpf</filename> that handles backspacing and
	underlining for printers that might not deal with such
	character streams well. And, of course, you can use any
	other filter program you want. The filter
	<command>lpf</command> is described in detail in section
	entitled <link linkend="printing-advanced-lpf">lpf: a
	Text Filter</link>.</para>

	<para>First, let us make the shell script
	<filename>/usr/local/libexec/if-simple</filename> be a
	simple text filter. Put the following text into that
	file with your favorite text editor:</para>

	<programlisting>#!/bin/sh
	#
	# if-simple - Simple text input filter for lpd
	# Installed in /usr/local/libexec/if-simple
	#
	# Simply copies stdin to stdout. Ignores all filter arguments.

	/bin/cat && exit 0
	exit 2</programlisting>

	<para>Make the file executable:</para>

	<screen>&prompt.root; <userinput><command>chmod 555 <filename>/usr/local/libexec/if-simple</filename></command></userinput></screen>

	<para>And then tell LPD to use it by specifying it with the
	<literal>if</literal> capability in
	<filename>/etc/printcap</filename>. We will add it to
	the two printers we have so far in the example
	<filename>/etc/printcap</filename>:</para>

	<programlisting>#
	# /etc/printcap for host rose - added text filter
	#
	rattan\|line\|diablo\|lp\|Diablo 630 Line Printer:\
	:sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\
	:lp=<filename class="devicefile">/dev/lpt0</filename>:\
	:if=<filename>/usr/local/libexec/if-simple</filename>:

	bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:\
	:sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:\
	:lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:\
	:if=<filename>/usr/local/libexec/if-simple</filename>:</programlisting>

	<note>
	<para>A copy of the <filename>if-simple</filename> script
	can be found in the <filename
	class="directory">/usr/share/examples/printing</filename>
	directory.</para>
	</note>
	</sect4>

	<sect4>
	<title>Turn on <application>LPD</application></title>

	<para>&man.lpd.8; is run from <filename>/etc/rc</filename>,
	controlled by the <literal>lpd_enable</literal> variable.
	This variable defaults to <literal>NO</literal>. If you
	have not done so already, add the line:</para>

	<programlisting>lpd_enable="YES"</programlisting>

	<para>to <filename>/etc/rc.conf</filename>, and then either
	restart your machine, or just run &man.lpd.8;.</para>

	<screen>&prompt.root; <userinput><command>lpd</command></userinput></screen>
	</sect4>

	<sect4 id="printing-trying">
	<title>Trying It Out</title>

	<para>You have reached the end of the simple
	<application>LPD</application> setup.
	Unfortunately, congratulations are not quite yet in order,
	since we still have to test the setup and correct any
	problems. To test the setup, try printing something. To
	print with the <application>LPD</application> system, you
	use the command &man.lpr.1;,
	which submits a job for printing.</para>

	<para>You can combine &man.lpr.1; with the &man.lptest.1;
	program, introduced in section <link
	linkend="printing-testing">Checking Printer
	Communications</link> to generate some test text.</para>

	<para><emphasis>To test the simple
	<application>LPD</application> setup:</emphasis></para>

	<para>Type:</para>

	<screen>&prompt.root; <userinput><command>lptest 20 5 \| lpr <option>-P</option><replaceable>printer-name</replaceable></command></userinput></screen>

	<para>Where <replaceable>printer-name</replaceable> is a the
	name of a printer (or an alias) specified in
	<filename>/etc/printcap</filename>. To test the default
	printer, type &man.lpr.1; without any <option>-P</option>
	argument. Again, if you are testing a printer that
	expects &postscript;, send a &postscript; program in that
	language instead of using &man.lptest.1;. You can do so
	by putting the program in a file and typing <command>lpr
	<replaceable>file</replaceable></command>.</para>

	<para>For a &postscript; printer, you should get the results
	of the program. If you are using &man.lptest.1;, then
	your results should look like the following:</para>

	<screen>!"#$%&'()*+,-./01234
	"#$%&'()*+,-./012345
	#$%&'()*+,-./0123456
	$%&'()*+,-./01234567
	%&'()*+,-./012345678</screen>

	<para>To further test the printer, try downloading larger
	programs (for language-based printers) or running
	&man.lptest.1; with different arguments. For example,
	<command>lptest 80 60</command> will produce 60 lines of
	80 characters each.</para>

	<para>If the printer did not work, see the <link
	linkend="printing-troubleshooting">Troubleshooting</link>
	section.</para>
	</sect4>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="printing-advanced">
	<title>Advanced Printer Setup</title>
	-
	- <warning>
	- <para>As of &os; 8.0, device nodes for serial ports have been
	- renamed from
	- <filename>/dev/ttyd<replaceable>N</replaceable></filename> to
	- <filename>/dev/ttyu<replaceable>N</replaceable></filename>.
	- &os; 7.X users will have to adapt the following
	- documentation according to these changes.</para>
	- </warning>

	<para>This section describes filters for printing specially
	formatted files, header pages, printing across networks, and
	restricting and accounting for printer usage.</para>

	<sect2 id="printing-advanced-filter-intro">
	<title>Filters</title>

	<indexterm>
	<primary>printing</primary>
	<secondary>filters</secondary>
	</indexterm>

	<para>Although <application>LPD</application> handles network
	protocols, queuing, access control, and other aspects of
	printing, most of the <emphasis>real</emphasis> work happens
	in the <emphasis>filters</emphasis>. Filters are programs
	that communicate with the printer and handle its device
	dependencies and special requirements. In the simple printer
	setup, we installed a plain text filter—an extremely
	simple one that should work with most printers (section <link
	linkend="printing-textfilter">Installing the Text
	Filter</link>).</para>

	<para>However, in order to take advantage of format conversion,
	printer accounting, specific printer quirks, and so on, you
	should understand how filters work. It will ultimately be
	the filter's responsibility to handle these aspects. And the
	bad news is that most of the time <emphasis>you</emphasis>
	have to provide filters yourself. The good news is that many
	are generally available; when they are not, they are usually
	easy to write.</para>

	<para>Also, &os; comes with one,
	<filename>/usr/libexec/lpr/lpf</filename>, that works with
	many printers that can print plain text. (It handles
	backspacing and tabs in the file, and does accounting, but
	that is about all it does.) There are also several filters
	and filter components in the &os; Ports Collection.</para>

	<para>Here is what you will find in this section:</para>

	<itemizedlist>
	<listitem>
	<para>Section <link linkend="printing-advanced-filters">How
	Filters Work</link>, tries to give an overview of a
	filter's role in the printing process. You should read
	this section to get an understanding of what is happening
	<quote>under the hood</quote> when
	<application>LPD</application> uses filters. This
	knowledge could help you anticipate and debug problems
	you might encounter as you install more and more filters
	for each of your printers.</para>
	</listitem>

	<listitem>
	<para><application>LPD</application> expects every printer
	to be able to print plain text by default. This presents
	a problem for &postscript; printers (or other
	language-based printers) which cannot directly print
	plain text. Section <link
	linkend="printing-advanced-if-conversion">Accommodating
	Plain Text Jobs on &postscript; Printers</link> tells
	you what you should do to overcome this problem. You
	should read this section if you have a &postscript;
	printer.</para>
	</listitem>

	<listitem>
	<para>&postscript; is a popular output format for many
	programs. Some people even write &postscript; code
	directly. Unfortunately, &postscript; printers are
	expensive. Section <link
	linkend="printing-advanced-ps">Simulating &postscript;
	on Non &postscript; Printers</link> tells how you can
	further modify a printer's text filter to accept and print
	&postscript; data on a <emphasis>non
	&postscript;</emphasis> printer. You should read this
	section if you do not have a &postscript; printer.</para>
	</listitem>

	<listitem>
	<para>Section <link
	linkend="printing-advanced-convfilters">Conversion
	Filters</link> tells about a way you can automate the
	conversion of specific file formats, such as graphic or
	typesetting data, into formats your printer can
	understand. After reading this section, you should be
	able to set up your printers such that users can type
	<command>lpr <option>-t</option></command> to print troff
	data, or <command>lpr <option>-d</option></command> to
	print &tex; DVI data, or <command>lpr
	<option>-v</option></command> to print raster image
	data, and so forth. The reading of this section is
	recommended.</para>
	</listitem>

	<listitem>
	<para>Section <link linkend="printing-advanced-of">Output
	Filters</link> tells all about a not often used feature
	of <application>LPD</application>: output filters. Unless
	you are printing header pages (see <link
	linkend="printing-advanced-header-pages">Header
	Pages</link>), you can probably skip that section
	altogether.</para>
	</listitem>

	<listitem>
	<para>Section <link linkend="printing-advanced-lpf">lpf:
	a Text Filter</link> describes <command>lpf</command>,
	a fairly complete if simple text filter for line
	printers (and laser printers that act like line
	printers) that comes with &os;. If you need a quick
	way to get printer accounting working for plain text,
	or if you have a printer which emits smoke when it sees
	backspace characters, you should definitely consider
	<command>lpf</command>.</para>
	</listitem>
	</itemizedlist>

	<note>
	<para>A copy of the various scripts described below can be
	found in the <filename
	class="directory">/usr/share/examples/printing</filename>
	directory.</para>
	</note>

	<sect3 id="printing-advanced-filters">
	<title>How Filters Work</title>

	<para>As mentioned before, a filter is an executable program
	started by <application>LPD</application> to handle the
	device-dependent part of communicating with the
	printer.</para>

	<para>When <application>LPD</application> wants to print a
	file in a job, it starts a filter program. It sets the
	filter's standard input to the file to print, its standard
	output to the printer, and its standard error to the error
	logging file (specified in the <literal>lf</literal>
	capability in <filename>/etc/printcap</filename>, or
	<filename class="devicefile">/dev/console</filename> by
	default).</para>

	<indexterm>
	<primary><command>troff</command></primary>
	</indexterm>
	<para>Which filter <application>LPD</application> starts and
	the filter's arguments depend on what is listed in the
	<filename>/etc/printcap</filename> file and what arguments
	the user specified for the job on the &man.lpr.1; command
	line. For example, if the user typed
	<command>lpr <option>-t</option></command>,
	<application>LPD</application> would start the troff filter,
	listed in the <literal>tf</literal> capability for the
	destination printer. If the user wanted to print plain
	text, it would start the <literal>if</literal> filter (this
	is mostly true: see <link
	linkend="printing-advanced-of">Output Filters</link> for
	details).</para>

	<para>There are three kinds of filters you can specify in
	<filename>/etc/printcap</filename>:</para>

	<itemizedlist>
	<listitem>
	<para>The <emphasis>text filter</emphasis>, confusingly
	called the <emphasis>input filter</emphasis> in
	<application>LPD</application> documentation, handles
	regular text printing. Think of it as the default
	filter. <application>LPD</application> expects every
	printer to be able to print plain text by default,
	and it is the text filter's job to make sure backspaces,
	tabs, or other special characters do not confuse the
	printer. If you are in an environment where you have
	to account for printer usage, the text filter must also
	account for pages printed, usually by counting the
	number of lines printed and comparing that to the number
	of lines per page the printer supports. The text filter
	is started with the following argument list:</para>

	<cmdsynopsis>
	<command>filter-name</command>
	<arg>-c</arg>
	<arg
	choice="plain">-w
	<replaceable>width</replaceable></arg>
	<arg
	choice="plain">-l
	<replaceable>length</replaceable></arg>
	<arg
	choice="plain">-i
	<replaceable>indent</replaceable></arg>
	<arg
	choice="plain">-n
	<replaceable>login</replaceable></arg>
	<arg
	choice="plain">-h
	<replaceable>host</replaceable></arg>
	<arg
	choice="plain"><replaceable>acct-file</replaceable></arg>
	</cmdsynopsis>

	<para>where</para>

	<variablelist>
	<varlistentry>
	<term><option>-c</option></term>

	<listitem>
	<para>appears if the job is submitted with
	<command>lpr <option>-l</option></command></para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><replaceable>width</replaceable></term>

	<listitem>
	<para>is the value from the <literal>pw</literal>
	(page width) capability specified in
	<filename>/etc/printcap</filename>, default
	132</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><replaceable>length</replaceable></term>

	<listitem>
	<para>is the value from the <literal>pl</literal>
	(page length) capability, default 66</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><replaceable>indent</replaceable></term>

	<listitem>
	<para>is the amount of the indentation from
	<command>lpr <option>-i</option></command>,
	default 0</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><replaceable>login</replaceable></term>

	<listitem>
	<para>is the account name of the user printing the
	file</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><replaceable>host</replaceable></term>

	<listitem>
	<para>is the host name from which the job was
	submitted</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><replaceable>acct-file</replaceable></term>

	<listitem>
	<para>is the name of the accounting file from the
	<literal>af</literal> capability.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</listitem>

	<listitem>
	<indexterm>
	<primary>printing</primary>
	<secondary>filters</secondary>
	</indexterm>

	<para>A <emphasis>conversion filter</emphasis> converts
	a specific file format into one the printer can render
	onto paper. For example, ditroff typesetting data
	cannot be directly printed, but you can install a
	conversion filter for ditroff files to convert the
	ditroff data into a form the printer can digest and
	print. Section <link
	linkend="printing-advanced-convfilters">Conversion
	Filters</link> tells all about them. Conversion
	filters also need to do accounting, if you need printer
	accounting. Conversion filters are started with the
	following arguments:</para>

	<cmdsynopsis>
	<command>filter-name</command>
	<arg choice="plain">-x
	<replaceable>pixel-width</replaceable></arg>
	<arg
	choice="plain">-y
	<replaceable>pixel-height</replaceable></arg>
	<arg
	choice="plain">-n
	<replaceable>login</replaceable></arg>
	<arg
	choice="plain">-h
	<replaceable>host</replaceable></arg>
	<arg
	choice="plain"><replaceable>acct-file</replaceable></arg>
	</cmdsynopsis>

	<para>where <replaceable>pixel-width</replaceable> is
	the value from the <literal>px</literal> capability
	(default 0) and <replaceable>pixel-height</replaceable>
	is the value from the <literal>py</literal> capability
	(default 0).</para>
	</listitem>

	<listitem>
	<para>The <emphasis>output filter</emphasis> is used
	only if there is no text filter, or if header pages are
	enabled. In our experience, output filters are rarely
	used. Section <link
	linkend="printing-advanced-of">Output Filters</link>
	describes them. There are only two arguments to an
	output filter:</para>

	<cmdsynopsis>
	<command>filter-name</command>
	<arg
	choice="plain">-w
	<replaceable>width</replaceable></arg>
	<arg
	choice="plain">-l
	<replaceable>length</replaceable></arg>
	</cmdsynopsis>

	<para>which are identical to the text filters
	<option>-w</option> and <option>-l</option>
	arguments.</para>
	</listitem>
	</itemizedlist>

	<para>Filters should also <emphasis>exit</emphasis> with the
	following exit status:</para>

	<variablelist>
	<varlistentry>
	<term>exit 0</term>

	<listitem>
	<para>If the filter printed the file
	successfully.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>exit 1</term>

	<listitem>
	<para>If the filter failed to print the file but wants
	<application>LPD</application> to
	try to print the file again.
	<application>LPD</application> will restart a filter
	if it exits with this status.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>exit 2</term>

	<listitem>
	<para>If the filter failed to print the file and does
	not want <application>LPD</application> to try again.
	<application>LPD</application> will throw out the
	file.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>The text filter that comes with the &os; release,
	<filename>/usr/libexec/lpr/lpf</filename>, takes advantage
	of the page width and length arguments to determine when
	to send a form feed and how to account for printer usage.
	It uses the login, host, and accounting file arguments to
	make the accounting entries.</para>

	<para>If you are shopping for filters, see if they are
	LPD-compatible. If they are, they must support the argument
	lists described above. If you plan on writing filters for
	general use, then have them support the same argument lists
	and exit codes.</para>
	</sect3>

	<sect3 id="printing-advanced-if-conversion">
	<title>Accommodating Plain Text Jobs on &postscript;
	Printers</title>

	<indexterm><primary>print jobs</primary></indexterm>

	<para>If you are the only user of your computer and
	&postscript; (or other language-based) printer, and you
	promise to never send plain text to your printer and to
	never use features of various programs that will want to
	send plain text to your printer, then you do not need to
	worry about this section at all.</para>

	<para>But, if you would like to send both &postscript; and
	plain text jobs to the printer, then you are urged to
	augment your printer setup. To do so, we have the text
	filter detect if the arriving job is plain text or
	&postscript;. All &postscript; jobs must start with
	<literal>%!</literal> (for other printer languages, see
	your printer documentation). If those are the first two
	characters in the job, we have &postscript;, and can pass
	the rest of the job directly. If those are not the first
	two characters in the file, then the filter will convert
	the text into &postscript; and print the result.</para>

	<para>How do we do this?</para>

	<indexterm>
	<primary>printers</primary>
	<secondary>serial</secondary>
	</indexterm>
	<para>If you have got a serial printer, a great way to do it
	is to install <command>lprps</command>.
	<command>lprps</command> is a &postscript; printer filter
	which performs two-way communication with the printer. It
	updates the printer's status file with verbose information
	from the printer, so users and administrators can see
	exactly what the state of the printer is (such as
	<errorname>toner low</errorname> or <errorname>paper
	jam</errorname>). But more importantly, it includes a
	program called <command>psif</command> which detects whether
	the incoming job is plain text and calls
	<command>textps</command> (another program that comes with
	<command>lprps</command>) to convert it to &postscript;.
	It then uses <command>lprps</command> to send the job to
	the printer.</para>

	<para><command>lprps</command> is part of the &os; Ports
	Collection (see <link linkend="ports">The Ports
	Collection</link>). You can install one of the both
	<filename role="package">print/lprps-a4</filename> and
	<filename role="package">print/lprps-letter</filename> ports
	according to the paper size used. After installing
	<command>lprps</command>, just specify the pathname to the
	<command>psif</command> program that is part of
	<command>lprps</command>. If you installed
	<command>lprps</command> from the Ports Collection, use
	the following in the serial &postscript; printer's entry
	in <filename>/etc/printcap</filename>:</para>

	<programlisting>:if=<filename>/usr/local/libexec/psif</filename>:</programlisting>

	<para>The <literal>rw</literal> capability should be also
	included in order to let <application>LPD</application> to
	open the printer in the read-write mode.</para>

	<para>If you have a parallel &postscript; printer (and
	therefore cannot use two-way communication with the printer,
	which <command>lprps</command> needs), you can use the
	following shell script as the text filter:</para>

	<programlisting>#!/bin/sh
	#
	# psif - Print PostScript or plain text on a PostScript printer
	# Script version; NOT the version that comes with lprps
	# Installed in /usr/local/libexec/psif
	#

	IFS="" read -r first_line
	first_two_chars=`expr "$first_line" : '$..$'`

	if [ "$first_two_chars" = "%!" ]; then
	#
	# PostScript job, print it.
	#
	echo "$first_line" && cat && printf "\004" && exit 0
	exit 2
	else
	#
	# Plain text, convert it, then print it.
	#
	( echo "$first_line"; cat ) \| /usr/local/bin/textps && printf "\004" && exit 0
	exit 2
	fi</programlisting>

	<para>In the above script, <command>textps</command> is a
	program we installed separately to convert plain text to
	&postscript;. You can use any text-to-&postscript; program
	you wish. The &os; Ports Collection (see <link
	linkend="ports">The Ports Collection</link>) includes a
	full featured text-to-&postscript; program called
	<literal>a2ps</literal> that you might want to
	investigate.</para>
	</sect3>

	<sect3 id="printing-advanced-ps">
	<title>Simulating &postscript; on Non &postscript;
	Printers</title>

	<indexterm>
	<primary>PostScript</primary>
	<secondary>emulating</secondary>
	</indexterm>
	<indexterm> <primary>Ghostscript</primary></indexterm>

	<para>&postscript; is the <emphasis>de facto</emphasis>
	standard for high quality typesetting and printing.
	&postscript; is, however, an <emphasis>expensive</emphasis>
	standard. Thankfully, Aladdin Enterprises has a free
	&postscript; work-alike called
	<application>Ghostscript</application> that runs with &os;.
	<application>Ghostscript</application> can read most
	&postscript; files and can render their pages onto a variety
	of devices, including many brands of non-&postscript;
	printers. By installing
	<application>Ghostscript</application> and using a special
	text filter for your printer, you can make your non
	&postscript; printer act like a real &postscript;
	printer.</para>

	<para><application>Ghostscript</application> is in the &os;
	Ports Collection, many versions are available, the most
	commonly used version is <filename
	role="package">print/ghostscript-gpl</filename>.</para>

	<para>To simulate &postscript;, we have the text filter detect
	if it is printing a &postscript; file. If it is not, then
	the filter will pass the file directly to the printer;
	otherwise, it will use
	<application>Ghostscript</application> to first convert the
	file into a format the printer will understand.</para>

	<para>Here is an example: the following script is a text
	filter for Hewlett Packard DeskJet 500 printers. For other
	printers, substitute the <option>-sDEVICE</option> argument
	to the <command>gs</command>
	(<application>Ghostscript</application>) command. (Type
	<command>gs <option>-h</option></command> to get a list of
	devices the current installation of
	<application>Ghostscript</application> supports.)</para>

	<programlisting>#!/bin/sh
	#
	# ifhp - Print Ghostscript-simulated PostScript on a DeskJet 500
	# Installed in /usr/local/libexec/ifhp

	#
	# Treat LF as CR+LF (to avoid the "staircase effect" on HP/PCL
	# printers):
	#
	printf "\033&k2G" \|\| exit 2

	#
	# Read first two characters of the file
	#
	IFS="" read -r first_line
	first_two_chars=`expr "$first_line" : '$..$'`

	if [ "$first_two_chars" = "%!" ]; then
	#
	# It is PostScript; use Ghostscript to scan-convert and print it.
	#
	/usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 \
	-sOutputFile=- - && exit 0
	else
	#
	# Plain text or HP/PCL, so just print it directly; print a form feed
	# at the end to eject the last page.
	#
	echo "$first_line" && cat && printf "\033&l0H" &&
	exit 0
	fi

	exit 2</programlisting>

	<para>Finally, you need to notify
	<application>LPD</application> of the filter via the
	<literal>if</literal> capability:</para>

	<programlisting>:if=<filename>/usr/local/libexec/ifhp</filename>:</programlisting>

	<para>That is it. You can type
	<command>lpr
	<filename><replaceable>plain.text</replaceable></filename></command>
	and
	<command>lpr
	<filename><replaceable>whatever.ps</replaceable></filename></command>
	and both should print successfully.</para>
	</sect3>

	<sect3 id="printing-advanced-convfilters">
	<title>Conversion Filters</title>

	<para>After completing the simple setup described in <link
	linkend="printing-simple">Simple Printer Setup</link>,
	the first thing you will probably want to do is install
	conversion filters for your favorite file formats (besides
	plain ASCII text).</para>

	<sect4>
	<title>Why Install Conversion Filters?</title>

	<indexterm>
	<primary>&tex;</primary>
	<secondary>printing DVI files</secondary>
	</indexterm>

	<para>Conversion filters make printing various kinds of
	files easy. As an example, suppose we do a lot of work
	with the &tex; typesetting system, and we have a
	&postscript; printer. Every time we generate a DVI file
	from &tex;, we cannot print it directly until we convert
	the DVI file into &postscript;. The command sequence
	goes like this:</para>

	<screen>&prompt.user; <userinput><command>dvips <filename><replaceable>seaweed-analysis.dvi</replaceable></filename></command></userinput>
	&prompt.user; <userinput><command>lpr <filename><replaceable>seaweed-analysis.ps</replaceable></filename></command></userinput></screen>

	<para>By installing a conversion filter for DVI files, we
	can skip the hand conversion step each time by having
	<application>LPD</application> do it for us. Now, each
	time we get a DVI file, we are just one step away from
	printing it:</para>

	<screen>&prompt.user; <userinput><command>lpr <option>-d</option> <filename><replaceable>seaweed-analysis.dvi</replaceable></filename></command></userinput></screen>

	<para>We got <application>LPD</application> to do the DVI
	file conversion for us by specifying the
	<option>-d</option> option. Section <link
	linkend="printing-lpr-options-format">Formatting and
	Conversion Options</link> lists the conversion
	options.</para>

	<para>For each of the conversion options you want a printer
	to support, install a <emphasis>conversion
	filter</emphasis> and specify its pathname in
	<filename>/etc/printcap</filename>. A conversion filter
	is like the text filter for the simple printer setup (see
	section <link linkend="printing-textfilter">Installing
	the Text Filter</link>) except that instead of printing
	plain text, the filter converts the file into a format
	the printer can understand.</para>
	</sect4>

	<sect4>
	<title>Which Conversion Filters Should I Install?</title>

	<para>You should install the conversion filters you expect
	to use. If you print a lot of DVI data, then a DVI
	conversion filter is in order. If you have got plenty
	of troff to print out, then you probably want a troff
	filter.</para>

	<para>The following table summarizes the filters that
	<application>LPD</application> works
	with, their capability entries for the
	<filename>/etc/printcap</filename> file, and how to
	invoke them with the <command>lpr</command>
	command:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="3">
	<thead>
	<row>
	<entry>File type</entry>
	<entry><filename>/etc/printcap</filename>
	capability</entry>
	<entry><command>lpr</command> option</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>cifplot</entry>
	<entry><literal>cf</literal></entry>
	<entry><option>-c</option></entry>
	</row>

	<row>
	<entry>DVI</entry>
	<entry><literal>df</literal></entry>
	<entry><option>-d</option></entry>
	</row>

	<row>
	<entry>plot</entry>
	<entry><literal>gf</literal></entry>
	<entry><option>-g</option></entry>
	</row>

	<row>
	<entry>ditroff</entry>
	<entry><literal>nf</literal></entry>
	<entry><option>-n</option></entry>
	</row>

	<row>
	<entry>FORTRAN text</entry>
	<entry><literal>rf</literal></entry>
	<entry><option>-f</option></entry>
	</row>

	<row>
	<entry>troff</entry>
	<entry><literal>tf</literal></entry>
	<entry><option>-f</option></entry>
	</row>

	<row>
	<entry>raster</entry>
	<entry><literal>vf</literal></entry>
	<entry><option>-v</option></entry>
	</row>

	<row>
	<entry>plain text</entry>
	<entry><literal>if</literal></entry>
	<entry>none, <option>-p</option>, or
	<option>-l</option></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>In our example, using
	<command>lpr <option>-d</option></command> means the
	printer needs a <literal>df</literal> capability in its
	entry in <filename>/etc/printcap</filename>.</para>

	<indexterm><primary>FORTRAN</primary></indexterm>
	<para>Despite what others might contend, formats like
	FORTRAN text and plot are probably obsolete. At your
	site, you can give new meanings to these or any of the
	formatting options just by installing custom filters.
	For example, suppose you would like to directly print
	Printerleaf files (files from the Interleaf desktop
	publishing program), but will never print plot files.
	You could install a Printerleaf conversion filter under
	the <literal>gf</literal> capability and then educate your
	users that <command>lpr <option>-g</option></command> mean
	<quote>print Printerleaf files.</quote></para>
	</sect4>

	<sect4>
	<title>Installing Conversion Filters</title>

	<para>Since conversion filters are programs you install
	outside of the base &os; installation, they should
	probably go under <filename
	class="directory">/usr/local</filename>. The
	directory <filename
	class="directory">/usr/local/libexec</filename> is a
	popular location, since they are specialized programs
	that only <application>LPD</application> will run; regular
	users should not ever need to run them.</para>

	<para>To enable a conversion filter, specify its pathname
	under the appropriate capability for the destination
	printer in <filename>/etc/printcap</filename>.</para>

	<para>In our example, we will add the DVI conversion filter
	to the entry for the printer named
	<literal>bamboo</literal>. Here is the example
	<filename>/etc/printcap</filename> file again, with
	the new <literal>df</literal> capability for the printer
	<literal>bamboo</literal>:</para>

	<programlisting>#
	# /etc/printcap for host rose - added df filter for bamboo
	#
	rattan\|line\|diablo\|lp\|Diablo 630 Line Printer:\
	:sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\
	:lp=<filename class="devicefile">/dev/lpt0</filename>:\
	:if=<filename>/usr/local/libexec/if-simple</filename>:

	bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:\
	:sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:\
	:lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\
	:if=<filename>/usr/local/libexec/psif</filename>:\
	:df=<filename>/usr/local/libexec/psdf</filename>:</programlisting>

	<para>The DVI filter is a shell script named
	<filename>/usr/local/libexec/psdf</filename>. Here is
	that script:</para>

	<programlisting>#!/bin/sh
	#
	# psdf - DVI to PostScript printer filter
	# Installed in /usr/local/libexec/psdf
	#
	# Invoked by lpd when user runs lpr -d
	#
	exec /usr/local/bin/dvips -f \| /usr/local/libexec/lprps "$@"</programlisting>

	<para>This script runs <command>dvips</command> in filter
	mode (the <option>-f</option> argument) on standard input,
	which is the job to print. It then starts the
	&postscript; printer filter <command>lprps</command>
	(see section <link
	linkend="printing-advanced-if-conversion">Accommodating
	Plain Text Jobs on &postscript; Printers</link>) with
	the arguments <application>LPD</application> passed to
	this script. The <command>lprps</command> utility will
	use those arguments to account for the pages
	printed.</para>
	</sect4>

	<sect4>
	<title>More Conversion Filter Examples</title>

	<para>There is no fixed set of steps to install conversion
	filters, some working examples are described in this
	section. Use these as guidance to making your own
	filters. Use them directly, if appropriate.</para>

	<para>This example script is a raster (well, GIF file,
	actually) conversion filter for a Hewlett Packard LaserJet
	III-Si printer:</para>

	<programlisting>#!/bin/sh
	#
	# hpvf - Convert GIF files into HP/PCL, then print
	# Installed in /usr/local/libexec/hpvf

	PATH=/usr/X11R6/bin:$PATH; export PATH
	giftopnm \| ppmtopgm \| pgmtopbm \| pbmtolj -resolution 300 \
	&& exit 0 \
	\|\| exit 2</programlisting>

	<para>It works by converting the GIF file into a portable
	anymap, converting that into a portable graymap,
	converting that into a portable bitmap, and converting
	that into LaserJet/PCL-compatible data.</para>

	<para>Here is the <filename>/etc/printcap</filename> file
	with an entry for a printer using the above filter:</para>

	<programlisting>#
	# /etc/printcap for host orchid
	#
	teak\|hp\|laserjet\|Hewlett Packard LaserJet 3Si:\
	:lp=<filename class="devicefile">/dev/lpt0</filename>:sh:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:\
	:if=<filename>/usr/local/libexec/hpif</filename>:\
	:vf=<filename>/usr/local/libexec/hpvf</filename>:</programlisting>

	<para>The following script is a conversion filter for troff
	data from the groff typesetting system for the
	&postscript; printer named
	<literal>bamboo</literal>:</para>

	<programlisting>#!/bin/sh
	#
	# pstf - Convert groff's troff data into PS, then print.
	# Installed in /usr/local/libexec/pstf
	#
	exec grops \| /usr/local/libexec/lprps "$@"</programlisting>

	<para>The above script makes use of <command>lprps</command>
	again to handle the communication with the printer. If
	the printer were on a parallel port, we would use this
	script instead:</para>

	<programlisting>#!/bin/sh
	#
	# pstf - Convert groff's troff data into PS, then print.
	# Installed in /usr/local/libexec/pstf
	#
	exec grops</programlisting>

	<para>That is it. Here is the entry we need to add to
	<filename>/etc/printcap</filename> to enable the
	filter:</para>

	<programlisting>:tf=<filename>/usr/local/libexec/pstf</filename>:</programlisting>

	<para>Here is an example that might make old hands at
	FORTRAN blush. It is a FORTRAN-text filter for any
	printer that can directly print plain text. We will
	install it for the printer <literal>teak</literal>:</para>

	<programlisting>#!/bin/sh
	#
	# hprf - FORTRAN text filter for LaserJet 3si:
	# Installed in /usr/local/libexec/hprf
	#

	printf "\033&k2G" && fpr && printf "\033&l0H" &&
	exit 0
	exit 2</programlisting>

	<para>And we will add this line to the
	<filename>/etc/printcap</filename> for the printer
	<literal>teak</literal> to enable this filter:</para>

	<programlisting>:rf=<filename>/usr/local/libexec/hprf</filename>:</programlisting>

	<para>Here is one final, somewhat complex example. We
	will add a DVI filter to the LaserJet printer
	<literal>teak</literal> introduced earlier. First, the
	easy part: updating <filename>/etc/printcap</filename>
	with the location of the DVI filter:</para>

	<programlisting>:df=<filename>/usr/local/libexec/hpdf</filename>:</programlisting>

	<para>Now, for the hard part: making the filter. For that,
	we need a DVI-to-LaserJet/PCL conversion program. The
	&os; Ports Collection (see <link linkend="ports">The Ports
	Collection</link>) has one: <filename
	role="package">print/dvi2xx</filename>. Installing this
	port gives us the program we need,
	<command>dvilj2p</command>, which converts DVI into
	LaserJet IIp, LaserJet III, and LaserJet 2000 compatible
	codes.</para>

	<para>The <command>dvilj2p</command> utility makes the
	filter <command>hpdf</command> quite complex since
	<command>dvilj2p</command> cannot read from standard
	input. It wants to work with a filename. What is worse,
	the filename has to end in <filename>.dvi</filename> so
	using <filename class="devicefile">/dev/fd/0</filename>
	for standard input is problematic. We can get around that
	problem by linking (symbolically) a temporary file name
	(one that ends in <filename>.dvi</filename>) to
	<filename class="devicefile">/dev/fd/0</filename>, thereby
	forcing <command>dvilj2p</command> to read from standard
	input.</para>

	<para>The only other fly in the ointment is the fact that
	we cannot use <filename class="directory">/tmp</filename>
	for the temporary link. Symbolic links are owned by user
	and group <username>bin</username>. The filter runs as
	user <username>daemon</username>. And the <filename
	class="directory">/tmp</filename> directory has the
	sticky bit set. The filter can create the link, but it
	will not be able clean up when done and remove it since
	the link will belong to a different user.</para>

	<para>Instead, the filter will make the symbolic link in
	the current working directory, which is the spooling
	directory (specified by the <literal>sd</literal>
	capability in <filename>/etc/printcap</filename>). This
	is a perfect place for filters to do their work,
	especially since there is (sometimes) more free disk space
	in the spooling directory than under
	<filename class="directory">/tmp</filename>.</para>

	<para>Here, finally, is the filter:</para>

	<programlisting>#!/bin/sh
	#
	# hpdf - Print DVI data on HP/PCL printer
	# Installed in /usr/local/libexec/hpdf

	PATH=/usr/local/bin:$PATH; export PATH

	#
	# Define a function to clean up our temporary files. These exist
	# in the current directory, which will be the spooling directory
	# for the printer.
	#
	cleanup() {
	rm -f hpdf$$.dvi
	}

	#
	# Define a function to handle fatal errors: print the given message
	# and exit 2. Exiting with 2 tells LPD to do not try to reprint the
	# job.
	#
	fatal() {
	echo "$@" 1>&2
	cleanup
	exit 2
	}

	#
	# If user removes the job, LPD will send SIGINT, so trap SIGINT
	# (and a few other signals) to clean up after ourselves.
	#
	trap cleanup 1 2 15

	#
	# Make sure we are not colliding with any existing files.
	#
	cleanup

	#
	# Link the DVI input file to standard input (the file to print).
	#
	ln -s /dev/fd/0 hpdf$$.dvi \|\| fatal "Cannot symlink /dev/fd/0"

	#
	# Make LF = CR+LF
	#
	printf "\033&k2G" \|\| fatal "Cannot initialize printer"

	#
	# Convert and print. Return value from dvilj2p does not seem to be
	# reliable, so we ignore it.
	#
	dvilj2p -M1 -q -e- dfhp$$.dvi

	#
	# Clean up and exit
	#
	cleanup
	exit 0</programlisting>
	</sect4>

	<sect4 id="printing-advanced-autoconv">
	<title>Automated Conversion: an Alternative to Conversion
	Filters</title>

	<para>All these conversion filters accomplish a lot for your
	printing environment, but at the cost forcing the user
	to specify (on the &man.lpr.1; command line) which one
	to use. If your users are not particularly computer
	literate, having to specify a filter option will become
	annoying. What is worse, though, is that an incorrectly
	specified filter option may run a filter on the wrong
	type of file and cause your printer to spew out hundreds
	of sheets of paper.</para>

	<para>Rather than install conversion filters at all, you
	might want to try having the text filter (since it is the
	default filter) detect the type of file it has been asked
	to print and then automatically run the right conversion
	filter. Tools such as <command>file</command> can be of
	help here. Of course, it will be hard to determine the
	differences between <emphasis>some</emphasis> file
	types—and, of course, you can still provide
	conversion filters just for them.</para>

	<indexterm><primary>apsfilter</primary></indexterm>
	<indexterm>
	<primary>printing</primary>
	<secondary>filters</secondary>
	<tertiary>apsfilter</tertiary>
	</indexterm>
	<para>The &os; Ports Collection has a text filter that
	performs automatic conversion called
	<command>apsfilter</command> (<filename
	role="package">print/apsfilter</filename>). It can
	detect plain text, &postscript;, DVI and almost any kind
	of files, run the proper conversions, and print.</para>
	</sect4>
	</sect3>

	<sect3 id="printing-advanced-of">
	<title>Output Filters</title>

	<para>The <application>LPD</application> spooling system
	supports one other type of filter that we have not yet
	explored: an output filter. An output filter is intended
	for printing plain text only, like the text filter, but
	with many simplifications. If you are using an output
	filter but no text filter, then:</para>

	<itemizedlist>
	<listitem>
	<para><application>LPD</application> starts an output
	filter once for the entire job instead of once for each
	file in the job.</para>
	</listitem>

	<listitem>
	<para><application>LPD</application> does not make any
	provision to identify the start or the end of files
	within the job for the output filter.</para>
	</listitem>

	<listitem>
	<para><application>LPD</application> does not pass the
	user's login or host to the filter, so it is not
	intended to do accounting. In fact, it gets only two
	arguments:</para>

	<cmdsynopsis>
	<command>filter-name</command>
	<arg
	choice="plain">-w<replaceable>width</replaceable></arg>
	<arg
	choice="plain">-l<replaceable>length</replaceable></arg>
	</cmdsynopsis>

	<para>Where <replaceable>width</replaceable> is from the
	<literal>pw</literal> capability and
	<replaceable>length</replaceable> is from the
	<literal>pl</literal> capability for the printer in
	question.</para>
	</listitem>
	</itemizedlist>

	<para>Do not be seduced by an output filter's simplicity.
	If you would like each file in a job to start on a different
	page an output filter <emphasis>will not work</emphasis>.
	Use a text filter (also known as an input filter); see
	section <link linkend="printing-textfilter">Installing the
	Text Filter</link>. Furthermore, an output filter is
	actually <emphasis>more complex</emphasis> in that it has
	to examine the byte stream being sent to it for special
	flag characters and must send signals to itself on behalf
	of <application>LPD</application>.</para>

	<para>However, an output filter is
	<emphasis>necessary</emphasis> if you want header pages and
	need to send escape sequences or other initialization
	strings to be able to print the header page. (But it is
	also <emphasis>futile</emphasis> if you want to charge
	header pages to the requesting user's account, since
	<application>LPD</application> does not give any user or
	host information to the output filter.)</para>

	<para>On a single printer, <application>LPD</application>
	allows both an output filter and text or other filters.
	In such cases, <application>LPD</application> will start
	the output filter to print the header page (see section
	<link linkend="printing-advanced-header-pages">Header
	Pages</link>) only. <application>LPD</application> then
	expects the output filter to <emphasis>stop
	itself</emphasis> by sending two bytes to the filter:
	ASCII 031 followed by ASCII 001. When an output filter
	sees these two bytes (031, 001), it should stop by sending
	<literal>SIGSTOP</literal> to itself. When
	<application>LPD</application>'s done running other filters,
	it will restart the output filter by sending
	<literal>SIGCONT</literal> to it.</para>

	<para>If there is an output filter but <emphasis>no</emphasis>
	text filter and <application>LPD</application> is working
	on a plain text job, <application>LPD</application> uses
	the output filter to do the job. As stated before, the
	output filter will print each file of the job in sequence
	with no intervening form feeds or other paper advancement,
	and this is probably <emphasis>not</emphasis> what you want.
	In almost all cases, you need a text filter.</para>

	<para>The program <command>lpf</command>, which we introduced
	earlier as a text filter, can also run as an output filter.
	If you need a quick-and-dirty output filter but do not want
	to write the byte detection and signal sending code, try
	<command>lpf</command>. You can also wrap
	<command>lpf</command> in a shell script to handle any
	initialization codes the printer might require.</para>
	</sect3>

	<sect3 id="printing-advanced-lpf">
	<title><command>lpf</command>: a Text Filter</title>

	<para>The program <filename>/usr/libexec/lpr/lpf</filename>
	that comes with &os; binary distribution is a text filter
	(input filter) that can indent output (job submitted with
	<command>lpr <option>-i</option></command>), allow literal
	characters to pass (job submitted with
	<command>lpr <option>-l</option></command>), adjust the
	printing position for backspaces and tabs in the job, and
	account for pages printed. It can also act like an output
	filter.</para>

	<para>The <command>lpf</command> filter is suitable for many
	printing environments. And although it has no capability
	to send initialization sequences to a printer, it is easy
	to write a shell script to do the needed initialization
	and then execute <command>lpf</command>.</para>

	<indexterm><primary>page accounting</primary></indexterm>
	<indexterm>
	<primary>accounting</primary>
	<secondary>printer</secondary>
	</indexterm>
	<para>In order for <command>lpf</command> to do page
	accounting correctly, it needs correct values filled in
	for the <literal>pw</literal> and <literal>pl</literal>
	capabilities in the <filename>/etc/printcap</filename> file.
	It uses these values to determine how much text can fit on
	a page and how many pages were in a user's job. For more
	information on printer accounting, see <link
	linkend="printing-advanced-acct">Accounting for Printer
	Usage</link>.</para>
	</sect3>
	</sect2>

	<sect2 id="printing-advanced-header-pages">
	<title>Header Pages</title>

	<para>If you have <emphasis>lots</emphasis> of users, all of
	them using various printers, then you probably want to
	consider <emphasis>header pages</emphasis> as a necessary
	evil.</para>

	<indexterm>
	<primary>banner pages</primary>
	<see>header pages</see>
	</indexterm>
	<indexterm><primary>header pages</primary></indexterm>
	<para>Header pages, also known as <emphasis>banner</emphasis>
	or <emphasis>burst pages</emphasis> identify to whom jobs
	belong after they are printed. They are usually printed in
	large, bold letters, perhaps with decorative borders, so that
	in a stack of printouts they stand out from the real documents
	that comprise users' jobs. They enable users to locate their
	jobs quickly. The obvious drawback to a header page is that
	it is yet one more sheet that has to be printed for every job,
	their ephemeral usefulness lasting not more than a few
	minutes, ultimately finding themselves in a recycling bin or
	rubbish heap. (Note that header pages go with each job, not
	each file in a job, so the paper waste might not be that
	bad.)</para>

	<para>The <application>LPD</application> system can provide
	header pages automatically for your printouts
	<emphasis>if</emphasis> your printer can directly print
	plain text. If you have a &postscript; printer, you will
	need an external program to generate the header page; see
	<link linkend="printing-advanced-header-pages-ps">Header Pages
	on &postscript; Printers</link>.</para>

	<sect3 id="printing-advanced-header-pages-enabling">
	<title>Enabling Header Pages</title>

	<para>In the <link linkend="printing-simple">Simple Printer
	Setup</link> section, we turned off header pages by
	specifying <literal>sh</literal> (meaning <quote>suppress
	header</quote>) in the <filename>/etc/printcap</filename>
	file. To enable header pages for a printer, just remove the
	<literal>sh</literal> capability.</para>

	<para>Sounds too easy, right?</para>

	<para>You are right. You <emphasis>might</emphasis> have to
	provide an output filter to send initialization strings to
	the printer. Here is an example output filter for Hewlett
	Packard PCL-compatible printers:</para>

	<programlisting>#!/bin/sh
	#
	# hpof - Output filter for Hewlett Packard PCL-compatible printers
	# Installed in /usr/local/libexec/hpof

	printf "\033&k2G" \|\| exit 2
	exec /usr/libexec/lpr/lpf</programlisting>

	<para>Specify the path to the output filter in the
	<literal>of</literal> capability. See the <link
	linkend="printing-advanced-of">Output Filters</link>
	section for more information.</para>

	<para>Here is an example <filename>/etc/printcap</filename>
	file for the printer <literal>teak</literal> that we
	introduced earlier; we enabled header pages and added the
	above output filter:</para>

	<programlisting>#
	# /etc/printcap for host orchid
	#
	teak\|hp\|laserjet\|Hewlett Packard LaserJet 3Si:\
	:lp=<filename class="devicefile">/dev/lpt0</filename>:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:\
	:if=<filename>/usr/local/libexec/hpif</filename>:\
	:vf=<filename>/usr/local/libexec/hpvf</filename>:\
	:of=<filename>/usr/local/libexec/hpof</filename>:</programlisting>

	<para>Now, when users print jobs to <literal>teak</literal>,
	they get a header page with each job. If users want to
	spend time searching for their printouts, they can suppress
	header pages by submitting the job with <command>lpr
	<option>-h</option></command>; see the <link
	linkend="printing-lpr-options-misc">Header Page
	Options</link> section for more &man.lpr.1;
	options.</para>

	<note>
	<para><application>LPD</application> prints a form feed
	character after the header page. If your printer uses
	a different character or sequence of characters to eject
	a page, specify them with the <literal>ff</literal>
	capability in <filename>/etc/printcap</filename>.</para>
	</note>
	</sect3>

	<sect3 id="printing-advanced-header-pages-controlling">
	<title>Controlling Header Pages</title>

	<para>By enabling header pages, <application>LPD</application>
	will produce a <emphasis>long header</emphasis>, a full
	page of large letters identifying the user, host, and job.
	Here is an example (<username>kelly</username> printed the
	job named <quote>outline</quote> from host
	<hostid>rose</hostid>):</para>

	<screen> k ll ll
	k l l
	k l l
	k k eeee l l y y
	k k e e l l y y
	k k eeeeee l l y y
	kk k e l l y y
	k k e e l l y yy
	k k eeee lll lll yyy y
	y
	y y
	yyyy


	ll
	t l i
	t l
	oooo u u ttttt l ii n nnn eeee
	o o u u t l i nn n e e
	o o u u t l i n n eeeeee
	o o u u t l i n n e
	o o u uu t t l i n n e e
	oooo uuu u tt lll iii n n eeee









	r rrr oooo ssss eeee
	rr r o o s s e e
	r o o ss eeeeee
	r o o ss e
	r o o s s e e
	r oooo ssss eeee







	Job: outline
	Date: Sun Sep 17 11:04:58 1995</screen>

	<para><application>LPD</application> appends a form feed after
	this text so the job starts on a new page (unless you have
	<literal>sf</literal> (suppress form feeds) in the
	destination printer's entry in
	<filename>/etc/printcap</filename>).</para>

	<para>If you prefer, <application>LPD</application> can make
	a <emphasis>short header</emphasis>; specify
	<literal>sb</literal> (short banner) in the
	<filename>/etc/printcap</filename> file. The header page
	will look like this:</para>

	<screen>rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995</screen>

	<para>Also by default, <application>LPD</application> prints
	the header page first, then the job. To reverse that,
	specify <literal>hl</literal> (header last) in
	<filename>/etc/printcap</filename>.</para>
	</sect3>

	<sect3 id="printing-advanced-header-pages-accounting">
	<title>Accounting for Header Pages</title>

	<para>Using <application>LPD</application>'s built-in header
	pages enforces a particular paradigm when it comes to
	printer accounting: header pages must be <emphasis>free of
	charge</emphasis>.</para>

	<para>Why?</para>

	<para>Because the output filter is the only external program
	that will have control when the header page is printed that
	could do accounting, and it is not provided with any
	<emphasis>user or host</emphasis> information or an
	accounting file, so it has no idea whom to charge for
	printer use. It is also not enough to just <quote>increase
	the page count by one</quote> by modifying the text
	filter or any of the conversion filters (which do have user
	and host information) since users can suppress header pages
	with <command>lpr <option>-h</option></command>. They could
	still be charged for header pages they did not print.
	Basically, <command>lpr <option>-h</option></command> will
	be the preferred option of environmentally-minded users,
	but you cannot offer any incentive to use it.</para>

	<para>It is <emphasis>still not enough</emphasis> to have each
	of the filters generate their own header pages (thereby
	being able to charge for them). If users wanted the option
	of suppressing the header pages with <command>lpr
	<option>-h</option></command>, they will still get them
	and be charged for them since <application>LPD</application>
	does not pass any knowledge of the <option>-h</option>
	option to any of the filters.</para>

	<para>So, what are your options?</para>

	<para>You can:</para>

	<itemizedlist>
	<listitem>
	<para>Accept <application>LPD</application>'s paradigm
	and make header pages free.</para>
	</listitem>

	<listitem>
	<para>Install an alternative to
	<application>LPD</application>, such as
	<application>LPRng</application>. Section <link
	linkend="printing-lpd-alternatives">Alternatives to
	the Standard Spooler</link> tells more about other
	spooling software you can substitute for
	<application>LPD</application>.</para>
	</listitem>

	<listitem>
	<para>Write a <emphasis>smart</emphasis> output filter.
	Normally, an output filter is not meant to do anything
	more than initialize a printer or do some simple
	character conversion. It is suited for header pages
	and plain text jobs (when there is no text (input)
	filter). But, if there is a text filter for the plain
	text jobs, then <application>LPD</application> will
	start the output filter only for the header pages.
	And the output filter can parse the header page text
	that <application>LPD</application> generates to
	determine what user and host to charge for the header
	page. The only other problem with this method is that
	the output filter still does not know what accounting
	file to use (it is not passed the name of the file from
	the <literal>af</literal> capability), but if you have
	a well-known accounting file, you can hard-code that
	into the output filter. To facilitate the parsing step,
	use the <literal>sh</literal> (short header) capability
	in <filename>/etc/printcap</filename>. Then again, all
	that might be too much trouble, and users will certainly
	appreciate the more generous system administrator who
	makes header pages free.</para>
	</listitem>
	</itemizedlist>
	</sect3>

	<sect3 id="printing-advanced-header-pages-ps">
	<title>Header Pages on &postscript; Printers</title>

	<para>As described above, <application>LPD</application> can
	generate a plain text header page suitable for many
	printers. Of course, &postscript; cannot directly print
	plain text, so the header page feature of
	<application>LPD</application> is useless—or mostly
	so.</para>

	<para>One obvious way to get header pages is to have every
	conversion filter and the text filter generate the header
	page. The filters should use the user and host arguments
	to generate a suitable header page. The drawback of this
	method is that users will always get a header page, even
	if they submit jobs with <command>lpr
	<option>-h</option></command>.</para>

	<para>Let us explore this method. The following script takes
	three arguments (user login name, host name, and job name)
	and makes a simple &postscript; header page:</para>

	<programlisting>#!/bin/sh
	#
	# make-ps-header - make a PostScript header page on stdout
	# Installed in /usr/local/libexec/make-ps-header
	#

	#
	# These are PostScript units (72 to the inch). Modify for A4 or
	# whatever size paper you are using:
	#
	page_width=612
	page_height=792
	border=72

	#
	# Check arguments
	#
	if [ $# -ne 3 ]; then
	echo "Usage: `basename $0` <user> <host> <job>" 1>&2
	exit 1
	fi

	#
	# Save these, mostly for readability in the PostScript, below.
	#
	user=$1
	host=$2
	job=$3
	date=`date`

	#
	# Send the PostScript code to stdout.
	#
	exec cat <<EOF
	%!PS

	%
	% Make sure we do not interfere with user's job that will follow
	%
	save

	%
	% Make a thick, unpleasant border around the edge of the paper.
	%
	$border $border moveto
	$page_width $border 2 mul sub 0 rlineto
	0 $page_height $border 2 mul sub rlineto
	currentscreen 3 -1 roll pop 100 3 1 roll setscreen
	$border 2 mul $page_width sub 0 rlineto closepath
	0.8 setgray 10 setlinewidth stroke 0 setgray

	%
	% Display user's login name, nice and large and prominent
	%
	/Helvetica-Bold findfont 64 scalefont setfont
	$page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto
	($user) show

	%
	% Now show the boring particulars
	%
	/Helvetica findfont 14 scalefont setfont
	/y 200 def
	[ (Job:) (Host:) (Date:) ] {
	200 y moveto show /y y 18 sub def }
	forall

	/Helvetica-Bold findfont 14 scalefont setfont
	/y 200 def
	[ ($job) ($host) ($date) ] {
	270 y moveto show /y y 18 sub def
	} forall

	%
	% That is it
	%
	restore
	showpage
	EOF</programlisting>

	<para>Now, each of the conversion filters and the text filter
	can call this script to first generate the header page, and
	then print the user's job. Here is the DVI conversion
	filter from earlier in this document, modified to make a
	header page:</para>

	<programlisting>#!/bin/sh
	#
	# psdf - DVI to PostScript printer filter
	# Installed in /usr/local/libexec/psdf
	#
	# Invoked by lpd when user runs lpr -d
	#

	orig_args="$@"

	fail() {
	echo "$@" 1>&2
	exit 2
	}

	while getopts "x:y:n:h:" option; do
	case $option in
	x\|y) ;; # Ignore
	n) login=$OPTARG ;;
	h) host=$OPTARG ;;
	*) echo "LPD started `basename $0` wrong." 1>&2
	exit 2
	;;
	esac
	done

	[ "$login" ] \|\| fail "No login name"
	[ "$host" ] \|\| fail "No host name"

	( /usr/local/libexec/make-ps-header $login $host "DVI File"
	/usr/local/bin/dvips -f ) \| eval /usr/local/libexec/lprps $orig_args</programlisting>

	<para>Notice how the filter has to parse the argument list in
	order to determine the user and host name. The parsing for
	the other conversion filters is identical. The text filter
	takes a slightly different set of arguments, though (see
	section <link linkend="printing-advanced-filters">How
	Filters Work</link>).</para>

	<para>As we have mentioned before, the above scheme, though
	fairly simple, disables the <quote>suppress header
	page</quote> option (the <option>-h</option> option) to
	<command>lpr</command>. If users wanted to save a tree (or
	a few pennies, if you charge for header pages), they would
	not be able to do so, since every filter's going to print a
	header page with every job.</para>

	<para>To allow users to shut off header pages on a per-job
	basis, you will need to use the trick introduced in section
	<link
	linkend="printing-advanced-header-pages-accounting">Accounting
	for Header Pages</link>: write an output filter that parses
	the LPD-generated header page and produces a &postscript;
	version. If the user submits the job with
	<command>lpr <option>-h</option></command>,
	then <application>LPD</application> will not generate a
	header page, and neither will your output filter.
	Otherwise, your output filter will read the text from
	<application>LPD</application> and send the appropriate
	header page &postscript; code to the printer.</para>

	<para>If you have a &postscript; printer on a serial line, you
	can make use of <command>lprps</command>, which comes with
	an output filter, <command>psof</command>, which does the
	above. Note that <command>psof</command> does not charge
	for header pages.</para>
	</sect3>
	</sect2>

	<sect2 id="printing-advanced-network-printers">
	<title>Networked Printing</title>

	<indexterm>
	<primary>printers</primary>
	<secondary>network</secondary>
	</indexterm>
	<indexterm><primary>network printing</primary></indexterm>
	<para>&os; supports networked printing: sending jobs to remote
	printers. Networked printing generally refers to two
	different things:</para>

	<itemizedlist>
	<listitem>
	<para>Accessing a printer attached to a remote host. You
	install a printer that has a conventional serial or
	parallel interface on one host. Then, you set up
	<application>LPD</application> to enable access to the
	printer from other hosts on the network. Section <link
	linkend="printing-advanced-network-rm">Printers
	Installed on Remote Hosts</link> tells how to do
	this.</para>
	</listitem>

	<listitem>
	<para>Accessing a printer attached directly to a network.
	The printer has a network interface in addition to (or in
	place of) a more conventional serial or parallel
	interface. Such a printer might work as follows:</para>

	<itemizedlist>
	<listitem>
	<para>It might understand the
	<application>LPD</application> protocol and can even
	queue jobs from remote hosts. In this case, it acts
	just like a regular host running
	<application>LPD</application>. Follow the same
	procedure in section <link
	linkend="printing-advanced-network-rm">Printers
	Installed on Remote Hosts</link> to set up such a
	printer.</para>
	</listitem>

	<listitem>
	<para>It might support a data stream network connection.
	In this case, you <quote>attach</quote> the printer to
	one host on the network by making that host
	responsible for spooling jobs and sending them to the
	printer. Section <link
	linkend="printing-advanced-network-net-if">Printers
	with Networked Data Stream Interfaces</link> gives
	some suggestions on installing such printers.</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</itemizedlist>

	<sect3 id="printing-advanced-network-rm">
	<title>Printers Installed on Remote Hosts</title>

	<para>The <application>LPD</application> spooling system has
	built-in support for sending jobs to other hosts also
	running <application>LPD</application> (or are compatible
	with <application>LPD</application>). This feature enables
	you to install a printer on one host and make it accessible
	from other hosts. It also works with printers that have
	network interfaces that understand the
	<application>LPD</application> protocol.</para>

	<para>To enable this kind of remote printing, first install a
	printer on one host, the <emphasis>printer host</emphasis>,
	using the simple printer setup described in the <link
	linkend="printing-simple">Simple Printer Setup</link>
	section. Do any advanced setup in <link
	linkend="printing-advanced">Advanced Printer Setup</link>
	that you need. Make sure to test the printer and see if it
	works with the features of <application>LPD</application>
	you have enabled. Also ensure that the <emphasis>local
	host</emphasis> has authorization to use the
	<application>LPD</application> service in the
	<emphasis>remote host</emphasis> (see <link
	linkend="printing-advanced-restricting-remote">Restricting
	Jobs from Remote Hosts</link>).</para>

	<indexterm>
	<primary>printers</primary>
	<secondary>network</secondary>
	</indexterm>
	<indexterm><primary>network printing</primary></indexterm>
	<para>If you are using a printer with a network interface that
	is compatible with <application>LPD</application>, then the
	<emphasis>printer host</emphasis> in the discussion below is
	the printer itself, and the <emphasis>printer
	name</emphasis> is the name you configured for the
	printer. See the documentation that accompanied your
	printer and/or printer-network interface.</para>

	<tip>
	<para>If you are using a Hewlett Packard Laserjet then the
	printer name <literal>text</literal> will automatically
	perform the LF to CRLF conversion for you, so you will not
	require the <filename>hpif</filename> script.</para>
	</tip>

	<para>Then, on the other hosts you want to have access to the
	printer, make an entry in their
	<filename>/etc/printcap</filename> files with the
	following:</para>

	<orderedlist>
	<listitem>
	<para>Name the entry anything you want. For simplicity,
	though, you probably want to use the same name and
	aliases as on the printer host.</para>
	</listitem>

	<listitem>
	<para>Leave the <literal>lp</literal> capability blank,
	explicitly (<literal>:lp=:</literal>).</para>
	</listitem>

	<listitem>
	<para>Make a spooling directory and specify its location
	in the <literal>sd</literal> capability.
	<application>LPD</application> will store jobs here
	before they get sent to the printer host.</para>
	</listitem>

	<listitem>
	<para>Place the name of the printer host in the
	<literal>rm</literal> capability.</para>
	</listitem>

	<listitem>
	<para>Place the printer name on the <emphasis>printer
	host</emphasis> in the <literal>rp</literal>
	capability.</para>
	</listitem>
	</orderedlist>

	<para>That is it. You do not need to list conversion filters,
	page dimensions, or anything else in the
	<filename>/etc/printcap</filename> file.</para>

	<para>Here is an example. The host <hostid>rose</hostid> has
	two printers, <literal>bamboo</literal> and
	<literal>rattan</literal>. We will enable users on the host
	<hostid>orchid</hostid> to print to those printers. Here is
	the <filename>/etc/printcap</filename> file for
	<hostid>orchid</hostid> (back from section <link
	linkend="printing-advanced-header-pages-enabling">Enabling
	Header Pages</link>). It already had the entry for the
	printer <literal>teak</literal>; we have added entries for
	the two printers on the host <hostid>rose</hostid>:</para>

	<programlisting>#
	# /etc/printcap for host orchid - added (remote) printers on rose
	#

	#
	# teak is local; it is connected directly to orchid:
	#
	teak\|hp\|laserjet\|Hewlett Packard LaserJet 3Si:\
	:lp=<filename class="devicefile">/dev/lpt0</filename>:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:\
	:if=<filename>/usr/local/libexec/ifhp</filename>:\
	:vf=<filename>/usr/local/libexec/vfhp</filename>:\
	:of=<filename>/usr/local/libexec/ofhp</filename>:

	#
	# rattan is connected to rose; send jobs for rattan to rose:
	#
	rattan\|line\|diablo\|lp\|Diablo 630 Line Printer:\
	:lp=:rm=rose:rp=rattan:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:

	#
	# bamboo is connected to rose as well:
	#
	bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:\
	:lp=:rm=rose:rp=bamboo:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:</programlisting>

	<para>Then, we just need to make spooling directories on
	<hostid>orchid</hostid>:</para>

	<screen>&prompt.root; <userinput><command>mkdir <option>-p</option> <filename class="directory">/var/spool/lpd/rattan</filename> <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput>
	&prompt.root; <userinput><command>chmod 770 <filename class="directory">/var/spool/lpd/rattan</filename> <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput>
	&prompt.root; <userinput><command>chown daemon:daemon <filename class="directory">/var/spool/lpd/rattan</filename> <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput></screen>

	<para>Now, users on <hostid>orchid</hostid> can print to
	<literal>rattan</literal> and <literal>bamboo</literal>.
	If, for example, a user on <hostid>orchid</hostid>
	typed:</para>

	<screen>&prompt.user; <userinput><command>lpr <option>-P</option> bamboo <option>-d</option> <filename><replaceable>sushi-review.dvi</replaceable></filename></command></userinput></screen>

	<para>the <application>LPD</application> system on
	<hostid>orchid</hostid> would copy the job to the spooling
	directory <filename
	class="directory">/var/spool/lpd/bamboo</filename> and
	note that it was a DVI job. As soon as the host
	<hostid>rose</hostid> has room in its
	<literal>bamboo</literal> spooling directory, the two
	<application>LPD</application>s would transfer the file to
	<hostid>rose</hostid>. The file would wait in
	<hostid>rose</hostid>'s queue until it was finally printed.
	It would be converted from DVI to &postscript; (since
	<literal>bamboo</literal> is a &postscript; printer) on
	<hostid>rose</hostid>.</para>
	</sect3>

	<sect3 id="printing-advanced-network-net-if">
	<title>Printers with Networked Data Stream Interfaces</title>

	<para>Often, when you buy a network interface card for a
	printer, you can get two versions: one which emulates a
	spooler (the more expensive version), or one which just lets
	you send data to it as if
	you were using a serial or parallel port (the cheaper
	version). This section tells how to use the cheaper
	version. For the more expensive one, see the previous
	section <link
	linkend="printing-advanced-network-rm">Printers Installed
	on Remote Hosts</link>.</para>

	<para>The format of the <filename>/etc/printcap</filename>
	file lets you specify what serial or parallel interface to
	use, and (if you are using a serial interface), what baud
	rate, whether to use flow control, delays for tabs,
	conversion of newlines, and more. But there is no way to
	specify a connection to a printer that is listening on a
	TCP/IP or other network port.</para>

	<para>To send data to a networked printer, you need to develop
	a communications program that can be called by the text and
	conversion filters. Here is one such example: the script
	<command>netprint</command> takes all data on standard input
	and sends it to a network-attached printer. We specify the
	hostname of the printer as the first argument and the port
	number to which to connect as the second argument to
	<command>netprint</command>. Note that this supports
	one-way communication only (&os; to printer); many network
	printers support two-way communication, and you might want
	to take advantage of that (to get printer status, perform
	accounting, etc.).</para>

	<programlisting>#!/usr/bin/perl
	#
	# netprint - Text filter for printer attached to network
	# Installed in /usr/local/libexec/netprint
	#
	$#ARGV eq 1 \|\| die "Usage: $0 <printer-hostname> <port-number>";

	$printer_host = $ARGV[0];
	$printer_port = $ARGV[1];

	require 'sys/socket.ph';

	($ignore, $ignore, $protocol) = getprotobyname('tcp');
	($ignore, $ignore, $ignore, $ignore, $address)
	= gethostbyname($printer_host);

	$sockaddr = pack('S n a4 x8', &AF_INET, $printer_port, $address);

	socket(PRINTER, &PF_INET, &SOCK_STREAM, $protocol)
	\|\| die "Can't create TCP/IP stream socket: $!";
	connect(PRINTER, $sockaddr) \|\| die "Can't contact $printer_host: $!";
	while (<STDIN>) { print PRINTER; }
	exit 0;</programlisting>

	<para>We can then use this script in various filters. Suppose
	we had a Diablo 750-N line printer connected to the network.
	The printer accepts data to print on port number 5100. The
	host name of the printer is <hostid>scrivener</hostid>.
	Here is the text filter for the printer:</para>

	<programlisting>#!/bin/sh
	#
	# diablo-if-net - Text filter for Diablo printer `scrivener' listening
	# on port 5100. Installed in /usr/local/libexec/diablo-if-net
	#
	exec /usr/libexec/lpr/lpf "$@" \| /usr/local/libexec/netprint scrivener 5100</programlisting>
	</sect3>
	</sect2>

	<sect2 id="printing-advanced-restricting">
	<title>Restricting Printer Usage</title>

	<indexterm>
	<primary>printers</primary>
	<secondary>restricting access to</secondary>
	</indexterm>
	<para>This section gives information on restricting printer
	usage. The <application>LPD</application> system lets you
	control who can access a printer, both locally or remotely,
	whether they can print multiple copies, how large their jobs
	can be, and how large the printer queues can get.</para>

	<sect3 id="printing-advanced-restricting-copies">
	<title>Restricting Multiple Copies</title>

	<para>The <application>LPD</application> system makes it easy
	for users to print multiple copies of a file. Users can
	print jobs with <command>lpr <option>-#5</option></command>
	(for example) and get five copies of each file in the job.
	Whether this is a good thing is up to you.</para>

	<para>If you feel multiple copies cause unnecessary wear and
	tear on your printers, you can disable the
	<option>-#</option> option to &man.lpr.1; by adding the
	<literal>sc</literal> capability to the
	<filename>/etc/printcap</filename> file. When users submit
	jobs with the <option>-#</option> option, they will
	see:</para>

	<screen>lpr: multiple copies are not allowed</screen>

	<para>Note that if you have set up access to a printer
	remotely (see section <link
	linkend="printing-advanced-network-rm">Printers
	Installed on Remote Hosts</link>), you need the
	<literal>sc</literal> capability on the remote
	<filename>/etc/printcap</filename> files as well, or else
	users will still be able to submit multiple-copy jobs by
	using another host.</para>

	<para>Here is an example. This is the
	<filename>/etc/printcap</filename> file for the host
	<hostid>rose</hostid>. The printer
	<literal>rattan</literal> is quite hearty, so we will allow
	multiple copies, but the laser
	printer <literal>bamboo</literal> is a bit more delicate, so
	we will disable multiple copies by adding the
	<literal>sc</literal> capability:</para>

	<programlisting>#
	# /etc/printcap for host rose - restrict multiple copies on bamboo
	#
	rattan\|line\|diablo\|lp\|Diablo 630 Line Printer:\
	:sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\
	:lp=<filename class="devicefile">/dev/lpt0</filename>:\
	:if=<filename>/usr/local/libexec/if-simple</filename>:

	bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:\
	:sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:\
	:lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\
	:if=<filename>/usr/local/libexec/psif</filename>:\
	:df=<filename>/usr/local/libexec/psdf</filename>:</programlisting>

	<para>Now, we also need to add the <literal>sc</literal>
	capability on the host <hostid>orchid</hostid>'s
	<filename>/etc/printcap</filename> (and while we are at it,
	let us disable multiple copies for the printer
	<literal>teak</literal>):</para>

	<programlisting>#
	# /etc/printcap for host orchid - no multiple copies for local
	# printer teak or remote printer bamboo
	teak\|hp\|laserjet\|Hewlett Packard LaserJet 3Si:\
	:lp=<filename class="devicefile">/dev/lpt0</filename>:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:sc:\
	:if=<filename>/usr/local/libexec/ifhp</filename>:\
	:vf=<filename>/usr/local/libexec/vfhp</filename>:\
	:of=<filename>/usr/local/libexec/ofhp</filename>:

	rattan\|line\|diablo\|lp\|Diablo 630 Line Printer:\
	:lp=:rm=rose:rp=rattan:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:

	bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:\
	:lp=:rm=rose:rp=bamboo:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:</programlisting>

	<para>By using the <literal>sc</literal> capability, we
	prevent the use of <command>lpr
	<option>-#</option></command>, but that still
	does not prevent users from running &man.lpr.1; multiple
	times, or from submitting the same file multiple times in
	one job like this:</para>

	<screen>&prompt.user; <userinput>lpr <filename><replaceable>forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign</replaceable></filename></userinput></screen>

	<para>There are many ways to prevent this abuse (including
	ignoring it) which you are free to explore.</para>
	</sect3>

	<sect3 id="printing-advanced-restricting-access">
	<title>Restricting Access to Printers</title>

	<para>You can control who can print to what printers by using
	the &unix; group mechanism and the <literal>rg</literal>
	capability in <filename>/etc/printcap</filename>. Just
	place the users you want to have access to a printer in a
	certain group, and then name that group in the
	<literal>rg</literal> capability.</para>

	<para>If users outside the group (including
	<username>root</username>) try to print to the controlled
	printer then they will be greeted with the following
	message:</para>

	<screen>lpr: Not a member of the restricted group</screen>

	<para>As with the <literal>sc</literal> (suppress multiple
	copies) capability, you need to specify
	<literal>rg</literal> on remote hosts that also have access
	to your printers, if you feel it is appropriate (see section
	<link linkend="printing-advanced-network-rm">Printers
	Installed on Remote Hosts</link>).</para>

	<para>For example, we will let anyone access the printer
	<literal>rattan</literal>, but only those in group
	<groupname>artists</groupname> can use
	<literal>bamboo</literal>. Here is the familiar
	<filename>/etc/printcap</filename> for host
	<hostid>rose</hostid>:</para>

	<programlisting>#
	# /etc/printcap for host rose - restricted group for bamboo
	#
	rattan\|line\|diablo\|lp\|Diablo 630 Line Printer:\
	:sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\
	:lp=<filename class="devicefile">/dev/lpt0</filename>:\
	:if=<filename>/usr/local/libexec/if-simple</filename>:

	bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:\
	:sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:rg=artists:\
	:lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\
	:if=<filename>/usr/local/libexec/psif</filename>:\
	:df=<filename>/usr/local/libexec/psdf</filename>:</programlisting>

	<para>Let us leave the other example
	<filename>/etc/printcap</filename> file (for the host
	<hostid>orchid</hostid>) alone. Of course, anyone on
	<hostid>orchid</hostid> can print to
	<literal>bamboo</literal>. It
	might be the case that we only allow certain logins on
	<hostid>orchid</hostid> anyway, and want them to have access
	to the printer. Or not.</para>

	<note>
	<para>There can be only one restricted group per
	printer.</para>
	</note>
	</sect3>

	<sect3 id="printing-advanced-restricting-sizes">
	<title>Controlling Sizes of Jobs Submitted</title>

	<indexterm><primary>print jobs</primary></indexterm>
	<para>If you have many users accessing the printers, you
	probably need to put an upper limit on the sizes of the
	files users can submit to print. After all, there is only
	so much free space on the filesystem that houses the
	spooling directories, and you also need to make sure there
	is room for the jobs of other users.</para>

	<indexterm>
	<primary>print jobs</primary>
	<secondary>controlling</secondary>
	</indexterm>
	<para><application>LPD</application> enables you to limit the
	maximum byte size a file in a job can be with the
	<literal>mx</literal> capability. The units are in
	<literal>BUFSIZ</literal> blocks, which are 1024 bytes. If
	you put a zero for this capability, there will be no limit
	on file size; however, if no <literal>mx</literal>
	capability is specified, then a default limit of 1000 blocks
	will be used.</para>

	<note>
	<para>The limit applies to <emphasis>files</emphasis> in a
	job, and <emphasis>not</emphasis> the total job
	size.</para>
	</note>

	<para><application>LPD</application> will not refuse a file
	that is larger than the limit you place on a printer.
	Instead, it will queue as much of the file up to the limit,
	which will then get printed. The rest will be discarded.
	Whether this is correct behavior is up for debate.</para>

	<para>Let us add limits to our example printers
	<literal>rattan</literal> and <literal>bamboo</literal>.
	Since those <groupname>artists</groupname>' &postscript;
	files tend to be large, we will limit them to five
	megabytes. We will put no limit on the plain text line
	printer:</para>

	<programlisting>#
	# /etc/printcap for host rose
	#

	#
	# No limit on job size:
	#
	rattan\|line\|diablo\|lp\|Diablo 630 Line Printer:\
	:sh:mx#0:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\
	:lp=<filename class="devicefile">/dev/lpt0</filename>:\
	:if=<filename>/usr/local/libexec/if-simple</filename>:

	#
	# Limit of five megabytes:
	#
	bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:\
	:sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:rg=artists:mx#5000:\
	:lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\
	:if=<filename>/usr/local/libexec/psif</filename>:\
	:df=<filename>/usr/local/libexec/psdf</filename>:</programlisting>

	<para>Again, the limits apply to the local users only. If you
	have set up access to your printers remotely, remote users
	will not get those limits. You will need to specify the
	<literal>mx</literal> capability in the remote
	<filename>/etc/printcap</filename> files as well. See
	section <link
	linkend="printing-advanced-network-rm">Printers Installed
	on Remote Hosts</link> for more information on remote
	printing.</para>

	<para>There is another specialized way to limit job sizes from
	remote printers; see section <link
	linkend="printing-advanced-restricting-remote">Restricting
	Jobs from Remote Hosts</link>.</para>
	</sect3>

	<sect3 id="printing-advanced-restricting-remote">
	<title>Restricting Jobs from Remote Hosts</title>

	<para>The <application>LPD</application> spooling system
	provides several ways to restrict print jobs submitted from
	remote hosts:</para>

	<variablelist>
	<varlistentry>
	<term>Host restrictions</term>

	<listitem>
	<para>You can control from which remote hosts a local
	<application>LPD</application> accepts requests with
	the files <filename>/etc/hosts.equiv</filename> and
	<filename>/etc/hosts.lpd</filename>.
	<application>LPD</application> checks to see if an
	incoming request is from a host listed in either one
	of these files. If not,
	<application>LPD</application> refuses the
	request.</para>

	<para>The format of these files is simple: one host name
	per line. Note that the file
	<filename>/etc/hosts.equiv</filename> is also used by
	the &man.ruserok.3; protocol, and affects programs
	like &man.rsh.1; and &man.rcp.1;, so be
	careful.</para>

	<para>For example, here is the
	<filename>/etc/hosts.lpd</filename> file on the host
	<hostid>rose</hostid>:</para>

	<programlisting>orchid
	violet
	madrigal.fishbaum.de</programlisting>

	<para>This means <hostid>rose</hostid> will accept
	requests from the hosts <hostid>orchid</hostid>,
	<hostid>violet</hostid>, and <hostid
	role="fqdn">madrigal.fishbaum.de</hostid>. If any
	other host tries to access <hostid>rose</hostid>'s
	<application>LPD</application>, the job will be
	refused.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Size restrictions</term>

	<listitem>
	<para>You can control how much free space there needs to
	remain on the filesystem where a spooling directory
	resides. Make a file called
	<filename>minfree</filename> in the spooling
	directory for the local printer. Insert in that file
	a number representing how many disk blocks (512 bytes)
	of free space there has to be for a remote job to be
	accepted.</para>

	<para>This lets you insure that remote users will not
	fill your filesystem. You can also use it to give a
	certain priority to local users: they will be able to
	queue jobs long after the free disk space has fallen
	below the amount specified in the
	<filename>minfree</filename> file.</para>

	<para>For example, let us add a
	<filename>minfree</filename> file for the printer
	<literal>bamboo</literal>. We examine
	<filename>/etc/printcap</filename> to find the
	spooling directory for this printer; here is
	<literal>bamboo</literal>'s entry:</para>

	<programlisting>bamboo\|ps\|PS\|S\|panasonic\|Panasonic KX-P4455 PostScript v51.4:\
	:sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:rg=artists:mx#5000:\
	:lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:mx#5000:\
	:if=<filename>/usr/local/libexec/psif</filename>:\
	:df=<filename>/usr/local/libexec/psdf</filename>:</programlisting>

	<para>The spooling directory is given in the
	<literal>sd</literal> capability. We will make three
	megabytes (which is 6144 disk blocks) the amount of
	free disk space that must exist on the filesystem for
	<application>LPD</application> to accept remote
	jobs:</para>

	<screen>&prompt.root; <userinput><command>echo 6144 > <filename>/var/spool/lpd/bamboo/minfree</filename></command></userinput></screen>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>User restrictions</term>

	<listitem>
	<para>You can control which remote users can print to
	local printers by specifying the <literal>rs</literal>
	capability in <filename>/etc/printcap</filename>.
	When <literal>rs</literal> appears in the entry for a
	locally-attached printer,
	<application>LPD</application> will accept jobs from
	remote hosts <emphasis>if</emphasis> the user
	submitting the job also has an account of the same
	login name on the local host. Otherwise,
	<application>LPD</application> refuses the job.</para>

	<para>This capability is particularly useful in an
	environment where there are (for example) different
	departments sharing a network, and some users
	transcend departmental boundaries. By giving them
	accounts on your systems, they can use your printers
	from their own departmental systems. If you would
	rather allow them to use <emphasis>only</emphasis>
	your printers and not your computer resources, you can
	give them <quote>token</quote> accounts, with no home
	directory and a useless shell like
	<filename>/usr/bin/false</filename>.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect3>
	</sect2>

	<sect2 id="printing-advanced-acct">
	<title>Accounting for Printer Usage</title>

	<indexterm>
	<primary>accounting</primary>
	<secondary>printer</secondary>
	</indexterm>
	<para>So, you need to charge for printouts. And why not? Paper
	and ink cost money. And then there are maintenance
	costs—printers are loaded with moving parts and tend to
	break down. You have examined your printers, usage patterns,
	and maintenance fees and have come up with a per-page (or
	per-foot, per-meter, or per-whatever) cost. Now, how do you
	actually start accounting for printouts?</para>

	<para>Well, the bad news is the <application>LPD</application>
	spooling system does not provide much help in this department.
	Accounting is highly dependent on the kind of printer in use,
	the formats being printed, and <emphasis>your</emphasis>
	equirements in charging for printer usage.</para>

	<para>To implement accounting, you have to modify a printer's
	text filter (to charge for plain text jobs) and the conversion
	filters (to charge for other file formats), to count pages or
	query the printer for pages printed. You cannot get away with
	using the simple output filter, since it cannot do accounting.
	See section <link
	linkend="printing-advanced-filter-intro">Filters</link>.</para>

	<para>Generally, there are two ways to do accounting:</para>

	<itemizedlist>
	<listitem>
	<para><emphasis>Periodic accounting</emphasis> is the more
	common way, possibly because it is easier. Whenever
	someone prints a job, the filter logs the user, host, and
	number of pages to an accounting file. Every month,
	semester, year, or whatever time period you prefer, you
	collect the accounting files for the various printers,
	tally up the pages printed by users, and charge for usage.
	Then you truncate all the logging files, starting with
	a clean slate for the next period.</para>
	</listitem>

	<listitem>
	<para><emphasis>Timely accounting</emphasis> is less common,
	probably because it is more difficult. This method has
	the filters charge users for printouts as soon as they use
	the printers. Like disk quotas, the accounting is
	immediate. You can prevent users from printing when their
	account goes in the red, and might provide a way for users
	to check and adjust their <quote>print quotas</quote>.
	But this method requires some database code to track users
	and their quotas.</para>
	</listitem>
	</itemizedlist>

	<para>The <application>LPD</application> spooling system
	supports both methods easily: since you have to provide the
	filters (well, most of the time), you also have to provide the
	accounting code. But there is a bright side: you have
	enormous flexibility in your accounting methods. For example,
	you choose whether to use periodic or timely accounting. You
	choose what information to log: user names, host names, job
	types, pages printed, square footage of paper used, how long
	the job took to print, and so forth. And you do so by
	modifying the filters to save this information.</para>

	<sect3>
	<title>Quick and Dirty Printer Accounting</title>

	<para>&os; comes with two programs that can get you set up
	with simple periodic accounting right away. They are the
	text filter <command>lpf</command>, described in section
	<link linkend="printing-advanced-lpf">lpf: a Text
	Filter</link>, and &man.pac.8;, a program to gather and
	total entries from printer accounting files.</para>

	<para>As mentioned in the section on filters (<link
	linkend="printing-advanced-filters">Filters</link>),
	<application>LPD</application> starts the text and the
	conversion filters with the name of the accounting file to
	use on the filter command line. The filters can use this
	argument to know where to write an accounting file entry.
	The name of this file comes from the <literal>af</literal>
	capability in <filename>/etc/printcap</filename>, and if not
	specified as an absolute path, is relative to the spooling
	directory.</para>

	<para><application>LPD</application> starts
	<command>lpf</command> with page width and length arguments
	(from the <literal>pw</literal> and <literal>pl</literal>
	capabilities). The <command>lpf</command> filter uses these
	arguments to determine how much paper will be used. After
	sending the file to the printer, it then writes an
	accounting entry in the accounting file. The entries look
	like this:</para>

	<programlisting>2.00 rose:andy
	3.00 rose:kelly
	3.00 orchid:mary
	5.00 orchid:mary
	2.00 orchid:zhang</programlisting>

	<para>You should use a separate accounting file for each
	printer, as <command>lpf</command> has no file locking logic
	built into it, and two <command>lpf</command>s might corrupt
	each other's entries if they were to write to the same file
	at the same time. An easy way to insure a separate
	accounting file for each printer is to use
	<literal>af=acct</literal> in
	<filename>/etc/printcap</filename>. Then, each accounting
	file will be in the spooling directory for a printer, in a
	file named <filename>acct</filename>.</para>

	<para>When you are ready to charge users for printouts, run
	the &man.pac.8; program. Just change to the spooling
	directory for the printer you want to collect on and type
	<command>pac</command>. You will get a dollar-centric
	summary like the following:</para>

	<screen> Login pages/feet runs price
	orchid:kelly 5.00 1 $ 0.10
	orchid:mary 31.00 3 $ 0.62
	orchid:zhang 9.00 1 $ 0.18
	rose:andy 2.00 1 $ 0.04
	rose:kelly 177.00 104 $ 3.54
	rose:mary 87.00 32 $ 1.74
	rose:root 26.00 12 $ 0.52

	total 337.00 154 $ 6.74</screen>

	<para>These are the arguments &man.pac.8; expects:</para>

	<variablelist>
	<varlistentry>
	<term><option>-P<replaceable>printer</replaceable></option></term>

	<listitem>
	<para>Which <replaceable>printer</replaceable> to
	summarize. This option works only if there is an
	absolute path in the <literal>af</literal> capability
	in <filename>/etc/printcap</filename>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-c</option></term>

	<listitem>
	<para>Sort the output by cost instead of alphabetically
	by user name.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-m</option></term>

	<listitem>
	<para>Ignore host name in the accounting files. With
	this option, user <username>smith</username> on host
	<hostid>alpha</hostid> is the same user
	<username>smith</username> on host
	<hostid>gamma</hostid>. Without, they are different
	users.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-p<replaceable>price</replaceable></option></term>

	<listitem>
	<para>Compute charges with
	<replaceable>price</replaceable> dollars per page or
	per foot instead of the price from the
	<literal>pc</literal> capability in
	<filename>/etc/printcap</filename>, or two cents (the
	default). You can specify
	<replaceable>price</replaceable> as a floating point
	number.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-r</option></term>

	<listitem>
	<para>Reverse the sort order.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-s</option></term>

	<listitem>
	<para>Make an accounting summary file and truncate the
	accounting file.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><replaceable>name</replaceable>
	<replaceable>…</replaceable></term>

	<listitem>
	<para>Print accounting information for the given user
	<replaceable>names</replaceable> only.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>In the default summary that &man.pac.8; produces, you
	see the number of pages printed by each user from various
	hosts. If, at your site, host does not matter (because
	users can use any host), run <command>pac
	<option>-m</option></command>, to produce the following
	summary:</para>

	<screen> Login pages/feet runs price
	andy 2.00 1 $ 0.04
	kelly 182.00 105 $ 3.64
	mary 118.00 35 $ 2.36
	root 26.00 12 $ 0.52
	zhang 9.00 1 $ 0.18

	total 337.00 154 $ 6.74</screen>


	<para>To compute the dollar amount due,
	&man.pac.8; uses the <literal>pc</literal> capability in the
	<filename>/etc/printcap</filename> file (default of 200, or
	2 cents per page). Specify, in hundredths of cents, the
	price per page or per foot you want to charge for printouts
	in this capability. You can override this value when you
	run &man.pac.8; with the <option>-p</option> option. The
	units for the <option>-p</option> option are in dollars,
	though, not hundredths of cents. For example,</para>

	<screen>&prompt.root; <userinput><command>pac <option>-p1.50</option></command></userinput></screen>

	<para>makes each page cost one dollar and fifty cents. You
	can really rake in the profits by using this option.</para>

	<para>Finally, running <command>pac
	<option>-s</option></command> will
	save the summary information in a summary accounting file,
	which is named the same as the printer's accounting file,
	but with <literal>_sum</literal> appended to the name. It
	then truncates the accounting file. When you run
	&man.pac.8; again, it rereads the summary file to get
	starting totals, then adds information from the regular
	accounting file.</para>
	</sect3>

	<sect3>
	<title>How Can You Count Pages Printed?</title>

	<para>In order to perform even remotely accurate accounting,
	you need to be able to determine how much paper a job uses.
	This is the essential problem of printer accounting.</para>

	<para>For plain text jobs, the problem is not that hard to
	solve: you count how many lines are in a job and compare it
	to how many lines per page your printer supports. Do not
	forget to take into account backspaces in the file which
	overprint lines, or long logical lines that wrap onto one or
	more additional physical lines.</para>

	<para>The text filter <command>lpf</command> (introduced in
	<link linkend="printing-advanced-lpf">lpf: a Text
	Filter</link>) takes into account these things when it
	does accounting. If you are writing a text filter which
	needs to do accounting, you might want to examine
	<command>lpf</command>'s source code.</para>

	<para>How do you handle other file formats, though?</para>

	<para>Well, for DVI-to-LaserJet or DVI-to-&postscript;
	conversion, you can have your filter parse the diagnostic
	output of <command>dvilj</command> or
	<command>dvips</command> and look to see how many pages were
	converted. You might be able to do similar things with
	other file formats and conversion programs.</para>

	<para>But these methods suffer from the fact that the printer
	may not actually print all those pages. For example, it
	could jam, run out of toner, or explode—and the user
	would still get charged.</para>

	<para>So, what can you do?</para>

	<para>There is only one <emphasis>sure</emphasis> way to do
	<emphasis>accurate</emphasis> accounting. Get a printer
	that can tell you how much paper it uses, and attach it via
	a serial line or a network connection. Nearly all
	&postscript; printers support this notion. Other makes and
	models do as well (networked Imagen laser printers, for
	example). Modify the filters for these printers to get the
	page usage after they print each job and have them log
	accounting information based on that value
	<emphasis>only</emphasis>. There is no line counting nor
	error-prone file examination required.</para>

	<para>Of course, you can always be generous and make all
	printouts free.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="printing-using">
	<title>Using Printers</title>

	<indexterm>
	<primary>printers</primary>
	<secondary>usage</secondary>
	</indexterm>
	<para>This section tells you how to use printers you have set up
	with &os;. Here is an overview of the user-level
	commands:</para>

	<variablelist>
	<varlistentry>
	<term>&man.lpr.1;</term>

	<listitem>
	<para>Print jobs</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&man.lpq.1;</term>

	<listitem>
	<para>Check printer queues</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>&man.lprm.1;</term>

	<listitem>
	<para>Remove jobs from a printer's queue</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>There is also an administrative command, &man.lpc.8;,
	described in the section <link
	linkend="printing-lpc">Administering Printers</link>, used to
	control printers and their queues.</para>

	<para>All three of the commands &man.lpr.1;, &man.lprm.1;, and
	&man.lpq.1; accept an option <option>-P
	<replaceable>printer-name</replaceable></option> to specify
	on which printer/queue to operate, as listed in the
	<filename>/etc/printcap</filename> file. This enables you to
	submit, remove, and check on jobs for various printers. If you
	do not use the <option>-P</option> option, then these commands
	use the printer specified in the <envar>PRINTER</envar>
	environment variable. Finally, if you do not have a
	<envar>PRINTER</envar> environment variable, these commands
	default to the printer named <literal>lp</literal>.</para>

	<para>Hereafter, the terminology <emphasis>default
	printer</emphasis> means the printer named in the
	<envar>PRINTER</envar> environment variable, or the printer
	named <literal>lp</literal> when there is no
	<envar>PRINTER</envar> environment variable.</para>

	<sect2 id="printing-lpr">
	<title>Printing Jobs</title>

	<para>To print files, type:</para>

	<screen>&prompt.user; <userinput><command>lpr <filename><replaceable>filename</replaceable></filename> <replaceable>...</replaceable></command></userinput></screen>

	<indexterm><primary>printing</primary></indexterm>
	<para>This prints each of the listed files to the default
	printer. If you list no files, &man.lpr.1; reads data to
	print from standard input. For example, this command prints
	some important system files:</para>

	<screen>&prompt.user; <userinput><command>lpr <filename>/etc/host.conf</filename> <filename>/etc/hosts.equiv</filename></command></userinput></screen>

	<para>To select a specific printer, type:</para>

	<screen>&prompt.user; <userinput><command>lpr <option>-P</option> <replaceable>printer-name</replaceable> <filename><replaceable>filename</replaceable></filename> <replaceable>...</replaceable></command></userinput></screen>

	<para>This example prints a long listing of the current
	directory to the printer named
	<literal>rattan</literal>:</para>

	<screen>&prompt.user; <userinput><command>ls <option>-l</option> \| lpr <option>-P</option> rattan</command></userinput></screen>

	<para>Because no files were listed for the &man.lpr.1; command,
	<command>lpr</command> read the data to print from standard
	input, which was the output of the <command>ls
	<option>-l</option></command> command.</para>

	<para>The &man.lpr.1; command can also accept a wide variety of
	options to control formatting, apply file conversions,
	generate multiple copies, and so forth. For more information,
	see the section <link linkend="printing-lpr-options">Printing
	Options</link>.</para>
	</sect2>

	<sect2 id="printing-lpq">
	<title>Checking Jobs</title>

	<indexterm><primary>print jobs</primary></indexterm>
	<para>When you print with &man.lpr.1;, the data you wish to
	print is put together in a package called a <quote>print
	job</quote>, which is sent to the
	<application>LPD</application> spooling system. Each printer
	has a queue of jobs, and your job waits in that queue along
	with other jobs from yourself and from other users. The
	printer prints those jobs in a first-come, first-served
	order.</para>

	<para>To display the queue for the default printer, type
	&man.lpq.1;. For a specific printer, use the
	<option>-P</option> option. For example, the command

	<screen>&prompt.user; <userinput><command>lpq <option>-P</option> bamboo</command></userinput></screen>

	shows the queue for the printer named
	<literal>bamboo</literal>. Here is an example of the output
	of the <command>lpq</command> command:</para>

	<screen>bamboo is ready and printing
	Rank Owner Job Files Total Size
	active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes
	2nd kelly 10 (standard input) 1635 bytes
	3rd mary 11 ... 78519 bytes</screen>

	<para>This shows three jobs in the queue for
	<literal>bamboo</literal>. The first job, submitted by user
	kelly, got assigned <quote>job number</quote> 9. Every job
	for a printer gets a unique job number. Most of the time you
	can ignore the job number, but you will need it if you want to
	cancel the job; see section <link
	linkend="printing-lprm">Removing Jobs</link> for
	details.</para>

	<para>Job number nine consists of two files; multiple files
	given on the &man.lpr.1; command line are treated as part of a
	single job. It is the currently active job (note the word
	<literal>active</literal> under the <quote>Rank</quote>
	column), which means the printer should be currently printing
	that job. The second job consists of data passed as the
	standard input to the &man.lpr.1; command. The third job came
	from user <username>mary</username>; it is a much larger job.
	The pathname of the file she is trying to print is too long to
	fit, so the &man.lpq.1; command just shows three dots.</para>

	<para>The very first line of the output from &man.lpq.1; is also
	useful: it tells what the printer is currently doing (or at
	least what <application>LPD</application> thinks the printer
	is doing).</para>

	<para>The &man.lpq.1; command also support a <option>-l</option>
	option to generate a detailed long listing. Here is an
	example of <command>lpq <option>-l</option></command>:</para>

	<screen>waiting for bamboo to become ready (offline ?)
	kelly: 1st [job 009rose]
	/etc/host.conf 73 bytes
	/etc/hosts.equiv 15 bytes

	kelly: 2nd [job 010rose]
	(standard input) 1635 bytes

	mary: 3rd [job 011rose]
	/home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytes</screen>
	</sect2>

	<sect2 id="printing-lprm">
	<title>Removing Jobs</title>

	<para>If you change your mind about printing a job, you can
	remove the job from the queue with the &man.lprm.1; command.
	Often, you can even use &man.lprm.1; to remove an active job,
	but some or all of the job might still get printed.</para>

	<para>To remove a job from the default printer, first use
	&man.lpq.1; to find the job number. Then type:</para>

	<screen>&prompt.user; <userinput><command>lprm <replaceable>job-number</replaceable></command></userinput></screen>

	<para>To remove the job from a specific printer, add the
	<option>-P</option> option. The following command removes job
	number 10 from the queue for the printer
	<literal>bamboo</literal>:</para>

	<screen>&prompt.user; <userinput><command>lprm <option>-P</option> bamboo 10</command></userinput></screen>

	<para>The &man.lprm.1; command has a few shortcuts:</para>

	<variablelist>
	<varlistentry>
	<term>lprm -</term>

	<listitem>
	<para>Removes all jobs (for the default printer) belonging
	to you.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>lprm <replaceable>user</replaceable></term>

	<listitem>
	<para>Removes all jobs (for the default printer) belonging
	to <replaceable>user</replaceable>. The superuser can
	remove other users' jobs; you can remove only your own
	jobs.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>lprm</term>

	<listitem>
	<para>With no job number, user name, or <option>-</option>
	appearing on the command line, &man.lprm.1; removes the
	currently active job on the default printer, if it
	belongs to you. The superuser can remove any active
	job.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>Just use the <option>-P</option> option with the above
	shortcuts to operate on a specific printer instead of the
	default. For example, the following command removes all jobs
	for the current user in the queue for the printer named
	<literal>rattan</literal>:</para>

	<screen>&prompt.user; <userinput><command>lprm <option>-P</option> rattan -</command></userinput></screen>

	<note>
	<para>If you are working in a networked environment,
	&man.lprm.1; will let you remove jobs only from the host
	from which the jobs were submitted, even if the same printer
	is available from other hosts. The following command
	sequence demonstrates this:</para>

	<screen>&prompt.user; <userinput><command>lpr <option>-P</option> rattan <filename><replaceable>myfile</replaceable></filename></command></userinput>
	&prompt.user; <userinput><command>rlogin orchid</command></userinput>
	&prompt.user; <userinput><command>lpq <option>-P</option> rattan</command></userinput>
	Rank Owner Job Files Total Size
	active seeyan 12 ... 49123 bytes
	2nd kelly 13 myfile 12 bytes
	&prompt.user; <userinput><command>lprm <option>-P</option> rattan 13</command></userinput>
	rose: Permission denied
	&prompt.user; <userinput><command>logout</command></userinput>
	&prompt.user; <userinput><command>lprm <option>-P</option> rattan 13</command></userinput>
	dfA013rose dequeued
	cfA013rose dequeued</screen>
	</note>
	</sect2>

	<sect2 id="printing-lpr-options">
	<title>Beyond Plain Text: Printing Options</title>

	<para>The &man.lpr.1; command supports a number of options that
	control formatting text, converting graphic and other file
	formats, producing multiple copies, handling of the job, and
	more. This section describes the options.</para>

	<sect3 id="printing-lpr-options-format">
	<title>Formatting and Conversion Options</title>

	<para>The following &man.lpr.1; options control formatting of
	the files in the job. Use these options if the job does not
	contain plain text or if you want plain text formatted
	through the &man.pr.1; utility.</para>

	<indexterm><primary>&tex;</primary></indexterm>
	<para>For example, the following command prints a DVI file
	(from the &tex; typesetting system) named
	<filename><replaceable>fish-report.dvi</replaceable></filename>
	to the printer named <literal>bamboo</literal>:</para>

	<screen>&prompt.user; <userinput><command>lpr <option>-P</option> bamboo -d <filename><replaceable>fish-report.dvi</replaceable></filename></command></userinput></screen>

	<para>These options apply to every file in the job, so you
	cannot mix (say) DVI and ditroff files together in a job.
	Instead, submit the files as separate jobs, using a
	different conversion option for each job.</para>

	<note>
	<para>All of these options except <option>-p</option> and
	<option>-T</option> require conversion filters installed
	for the destination printer. For example, the
	<option>-d</option> option requires the DVI conversion
	filter. Section <link
	linkend="printing-advanced-convfilters">Conversion
	Filters</link> gives details.</para>
	</note>

	<variablelist>
	<varlistentry>
	<term><option>-c</option></term>

	<listitem>
	<para>Print cifplot files.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-d</option></term>

	<listitem>
	<para>Print DVI files.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-f</option></term>

	<listitem>
	<para>Print FORTRAN text files.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-g</option></term>

	<listitem>
	<para>Print plot data.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-i
	<replaceable>number</replaceable></option></term>

	<listitem>
	<para>Indent the output by
	<replaceable>number</replaceable> columns; if you omit
	<replaceable>number</replaceable>, indent by 8
	columns. This option works only with certain
	conversion filters.</para>

	<note>
	<para>Do not put any space between the
	<option>-i</option> and the number.</para>
	</note>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-l</option></term>

	<listitem>
	<para>Print literal text data, including control
	characters.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-n</option></term>

	<listitem>
	<para>Print ditroff (device independent troff)
	data.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-p</term>

	<listitem>
	<para>Format plain text with &man.pr.1; before printing.
	See &man.pr.1; for more information.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-T
	<replaceable>title</replaceable></option></term>

	<listitem>
	<para>Use <replaceable>title</replaceable> on the
	&man.pr.1; header instead of the file name. This
	option has effect only when used with the
	<option>-p</option>
	option.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-t</option></term>

	<listitem>
	<para>Print troff data.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-v</option></term>

	<listitem>
	<para>Print raster data.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>Here is an example: this command prints a nicely
	formatted version of the &man.ls.1; manual page on the
	default printer:</para>

	<screen>&prompt.user; <userinput><command>zcat <filename>/usr/share/man/man1/ls.1.gz</filename> \| troff <option>-t</option> -man \| lpr <option>-t</option></command></userinput></screen>

	<para>The &man.zcat.1; command uncompresses the source of the
	&man.ls.1; manual page and passes it to the &man.troff.1;
	command, which formats that source and makes GNU troff
	output and passes it to &man.lpr.1;, which submits the job
	to the <application>LPD</application> spooler. Because we
	used the <option>-t</option> option to &man.lpr.1;, the
	spooler will convert the GNU troff output into a format the
	default printer can understand when it prints the
	job.</para>
	</sect3>

	<sect3 id="printing-lpr-options-job-handling">
	<title>Job Handling Options</title>

	<para>The following options to &man.lpr.1; tell
	<application>LPD</application> to handle the job
	specially:</para>

	<variablelist>
	<varlistentry>
	<term>-# <replaceable>copies</replaceable></term>

	<listitem>
	<para>Produce a number of
	<replaceable>copies</replaceable> of each file in the
	job instead of just one copy. An administrator may
	disable this option to reduce printer wear-and-tear
	and encourage photocopier usage. See section <link
	linkend="printing-advanced-restricting-copies">Restricting
	Multiple Copies</link>.</para>

	<para>This example prints three copies of
	<filename><replaceable>parser.c</replaceable></filename>
	followed by three copies of
	<filename><replaceable>parser.h</replaceable></filename>
	to the default printer:</para>

	<screen>&prompt.user; <userinput><command>lpr <option>-#3</option> <filename><replaceable>parser.c parser.h</replaceable></filename></command></userinput></screen>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-m</term>

	<listitem>
	<para>Send mail after completing the print job. With
	this option, the <application>LPD</application> system
	will send mail to your account when it finishes
	handling your job. In its message, it will tell you
	if the job completed successfully or if there was an
	error, and (often) what the error was.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-s</term>

	<listitem>
	<para>Do not copy the files to the spooling directory,
	but make symbolic links to them instead.</para>

	<para>If you are printing a large job, you probably want
	to use this option. It saves space in the spooling
	directory (your job might overflow the free space on
	the filesystem where the spooling directory resides).
	It saves time as well since
	<application>LPD</application> will not have to copy
	each and every byte of your job to the spooling
	directory.</para>

	<para>There is a drawback, though: since
	<application>LPD</application> will refer to the
	original files directly, you cannot modify or remove
	them until they have been printed.</para>

	<note>
	<para>If you are printing to a remote printer,
	<application>LPD</application> will eventually have
	to copy files from the local host to the remote
	host, so the <option>-s</option> option will save
	space only on the local spooling directory, not the
	remote. It is still useful, though.</para>
	</note>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-r</term>

	<listitem>
	<para>Remove the files in the job after copying them to
	the spooling directory, or after printing them with
	the <option>-s</option> option. Be careful with this
	option!</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect3>

	<sect3 id="printing-lpr-options-misc">
	<title>Header Page Options</title>

	<para>These options to &man.lpr.1; adjust the text that
	normally appears on a job's header page. If header pages
	are suppressed for the destination printer, these options
	have no effect. See section <link
	linkend="printing-advanced-header-pages">Header
	Pages</link>
	for information about setting up header pages.</para>

	<variablelist>
	<varlistentry>
	<term>-C <replaceable>text</replaceable></term>

	<listitem>
	<para>Replace the hostname on the header page with
	<replaceable>text</replaceable>. The hostname is
	normally the name of the host from which the job was
	submitted.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-J <replaceable>text</replaceable></term>

	<listitem>
	<para>Replace the job name on the header page with
	<replaceable>text</replaceable>. The job name is
	normally the name of the first file of the job, or
	<filename>stdin</filename> if you are printing
	standard input.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>-h</term>

	<listitem>
	<para>Do not print any header page.</para>

	<note>
	<para>At some sites, this option may have no effect
	due to the way header pages are generated. See
	<link
	linkend="printing-advanced-header-pages">Header
	Pages</link> for details.</para>
	</note>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect3>
	</sect2>

	<sect2 id="printing-lpc">
	<title>Administering Printers</title>

	<para>As an administrator for your printers, you have had to
	install, set up, and test them. Using the &man.lpc.8;
	command, you can interact with your printers in yet more ways.
	With &man.lpc.8;, you can</para>

	<itemizedlist>
	<listitem>
	<para>Start and stop the printers</para>
	</listitem>

	<listitem>
	<para>Enable and disable their queues</para>
	</listitem>

	<listitem>
	<para>Rearrange the order of the jobs in each queue.</para>
	</listitem>
	</itemizedlist>

	<para>First, a note about terminology: if a printer is
	<emphasis>stopped</emphasis>, it will not print anything in
	its queue. Users can still submit jobs, which will wait in
	the queue until the printer is <emphasis>started</emphasis> or
	the queue is cleared.</para>

	<para>If a queue is <emphasis>disabled</emphasis>, no user
	(except <username>root</username>) can submit jobs for the
	printer. An <emphasis>enabled</emphasis> queue allows jobs to
	be submitted. A printer can be <emphasis>started</emphasis>
	for a disabled queue, in which case it will continue to print
	jobs in the queue until the queue is empty.</para>

	<para>In general, you have to have <username>root</username>
	privileges to use the &man.lpc.8; command. Ordinary users can
	use the &man.lpc.8; command to get printer status and to
	restart a hung printer only.</para>

	<para>Here is a summary of the &man.lpc.8; commands. Most of
	the commands take a <replaceable>printer-name</replaceable>
	argument to tell on which printer to operate. You can use
	<literal>all</literal> for the
	<replaceable>printer-name</replaceable> to mean all printers
	listed in <filename>/etc/printcap</filename>.</para>

	<variablelist>
	<varlistentry>
	<term><command>abort
	<replaceable>printer-name</replaceable></command></term>

	<listitem>
	<para>Cancel the current job and stop the printer. Users
	can still submit jobs if the queue is enabled.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>clean
	<replaceable>printer-name</replaceable></command></term>

	<listitem>
	<para>Remove old files from the printer's spooling
	directory. Occasionally, the files that make up a job
	are not properly removed by
	<application>LPD</application>, particularly if there
	have been errors during printing or a lot of
	administrative activity. This command finds files that
	do not belong in the spooling directory and removes
	them.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>disable
	<replaceable>printer-name</replaceable></command></term>

	<listitem>
	<para>Disable queuing of new jobs. If the printer is
	running, it will continue to print any jobs remaining in
	the queue. The superuser (<username>root</username>)
	can always submit jobs, even to a disabled queue.</para>

	<para>This command is useful while you are testing a new
	printer or filter installation: disable the queue and
	submit jobs as <username>root</username>. Other users
	will not be able to submit jobs until you complete your
	testing and re-enable the queue with the
	<command>enable</command> command.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>down <replaceable>printer-name</replaceable>
	<replaceable>message</replaceable></command></term>

	<listitem>
	<para>Take a printer down. Equivalent to
	<command>disable</command> followed by
	<command>stop</command>. The
	<replaceable>message</replaceable> appears as the
	printer's status whenever a user checks the printer's
	queue with &man.lpq.1; or status with <command>lpc
	status</command>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>enable
	<replaceable>printer-name</replaceable></command></term>

	<listitem>
	<para>Enable the queue for a printer. Users can submit
	jobs but the printer will not print anything until it is
	started.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>help
	<replaceable>command-name</replaceable></command></term>

	<listitem>
	<para>Print help on the command
	<replaceable>command-name</replaceable>. With no
	<replaceable>command-name</replaceable>, print a summary
	of the commands available.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>restart
	<replaceable>printer-name</replaceable></command></term>

	<listitem>
	<para>Start the printer. Ordinary users can use this
	command if some extraordinary circumstance hangs
	<application>LPD</application>, but they cannot start
	a printer stopped with either the
	<command>stop</command> or
	<command>down</command> commands. The
	<command>restart</command> command is equivalent to
	<command>abort</command> followed by
	<command>start</command>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>start
	<replaceable>printer-name</replaceable></command></term>

	<listitem>
	<para>Start the printer. The printer will print jobs in
	its queue.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>stop
	<replaceable>printer-name</replaceable></command></term>

	<listitem>
	<para>Stop the printer. The printer will finish the
	current job and will not print anything else in its
	queue. Even though the printer is stopped, users can
	still submit jobs to an enabled queue.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>topq <replaceable>printer-name</replaceable>
	<replaceable>job-or-username</replaceable></command></term>

	<listitem>
	<para>Rearrange the queue for
	<replaceable>printer-name</replaceable> by placing the
	jobs with the listed <replaceable>job</replaceable>
	numbers or the jobs belonging to
	<replaceable>username</replaceable> at the top of
	the queue. For this command, you cannot use
	<literal>all</literal> as the
	<replaceable>printer-name</replaceable>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>up
	<replaceable>printer-name</replaceable></command></term>

	<listitem>
	<para>Bring a printer up; the opposite of the
	<command>down</command> command. Equivalent to
	<command>start</command> followed by
	<command>enable</command>.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>&man.lpc.8; accepts the above commands on the command
	line. If you do not enter any commands, &man.lpc.8; enters an
	interactive mode, where you can enter commands until you type
	<command>exit</command>, <command>quit</command>, or
	end-of-file.</para>
	</sect2>
	</sect1>

	<sect1 id="printing-lpd-alternatives">
	<title>Alternatives to the Standard Spooler</title>

	<para>If you have been reading straight through this manual, by
	now you have learned just about everything there is to know
	about the <application>LPD</application> spooling system that
	comes with &os;. You can probably appreciate many of its
	shortcomings, which naturally leads to the question: <quote>What
	other spooling systems are out there (and work with
	&os;)?</quote></para>

	<variablelist>
	<varlistentry>
	<term>LPRng</term>

	<listitem>
	<indexterm><primary>LPRng</primary></indexterm>

	<para><application>LPRng</application>, which purportedly
	means <quote>LPR: the Next Generation</quote> is a
	complete rewrite of PLP. Patrick Powell and Justin Mason
	(the principal maintainer of PLP) collaborated to make
	<application>LPRng</application>. The main site for
	<application>LPRng</application> is <ulink
	url="http://www.lprng.org/"></ulink>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>CUPS</term>

	<listitem>
	<indexterm><primary>CUPS</primary></indexterm>

	<para><application>CUPS</application>, the Common UNIX
	Printing System, provides a portable printing layer for
	&unix;-based operating systems. It has been developed by
	Easy Software Products to promote a standard printing
	solution for all &unix; vendors and users.</para>

	<para><application>CUPS</application> uses the Internet
	Printing Protocol (<acronym>IPP</acronym>) as the basis
	for managing print jobs and queues. The Line Printer
	Daemon (<acronym>LPD</acronym>), Server Message Block
	(<acronym>SMB</acronym>), and AppSocket (aka JetDirect)
	protocols are also supported with reduced functionality.
	CUPS adds network printer browsing and PostScript Printer
	Description (<acronym>PPD</acronym>) based printing
	options to support real-world printing under
	&unix;.</para>

	<para>The main site for <application>CUPS</application> is
	<ulink url="http://www.cups.org/"></ulink>.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>HPLIP</term>

	<listitem>
	<indexterm><primary>HPLIP</primary></indexterm>

	<para><application>HPLIP</application>, the HP &linux;
	Imaging and Printing system, is an HP-developed suite of
	programs that supports printing, scanning and fax
	facilities for HP appliances. This suite of programs
	utilizes the <application>CUPS</application> printing
	system as a backend for some of its printing
	features.</para>

	<para>The main site for <application>HPLIP</application>
	is <ulink
	url="http://hplipopensource.com/hplip-web/index.html"></ulink>.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect1>

	<sect1 id="printing-troubleshooting">
	<title>Troubleshooting</title>

	<para>After performing the simple test with &man.lptest.1;, you
	might have gotten one of the following results instead of the
	correct printout:</para>

	<variablelist>
	<varlistentry>
	<term>It worked, after awhile; or, it did not eject a full
	sheet.</term>

	<listitem>
	<para>The printer printed the above, but it sat for awhile
	and did nothing. In fact, you might have needed to press
	a PRINT REMAINING or FORM FEED button on the printer to
	get any results to appear.</para>

	<para>If this is the case, the printer was probably waiting
	to see if there was any more data for your job before it
	printed anything. To fix this problem, you can have the
	text filter send a FORM FEED character (or whatever is
	necessary) to the printer. This is usually sufficient to
	have the printer immediately print any text remaining in
	its internal buffer. It is also useful to make sure each
	print job ends on a full sheet, so the next job does not
	start somewhere on the middle of the last page of the
	previous job.</para>

	<para>The following replacement for the shell script
	<filename>/usr/local/libexec/if-simple</filename> prints
	a form feed after it sends the job to the printer:</para>

	<programlisting>#!/bin/sh
	#
	# if-simple - Simple text input filter for lpd
	# Installed in /usr/local/libexec/if-simple
	#
	# Simply copies stdin to stdout. Ignores all filter arguments.
	# Writes a form feed character (\f) after printing job.

	/bin/cat && printf "\f" && exit 0
	exit 2</programlisting>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>It produced the <quote>staircase effect.</quote></term>

	<listitem>
	<para>You got the following on paper:</para>

	<screen>!"#$%&'()*+,-./01234
	"#$%&'()*+,-./012345
	#$%&'()*+,-./0123456</screen>

	<indexterm><primary>MS-DOS</primary></indexterm>
	<indexterm><primary>OS/2</primary></indexterm>
	<indexterm><primary>ASCII</primary></indexterm>
	<para>You have become another victim of the
	<emphasis>staircase effect</emphasis>, caused by
	conflicting interpretations of what characters should
	indicate a new line. &unix; style operating systems use a
	single character: ASCII code 10, the line feed (LF).
	&ms-dos;, &os2;, and others uses a pair of characters,
	ASCII code 10 <emphasis>and</emphasis> ASCII code 13 (the
	carriage return or CR). Many printers use the &ms-dos;
	convention for representing new-lines.</para>

	<para>When you print with &os;, your text used just the line
	feed character. The printer, upon seeing a line feed
	character, advanced the paper one line, but maintained the
	same horizontal position on the page for the next
	character to print. That is what the carriage return is
	for: to move the location of the next character to print
	to the left edge of the paper.</para>

	<para>Here is what &os; wants your printer to do:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<tbody>
	<row>
	<entry>Printer received CR</entry>
	<entry>Printer prints CR</entry>
	</row>

	<row>
	<entry>Printer received LF</entry>
	<entry>Printer prints CR + LF</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>Here are some ways to achieve this:</para>

	<itemizedlist>
	<listitem>
	<para>Use the printer's configuration switches or
	control panel to alter its interpretation of these
	characters. Check your printer's manual to find out
	how to do this.</para>

	<note>
	<para>If you boot your system into other operating
	systems besides &os;, you may have to
	<emphasis>reconfigure</emphasis> the printer to use
	a an interpretation for CR and LF characters that
	those other operating systems use. You might prefer
	one of the other solutions, below.</para>
	</note>
	</listitem>

	<listitem>
	<para>Have &os;'s serial line driver automatically
	convert LF to CR+LF. Of course, this works with
	printers on serial ports <emphasis>only</emphasis>.
	To enable this feature, use the <literal>ms#</literal>
	capability and set the <literal>onlcr</literal> mode
	in the <filename>/etc/printcap</filename> file for the
	printer.</para>
	</listitem>

	<listitem>
	<para>Send an <emphasis>escape code</emphasis> to the
	printer to have it temporarily treat LF characters
	differently. Consult your printer's manual for escape
	codes that your printer might support. When you find
	the proper escape code, modify the text filter to send
	the code first, then send the print job.</para>

	<indexterm><primary>PCL</primary></indexterm>
	<para>Here is an example text filter for printers that
	understand the Hewlett-Packard PCL escape codes. This
	filter makes the printer treat LF characters as a LF
	and CR; then it sends the job; then it sends a form
	feed to eject the last page of the job. It should
	work with nearly all Hewlett Packard printers.</para>

	<programlisting>#!/bin/sh
	#
	# hpif - Simple text input filter for lpd for HP-PCL based printers
	# Installed in /usr/local/libexec/hpif
	#
	# Simply copies stdin to stdout. Ignores all filter arguments.
	# Tells printer to treat LF as CR+LF. Ejects the page when done.

	printf "\033&k2G" && cat && printf "\033&l0H" && exit 0
	exit 2</programlisting>

	<para>Here is an example
	<filename>/etc/printcap</filename>
	from a host called <hostid>orchid</hostid>. It has a
	single printer attached to its first parallel port, a
	Hewlett Packard LaserJet 3Si named
	<literal>teak</literal>. It is using the above script
	as its text filter:</para>

	<programlisting>#
	# /etc/printcap for host orchid
	#
	teak\|hp\|laserjet\|Hewlett Packard LaserJet 3Si:\
	:lp=<filename class="devicefile">/dev/lpt0</filename>:sh:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:\
	:if=<filename>/usr/local/libexec/hpif</filename>:</programlisting>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>It overprinted each line.</term>

	<listitem>
	<para>The printer never advanced a line. All of the lines
	of text were printed on top of each other on one
	line.</para>

	<para>This problem is the <quote>opposite</quote> of the
	staircase effect, described above, and is much rarer.
	Somewhere, the LF characters that &os; uses to end a line
	are being treated as CR characters to return the print
	location to the left edge of the paper, but not also down
	a line.</para>

	<para>Use the printer's configuration switches or control
	panel to enforce the following interpretation of LF and
	CR characters:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Printer receives</entry>
	<entry>Printer prints</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>CR</entry>
	<entry>CR</entry>
	</row>

	<row>
	<entry>LF</entry>
	<entry>CR + LF</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>The printer lost characters.</term>

	<listitem>
	<para>While printing, the printer did not print a few
	characters in each line. The problem might have gotten
	worse as the printer ran, losing more and more
	characters.</para>

	<para>The problem is that the printer cannot keep up with
	the speed at which the computer sends data over a serial
	line (this problem should not occur with printers on
	parallel ports). There are two ways to overcome the
	problem:</para>

	<itemizedlist>
	<listitem>
	<para>If the printer supports XON/XOFF flow control,
	have &os; use it by specifying the
	<literal>ixon</literal> mode in the
	<literal>ms#</literal> capability.</para>
	</listitem>

	<listitem>
	<para>If the printer supports the Request to Send /
	Clear to Send hardware handshake (commonly known as
	<literal>RTS/CTS</literal>), specify the
	<literal>crtscts</literal> mode in the
	<literal>ms#</literal> capability. Make sure the
	cable connecting the printer to the computer is
	correctly wired for hardware flow control.</para>
	</listitem>
	</itemizedlist>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>It printed garbage.</term>

	<listitem>
	<para>The printer printed what appeared to be random
	garbage, but not the desired text.</para>

	<para>This is usually another symptom of incorrect
	communications parameters with a serial printer.
	Double-check the bps rate in the <literal>br</literal>
	capability, and the parity setting in the
	<literal>ms#</literal> capability; make sure the printer
	is using the same settings as specified in the
	<filename>/etc/printcap</filename> file.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Nothing happened.</term>

	<listitem>
	<para>If nothing happened, the problem is probably within
	&os; and not the hardware. Add the log file
	(<literal>lf</literal>) capability to the entry for the
	printer you are debugging in the
	<filename>/etc/printcap</filename> file. For example,
	here is the entry for <literal>rattan</literal>, with the
	<literal>lf</literal> capability:</para>

	<programlisting>rattan\|line\|diablo\|lp\|Diablo 630 Line Printer:\
	:sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\
	:lp=<filename class="devicefile">/dev/lpt0</filename>:\
	:if=<filename>/usr/local/libexec/if-simple</filename>:\
	:lf=<filename>/var/log/rattan.log</filename></programlisting>

	<para>Then, try printing again. Check the log file (in our
	example, <filename>/var/log/rattan.log</filename>) to see
	any error messages that might appear. Based on the
	messages you see, try to correct the problem.</para>

	<para>If you do not specify a <literal>lf</literal>
	capability, <application>LPD</application> uses
	<filename class="devicefile">/dev/console</filename> as a
	default.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/security/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/security/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/security/chapter.xml (revision 41355)
	@@ -1,4152 +1,4152 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="security">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Matthew</firstname>
	<surname>Dillon</surname>
	<contrib>Much of this chapter has been taken from the
	security(7) manual page by </contrib>
	</author>
	</authorgroup>
	</chapterinfo>

	<title>Security</title>

	<indexterm><primary>security</primary></indexterm>

	<sect1 id="security-synopsis">
	<title>Synopsis</title>

	<para>This chapter will provide a basic introduction to system
	security concepts, some general good rules of thumb, and some
	advanced topics under &os;. A lot of the topics covered here
	can be applied to system and Internet security in general as
	well. The Internet is no longer a <quote>friendly</quote> place
	in which everyone wants to be your kind neighbor. Securing your
	system is imperative to protect your data, intellectual
	property, time, and much more from the hands of hackers and the
	like.</para>

	<para>&os; provides an array of utilities and mechanisms to ensure
	the integrity and security of your system and network.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>Basic system security concepts, in respect to
	&os;.</para>
	</listitem>

	<listitem>
	<para>About the various crypt mechanisms available in &os;,
	such as <acronym>DES</acronym> and
	<acronym>MD5</acronym>.</para>
	</listitem>

	<listitem>
	<para>How to set up one-time password authentication.</para>
	</listitem>

	<listitem>
	<para>How to configure <acronym>TCP</acronym> Wrappers for use
	with <application>inetd</application>.</para>
	</listitem>

	<listitem>
	<para>How to set up <application>Kerberos5</application> on
	&os;.</para>
	</listitem>

	<listitem>
	<para>How to configure IPsec and create a
	<acronym>VPN</acronym> between &os;/&windows;
	machines.</para>
	</listitem>

	<listitem>
	<para>How to configure and use
	<application>OpenSSH</application>, &os;'s
	<acronym>SSH</acronym> implementation.</para>
	</listitem>

	<listitem>
	<para>What file system <acronym>ACL</acronym>s are and how to
	use them.</para>
	</listitem>

	<listitem>
	<para>How to use the <application>Portaudit</application>
	utility to audit third party software packages installed
	from the Ports Collection.</para>
	</listitem>

	<listitem>
	<para>How to utilize the &os; security advisories
	publications.</para>
	</listitem>

	<listitem>
	<para>Have an idea of what Process Accounting is and how to
	enable it on &os;.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	<para>Understand basic &os; and Internet concepts.</para>
	</listitem>
	</itemizedlist>

	<para>Additional security topics are covered throughout this book.
	For example, Mandatory Access Control is discussed in <xref
	linkend="mac"/> and Internet Firewalls are discussed in <xref
	linkend="firewalls"/>.</para>
	</sect1>

	<sect1 id="security-intro">
	<title>Introduction</title>

	<para>Security is a function that begins and ends with the system
	administrator. While all BSD &unix; multi-user systems have
	some inherent security, the job of building and maintaining
	additional security mechanisms to keep those users
	<quote>honest</quote> is probably one of the single largest
	undertakings of the sysadmin. Machines are only as secure as
	you make them, and security concerns are ever competing with the
	human necessity for convenience. &unix; systems, in general,
	are capable of running a huge number of simultaneous processes
	and many of these processes operate as servers — meaning
	that external entities can connect and talk to them. As
	yesterday's mini-computers and mainframes become today's
	desktops, and as computers become networked and inter-networked,
	security becomes an even bigger issue.</para>

	<para>System security also pertains to dealing with various forms
	of attack, including attacks that attempt to crash, or otherwise
	make a system unusable, but do not attempt to compromise the
	<username>root</username> account (<quote>break root</quote>).
	Security concerns can be split up into several
	categories:</para>

	<orderedlist>
	<listitem>
	<para>Denial of service attacks.</para>
	</listitem>

	<listitem>
	<para>User account compromises.</para>
	</listitem>

	<listitem>
	<para>Root compromise through accessible servers.</para>
	</listitem>

	<listitem>
	<para>Root compromise via user accounts.</para>
	</listitem>

	<listitem>
	<para>Backdoor creation.</para>
	</listitem>
	</orderedlist>

	<indexterm>
	<primary>DoS attacks</primary>
	<see>Denial of Service (DoS)</see>
	</indexterm>
	<indexterm>
	<primary>security</primary>
	<secondary>DoS attacks</secondary>
	<see>Denial of Service (DoS)</see>
	</indexterm>
	<indexterm><primary>Denial of Service (DoS)</primary></indexterm>

	<para>A denial of service attack is an action that deprives the
	machine of needed resources. Typically, DoS attacks are
	brute-force mechanisms that attempt to crash or otherwise make a
	machine unusable by overwhelming its servers or network stack.
	Some DoS attacks try to take advantage of bugs in the networking
	stack to crash a machine with a single packet. The latter can
	only be fixed by applying a bug fix to the kernel. Attacks on
	servers can often be fixed by properly specifying options to
	limit the load the servers incur on the system under adverse
	conditions. Brute-force network attacks are harder to deal
	with. A spoofed-packet attack, for example, is nearly
	impossible to stop, short of cutting your system off from the
	Internet. It may not be able to take your machine down, but it
	can saturate your Internet connection.</para>

	<indexterm>
	<primary>security</primary>
	<secondary>account compromises</secondary>
	</indexterm>

	<para>A user account compromise is even more common than a DoS
	attack. Many sysadmins still run standard
	<application>telnetd</application>,
	<application>rlogind</application>,
	<application>rshd</application>, and
	<application>ftpd</application> servers on their machines.
	These servers, by default, do not operate over encrypted
	connections. The result is that if you have any moderate-sized
	user base, one or more of your users logging into your system
	from a remote location (which is the most common and convenient
	way to login to a system) will have his or her password sniffed.
	The attentive system admin will analyze his remote access logs
	looking for suspicious source addresses even for successful
	logins.</para>

	<para>One must always assume that once an attacker has access to a
	user account, the attacker can break <username>root</username>.
	However, the reality is that in a well secured and maintained
	system, access to a user account does not necessarily give the
	attacker access to <username>root</username>. The distinction
	is important because without access to <username>root</username>
	the attacker cannot generally hide his tracks and may, at best,
	be able to do nothing more than mess with the user's files, or
	crash the machine. User account compromises are very common
	because users tend not to take the precautions that sysadmins
	take.</para>

	<indexterm>
	<primary>security</primary>
	<secondary>backdoors</secondary>
	</indexterm>

	<para>System administrators must keep in mind that there are
	potentially many ways to break <username>root</username> on a
	machine. The attacker may know the <username>root</username>
	password, the attacker may find a bug in a root-run server and
	be able to break <username>root</username> over a network
	connection to that server, or the attacker may know of a bug in
	a suid-root program that allows the attacker to break
	<username>root</username> once he has broken into a user's
	account. If an attacker has found a way to break
	<username>root</username> on a machine, the attacker may not
	have a need to install a backdoor. Many of the
	<username>root</username> holes found and closed to date involve
	a considerable amount of work by the attacker to cleanup after
	himself, so most attackers install backdoors. A backdoor
	provides the attacker with a way to easily regain
	<username>root</username> access to the system, but it also
	gives the smart system administrator a convenient way to detect
	the intrusion. Making it impossible for an attacker to install
	a backdoor may actually be detrimental to your security, because
	it will not close off the hole the attacker found to break in
	the first place.</para>

	<para>Security remedies should always be implemented with a
	multi-layered <quote>onion peel</quote> approach and can be
	categorized as follows:</para>

	<orderedlist>
	<listitem>
	<para>Securing <username>root</username> and staff
	accounts.</para>
	</listitem>

	<listitem>
	<para>Securing <username>root</username>–run servers
	and suid/sgid binaries.</para>
	</listitem>

	<listitem>
	<para>Securing user accounts.</para>
	</listitem>

	<listitem>
	<para>Securing the password file.</para>
	</listitem>

	<listitem>
	<para>Securing the kernel core, raw devices, and
	file systems.</para>
	</listitem>

	<listitem>
	<para>Quick detection of inappropriate changes made to the
	system.</para>
	</listitem>

	<listitem>
	<para>Paranoia.</para>
	</listitem>
	</orderedlist>

	<para>The next section of this chapter will cover the above bullet
	items in greater depth.</para>
	</sect1>

	<sect1 id="securing-freebsd">
	<title>Securing &os;</title>

	<indexterm>
	<primary>security</primary>
	<secondary>securing &os;</secondary>
	</indexterm>

	<note>
	<title>Command Versus Protocol</title>

	<para>Throughout this document, we will use
	<application>bold</application> text to refer to an
	application, and a <command>monospaced</command> font to refer
	to specific commands. Protocols will use a normal font. This
	typographical distinction is useful for instances such as ssh,
	since it is a protocol as well as command.</para>
	</note>

	<para>The sections that follow will cover the methods of securing
	your &os; system that were mentioned in the <link
	linkend="security-intro">last section</link> of this
	chapter.</para>

	<sect2 id="securing-root-and-staff">
	<title>Securing the <username>root</username> Account and
	Staff Accounts</title>

	<indexterm>
	<primary><command>su</command></primary>
	</indexterm>

	<para>First off, do not bother securing staff accounts if you
	have not secured the <username>root</username> account. Most
	systems have a password assigned to the
	<username>root</username> account. The first thing you do is
	assume that the password is <emphasis>always</emphasis>
	compromised. This does not mean that you should remove the
	password. The password is almost always necessary for console
	access to the machine. What it does mean is that you should
	not make it possible to use the password outside of the
	console or possibly even with the &man.su.1; command. For
	example, make sure that your ptys are specified as being
	insecure in the <filename>/etc/ttys</filename> file so that
	direct <username>root</username> logins via
	<command>telnet</command> or <command>rlogin</command> are
	disallowed. If using other login services such as
	<application>sshd</application>, make sure that direct
	<username>root</username> logins are disabled there as well.
	You can do this by editing your
	<filename>/etc/ssh/sshd_config</filename> file, and making
	sure that <literal>PermitRootLogin</literal> is set to
	<literal>no</literal>. Consider every access method —
	services such as FTP often fall through the cracks. Direct
	<username>root</username> logins should only be allowed via
	the system console.</para>

	<indexterm>
	<primary><groupname>wheel</groupname></primary>
	</indexterm>

	<para>Of course, as a sysadmin you have to be able to get to
	<username>root</username>, so we open up a few holes. But we
	make sure these holes require additional password verification
	to operate. One way to make <username>root</username>
	accessible is to add appropriate staff accounts to the
	<groupname>wheel</groupname> group (in
	<filename>/etc/group</filename>). The staff members placed in
	the <groupname>wheel</groupname> group are allowed to
	<command>su</command> to <username>root</username>. You
	should never give staff members native
	<groupname>wheel</groupname> access by putting them in the
	<groupname>wheel</groupname> group in their password entry.
	Staff accounts should be placed in a
	<groupname>staff</groupname> group, and then added to the
	<groupname>wheel</groupname> group via the
	<filename>/etc/group</filename> file. Only those staff
	members who actually need to have <username>root</username>
	access should be placed in the <groupname>wheel</groupname>
	group. It is also possible, when using an authentication
	method such as Kerberos, to use Kerberos'
	<filename>.k5login</filename> file in the
	<username>root</username> account to allow a &man.ksu.1; to
	<username>root</username> without having to place anyone at
	all in the <groupname>wheel</groupname> group. This may be
	the better solution since the <groupname>wheel</groupname>
	mechanism still allows an intruder to break
	<username>root</username> if the intruder has gotten hold of
	your password file and can break into a staff account. While
	having the <groupname>wheel</groupname> mechanism is better
	than having nothing at all, it is not necessarily the safest
	option.</para>

	<para>To lock an account completely, the &man.pw.8; command
	should be used:</para>

	<screen>&prompt.root; <userinput>pw lock <replaceable>staff</replaceable></userinput></screen>

	<para>This will prevent the user from logging in using any
	mechanism, including &man.ssh.1;.</para>

	<para>Another method of blocking access to accounts would be to
	replace the encrypted password with a single
	<quote><literal>*</literal></quote> character. This character
	would never match the encrypted password and thus block user
	access. For example, the following staff account:</para>

	<programlisting>foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting>

	<para>Should be changed to this:</para>

	<programlisting>foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting>

	<para>This will prevent the <username>foobar</username> user
	from logging in using conventional methods. This method for
	access restriction is flawed on sites using
	<application>Kerberos</application> or in situations where the
	user has set up keys with &man.ssh.1;.</para>

	<para>These security mechanisms also assume that you are logging
	in from a more restrictive server to a less restrictive
	server. For example, if your main box is running all sorts of
	servers, your workstation should not be running any. In order
	for your workstation to be reasonably secure you should run as
	few servers as possible, up to and including no servers at
	all, and you should run a password-protected screen blanker.
	Of course, given physical access to a workstation an attacker
	can break any sort of security you put on it. This is
	definitely a problem that you should consider, but you should
	also consider the fact that the vast majority of break-ins
	occur remotely, over a network, from people who do not have
	physical access to your workstation or servers.</para>

	<para>Using something like Kerberos also gives you the ability
	to disable or change the password for a staff account in one
	place, and have it immediately affect all the machines on
	which the staff member may have an account. If a staff
	member's account gets compromised, the ability to instantly
	change his password on all machines should not be underrated.
	With discrete passwords, changing a password on N machines can
	be a mess. You can also impose re-passwording restrictions
	with Kerberos: not only can a Kerberos ticket be made to
	timeout after a while, but the Kerberos system can require
	that the user choose a new password after a certain period of
	time (say, once a month).</para>
	</sect2>

	<sect2>
	<title>Securing Root-run Servers and SUID/SGID Binaries</title>

	<indexterm>
	<primary><command>ntalk</command></primary>
	</indexterm>
	<indexterm>
	<primary><command>comsat</command></primary>
	</indexterm>
	<indexterm>
	<primary><command>finger</command></primary>
	</indexterm>
	<indexterm>
	<primary>sandboxes</primary>
	</indexterm>
	<indexterm>
	<primary><application>sshd</application></primary>
	</indexterm>
	<indexterm>
	<primary><application>telnetd</application></primary>
	</indexterm>
	<indexterm>
	<primary><application>rshd</application></primary>
	</indexterm>
	<indexterm>
	<primary><application>rlogind</application></primary>
	</indexterm>

	<para>The prudent sysadmin only runs the servers he needs to, no
	more, no less. Be aware that third party servers are often
	the most bug-prone. For example, running an old version of
	<application>imapd</application> or
	<application>popper</application> is like giving a universal
	<username>root</username> ticket out to the entire world.
	Never run a server that you have not checked out carefully.
	Many servers do not need to be run as
	<username>root</username>. For example, the
	<application>ntalk</application>,
	<application>comsat</application>, and
	<application>finger</application> daemons can be run in
	special user <firstterm>sandboxes</firstterm>. A sandbox is
	not perfect, unless you go through a large amount of trouble,
	but the onion approach to security still stands: If someone is
	able to break in through a server running in a sandbox, they
	still have to break out of the sandbox. The more layers the
	attacker must break through, the lower the likelihood of his
	success. Root holes have historically been found in virtually
	every server ever run as <username>root</username>, including
	basic system servers. If you are running a machine through
	which people only login via <application>sshd</application>
	and never login via <application>telnetd</application> or
	<application>rshd</application> or
	<application>rlogind</application>, then turn off those
	services!</para>

	<para>&os; now defaults to running
	<application>ntalkd</application>,
	<application>comsat</application>, and
	<application>finger</application> in a sandbox. Another
	program which may be a candidate for running in a sandbox is
	&man.named.8;. <filename>/etc/defaults/rc.conf</filename>
	includes the arguments necessary to run
	<application>named</application> in a sandbox in a
	commented-out form. Depending on whether you are installing a
	new system or upgrading an existing system, the special user
	accounts used by these sandboxes may not be installed. The
	prudent sysadmin would research and implement sandboxes for
	servers whenever possible.</para>

	<indexterm>
	<primary><application>sendmail</application></primary>
	</indexterm>

	<para>There are a number of other servers that typically do not
	run in sandboxes: <application>sendmail</application>,
	<application>popper</application>,
	<application>imapd</application>,
	<application>ftpd</application>, and others. There are
	alternatives to some of these, but installing them may require
	more work than you are willing to perform (the convenience
	factor strikes again). You may have to run these servers as
	<username>root</username> and rely on other mechanisms to
	detect break-ins that might occur through them.</para>

	<para>The other big potential <username>root</username> holes in
	a system are the suid-root and sgid binaries installed on the
	system. Most of these binaries, such as
	<application>rlogin</application>, reside in <filename
	class="directory">/bin</filename>, <filename
	class="directory">/sbin</filename>, <filename
	class="directory">/usr/bin</filename>, or <filename
	class="directory">/usr/sbin</filename>. While nothing is
	100% safe, the system-default suid and sgid binaries can be
	considered reasonably safe. Still, <username>root</username>
	holes are occasionally found in these binaries. A
	<username>root</username> hole was found in
	<literal>Xlib</literal> in 1998 that made
	<application>xterm</application> (which is typically suid)
	vulnerable. It is better to be safe than sorry and the
	prudent sysadmin will restrict suid binaries, that only staff
	should run, to a special group that only staff can access, and
	get rid of (<command>chmod 000</command>) any suid binaries
	that nobody uses. A server with no display generally does not
	need an <application>xterm</application> binary. Sgid
	binaries can be almost as dangerous. If an intruder can break
	an sgid-kmem binary, the intruder might be able to read
	<filename>/dev/kmem</filename> and thus read the encrypted
	password file, potentially compromising any passworded
	account. Alternatively an intruder who breaks group
	<literal>kmem</literal> can monitor keystrokes sent through
	ptys, including ptys used by users who login through secure
	methods. An intruder that breaks the
	<groupname>tty</groupname> group can write to almost any
	user's tty. If a user is running a terminal program or
	emulator with a keyboard-simulation feature, the intruder can
	potentially generate a data stream that causes the user's
	terminal to echo a command, which is then run as that
	user.</para>
	</sect2>

	<sect2 id="secure-users">
	<title>Securing User Accounts</title>

	<para>User accounts are usually the most difficult to secure.
	While you can impose draconian access restrictions on your
	staff and <quote>star</quote> out their passwords, you may not
	be able to do so with any general user accounts you might
	have. If you do have sufficient control, then you may win out
	and be able to secure the user accounts properly. If not, you
	simply have to be more vigilant in your monitoring of those
	accounts. Use of ssh and Kerberos for user accounts is more
	problematic, due to the extra administration and technical
	support required, but still a very good solution compared to a
	encrypted password file.</para>
	</sect2>

	<sect2>
	<title>Securing the Password File</title>

	<para>The only sure fire way is to star out as many passwords as
	you can and use ssh or Kerberos for access to those accounts.
	Even though the encrypted password file
	(<filename>/etc/spwd.db</filename>) can only be read by
	<username>root</username>, it may be possible for an intruder
	to obtain read access to that file even if the attacker cannot
	obtain root-write access.</para>

	<para>Your security scripts should always check for and report
	changes to the password file (see the <link
	linkend="security-integrity">Checking file integrity</link>
	section below).</para>
	</sect2>

	<sect2>
	<title>Securing the Kernel Core, Raw Devices, and
	File Systems</title>

	<para>If an attacker breaks <username>root</username> he can do
	just about anything, but there are certain conveniences. For
	example, most modern kernels have a packet sniffing device
	driver built in. Under &os; it is called the
	<devicename>bpf</devicename> device. An intruder will
	commonly attempt to run a packet sniffer on a compromised
	machine. You do not need to give the intruder the capability
	and most systems do not have the need for the
	<devicename>bpf</devicename> device compiled in.</para>

	<indexterm>
	<primary><command>sysctl</command></primary>
	</indexterm>

	<para>But even if you turn off the <devicename>bpf</devicename>
	device, you still have <filename>/dev/mem</filename> and
	<filename>/dev/kmem</filename> to worry about. For that
	matter, the intruder can still write to raw disk devices.
	Also, there is another kernel feature called the module
	loader, &man.kldload.8;. An enterprising intruder can use a
	KLD module to install his own <devicename>bpf</devicename>
	device, or other sniffing device, on a running kernel. To
	avoid these problems you have to run the kernel at a higher
	secure level, at least securelevel 1.</para>

	<para>The secure level of the kernel can be set in a variety of
	ways. The simplest way of raising the secure level of a
	running kernel is through a <command>sysctl</command> on the
	<varname>kern.securelevel</varname> kernel variable:</para>

	<screen>&prompt.root; <userinput>sysctl kern.securelevel=<replaceable>1</replaceable></userinput></screen>

	<para>By default, the &os; kernel boots with a secure level of
	-1. The secure level will remain at -1 unless it is altered,
	either by the administrator or by &man.init.8; because of a
	setting in the start up scripts. The secure level may be
	raised during system startup by setting the
	<varname>kern_securelevel_enable</varname> variable to
	<literal>YES</literal> in the
	<filename>/etc/rc.conf</filename> file, and the value of the
	<varname>kern_securelevel</varname> variable to the desired
	secure level.</para>

	<para>The default secure level of a &os; system right after the
	startup scripts are done is -1. This is called
	<quote>insecure mode</quote> because immutable file flags may
	be turned off, all devices may be read from or written to, and
	so on.</para>

	<para>Once the secure level is set to 1 or a higher value, the
	append-only and immutable files are honored, they cannot be
	turned off, and access to raw devices will be denied. Higher
	levels restrict even more operations. For a full description
	of the effect of various secure levels, please read the
	- &man.security.7; manual page (or the manual page of
	- &man.init.8; in releases older than &os; 7.0).</para>
	+ &man.security.7; manual page.</para>

	<note>
	<para>Bumping the secure level to 1 or higher may cause a few
	problems to X11 (access to <filename>/dev/io</filename> will
	be blocked), or to the installation of &os; built from
	source (the <maketarget>installworld</maketarget> part of
	the process needs to temporarily reset the append-only and
	immutable flags of some files), and in a few other cases.
	Sometimes, as in the case of X11, it may be possible to work
	around this by starting &man.xdm.1; pretty early in the boot
	process, when the securelevel is still low enough.
	Workarounds like this may not be possible for all secure
	levels or for all the potential restrictions they enforce.
	A bit of forward planning is a good idea. Understanding the
	restrictions imposed by each secure level is important as
	they severely diminish the ease of system use. It will also
	make choosing a default setting much simpler and prevent any
	surprises.</para>
	</note>

	<para>If the kernel's secure level is raised to 1 or a higher
	value, it may be useful to set the <literal>schg</literal>
	flag on critical startup binaries, directories, and script
	files (i.e., everything that gets run up to the point where
	the securelevel is set). This might be overdoing it, and
	upgrading the system is much more difficult when it operates
	at a high secure level. A less strict compromise is to run
	the system at a higher secure level but skip setting the
	<literal>schg</literal> flag for every system file and
	directory under the sun. Another possibility is to simply
	mount <filename class="directory">/</filename> and <filename
	class="directory">/usr</filename> read-only. It should be
	noted that being too draconian about what is permitted may
	prevent the all-important detection of an intrusion.</para>
	</sect2>

	<sect2 id="security-integrity">
	<title>Checking File Integrity: Binaries, Configuration Files,
	Etc.</title>

	<para>When it comes right down to it, you can only protect your
	core system configuration and control files so much before the
	convenience factor rears its ugly head. For example, using
	<command>chflags</command> to set the <literal>schg</literal>
	bit on most of the files in <filename
	class="directory">/</filename> and <filename
	class="directory">/usr</filename> is probably
	counterproductive, because while it may protect the files, it
	also closes a detection window. The last layer of your
	security onion is perhaps the most important —
	detection. The rest of your security is pretty much useless
	(or, worse, presents you with a false sense of security) if
	you cannot detect potential intrusions. Half the job of the
	onion is to slow down the attacker, rather than stop him, in
	order to be able to catch him in the act.</para>

	<para>The best way to detect an intrusion is to look for
	modified, missing, or unexpected files. The best way to look
	for modified files is from another (often centralized)
	limited-access system. Writing your security scripts on the
	extra-secure limited-access system makes them mostly invisible
	to potential attackers, and this is important. In order to
	take maximum advantage you generally have to give the
	limited-access box significant access to the other machines in
	the business, usually either by doing a read-only NFS export
	of the other machines to the limited-access box, or by setting
	up ssh key-pairs to allow the limited-access box to ssh to the
	other machines. Except for its network traffic, NFS is the
	least visible method — allowing you to monitor the file
	systems on each client box virtually undetected. If your
	limited-access server is connected to the client boxes through
	a switch, the NFS method is often the better choice. If your
	limited-access server is connected to the client boxes through
	a hub, or through several layers of routing, the NFS method
	may be too insecure (network-wise) and using ssh may be the
	better choice even with the audit-trail tracks that ssh
	lays.</para>

	<para>Once you have given a limited-access box at least read
	access to the client systems it is supposed to monitor, you
	must write scripts to do the actual monitoring. Given an NFS
	mount, you can write scripts out of simple system utilities
	such as &man.find.1; and &man.md5.1;. It is best to
	physically md5 the client-box files at least once a day, and
	to test control files such as those found in <filename
	class="directory">/etc</filename> and <filename
	class="directory">/usr/local/etc</filename> even more often.
	When mismatches are found, relative to the base md5
	information the limited-access machine knows is valid, it
	should scream at a sysadmin to go check it out. A good
	security script will also check for inappropriate suid
	binaries and for new or deleted files on system partitions
	such as <filename class="directory">/</filename> and <filename
	class="directory">/usr</filename>.</para>

	<para>When using ssh rather than NFS, writing the security
	script is much more difficult. You essentially have to
	<command>scp</command> the scripts to the client box in order
	to run them, making them visible, and for safety you also need
	to <command>scp</command> the binaries (such as find) that
	those scripts use. The <application>ssh</application> client
	on the client box may already be compromised. All in all,
	using ssh may be necessary when running over insecure links,
	but it is also a lot harder to deal with.</para>

	<para>A good security script will also check for changes to user
	and staff members access configuration files:
	<filename>.rhosts</filename>, <filename>.shosts</filename>,
	<filename>.ssh/authorized_keys</filename> and so forth, files
	that might fall outside the purview of the
	<literal>MD5</literal> check.</para>

	<para>If you have a huge amount of user disk space, it may take
	too long to run through every file on those partitions. In
	this case, setting mount flags to disallow suid binaries is a
	good idea. The <literal>nosuid</literal> option (see
	&man.mount.8;) is what you want to look into. You should
	probably scan them anyway, at least once a week, since the
	object of this layer is to detect a break-in attempt, whether
	or not the attempt succeeds.</para>

	<para>Process accounting (see &man.accton.8;) is a relatively
	low-overhead feature of the operating system which might help
	as a post-break-in evaluation mechanism. It is especially
	useful in tracking down how an intruder has actually broken
	into a system, assuming the file is still intact after the
	break-in has occurred.</para>

	<para>Finally, security scripts should process the log files,
	and the logs themselves should be generated in as secure a
	manner as possible — remote syslog can be very useful.
	An intruder will try to cover his tracks, and log files are
	critical to the sysadmin trying to track down the time and
	method of the initial break-in. One way to keep a permanent
	record of the log files is to run the system console to a
	serial port and collect the information to a secure machine
	monitoring the consoles.</para>
	</sect2>

	<sect2>
	<title>Paranoia</title>

	<para>A little paranoia never hurts. As a rule, a sysadmin can
	add any number of security features, as long as they do not
	affect convenience, and can add security features that
	<emphasis>do</emphasis> affect convenience with some added
	thought. Even more importantly, a security administrator
	should mix it up a bit — if you use recommendations such
	as those given by this document verbatim, you give away your
	methodologies to the prospective attacker who also has access
	to this document.</para>
	</sect2>

	<sect2>
	<title>Denial of Service Attacks</title>

	<indexterm>
	<primary>Denial of Service (DoS)</primary>
	</indexterm>

	<para>This section covers Denial of Service attacks. A DoS
	attack is typically a packet attack. While there is not much
	you can do about modern spoofed packet attacks that saturate
	your network, you can generally limit the damage by ensuring
	that the attacks cannot take down your servers by:</para>

	<orderedlist>
	<listitem>
	<para>Limiting server forks.</para>
	</listitem>

	<listitem>
	<para>Limiting springboard attacks (ICMP response attacks,
	ping broadcast, etc.).</para>
	</listitem>

	<listitem>
	<para>Overloading the Kernel Route Cache.</para>
	</listitem>
	</orderedlist>

	<para>A common DoS attack scenario is attacking a forking server
	and making it spawn so many child processes that the host
	system eventually runs out of memory, file descriptors, etc.
	and then grinds to a halt. <application>inetd</application>
	(see &man.inetd.8;) has several options to limit this sort of
	attack. It should be noted that while it is possible to
	prevent a machine from going down, it is not generally
	possible to prevent a service from being disrupted by the
	attack. Read the <application>inetd</application> manual page
	carefully and pay specific attention to the
	<option>-c</option>, <option>-C</option>, and
	<option>-R</option> options. Note that spoofed-IP attacks
	will circumvent the <option>-C</option> option to
	<application>inetd</application>, so typically a combination
	of options must be used. Some standalone servers have
	self-fork-limitation parameters.</para>

	<para><application>Sendmail</application> has its
	<option>-OMaxDaemonChildren</option> option, which tends to
	work much better than trying to use
	<application>Sendmail</application>'s load limiting options
	due to the load lag. You should specify a
	<literal>MaxDaemonChildren</literal> parameter, when you start
	<application>sendmail</application>; high enough to handle
	your expected load, but not so high that the computer cannot
	handle that number of <application>Sendmail</application>
	instances without falling on its face. It is also prudent to
	run <application>Sendmail</application> in queued mode
	(<option>-ODeliveryMode=queued</option>) and to run the daemon
	(<command>sendmail -bd</command>) separate from the queue-runs
	(<command>sendmail -q15m</command>). If you still want
	real-time delivery you can run the queue at a much lower
	interval, such as <option>-q1m</option>, but be sure to
	specify a reasonable <literal>MaxDaemonChildren</literal>
	option for <emphasis>that</emphasis>
	<application>Sendmail</application> to prevent cascade
	failures.</para>

	<para><application>Syslogd</application> can be attacked
	directly and it is strongly recommended that you use the
	<option>-s</option> option whenever possible, and the
	<option>-a</option> option otherwise.</para>

	<para>You should also be fairly careful with connect-back
	services such as <application>TCP Wrapper</application>'s
	reverse-identd, which can be attacked directly. You generally
	do not want to use the reverse-ident feature of
	<application>TCP Wrapper</application> for this reason.</para>

	<para>It is a very good idea to protect internal services from
	external access by firewalling them off at your border
	routers. The idea here is to prevent saturation attacks from
	outside your LAN, not so much to protect internal services
	from network-based <username>root</username> compromise.
	Always configure an exclusive firewall, i.e., <quote>firewall
	everything <emphasis>except</emphasis> ports A, B, C, D, and
	M-Z</quote>. This way you can firewall off all of your low
	ports except for certain specific services such as
	<application>named</application> (if you are primary for a
	zone), <application>ntalkd</application>,
	<application>sendmail</application>, and other
	Internet-accessible services. If you try to configure the
	firewall the other way — as an inclusive or permissive
	firewall, there is a good chance that you will forget to
	<quote>close</quote> a couple of services, or that you will
	add a new internal service and forget to update the firewall.
	You can still open up the high-numbered port range on the
	firewall, to allow permissive-like operation, without
	compromising your low ports. Also take note that &os; allows
	you to control the range of port numbers used for dynamic
	binding, via the various
	<varname>net.inet.ip.portrange</varname>
	<command>sysctl</command>'s (<command>sysctl -a \| fgrep
	portrange</command>), which can also ease the complexity of
	your firewall's configuration. For example, you might use a
	normal first/last range of 4000 to 5000, and a hiport range of
	49152 to 65535, then block off everything under 4000 in your
	firewall (except for certain specific Internet-accessible
	ports, of course).</para>

	<para>Another common DoS attack is called a springboard attack
	— to attack a server in a manner that causes the server
	to generate responses which overloads the server, the local
	network, or some other machine. The most common attack of
	this nature is the <emphasis>ICMP ping broadcast
	attack</emphasis>. The attacker spoofs ping packets sent to
	your LAN's broadcast address with the source IP address set to
	the actual machine they wish to attack. If your border
	routers are not configured to stomp on ping packets to
	broadcast addresses, your LAN winds up generating sufficient
	responses to the spoofed source address to saturate the
	victim, especially when the attacker uses the same trick on
	several dozen broadcast addresses over several dozen different
	networks at once. Broadcast attacks of over a hundred and
	twenty megabits have been measured. A second common
	springboard attack is against the ICMP error reporting system.
	By constructing packets that generate ICMP error responses, an
	attacker can saturate a server's incoming network and cause
	the server to saturate its outgoing network with ICMP
	responses. This type of attack can also crash the server by
	running it out of memory, especially if the server cannot
	drain the ICMP responses it generates fast enough. Use the
	<application>sysctl</application> variable
	<literal>net.inet.icmp.icmplim</literal> to limit these
	attacks. The last major class of springboard attacks is
	related to certain internal <application>inetd</application>
	services such as the udp echo service. An attacker simply
	spoofs a UDP packet with the source address being server A's
	echo port, and the destination address being server B's echo
	port, where server A and B are both on your LAN. The two
	servers then bounce this one packet back and forth between
	each other. The attacker can overload both servers and their
	LANs simply by injecting a few packets in this manner.
	Similar problems exist with the internal
	<application>chargen</application> port. A competent sysadmin
	will turn off all of these inetd-internal test
	services.</para>

	<para>Spoofed packet attacks may also be used to overload the
	kernel route cache. Refer to the
	<varname>net.inet.ip.rtexpire</varname>,
	<varname>rtminexpire</varname>, and
	<varname>rtmaxcache</varname> <command>sysctl</command>
	parameters. A spoofed packet attack that uses a random source
	IP will cause the kernel to generate a temporary cached route
	in the route table, viewable with <command>netstat -rna \|
	fgrep W3</command>. These routes typically timeout in 1600
	seconds or so. If the kernel detects that the cached route
	table has gotten too big it will dynamically reduce the
	<varname>rtexpire</varname> but will never decrease it to less
	than <varname>rtminexpire</varname>. There are two
	problems:</para>

	<orderedlist>
	<listitem>

	<para>The kernel does not react quickly enough when a
	lightly loaded server is suddenly attacked.</para>
	</listitem>

	<listitem>
	<para>The <varname>rtminexpire</varname> is not low enough
	for the kernel to survive a sustained attack.</para>
	</listitem>
	</orderedlist>

	<para>If your servers are connected to the Internet via a T3 or
	better, it may be prudent to manually override both
	<varname>rtexpire</varname> and <varname>rtminexpire</varname>
	via &man.sysctl.8;. Never set either parameter to zero
	(unless you want to crash the machine). Setting both
	parameters to 2 seconds should be sufficient to protect the
	route table from attack.</para>
	</sect2>

	<sect2>
	<title>Access Issues with Kerberos and SSH</title>

	<indexterm><primary><command>ssh</command></primary></indexterm>

	<para>There are a few issues with both Kerberos and
	ssh that need to be addressed if
	you intend to use them. Kerberos 5 is an excellent
	authentication protocol, but there are bugs in the kerberized
	<application>telnet</application> and
	<application>rlogin</application> applications that make them
	unsuitable for dealing with binary streams. Also, by default
	Kerberos does not encrypt a session unless you use the
	<option>-x</option> option. <application>ssh</application>
	encrypts everything by default.</para>

	<para>Ssh works quite well in every respect except that it
	forwards encryption keys by default. What this means is that
	if you have a secure workstation holding keys that give you
	access to the rest of the system, and you ssh to an insecure
	machine, your keys are usable. The actual keys themselves are
	not exposed, but ssh installs a forwarding port for the
	duration of your login, and if an attacker has broken
	<username>root</username> on the insecure machine he can
	utilize that port to use your keys to gain access to any other
	machine that your keys unlock.</para>

	<para>We recommend that you use ssh in combination with Kerberos
	whenever possible for staff logins.
	<application>Ssh</application> can be compiled with Kerberos
	support. This reduces your reliance on potentially exposed
	ssh keys while at the same time protecting passwords via
	Kerberos. Ssh keys should only be used for automated tasks
	from secure machines (something that Kerberos is unsuited to
	do). We also recommend that you either turn off
	key-forwarding in the ssh configuration, or that you make use
	of the <literal>from=IP/DOMAIN</literal> option that ssh
	allows in its <filename>authorized_keys</filename> file to
	make the key only usable to entities logging in from specific
	machines.</para>
	</sect2>
	</sect1>

	<sect1 id="crypt">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Bill</firstname>
	<surname>Swingle</surname>
	<contrib>Parts rewritten and updated by </contrib>
	</author>
	</authorgroup>
	<!-- 21 Mar 2000 -->
	</sect1info>

	<title>DES, Blowfish, MD5, SHA256, SHA512, and Crypt</title>

	<indexterm>
	<primary>security</primary>
	<secondary>crypt</secondary>
	</indexterm>

	<indexterm><primary>crypt</primary></indexterm>
	<indexterm><primary>Blowfish</primary></indexterm>
	<indexterm><primary>DES</primary></indexterm>
	<indexterm><primary>MD5</primary></indexterm>
	<indexterm><primary>SHA256</primary></indexterm>
	<indexterm><primary>SHA512</primary></indexterm>

	<para>Every user on a &unix; system has a password associated with
	their account. It seems obvious that these passwords need to be
	known only to the user and the actual operating system. In
	order to keep these passwords secret, they are encrypted with
	what is known as a <quote>one-way hash</quote>, that is, they
	can only be easily encrypted but not decrypted. In other words,
	what we told you a moment ago was obvious is not even true: the
	operating system itself does not <emphasis>really</emphasis>
	know the password. It only knows the
	<emphasis>encrypted</emphasis> form of the password. The only
	way to get the <quote>plain-text</quote> password is by a brute
	force search of the space of possible passwords.</para>

	<para>Unfortunately the only secure way to encrypt passwords when
	&unix; came into being was based on DES, the Data Encryption
	Standard. This was not such a problem for users resident in the
	US, but since the source code for DES could not be exported
	outside the US, &os; had to find a way to both comply with US
	law and retain compatibility with all the other &unix; variants
	that still used DES.</para>

	<para>The solution was to divide up the encryption libraries so
	that US users could install the DES libraries and use DES but
	international users still had an encryption method that could be
	exported abroad. This is how &os; came to use MD5 as its
	default encryption method. MD5 is believed to be more secure
	than DES, so installing DES is offered primarily for
	compatibility reasons.</para>

	<sect2>
	<title>Recognizing Your Crypt Mechanism</title>

	<para>Currently the library supports DES, MD5, Blowfish, SHA256,
	- and SHA512 hash functions. By default &os; uses MD5 to
	- encrypt passwords.</para>
	+ and SHA512 hash functions. By default &os; 9.1 and later
	+ uses SHA512 to encrypt passwords. Older versions use MD5 by
	+ default.</para>

	<para>It is pretty easy to identify which encryption method &os;
	is set up to use. Examining the encrypted passwords in the
	<filename>/etc/master.passwd</filename> file is one way.
	Passwords encrypted with the MD5 hash are longer than those
	encrypted with the DES hash and also begin with the characters
	<literal>&dollar;1&dollar;</literal>. Passwords starting with
	<literal>&dollar;2a&dollar;</literal> are encrypted with the
	Blowfish hash function. DES password strings do not have any
	particular identifying characteristics, but they are shorter
	than MD5 passwords, and are coded in a 64-character alphabet
	which does not include the <literal>&dollar;</literal>
	character, so a relatively short string which does not begin
	with a dollar sign is very likely a DES password. Both SHA256
	and SHA512 begin with the characters
	<literal>&dollar;6&dollar;</literal>.</para>

	<para>The password format used for new passwords is controlled
	by the <literal>passwd_format</literal> login capability in
	<filename>/etc/login.conf</filename>, which takes values of
	<literal>des</literal>, <literal>md5</literal>,
	<literal>blf</literal>, <literal>sha256</literal> or
	<literal>sha512</literal>. See the &man.login.conf.5; manual
	page for more information about login capabilities.</para>
	</sect2>
	</sect1>

	<sect1 id="one-time-passwords">
	<title>One-time Passwords</title>

	<indexterm><primary>one-time passwords</primary></indexterm>
	<indexterm>
	<primary>security</primary>
	<secondary>one-time passwords</secondary>
	</indexterm>

	<para>By default, &os; includes support for OPIE (One-time
	Passwords In Everything), which uses the MD5 hash by
	default.</para>

	<para>There are three different sorts of passwords which we will
	discuss below. The first is your usual &unix; style or Kerberos
	password; we will call this a <quote>&unix; password</quote>.
	The second sort is the one-time password which is generated by
	the OPIE &man.opiekey.1; program and accepted by the
	&man.opiepasswd.1; program and the login prompt; we will call
	this a <quote>one-time password</quote>. The final sort of
	password is the secret password which you give to the
	<command>opiekey</command> program (and sometimes the
	<command>opiepasswd</command> programs) which it uses to
	generate one-time passwords; we will call it a <quote>secret
	password</quote> or just unqualified
	<quote>password</quote>.</para>

	<para>The secret password does not have anything to do with your
	&unix; password; they can be the same but this is not
	recommended. OPIE secret passwords are not limited to 8
	characters like old &unix; passwords<footnote><para>Under &os;
	the standard login password may be up to 128 characters in
	length.</para></footnote>, they can be as long as you like.
	Passwords of six or seven word long phrases are fairly common.
	For the most part, the OPIE system operates completely
	independently of the &unix; password system.</para>

	<para>Besides the password, there are two other pieces of data
	that are important to OPIE. One is what is known as the
	<quote>seed</quote> or <quote>key</quote>, consisting of two
	letters and five digits. The other is what is called the
	<quote>iteration count</quote>, a number between 1 and 100.
	OPIE creates the one-time password by concatenating the seed and
	the secret password, then applying the MD5 hash as many times as
	specified by the iteration count and turning the result into six
	short English words. These six English words are your one-time
	password. The authentication system (primarily PAM) keeps track
	of the last one-time password used, and the user is
	authenticated if the hash of the user-provided password is equal
	to the previous password. Because a one-way hash is used it is
	impossible to generate future one-time passwords if a
	successfully used password is captured; the iteration count is
	decremented after each successful login to keep the user and the
	login program in sync. When the iteration count gets down to 1,
	OPIE must be reinitialized.</para>

	<para>There are a few programs involved in each system which we
	will discuss below. The <command>opiekey</command> program
	accepts an iteration count, a seed, and a secret password, and
	generates a one-time password or a consecutive list of one-time
	passwords. The <command>opiepasswd</command> program is used to
	initialize OPIE, and to change passwords, iteration counts, or
	seeds; it takes either a secret passphrase, or an iteration
	count, seed, and a one-time password. The
	<command>opieinfo</command> program will examine the relevant
	credentials files (<filename>/etc/opiekeys</filename>) and print
	out the invoking user's current iteration count and seed.</para>

	<para>There are four different sorts of operations we will cover.
	The first is using <command>opiepasswd</command> over a secure
	connection to set up one-time-passwords for the first time, or
	to change your password or seed. The second operation is using
	<command>opiepasswd</command> over an insecure connection, in
	conjunction with <command>opiekey</command> over a secure
	connection, to do the same. The third is using
	<command>opiekey</command> to log in over an insecure
	connection. The fourth is using <command>opiekey</command> to
	generate a number of keys which can be written down or printed
	out to carry with you when going to some location without secure
	connections to anywhere.</para>

	<sect2>
	<title>Secure Connection Initialization</title>

	<para>To initialize OPIE for the first time, execute the
	<command>opiepasswd</command> command:</para>

	<screen>&prompt.user; <userinput>opiepasswd -c</userinput>
	[grimreaper] ~ $ opiepasswd -f -c
	Adding unfurl:
	Only use this method from the console; NEVER from remote. If you are using
	telnet, xterm, or a dial-in, type ^C now or exit with no password.
	Then run opiepasswd without the -c parameter.
	Using MD5 to compute responses.
	Enter new secret pass phrase:
	Again new secret pass phrase:

	ID unfurl OTP key is 499 to4268
	MOS MALL GOAT ARM AVID COED</screen>

	<para>At the <prompt>Enter new secret pass phrase:</prompt> or
	<prompt>Enter secret password:</prompt> prompts, you should
	enter a password or phrase. Remember, this is not the
	password that you will use to login with, this is used to
	generate your one-time login keys. The <quote>ID</quote> line
	gives the parameters of your particular instance: your login
	name, the iteration count, and seed. When logging in the
	system will remember these parameters and present them back to
	you so you do not have to remember them. The last line gives
	the particular one-time password which corresponds to those
	parameters and your secret password; if you were to re-login
	immediately, this one-time password is the one you would
	use.</para>
	</sect2>

	<sect2>
	<title>Insecure Connection Initialization</title>

	<para>To initialize or change your secret password over an
	insecure connection, you will need to already have a secure
	connection to some place where you can run
	<command>opiekey</command>; this might be in the form of a
	shell prompt on a machine you trust. You will also need to
	make up an iteration count (100 is probably a good value), and
	you may make up your own seed or use a randomly-generated one.
	Over on the insecure connection (to the machine you are
	initializing), use <command>opiepasswd</command>:</para>

	<screen>&prompt.user; <userinput>opiepasswd</userinput>

	Updating unfurl:
	You need the response from an OTP generator.
	Old secret pass phrase:
	otp-md5 498 to4268 ext
	Response: GAME GAG WELT OUT DOWN CHAT
	New secret pass phrase:
	otp-md5 499 to4269
	Response: LINE PAP MILK NELL BUOY TROY

	ID mark OTP key is 499 gr4269
	LINE PAP MILK NELL BUOY TROY</screen>

	<para>To accept the default seed press <keycap>Return</keycap>.
	Then before entering an access password, move over to your
	secure connection and give it the same parameters:</para>

	<screen>&prompt.user; <userinput>opiekey 498 to4268</userinput>
	Using the MD5 algorithm to compute response.
	Reminder: Don't use opiekey from telnet or dial-in sessions.
	Enter secret pass phrase:
	GAME GAG WELT OUT DOWN CHAT</screen>

	<para>Now switch back over to the insecure connection, and copy
	the one-time password generated over to the relevant
	program.</para>
	</sect2>

	<sect2>
	<title>Generating a Single One-time Password</title>

	<para>Once you have initialized OPIE and login, you will be
	presented with a prompt like this:</para>

	<screen>&prompt.user; <userinput>telnet example.com</userinput>
	Trying 10.0.0.1...
	Connected to example.com
	Escape character is '^]'.

	FreeBSD/i386 (example.com) (ttypa)

	login: <userinput><username></userinput>
	otp-md5 498 gr4269 ext
	Password: </screen>

	<para>As a side note, the OPIE prompts have a useful feature
	(not shown here): if you press <keycap>Return</keycap> at the
	password prompt, the prompter will turn echo on, so you can
	see what you are typing. This can be extremely useful if you
	are attempting to type in a password by hand, such as from a
	printout.</para>

	<indexterm><primary>MS-DOS</primary></indexterm>
	<indexterm><primary>Windows</primary></indexterm>
	<indexterm><primary>MacOS</primary></indexterm>

	<para>At this point you need to generate your one-time password
	to answer this login prompt. This must be done on a trusted
	system that you can run <command>opiekey</command> on. (There
	are versions of these for DOS, &windows; and &macos; as well.)
	They need the iteration count and the seed as command line
	options. You can cut-and-paste these right from the login
	prompt on the machine that you are logging in to.</para>

	<para>On the trusted system:</para>

	<screen>&prompt.user; <userinput>opiekey 498 to4268</userinput>
	Using the MD5 algorithm to compute response.
	Reminder: Don't use opiekey from telnet or dial-in sessions.
	Enter secret pass phrase:
	GAME GAG WELT OUT DOWN CHAT</screen>

	<para>Now that you have your one-time password you can continue
	logging in.</para>
	</sect2>

	<sect2>
	<title>Generating Multiple One-time Passwords</title>

	<para>Sometimes you have to go places where you do not have
	access to a trusted machine or secure connection. In this
	case, it is possible to use the <command>opiekey</command>
	command to generate a number of one-time passwords beforehand
	to be printed out and taken with you. For example:</para>

	<screen>&prompt.user; <userinput>opiekey -n 5 30 zz99999</userinput>
	Using the MD5 algorithm to compute response.
	Reminder: Don't use opiekey from telnet or dial-in sessions.
	Enter secret pass phrase: <userinput><secret password></userinput>
	26: JOAN BORE FOSS DES NAY QUIT
	27: LATE BIAS SLAY FOLK MUCH TRIG
	28: SALT TIN ANTI LOON NEAL USE
	29: RIO ODIN GO BYE FURY TIC
	30: GREW JIVE SAN GIRD BOIL PHI</screen>

	<para>The <option>-n 5</option> requests five keys in sequence,
	the <option>30</option> specifies what the last iteration
	number should be. Note that these are printed out in
	<emphasis>reverse</emphasis> order of eventual use. If you
	are really paranoid, you might want to write the results down
	by hand; otherwise you can cut-and-paste into
	<command>lpr</command>. Note that each line shows both the
	iteration count and the one-time password; you may still find
	it handy to scratch off passwords as you use them.</para>
	</sect2>

	<sect2>
	<title>Restricting Use of &unix; Passwords</title>

	<para>OPIE can restrict the use of &unix; passwords based on the
	IP address of a login session. The relevant file is
	<filename>/etc/opieaccess</filename>, which is present by
	default. Please check &man.opieaccess.5; for more information
	on this file and which security considerations you should be
	aware of when using it.</para>

	<para>Here is a sample <filename>opieaccess</filename>
	file:</para>

	<programlisting>permit 192.168.0.0 255.255.0.0</programlisting>

	<para>This line allows users whose IP source address (which is
	vulnerable to spoofing) matches the specified value and mask,
	to use &unix; passwords at any time.</para>

	<para>If no rules in <filename>opieaccess</filename> are
	matched, the default is to deny non-OPIE logins.</para>
	</sect2>
	</sect1>

	<sect1 id="tcpwrappers">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>TCP Wrappers</title>

	<indexterm><primary>TCP Wrappers</primary></indexterm>

	<para>Anyone familiar with &man.inetd.8; has probably heard of
	<acronym>TCP</acronym> Wrappers at some point. But few
	individuals seem to fully comprehend its usefulness in a network
	environment. It seems that everyone wants to install a firewall
	to handle network connections. While a firewall has a wide
	variety of uses, there are some things that a firewall will not
	handle, such as sending text back to the connection originator.
	The <acronym>TCP</acronym> Wrappers software does this and much
	more. In the next few sections many of the
	<acronym>TCP</acronym> Wrappers features will be discussed, and,
	when applicable, example configuration lines will be
	provided.</para>

	<para>The <acronym>TCP</acronym> Wrappers software extends the
	abilities of <application>inetd</application> to provide support
	for every server daemon under its control. Using this method it
	is possible to provide logging support, return messages to
	connections, permit a daemon to only accept internal
	connections, etc. While some of these features can be provided
	by implementing a firewall, this will add not only an extra
	layer of protection but go beyond the amount of control a
	firewall can provide.</para>

	<para>The added functionality of <acronym>TCP</acronym> Wrappers
	should not be considered a replacement for a good firewall.
	<acronym>TCP</acronym> Wrappers can be used in conjunction
	with a firewall or other security enhancements though and
	it can serve nicely as an extra layer of protection
	for the system.</para>

	<para>Since this is an extension to the configuration of
	<application>inetd</application>, the reader is expected have
	read the <link linkend="network-inetd">inetd
	configuration</link> section.</para>

	<note>
	<para>While programs run by &man.inetd.8; are not exactly
	<quote>daemons</quote>, they have traditionally been called
	daemons. This is the term we will use in this section
	too.</para>
	</note>

	<sect2>
	<title>Initial Configuration</title>

	<para>The only requirement of using <acronym>TCP</acronym>
	Wrappers in &os; is to ensure the
	<application>inetd</application> server is started from
	<filename>rc.conf</filename> with the <option>-Ww</option>
	option; this is the default setting. Of course, proper
	configuration of <filename>/etc/hosts.allow</filename> is also
	expected, but &man.syslogd.8; will throw messages in the
	system logs in these cases.</para>

	<note>
	<para>Unlike other implementations of <acronym>TCP</acronym>
	Wrappers, the use of <filename>hosts.deny</filename> has
	been deprecated. All configuration options should be placed
	in <filename>/etc/hosts.allow</filename>.</para>
	</note>

	<para>In the simplest configuration, daemon connection policies
	are set to either be permitted or blocked depending on the
	options in <filename>/etc/hosts.allow</filename>. The default
	configuration in &os; is to allow a connection to every daemon
	started with <application>inetd</application>. Changing this
	will be discussed only after the basic configuration is
	covered.</para>

	<para>Basic configuration usually takes the form of
	<literal>daemon : address : action</literal>. Where
	<literal>daemon</literal> is the daemon name which
	<command>inetd</command> started. The
	<literal>address</literal> can be a valid hostname, an
	<acronym>IP</acronym> address or an IPv6 address enclosed in
	brackets ([ ]). The <literal>action</literal> field can
	be either <literal>allow</literal> or <literal>deny</literal>
	to grant or deny access appropriately. Keep in mind that
	configuration works off a first rule match semantic, meaning
	that the configuration file is scanned in ascending order for
	a matching rule. When a match is found the rule is applied
	and the search process will halt.</para>

	<para>Several other options exist but they will be explained
	in a later section. A simple configuration line may easily be
	constructed from that information alone. For example, to
	allow <acronym>POP</acronym>3 connections via the
	<filename role="package">mail/qpopper</filename> daemon,
	the following lines should be appended to
	<filename>hosts.allow</filename>:</para>

	<programlisting># This line is required for POP3 connections:
	qpopper : ALL : allow</programlisting>

	<para>After adding this line, <application>inetd</application>
	will need to be restarted by using &man.service.8;:</para>

	<screen>&prompt.root; <userinput>service inetd restart</userinput></screen>
	</sect2>

	<sect2>
	<title>Advanced Configuration</title>

	<para><acronym>TCP</acronym> Wrappers has advanced options too;
	they will allow for more control over the way connections are
	handled. In some cases it may be a good idea to return a
	comment to certain hosts or daemon connections. In other
	cases, perhaps a log file should be recorded or an email sent
	to the administrator. Other situations may require the use of
	a service for local connections only. This is all possible
	through the use of configuration options known as
	<literal>wildcards</literal>, expansion characters and
	external command execution. The next two sections are written
	to cover these situations.</para>

	<sect3>
	<title>External Commands</title>

	<para>Suppose that a situation occurs where a connection
	should be denied yet a reason should be sent to the
	individual who attempted to establish that connection. How
	could it be done? That action can be made possible by using
	the <option>twist</option> option. When a connection
	attempt is made, <option>twist</option> will be called to
	execute a shell command or script. An example already
	exists in the <filename>hosts.allow</filename> file:</para>

	<programlisting># The rest of the daemons are protected.
	ALL : ALL \
	: severity auth.info \
	: twist /bin/echo "You are not welcome to use %d from %h."</programlisting>

	<para>This example shows that the message,
	<quote>You are not allowed to use <literal>daemon</literal>
	from <literal>hostname</literal>.</quote> will be returned
	for any daemon not previously configured in the access file.
	This is extremely useful for sending a reply back to the
	connection initiator right after the established connection
	is dropped. Note that any message returned
	<emphasis>must</emphasis> be wrapped in quote
	<literal>"</literal> characters; there are no exceptions to
	this rule.</para>

	<warning>
	<para>It may be possible to launch a denial of service
	attack on the server if an attacker, or group of
	attackers, could flood these daemons with connection
	requests.</para>
	</warning>

	<para>Another possibility is to use the <option>spawn</option>
	option in these cases. Like <option>twist</option>, the
	<option>spawn</option> option implicitly denies the
	connection and may be used to run external shell commands or
	scripts. Unlike <option>twist</option>,
	<option>spawn</option> will not send a reply back to the
	individual who established the connection. For an example,
	consider the following configuration line:</para>

	<programlisting># We do not allow connections from example.com:
	ALL : .example.com \
	: spawn (/bin/echo %a from %h attempted to access %d >> \
	/var/log/connections.log) \
	: deny</programlisting>

	<para>This will deny all connection attempts from the <hostid
	role="fqdn">*.example.com</hostid> domain; simultaneously
	logging the hostname, <acronym>IP</acronym> address and the
	daemon which they attempted to access in the
	<filename>/var/log/connections.log</filename> file.</para>

	<para>Aside from the already explained substitution characters
	above, e.g., <literal>%a</literal>, a few others exist. See
	the &man.hosts.access.5; manual page for the complete
	list.</para>
	</sect3>

	<sect3>
	<title>Wildcard Options</title>

	<para>Thus far the <literal>ALL</literal> option has been used
	continuously throughout the examples. Other options exist
	which could extend the functionality a bit further. For
	instance, <literal>ALL</literal> may be used to match every
	instance of either a daemon, domain or an
	<acronym>IP</acronym> address. Another wildcard available
	is <literal>PARANOID</literal> which may be used to match
	any host which provides an <acronym>IP</acronym> address
	that may be forged. In other words,
	<literal>PARANOID</literal> may be used to define an action
	to be taken whenever a connection is made from an
	<acronym>IP</acronym> address that differs from its
	hostname. The following example may shed some more light on
	this discussion:</para>

	<programlisting># Block possibly spoofed requests to sendmail:
	sendmail : PARANOID : deny</programlisting>

	<para>In that example all connection requests to
	<command>sendmail</command> which have an
	<acronym>IP</acronym> address that varies from its hostname
	will be denied.</para>

	<caution>
	<para>Using the <literal>PARANOID</literal> wildcard may
	severely cripple servers if the client or server has a
	broken <acronym>DNS</acronym> setup. Administrator
	discretion is advised.</para>
	</caution>

	<para>To learn more about wildcards and their associated
	functionality, see the &man.hosts.access.5; manual
	page.</para>

	<para>Before any of the specific configuration lines above
	will work, the first configuration line should be commented
	out in <filename>hosts.allow</filename>. This was noted at
	the beginning of this section.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="kerberos5">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tillman</firstname>
	<surname>Hodgson</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Mark</firstname>
	<surname>Murray</surname>
	<contrib>Based on a contribution by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title><application>Kerberos5</application></title>

	<para><application>Kerberos</application> is a network add-on
	system/protocol that allows users to authenticate themselves
	through the services of a secure server. Services such as
	remote login, remote copy, secure inter-system file copying and
	other high-risk tasks are made considerably safer and more
	controllable.</para>

	<para><application>Kerberos</application> can be described as an
	identity-verifying proxy system. It can also be described as a
	trusted third-party authentication system.
	<application>Kerberos</application> provides only one function
	— the secure authentication of users on the network. It
	does not provide authorization functions (what users are allowed
	to do) or auditing functions (what those users did). After a
	client and server have used <application>Kerberos</application>
	to prove their identity, they can also encrypt all of their
	communications to assure privacy and data integrity as they go
	about their business.</para>

	<para>Therefore it is highly recommended that
	<application>Kerberos</application> be used with other security
	methods which provide authorization and audit services.</para>

	<para>The following instructions can be used as a guide on how to
	set up <application>Kerberos</application> as distributed for
	&os;. However, you should refer to the relevant manual pages
	for a complete description.</para>

	<para>For purposes of demonstrating a
	<application>Kerberos</application> installation, the various
	name spaces will be handled as follows:</para>

	<itemizedlist>
	<listitem>
	<para>The <acronym>DNS</acronym> domain (<quote>zone</quote>)
	will be example.org.</para>
	</listitem>

	<listitem>
	<para>The <application>Kerberos</application> realm will be
	EXAMPLE.ORG.</para>
	</listitem>
	</itemizedlist>

	<note>
	<para>Please use real domain names when setting up
	<application>Kerberos</application> even if you intend to run
	it internally. This avoids <acronym>DNS</acronym> problems
	and assures inter-operation with other
	<application>Kerberos</application> realms.</para>
	</note>

	<sect2>
	<title>History</title>

	<indexterm>
	<primary>Kerberos5</primary>
	<secondary>history</secondary>
	</indexterm>

	<para><application>Kerberos</application> was created by
	<acronym>MIT</acronym> as a solution to network security
	problems. The <application>Kerberos</application> protocol
	uses strong cryptography so that a client can prove its
	identity to a server (and vice versa) across an insecure
	network connection.</para>

	<para><application>Kerberos</application> is both the name of a
	network authentication protocol and an adjective to describe
	programs that implement the program
	(<application>Kerberos</application> telnet, for example).
	The current version of the protocol is version 5, described in
	<acronym>RFC</acronym> 1510.</para>

	<para>Several free implementations of this protocol are
	available, covering a wide range of operating systems. The
	Massachusetts Institute of Technology
	(<acronym>MIT</acronym>), where
	<application>Kerberos</application> was originally developed,
	continues to develop their <application>Kerberos</application>
	package. It is commonly used in the <acronym>US</acronym> as
	a cryptography product, as such it has historically been
	affected by <acronym>US</acronym> export regulations. The
	<acronym>MIT</acronym> <application>Kerberos</application> is
	available as a port (<filename
	role="package">security/krb5</filename>). Heimdal
	<application>Kerberos</application> is another version 5
	implementation, and was explicitly developed outside of the
	<acronym>US</acronym> to avoid export regulations (and is thus
	often included in non-commercial &unix; variants). The
	Heimdal <application>Kerberos</application> distribution is
	available as a port (<filename
	role="package">security/heimdal</filename>), and a minimal
	installation of it is included in the base &os;
	install.</para>

	<para>In order to reach the widest audience, these instructions
	assume the use of the Heimdal distribution included in
	&os;.</para>
	</sect2>

	<sect2>
	<title>Setting up a Heimdal <acronym>KDC</acronym></title>

	<indexterm>
	<primary>Kerberos5</primary>
	<secondary>Key Distribution Center</secondary>
	</indexterm>

	<para>The Key Distribution Center (<acronym>KDC</acronym>) is
	the centralized authentication service that
	<application>Kerberos</application> provides — it is the
	computer that issues <application>Kerberos</application>
	tickets. The <acronym>KDC</acronym> is considered
	<quote>trusted</quote> by all other computers in the
	<application>Kerberos</application> realm, and thus has
	heightened security concerns.</para>

	<para>Note that while running the
	<application>Kerberos</application> server requires very few
	computing resources, a dedicated machine acting only as a
	<acronym>KDC</acronym> is recommended for security
	reasons.</para>

	<para>To begin setting up a <acronym>KDC</acronym>, ensure that
	your <filename>/etc/rc.conf</filename> file contains the
	correct settings to act as a <acronym>KDC</acronym> (you may
	need to adjust paths to reflect your own system):</para>

	<programlisting>kerberos5_server_enable="YES"
	kadmind5_server_enable="YES"</programlisting>

	<para>Next we will set up your
	<application>Kerberos</application> config file,
	<filename>/etc/krb5.conf</filename>:</para>

	<programlisting>[libdefaults]
	default_realm = EXAMPLE.ORG
	[realms]
	EXAMPLE.ORG = {
	kdc = kerberos.example.org
	admin_server = kerberos.example.org
	}
	[domain_realm]
	.example.org = EXAMPLE.ORG</programlisting>

	<para>Note that this <filename>/etc/krb5.conf</filename> file
	implies that your <acronym>KDC</acronym> will have the
	fully-qualified hostname of <hostid
	role="fqdn">kerberos.example.org</hostid>. You will need to
	add a CNAME (alias) entry to your zone file to accomplish this
	if your <acronym>KDC</acronym> has a different
	hostname.</para>

	<note>
	<para>For large networks with a properly configured
	<acronym>BIND</acronym> <acronym>DNS</acronym> server, the
	above example could be trimmed to:</para>

	<programlisting>[libdefaults]
	default_realm = EXAMPLE.ORG</programlisting>

	<para>With the following lines being appended to the
	<hostid role="fqdn">example.org</hostid> zonefile:</para>

	<programlisting>_kerberos._udp IN SRV 01 00 88 kerberos.example.org.
	_kerberos._tcp IN SRV 01 00 88 kerberos.example.org.
	_kpasswd._udp IN SRV 01 00 464 kerberos.example.org.
	_kerberos-adm._tcp IN SRV 01 00 749 kerberos.example.org.
	_kerberos IN TXT EXAMPLE.ORG</programlisting>
	</note>

	<note>
	<para>For clients to be able to find the
	<application>Kerberos</application> services, you
	<emphasis>must</emphasis> have either a fully configured
	<filename>/etc/krb5.conf</filename> or a minimally
	configured <filename>/etc/krb5.conf</filename>
	<emphasis>and</emphasis> a properly configured DNS
	server.</para>
	</note>

	<para>Next we will create the
	<application>Kerberos</application> database. This database
	contains the keys of all principals encrypted with a master
	password. You are not required to remember this password, it
	will be stored in a file
	(<filename>/var/heimdal/m-key</filename>). To create the
	master key, run <command>kstash</command> and enter a
	password.</para>

	<para>Once the master key has been created, you can initialize
	the database using the <command>kadmin</command> program with
	the <literal>-l</literal> option (standing for
	<quote>local</quote>). This option instructs
	<command>kadmin</command> to modify the database files
	directly rather than going through the
	<command>kadmind</command> network service. This handles the
	chicken-and-egg problem of trying to connect to the database
	before it is created. Once you have the
	<command>kadmin</command> prompt, use the
	<command>init</command> command to create your realms initial
	database.</para>

	<para>Lastly, while still in <command>kadmin</command>, create
	your first principal using the <command>add</command> command.
	Stick to the defaults options for the principal for now, you
	can always change them later with the
	<command>modify</command> command. Note that you can use the
	<literal>?</literal> command at any prompt to see the
	available options.</para>

	<para>A sample database creation session is shown below:</para>

	<screen>&prompt.root; <userinput>kstash</userinput>
	Master key: <userinput>xxxxxxxx</userinput>
	Verifying password - Master key: <userinput>xxxxxxxx</userinput>

	&prompt.root; <userinput>kadmin -l</userinput>
	kadmin> <userinput>init EXAMPLE.ORG</userinput>
	Realm max ticket life [unlimited]:
	kadmin> <userinput>add tillman</userinput>
	Max ticket life [unlimited]:
	Max renewable life [unlimited]:
	Attributes []:
	Password: <userinput>xxxxxxxx</userinput>
	Verifying password - Password: <userinput>xxxxxxxx</userinput></screen>

	<para>Now it is time to start up the <acronym>KDC</acronym>
	services. Run <command>service kerberos start</command> and
	<command>service kadmind start</command> to bring up the
	services. Note that you will not have any kerberized daemons
	running at this point but you should be able to confirm that
	the <acronym>KDC</acronym> is functioning by obtaining and
	listing a ticket for the principal (user) that you just
	created from the command-line of the <acronym>KDC</acronym>
	itself:</para>

	<screen>&prompt.user; <userinput>kinit <replaceable>tillman</replaceable></userinput>
	tillman@EXAMPLE.ORG's Password:

	&prompt.user; <userinput>klist</userinput>
	Credentials cache: FILE:<filename>/tmp/krb5cc_500</filename>
	Principal: tillman@EXAMPLE.ORG

	Issued Expires Principal
	Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG</screen>

	<para>The ticket can then be revoked when you have
	finished:</para>

	<screen>&prompt.user; <userinput>kdestroy</userinput></screen>
	</sect2>

	<sect2>
	<title><application>Kerberos</application> Enabling a Server
	with Heimdal Services</title>

	<indexterm>
	<primary>Kerberos5</primary>
	<secondary>enabling services</secondary>
	</indexterm>

	<para>First, we need a copy of the
	<application>Kerberos</application> configuration file,
	<filename>/etc/krb5.conf</filename>. To do so, simply copy
	it over to the client computer from the
	<acronym>KDC</acronym> in a secure fashion (using network
	utilities, such as &man.scp.1;, or physically via a floppy
	disk).</para>

	<para>Next you need a <filename>/etc/krb5.keytab</filename>
	file. This is the major difference between a server
	providing <application>Kerberos</application> enabled
	daemons and a workstation — the server must have a
	<filename>keytab</filename> file. This file contains the
	server's host key, which allows it and the
	<acronym>KDC</acronym> to verify each others identity. It
	must be transmitted to the server in a secure fashion, as
	the security of the server can be broken if the key is made
	public. This explicitly means that transferring it via a
	clear text channel, such as <acronym>FTP</acronym>, is a
	very bad idea.</para>

	<para>Typically, you transfer the <filename>keytab</filename>
	to the server using the <command>kadmin</command> program.
	This is handy because you also need to create the host
	principal (the <acronym>KDC</acronym> end of the
	<filename>krb5.keytab</filename>) using
	<command>kadmin</command>.</para>

	<para>Note that you must have already obtained a ticket and
	that this ticket must be allowed to use the
	<command>kadmin</command> interface in the
	<filename>kadmind.acl</filename>. See the section titled
	<quote>Remote administration</quote> in the Heimdal info
	pages (<command>info heimdal</command>) for details on
	designing access control lists. If you do not want to
	enable remote <command>kadmin</command> access, you can
	simply securely connect to the <acronym>KDC</acronym> (via
	local console, &man.ssh.1; or
	<application>Kerberos</application> &man.telnet.1;) and
	perform administration locally using
	<command>kadmin -l</command>.</para>

	<para>After installing the <filename>/etc/krb5.conf</filename>
	file, you can use <command>kadmin</command> from the
	<application>Kerberos</application> server. The
	<command>add --random-key</command> command will let you add
	the server's host principal, and the <command>ext</command>
	command will allow you to extract the server's host
	principal to its own keytab. For example:</para>

	<screen>&prompt.root; <userinput>kadmin</userinput>
	kadmin><userinput> add --random-key host/myserver.example.org</userinput>
	Max ticket life [unlimited]:
	Max renewable life [unlimited]:
	Attributes []:
	kadmin><userinput> ext host/myserver.example.org</userinput>
	kadmin><userinput> exit</userinput></screen>

	<para>Note that the <command>ext</command> command (short for
	<quote>extract</quote>) stores the extracted key in
	<filename>/etc/krb5.keytab</filename> by default.</para>

	<para>If you do not have <command>kadmind</command> running on
	the <acronym>KDC</acronym> (possibly for security reasons)
	and thus do not have access to <command>kadmin</command>
	remotely, you can add the host principal
	(<username>host/myserver.EXAMPLE.ORG</username>) directly on
	the <acronym>KDC</acronym> and then extract it to a
	temporary file (to avoid over-writing the
	<filename>/etc/krb5.keytab</filename> on the
	<acronym>KDC</acronym>) using something like this:</para>

	<screen>&prompt.root; <userinput>kadmin</userinput>
	kadmin><userinput> ext --keytab=/tmp/example.keytab host/myserver.example.org</userinput>
	kadmin><userinput> exit</userinput></screen>

	<para>You can then securely copy the keytab to the server
	computer (using <command>scp</command> or a floppy, for
	example). Be sure to specify a non-default keytab name to
	avoid over-writing the keytab on the
	<acronym>KDC</acronym>.</para>

	<para>At this point your server can communicate with the
	<acronym>KDC</acronym> (due to its
	<filename>krb5.conf</filename> file) and it can prove its
	own identity (due to the <filename>krb5.keytab</filename>
	file). It is now ready for you to enable some
	<application>Kerberos</application> services. For this
	example we will enable the <command>telnet</command> service
	by putting a line like this into your
	<filename>/etc/inetd.conf</filename> and then restarting the
	&man.inetd.8; service with <command>service inetd
	restart</command>:</para>

	<programlisting>telnet stream tcp nowait root /usr/libexec/telnetd telnetd -a user</programlisting>

	<para>The critical bit is that the <command>-a</command> (for
	authentication) type is set to user. Consult the
	&man.telnetd.8; manual page for more details.</para>
	</sect2>

	<sect2>
	<title><application>Kerberos</application> Enabling a Client
	with Heimdal</title>

	<indexterm>
	<primary>Kerberos5</primary>
	<secondary>configure clients</secondary>
	</indexterm>

	<para>Setting up a client computer is almost trivially easy.
	As far as <application>Kerberos</application> configuration
	goes, you only need the <application>Kerberos</application>
	configuration file, located at
	<filename>/etc/krb5.conf</filename>. Simply securely copy
	it over to the client computer from the
	<acronym>KDC</acronym>.</para>

	<para>Test your client computer by attempting to use
	<command>kinit</command>, <command>klist</command>, and
	<command>kdestroy</command> from the client to obtain, show,
	and then delete a ticket for the principal you created
	above. You should also be able to use
	<application>Kerberos</application> applications to connect
	to <application>Kerberos</application> enabled servers,
	though if that does not work and obtaining a ticket does the
	problem is likely with the server and not with the client or
	the <acronym>KDC</acronym>.</para>

	<para>When testing an application like
	<command>telnet</command>, try using a packet sniffer (such
	as &man.tcpdump.1;) to confirm that your password is not
	sent in the clear. Try using <command>telnet</command> with
	the <literal>-x</literal> option, which encrypts the entire
	data stream (similar to <command>ssh</command>).</para>

	<para>Various non-core <application>Kerberos</application>
	client applications are also installed by default. This is
	where the <quote>minimal</quote> nature of the base Heimdal
	installation is felt: <command>telnet</command> is the only
	<application>Kerberos</application> enabled service.</para>

	<para>The Heimdal port adds some of the missing client
	applications: <application>Kerberos</application> enabled
	versions of <command>ftp</command>, <command>rsh</command>,
	<command>rcp</command>, <command>rlogin</command>, and a few
	other less common programs. The <acronym>MIT</acronym> port
	also contains a full suite of
	<application>Kerberos</application> client
	applications.</para>
	</sect2>

	<sect2>
	<title>User Configuration Files: <filename>.k5login</filename>
	and <filename>.k5users</filename></title>

	<indexterm>
	<primary><filename>.k5login</filename></primary>
	</indexterm>

	<indexterm>
	<primary><filename>.k5users</filename></primary>
	</indexterm>

	<para>Users within a realm typically have their
	<application>Kerberos</application> principal (such as
	<username>tillman@EXAMPLE.ORG</username>) mapped to a local
	user account (such as a local account named
	<username>tillman</username>). Client applications such as
	<command>telnet</command> usually do not require a user name
	or a principal.</para>

	<para>Occasionally, however, you want to grant access to a
	local user account to someone who does not have a matching
	<application>Kerberos</application> principal. For example,
	<username>tillman@EXAMPLE.ORG</username> may need access to
	the local user account <username>webdevelopers</username>.
	Other principals may also need access to that local
	account.</para>

	<para>The <filename>.k5login</filename> and
	<filename>.k5users</filename> files, placed in a users home
	directory, can be used similar to a powerful combination of
	<filename>.hosts</filename> and
	<filename>.rhosts</filename>, solving this problem. For
	example, if a <filename>.k5login</filename> with the
	following contents:</para>

	<screen>tillman@example.org
	jdoe@example.org</screen>

	<para>Were to be placed into the home directory of the local
	user <username>webdevelopers</username> then both principals
	listed would have access to that account without requiring a
	shared password.</para>

	<para>Reading the manual pages for these commands is
	recommended. Note that the <command>ksu</command> manual
	page covers <filename>.k5users</filename>.</para>
	</sect2>

	<sect2>
	<title><application>Kerberos</application> Tips, Tricks, and
	Troubleshooting</title>

	<itemizedlist>
	<indexterm>
	<primary>Kerberos5</primary>
	<secondary>troubleshooting</secondary>
	</indexterm>

	<listitem>
	<para>When using either the Heimdal or
	<acronym>MIT</acronym>
	<application>Kerberos</application> ports ensure that
	your <envar>PATH</envar> environment variable lists the
	<application>Kerberos</application> versions of the
	client applications before the system versions.</para>
	</listitem>

	<listitem>
	<para>Do all the computers in your realm have synchronized
	time settings? If not, authentication may fail.
	<xref linkend="network-ntp"/> describes how to synchronize
	clocks using <acronym>NTP</acronym>.</para>
	</listitem>

	<listitem>
	<para><acronym>MIT</acronym> and Heimdal inter-operate
	nicely. Except for <command>kadmin</command>, the
	protocol for which is not standardized.</para>
	</listitem>

	<listitem>
	<para>If you change your hostname, you also need to change
	your <username>host/</username> principal and update
	your keytab. This also applies to special keytab
	entries like the <username>www/</username> principal
	used for Apache's
	<filename
	role="package">www/mod_auth_kerb</filename>.</para>
	</listitem>

	<listitem>
	<para>All hosts in your realm must be resolvable (both
	forwards and reverse) in <acronym>DNS</acronym> (or
	<filename>/etc/hosts</filename> as a minimum). CNAMEs
	will work, but the A and PTR records must be correct and
	in place. The error message is not very intuitive:
	<errorname>Kerberos5 refuses authentication because Read
	req failed: Key table entry not
	found</errorname>.</para>
	</listitem>

	<listitem>
	<para>Some operating systems that may being acting as
	clients to your <acronym>KDC</acronym> do not set the
	permissions for <command>ksu</command> to be setuid
	<username>root</username>. This means that
	<command>ksu</command> does not work, which is a good
	security idea but annoying. This is not a
	<acronym>KDC</acronym> error.</para>
	</listitem>

	<listitem>
	<para>With <acronym>MIT</acronym>
	<application>Kerberos</application>, if you want to
	allow a principal to have a ticket life longer than the
	default ten hours, you must use
	<command>modify_principal</command> in
	<command>kadmin</command> to change the maxlife of both
	the principal in question and the
	<username>krbtgt</username> principal. Then the
	principal can use the <literal>-l</literal> option with
	<command>kinit</command> to request a ticket with a
	longer lifetime.</para>
	</listitem>

	<listitem>
	<note>
	<para>If you run a packet sniffer on your
	<acronym>KDC</acronym> to add in troubleshooting and
	then run <command>kinit</command> from a workstation,
	you will notice that your <acronym>TGT</acronym> is
	sent immediately upon running <command>kinit</command>
	— even before you type your password! The
	explanation is that the
	<application>Kerberos</application> server freely
	transmits a <acronym>TGT</acronym> (Ticket Granting
	Ticket) to any unauthorized request; however, every
	<acronym>TGT</acronym> is encrypted in a key derived
	from the user's password. Therefore, when a user
	types their password it is not being sent to the
	<acronym>KDC</acronym>, it is being used to decrypt
	the <acronym>TGT</acronym> that
	<command>kinit</command> already obtained. If the
	decryption process results in a valid ticket with a
	valid time stamp, the user has valid
	<application>Kerberos</application> credentials.
	These credentials include a session key for
	establishing secure communications with the
	<application>Kerberos</application> server in the
	future, as well as the actual ticket-granting ticket,
	which is actually encrypted with the
	<application>Kerberos</application> server's own key.
	This second layer of encryption is unknown to the
	user, but it is what allows the
	<application>Kerberos</application> server to verify
	the authenticity of each
	<acronym>TGT</acronym>.</para>
	</note>
	</listitem>

	<listitem>
	<para>If you want to use long ticket lifetimes (a week,
	for example) and you are using
	<application>OpenSSH</application> to connect to the
	machine where your ticket is stored, make sure that
	<application>Kerberos</application>
	<option>TicketCleanup</option> is set to
	<literal>no</literal> in your
	<filename>sshd_config</filename> or else your tickets
	will be deleted when you log out.</para>
	</listitem>

	<listitem>
	<para>Remember that host principals can have a longer
	ticket lifetime as well. If your user principal has a
	lifetime of a week but the host you are connecting to
	has a lifetime of nine hours, you will have an expired
	host principal in your cache and the ticket cache will
	not work as expected.</para>
	</listitem>

	<listitem>
	<para>When setting up a <filename>krb5.dict</filename>
	file to prevent specific bad passwords from being used
	(the manual page for <command>kadmind</command> covers
	this briefly), remember that it only applies to
	principals that have a password policy assigned to them.
	The <filename>krb5.dict</filename> files format is
	simple: one string per line. Creating a symbolic link
	to <filename>/usr/share/dict/words</filename> might be
	useful.</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2>
	<title>Differences with the <acronym>MIT</acronym>
	Port</title>

	<para>The major difference between the <acronym>MIT</acronym>
	and Heimdal installs relates to the
	<command>kadmin</command> program which has a different (but
	equivalent) set of commands and uses a different protocol.
	This has a large implications if your <acronym>KDC</acronym>
	is <acronym>MIT</acronym> as you will not be able to use the
	Heimdal <command>kadmin</command> program to administer your
	<acronym>KDC</acronym> remotely (or vice versa, for that
	matter).</para>

	<para>The client applications may also take slightly different
	command line options to accomplish the same tasks.
	Following the instructions on the <acronym>MIT</acronym>
	<application>Kerberos</application> web site
	(<ulink url="http://web.mit.edu/Kerberos/www/"></ulink>) is
	recommended. Be careful of path issues: the
	<acronym>MIT</acronym> port installs into
	<filename class="directory">/usr/local/</filename> by default,
	and the <quote>normal</quote> system applications may be run
	instead of <acronym>MIT</acronym> if your
	<envar>PATH</envar> environment variable lists the system
	directories first.</para>

	<note>
	<para>With the <acronym>MIT</acronym>
	<filename role="package">security/krb5</filename> port that
	is provided by &os;, be sure to read the
	<filename>/usr/local/share/doc/krb5/README.FreeBSD</filename>
	file installed by the port if you want to understand why
	logins via <command>telnetd</command> and
	<command>klogind</command> behave somewhat oddly. Most
	importantly, correcting the <quote>incorrect permissions on
	cache file</quote> behavior requires that the
	<command>login.krb5</command> binary be used for
	authentication so that it can properly change ownership for
	the forwarded credentials.</para>
	</note>

	<para>The <filename>rc.conf</filename> must also be modified
	to contain the following configuration:</para>

	<programlisting>kerberos5_server="/usr/local/sbin/krb5kdc"
	kadmind5_server="/usr/local/sbin/kadmind"
	kerberos5_server_enable="YES"
	kadmind5_server_enable="YES"</programlisting>

	<para>This is done because the applications for
	<acronym>MIT</acronym> kerberos installs binaries in the
	<filename class="directory">/usr/local</filename>
	hierarchy.</para>
	</sect2>

	<sect2>
	<title>Mitigating Limitations Found in
	<application>Kerberos</application></title>

	<indexterm>
	<primary>Kerberos5</primary>
	<secondary>limitations and shortcomings</secondary>
	</indexterm>

	<sect3>
	<title><application>Kerberos</application> is an
	all-or-nothing approach</title>

	<para>Every service enabled on the network must be modified
	to work with <application>Kerberos</application> (or be
	otherwise secured against network attacks) or else the
	users credentials could be stolen and re-used. An example
	of this would be <application>Kerberos</application>
	enabling all remote shells (via <command>rsh</command> and
	<command>telnet</command>, for example) but not converting
	the <acronym>POP3</acronym> mail server which sends
	passwords in plain text.</para>
	</sect3>

	<sect3>
	<title><application>Kerberos</application> is Intended for
	Single-User Workstations</title>

	<para>In a multi-user environment,
	<application>Kerberos</application> is less secure.
	This is because it stores the tickets in the
	<filename class="directory">/tmp</filename> directory, which
	is readable by all users. If a user is sharing a computer
	with several other people simultaneously (i.e.
	multi-user), it is possible that the user's tickets can be
	stolen (copied) by another user.</para>

	<para>This can be overcome with the <literal>-c</literal>
	filename command-line option or (preferably) the
	<envar>KRB5CCNAME</envar> environment variable, but this
	is rarely done. In principal, storing the ticket in the
	users home directory and using simple file permissions can
	mitigate this problem.</para>
	</sect3>

	<sect3>
	<title>The KDC is a Single Point of Failure</title>

	<para>By design, the <acronym>KDC</acronym> must be as
	secure as the master password database is contained on it.
	The <acronym>KDC</acronym> should have absolutely no other
	services running on it and should be physically secured.
	The danger is high because
	<application>Kerberos</application> stores all passwords
	encrypted with the same key (the <quote>master</quote>
	key), which in turn is stored as a file on the
	<acronym>KDC</acronym>.</para>

	<para>As a side note, a compromised master key is not quite
	as bad as one might normally fear. The master key is only
	used to encrypt the <application>Kerberos</application>
	database and as a seed for the random number generator.
	As long as access to your <acronym>KDC</acronym> is
	secure, an attacker cannot do much with the master
	key.</para>

	<para>Additionally, if the <acronym>KDC</acronym> is
	unavailable (perhaps due to a denial of service attack or
	network problems) the network services are unusable as
	authentication can not be performed, a recipe for a
	denial-of-service attack. This can alleviated with
	multiple <acronym>KDC</acronym>s (a single master and one
	or more slaves) and with careful implementation of
	secondary or fall-back authentication
	(<acronym>PAM</acronym> is excellent for this).</para>
	</sect3>

	<sect3>
	<title><application>Kerberos</application>
	Shortcomings</title>

	<para><application>Kerberos</application> allows users,
	hosts and services to authenticate between themselves. It
	does not have a mechanism to authenticate the
	<acronym>KDC</acronym> to the users, hosts or services.
	This means that a trojanned <command>kinit</command> (for
	example) could record all user names and passwords.
	Something like
	<filename role="package">security/tripwire</filename> or
	other file system integrity checking tools can alleviate
	this.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Resources and further information</title>

	<indexterm>
	<primary>Kerberos5</primary>
	<secondary>external resources</secondary>
	</indexterm>

	<itemizedlist>
	<listitem>
	<para><ulink
	url="http://www.faqs.org/faqs/Kerberos-faq/general/preamble.html">
	The <application>Kerberos</application>
	FAQ</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="http://web.mit.edu/Kerberos/www/dialogue.html">Designing
	an Authentication System: a Dialog in Four
	Scenes</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="http://www.ietf.org/rfc/rfc1510.txt?number=1510">RFC
	1510, The <application>Kerberos</application> Network
	Authentication Service (V5)</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="http://web.mit.edu/Kerberos/www/"><acronym>MIT</acronym>
	<application>Kerberos</application> home
	page</ulink></para>
	</listitem>

	<listitem>
	<para><ulink url="http://www.pdc.kth.se/heimdal/">Heimdal
	<application>Kerberos</application> home
	page</ulink></para>
	</listitem>
	</itemizedlist>
	</sect2>
	</sect1>

	<sect1 id="openssl">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>OpenSSL</title>

	<indexterm>
	<primary>security</primary>
	<secondary>OpenSSL</secondary>
	</indexterm>

	<para>One feature that many users overlook is the
	<application>OpenSSL</application> toolkit included in &os;.
	<application>OpenSSL</application> provides an encryption
	transport layer on top of the normal communications layer;
	thus allowing it to be intertwined with many network
	applications and services.</para>

	<para>Some uses of <application>OpenSSL</application> may
	include encrypted authentication of mail clients, web based
	transactions such as credit card payments and more. Many
	ports such as
	<filename role="package">www/apache22</filename>, and
	<filename role="package">mail/claws-mail</filename> will offer
	compilation support for building with
	<application>OpenSSL</application>.</para>

	<note>
	<para>In most cases the Ports Collection will attempt to build
	the <filename role="package">security/openssl</filename>
	port unless the <makevar>WITH_OPENSSL_BASE</makevar> make
	variable is explicitly set to <quote>yes</quote>.</para>
	</note>

	<para>The version of <application>OpenSSL</application> included
	in &os; supports Secure Sockets Layer v2/v3 (SSLv2/SSLv3),
	Transport Layer Security v1 (TLSv1) network security protocols
	and can be used as a general cryptographic library.</para>

	<note>
	<para>While <application>OpenSSL</application> supports the
	<acronym>IDEA</acronym> algorithm, it is disabled by default
	due to United States patents. To use it, the license should
	be reviewed and, if the restrictions are acceptable, the
	<makevar>MAKE_IDEA</makevar> variable must be set in
	<filename>make.conf</filename>.</para>
	</note>

	<para>One of the most common uses of
	<application>OpenSSL</application> is to provide certificates
	for use with software applications. These certificates ensure
	that the credentials of the company or individual are valid
	and not fraudulent. If the certificate in question has not
	been verified by one of the several <quote>Certificate
	Authorities</quote>, or <acronym>CA</acronym>s, a warning is
	usually produced. A Certificate Authority is a company, such
	as <ulink url="http://www.verisign.com">VeriSign</ulink>,
	which will sign certificates in order to validate credentials
	of individuals or companies. This process has a cost
	associated with it and is definitely not a requirement for
	using certificates; however, it can put some of the more
	paranoid users at ease.</para>

	<sect2>
	<title>Generating Certificates</title>

	<indexterm>
	<primary>OpenSSL</primary>
	<secondary>certificate generation</secondary>
	</indexterm>

	<para>To generate a certificate, the following command is
	available:</para>

	<screen>&prompt.root; <userinput>openssl req -new -nodes -out req.pem -keyout cert.pem</userinput>
	Generating a 1024 bit RSA private key
	................++++++
	.......................................++++++
	writing new private key to 'cert.pem'
	-----
	You are about to be asked to enter information that will be incorporated
	into your certificate request.
	What you are about to enter is what is called a Distinguished Name or a DN.
	There are quite a few fields but you can leave some blank
	For some fields there will be a default value,
	If you enter '.', the field will be left blank.
	-----
	Country Name (2 letter code) [AU]:<userinput><replaceable>US</replaceable></userinput>
	State or Province Name (full name) [Some-State]:<userinput><replaceable>PA</replaceable></userinput>
	Locality Name (eg, city) []:<userinput><replaceable>Pittsburgh</replaceable></userinput>
	Organization Name (eg, company) [Internet Widgits Pty Ltd]:<userinput><replaceable>My Company</replaceable></userinput>
	Organizational Unit Name (eg, section) []:<userinput><replaceable>Systems Administrator</replaceable></userinput>
	Common Name (eg, YOUR name) []:<userinput><replaceable>localhost.example.org</replaceable></userinput>
	Email Address []:<userinput><replaceable>trhodes@FreeBSD.org</replaceable></userinput>

	Please enter the following 'extra' attributes
	to be sent with your certificate request
	A challenge password []:<userinput><replaceable>SOME PASSWORD</replaceable></userinput>
	An optional company name []:<userinput><replaceable>Another Name</replaceable></userinput></screen>

	<para>Notice the response directly after the
	<quote>Common Name</quote> prompt shows a domain name. This
	prompt requires a server name to be entered for verification
	purposes; placing anything but a domain name would yield a
	useless certificate. Other options, for instance expire
	time, alternate encryption algorithms, etc. are available.
	A complete list may be obtained by viewing the
	&man.openssl.1; manual page.</para>

	<para>Two files should now exist in the directory in which the
	aforementioned command was issued. The certificate request,
	<filename>req.pem</filename>, may be sent to a certificate
	authority who will validate the credentials that you
	entered, sign the request and return the certificate to you.
	The second file created will be named
	<filename>cert.pem</filename> and is the private key for the
	certificate and should be protected at all costs; if this
	falls in the hands of others it can be used to impersonate
	you (or your server).</para>

	<para>In cases where a signature from a <acronym>CA</acronym>
	is not required, a self signed certificate can be created.
	First, generate the <acronym>RSA</acronym> key:</para>

	<screen>&prompt.root; <userinput>openssl dsaparam -rand -genkey -out <filename>myRSA.key</filename> 1024</userinput></screen>

	<para>Next, generate the <acronym>CA</acronym> key:</para>

	<screen>&prompt.root; <userinput>openssl gendsa -des3 -out <filename>myca.key</filename> <filename>myRSA.key</filename></userinput></screen>

	<para>Use this key to create the certificate:</para>

	<screen>&prompt.root; <userinput>openssl req -new -x509 -days 365 -key <filename>myca.key</filename> -out <filename>new.crt</filename></userinput></screen>

	<para>Two new files should appear in the directory: a
	certificate authority signature file,
	<filename>myca.key</filename> and the certificate itself,
	<filename>new.crt</filename>. These should be placed in a
	directory, preferably under
	<filename class="directory">/etc</filename>, which is readable
	only by <username>root</username>. Permissions of 0700 should
	be fine for this and they can be set with the
	<command>chmod</command> utility.</para>
	</sect2>

	<sect2>
	<title>Using Certificates, an Example</title>

	<para>So what can these files do? A good use would be to
	encrypt connections to the
	<application>Sendmail</application> <acronym>MTA</acronym>.
	This would dissolve the use of clear text authentication for
	users who send mail via the local
	<acronym>MTA</acronym>.</para>

	<note>
	<para>This is not the best use in the world as some
	<acronym>MUA</acronym>s will present the user with an
	error if they have not installed the certificate locally.
	Refer to the documentation included with the software for
	more information on certificate installation.</para>
	</note>

	<para>The following lines should be placed inside the local
	<filename>.mc</filename> file:</para>

	<programlisting>dnl SSL Options
	define(`confCACERT_PATH',`/etc/certs')dnl
	define(`confCACERT',`/etc/certs/new.crt')dnl
	define(`confSERVER_CERT',`/etc/certs/new.crt')dnl
	define(`confSERVER_KEY',`/etc/certs/myca.key')dnl
	define(`confTLS_SRV_OPTIONS', `V')dnl</programlisting>

	<para>Where <filename class="directory">/etc/certs/</filename>
	is the directory to be used for storing the certificate and
	key files locally. The last few requirements are a rebuild
	of the local <filename>.cf</filename> file. This is easily
	achieved by typing <command>make
	<maketarget>install</maketarget></command> within the
	<filename class="directory">/etc/mail</filename> directory.
	Follow that up with <command>make
	<maketarget>restart</maketarget></command> which should
	start the <application>Sendmail</application> daemon.</para>

	<para>If all went well there will be no error messages in the
	<filename>/var/log/maillog</filename> file and
	<application>Sendmail</application> will show up in the
	process list.</para>

	<para>For a simple test, simply connect to the mail server
	using the &man.telnet.1; utility:</para>

	<screen>&prompt.root; <userinput>telnet <replaceable>example.com</replaceable> 25</userinput>
	Trying 192.0.34.166...
	Connected to <hostid role="fqdn">example.com</hostid>.
	Escape character is '^]'.
	220 <hostid role="fqdn">example.com</hostid> ESMTP Sendmail 8.12.10/8.12.10; Tue, 31 Aug 2004 03:41:22 -0400 (EDT)
	<userinput>ehlo <replaceable>example.com</replaceable></userinput>
	250-example.com Hello example.com [192.0.34.166], pleased to meet you
	250-ENHANCEDSTATUSCODES
	250-PIPELINING
	250-8BITMIME
	250-SIZE
	250-DSN
	250-ETRN
	250-AUTH LOGIN PLAIN
	250-STARTTLS
	250-DELIVERBY
	250 HELP
	<userinput>quit</userinput>
	221 2.0.0 <hostid role="fqdn">example.com</hostid> closing connection
	Connection closed by foreign host.</screen>

	<para>If the <quote>STARTTLS</quote> line appears in the
	output then everything is working correctly.</para>
	</sect2>
	</sect1>

	<sect1 id="ipsec">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Nik</firstname>
	<surname>Clayton</surname>
	<affiliation>
	<address><email>nik@FreeBSD.org</email></address>
	</affiliation>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>VPN over IPsec</title>

	<indexterm>
	<primary>IPsec</primary>
	</indexterm>

	<para>Creating a VPN between two networks, separated by the
	Internet, using FreeBSD gateways.</para>

	<sect2>
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Hiten M.</firstname>
	<surname>Pandya</surname>
	<affiliation>
	<address><email>hmp@FreeBSD.org</email></address>
	</affiliation>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>Understanding IPsec</title>

	<para>This section will guide you through the process of
	setting up IPsec. In order to set up IPsec, it is necessary
	that you are familiar with the concepts of building a custom
	kernel (see <xref linkend="kernelconfig"/>).</para>

	<para><emphasis>IPsec</emphasis> is a protocol which sits on
	top of the Internet Protocol (IP) layer. It allows two or
	more hosts to communicate in a secure manner (hence the
	name). The FreeBSD IPsec <quote>network stack</quote> is
	based on the <ulink url="http://www.kame.net/">KAME</ulink>
	implementation, which has support for both protocol
	families, IPv4 and IPv6.</para>

	<indexterm>
	<primary>IPsec</primary>
	<secondary>ESP</secondary>
	</indexterm>

	<indexterm>
	<primary>IPsec</primary>
	<secondary>AH</secondary>
	</indexterm>

	<para>IPsec consists of two sub-protocols:</para>

	<itemizedlist>
	<listitem>
	<para><emphasis>Encapsulated Security Payload
	ESP)</emphasis>, protects the IP packet data from
	third party interference, by encrypting the contents
	using symmetric cryptography algorithms (like Blowfish,
	3DES).</para>
	</listitem>

	<listitem>
	<para><emphasis>Authentication Header (AH)</emphasis>,
	protects the IP packet header from third party
	interference and spoofing, by computing a cryptographic
	checksum and hashing the IP packet header fields with a
	secure hashing function. This is then followed by an
	additional header that contains the hash, to allow the
	information in the packet to be authenticated.</para>
	</listitem>
	</itemizedlist>

	<para><acronym>ESP</acronym> and <acronym>AH</acronym> can
	either be used together or separately, depending on the
	environment.</para>

	<indexterm>
	<primary>VPN</primary>
	</indexterm>

	<indexterm>
	<primary>virtual private network</primary>
	<see>VPN</see>
	</indexterm>

	<para>IPsec can either be used to directly encrypt the traffic
	between two hosts (known as <emphasis>Transport
	Mode</emphasis>); or to build <quote>virtual
	tunnels</quote> between two subnets, which could be used for
	secure communication between two corporate networks (known
	as <emphasis>Tunnel Mode</emphasis>). The latter is more
	commonly known as a <emphasis>Virtual Private Network
	(VPN)</emphasis>. The &man.ipsec.4; manual page should be
	consulted for detailed information on the IPsec subsystem in
	FreeBSD.</para>

	<para>To add IPsec support to your kernel, add the following
	options to your kernel configuration file:</para>

	<indexterm>
	<primary>kernel options</primary>
	<secondary>IPSEC</secondary>
	</indexterm>

	<screen>
	options IPSEC #IP security
	device crypto</screen>

	<indexterm>
	<primary>kernel options</primary>
	<secondary>IPSEC_DEBUG</secondary>
	</indexterm>

	<para>If IPsec debugging support is desired, the following
	kernel option should also be added:</para>

	<screen>
	options IPSEC_DEBUG #debug for IP security</screen>
	</sect2>

	<sect2>
	<title>The Problem</title>

	<para>There is no standard for what constitutes a VPN. VPNs
	can be implemented using a number of different technologies,
	each of which have their own strengths and weaknesses. This
	section presents a scenario, and the strategies used for
	implementing a VPN for this scenario.</para>
	</sect2>

	<sect2>
	<title>The Scenario: Two networks, one home based and one
	corporate based. Both are connected to the Internet, and
	expected, via this <acronym>VPN</acronym> to behave as
	one.</title>

	<indexterm>
	<primary>VPN</primary>
	<secondary>creating</secondary>
	</indexterm>

	<para>The premise is as follows:</para>

	<itemizedlist>
	<listitem>
	<para>You have at least two sites</para>
	</listitem>

	<listitem>
	<para>Both sites are using IP internally</para>
	</listitem>

	<listitem>
	<para>Both sites are connected to the Internet, through a
	gateway that is running FreeBSD.</para>
	</listitem>

	<listitem>
	<para>The gateway on each network has at least one public
	IP address.</para>
	</listitem>

	<listitem>
	<para>The internal addresses of the two networks can be
	public or private IP addresses, it does not matter.
	They just may not collide; e.g.: may not both use
	<hostid role="ipaddr">192.168.1.x</hostid>.</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2>
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<affiliation>
	<address><email>trhodes@FreeBSD.org</email></address>
	</affiliation>
	<contrib>Written by </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>Configuring IPsec on &os;</title>

	<para>To begin, the
	<filename role="package">security/ipsec-tools</filename>
	must be installed from the Ports Collection. This third
	party software package provides a number of applications
	which will help support the configuration.</para>

	<para>The next requirement is to create two &man.gif.4;
	pseudo-devices which will be used to tunnel packets and
	allow both networks to communicate properly. As
	<username>root</username>, run the following commands,
	replacing the <replaceable>internal</replaceable> and
	<replaceable>external</replaceable> items with the real
	internal and external gateways:</para>

	<screen>&prompt.root; <userinput>ifconfig gif0 create</userinput></screen>

	<screen>&prompt.root; <userinput>ifconfig gif0 <replaceable>internal1 internal2</replaceable></userinput></screen>

	<screen>&prompt.root; <userinput>ifconfig gif0 tunnel <replaceable>external1 external2</replaceable></userinput></screen>

	<para>For example, the corporate <acronym>LAN</acronym>'s
	public <acronym>IP</acronym> is
	<hostid role="ipaddr">172.16.5.4</hostid> having a private
	<acronym>IP</acronym> of
	<hostid role="ipaddr">10.246.38.1</hostid>. The home
	<acronym>LAN</acronym>'s public <acronym>IP</acronym> is
	<hostid role="ipaddr">192.168.1.12</hostid> with an internal
	private <acronym>IP</acronym> of
	<hostid role="ipaddr">10.0.0.5</hostid>.</para>

	<para>This may seem confusing, so review the following example
	output from the &man.ifconfig.8; command:</para>

	<programlisting>Gateway 1:

	gif0: flags=8051 mtu 1280
	tunnel inet 172.16.5.4 --> 192.168.1.12
	inet6 fe80::2e0:81ff:fe02:5881%gif0 prefixlen 64 scopeid 0x6
	inet 10.246.38.1 --> 10.0.0.5 netmask 0xffffff00

	Gateway 2:

	gif0: flags=8051 mtu 1280
	tunnel inet 192.168.1.12 --> 172.16.5.4
	inet 10.0.0.5 --> 10.246.38.1 netmask 0xffffff00
	inet6 fe80::250:bfff:fe3a:c1f%gif0 prefixlen 64 scopeid 0x4</programlisting>

	<para>Once complete, both private <acronym>IP</acronym>s
	should be reachable using the &man.ping.8; command like
	the following output suggests:</para>

	<programlisting>priv-net# ping 10.0.0.5
	PING 10.0.0.5 (10.0.0.5): 56 data bytes
	64 bytes from 10.0.0.5: icmp_seq=0 ttl=64 time=42.786 ms
	64 bytes from 10.0.0.5: icmp_seq=1 ttl=64 time=19.255 ms
	64 bytes from 10.0.0.5: icmp_seq=2 ttl=64 time=20.440 ms
	64 bytes from 10.0.0.5: icmp_seq=3 ttl=64 time=21.036 ms
	--- 10.0.0.5 ping statistics ---
	4 packets transmitted, 4 packets received, 0% packet loss
	round-trip min/avg/max/stddev = 19.255/25.879/42.786/9.782 ms

	corp-net# ping 10.246.38.1
	PING 10.246.38.1 (10.246.38.1): 56 data bytes
	64 bytes from 10.246.38.1: icmp_seq=0 ttl=64 time=28.106 ms
	64 bytes from 10.246.38.1: icmp_seq=1 ttl=64 time=42.917 ms
	64 bytes from 10.246.38.1: icmp_seq=2 ttl=64 time=127.525 ms
	64 bytes from 10.246.38.1: icmp_seq=3 ttl=64 time=119.896 ms
	64 bytes from 10.246.38.1: icmp_seq=4 ttl=64 time=154.524 ms
	--- 10.246.38.1 ping statistics ---
	5 packets transmitted, 5 packets received, 0% packet loss
	round-trip min/avg/max/stddev = 28.106/94.594/154.524/49.814 ms</programlisting>

	<para>As expected, both sides have the ability to send and
	receive <acronym>ICMP</acronym> packets from the privately
	configured addresses. Next, both gateways must be told how
	to route packets in order to correctly send traffic from
	either network. The following command will achieve this
	goal:</para>

	<screen>&prompt.root; <userinput>corp-net# route add <replaceable>10.0.0.0 10.0.0.5 255.255.255.0</replaceable></userinput></screen>

	<screen>&prompt.root; <userinput>corp-net# route add net <replaceable>10.0.0.0: gateway 10.0.0.5</replaceable></userinput></screen>

	<screen>&prompt.root; <userinput>priv-net# route add <replaceable>10.246.38.0 10.246.38.1 255.255.255.0</replaceable></userinput></screen>

	<screen>&prompt.root; <userinput>priv-net# route add host <replaceable>10.246.38.0: gateway 10.246.38.1</replaceable></userinput></screen>

	<para>At this point, internal machines should be reachable
	from each gateway as well as from machines behind the
	gateways. This is easily determined from the following
	example:</para>

	<programlisting>corp-net# ping 10.0.0.8
	PING 10.0.0.8 (10.0.0.8): 56 data bytes
	64 bytes from 10.0.0.8: icmp_seq=0 ttl=63 time=92.391 ms
	64 bytes from 10.0.0.8: icmp_seq=1 ttl=63 time=21.870 ms
	64 bytes from 10.0.0.8: icmp_seq=2 ttl=63 time=198.022 ms
	64 bytes from 10.0.0.8: icmp_seq=3 ttl=63 time=22.241 ms
	64 bytes from 10.0.0.8: icmp_seq=4 ttl=63 time=174.705 ms
	--- 10.0.0.8 ping statistics ---
	5 packets transmitted, 5 packets received, 0% packet loss
	round-trip min/avg/max/stddev = 21.870/101.846/198.022/74.001 ms

	priv-net# ping 10.246.38.107
	PING 10.246.38.1 (10.246.38.107): 56 data bytes
	64 bytes from 10.246.38.107: icmp_seq=0 ttl=64 time=53.491 ms
	64 bytes from 10.246.38.107: icmp_seq=1 ttl=64 time=23.395 ms
	64 bytes from 10.246.38.107: icmp_seq=2 ttl=64 time=23.865 ms
	64 bytes from 10.246.38.107: icmp_seq=3 ttl=64 time=21.145 ms
	64 bytes from 10.246.38.107: icmp_seq=4 ttl=64 time=36.708 ms
	--- 10.246.38.107 ping statistics ---
	5 packets transmitted, 5 packets received, 0% packet loss
	round-trip min/avg/max/stddev = 21.145/31.721/53.491/12.179 ms</programlisting>

	<para>Setting up the tunnels is the easy part. Configuring
	a secure link is a much more in depth process. The
	following configuration uses pre-shared
	(<acronym>PSK</acronym>) <acronym>RSA</acronym> keys. Aside
	from the <acronym>IP</acronym> addresses, both
	<filename>/usr/local/etc/racoon/racoon.conf</filename> files
	will be identical and look similar to</para>

	<programlisting>path pre_shared_key "/usr/local/etc/racoon/psk.txt"; #location of pre-shared key file
	log debug; #log verbosity setting: set to 'notify' when testing and debugging is complete

	padding # options are not to be changed
	{
	maximum_length 20;
	randomize off;
	strict_check off;
	exclusive_tail off;
	}

	timer # timing options. change as needed
	{
	counter 5;
	interval 20 sec;
	persend 1;
	# natt_keepalive 15 sec;
	phase1 30 sec;
	phase2 15 sec;
	}

	listen # address [port] that racoon will listening on
	{
	isakmp 172.16.5.4 [500];
	isakmp_natt 172.16.5.4 [4500];
	}

	remote 192.168.1.12 [500]
	{
	exchange_mode main,aggressive;
	doi ipsec_doi;
	situation identity_only;
	my_identifier address 172.16.5.4;
	peers_identifier address 192.168.1.12;
	lifetime time 8 hour;
	passive off;
	proposal_check obey;
	# nat_traversal off;
	generate_policy off;

	proposal {
	encryption_algorithm blowfish;
	hash_algorithm md5;
	authentication_method pre_shared_key;
	lifetime time 30 sec;
	dh_group 1;
	}
	}

	sainfo (address 10.246.38.0/24 any address 10.0.0.0/24 any) # address $network/$netmask $type address $network/$netmask $type ( $type being any or esp)
	{ # $network must be the two internal networks you are joining.
	pfs_group 1;
	lifetime time 36000 sec;
	encryption_algorithm blowfish,3des,des;
	authentication_algorithm hmac_md5,hmac_sha1;
	compression_algorithm deflate;
	}</programlisting>

	<para>Explaining every available option, along with those
	listed in these examples is beyond the scope of this
	document. There is plenty of relevant information in the
	<application>racoon</application> configuration manual
	page.</para>

	<para>The <acronym>SPD</acronym> policies need to be
	configured so &os; and <application>racoon</application> is
	able to encrypt and decrypt network traffic between
	hosts.</para>

	<para>This task may be undertaken with a simple shell script
	similar to the following which is on the corporate gateway.
	This file will be used during system initialization and
	should be saved as
	<filename>/usr/local/etc/racoon/setkey.conf</filename>.</para>

	<programlisting>flush;
	spdflush;
	# To the home network
	spdadd 10.246.38.0/24 10.0.0.0/24 any -P out ipsec esp/tunnel/172.16.5.4-192.168.1.12/use;
	spdadd 10.0.0.0/24 10.246.38.0/24 any -P in ipsec esp/tunnel/192.168.1.12-172.16.5.4/use;</programlisting>

	<para>Once in place, <application>racoon</application> may be
	started on both gateways using the following command:</para>

	<screen>&prompt.root; <userinput>/usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf -l /var/log/racoon.log</userinput></screen>

	<para>The output should be similar to the following:</para>

	<programlisting>corp-net# /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf
	Foreground mode.
	2006-01-30 01:35:47: INFO: begin Identity Protection mode.
	2006-01-30 01:35:48: INFO: received Vendor ID: KAME/racoon
	2006-01-30 01:35:55: INFO: received Vendor ID: KAME/racoon
	2006-01-30 01:36:04: INFO: ISAKMP-SA established 172.16.5.4[500]-192.168.1.12[500] spi:623b9b3bd2492452:7deab82d54ff704a
	2006-01-30 01:36:05: INFO: initiate new phase 2 negotiation: 172.16.5.4[0]192.168.1.12[0]
	2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]->172.16.5.4[0] spi=28496098(0x1b2d0e2)
	2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]->192.168.1.12[0] spi=47784998(0x2d92426)
	2006-01-30 01:36:13: INFO: respond new phase 2 negotiation: 172.16.5.4[0]192.168.1.12[0]
	2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]->172.16.5.4[0] spi=124397467(0x76a279b)
	2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]->192.168.1.12[0] spi=175852902(0xa7b4d66)</programlisting>

	<para>To ensure the tunnel is working properly, switch to
	another console and use &man.tcpdump.1; to view network
	traffic using the following command. Replace
	<literal>em0</literal> with the network interface card as
	required.</para>

	<screen>&prompt.root; <userinput>tcpdump -i em0 host <replaceable>172.16.5.4 and dst 192.168.1.12</replaceable></userinput></screen>

	<para>Data similar to the following should appear on the
	console. If not, there is an issue, and debugging the
	returned data will be required.</para>

	<programlisting>01:47:32.021683 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xa)
	01:47:33.022442 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xb)
	01:47:34.024218 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xc)</programlisting>

	<para>At this point, both networks should be available and
	seem to be part of the same network. Most likely both
	networks are protected by a firewall, as they should be. To
	allow traffic to flow between them, rules need to be added
	to pass packets back and forth. For the &man.ipfw.8;
	firewall, add the following lines to the firewall
	configuration file:</para>

	<programlisting>ipfw add 00201 allow log esp from any to any
	ipfw add 00202 allow log ah from any to any
	ipfw add 00203 allow log ipencap from any to any
	ipfw add 00204 allow log udp from any 500 to any</programlisting>

	<note>
	<para>The rule numbers may need to be altered depending on
	the current host configuration.</para>
	</note>

	<para>For users of &man.pf.4; or &man.ipf.8;, the following
	rules should do the trick:</para>

	<programlisting>pass in quick proto esp from any to any
	pass in quick proto ah from any to any
	pass in quick proto ipencap from any to any
	pass in quick proto udp from any port = 500 to any port = 500
	pass in quick on gif0 from any to any
	pass out quick proto esp from any to any
	pass out quick proto ah from any to any
	pass out quick proto ipencap from any to any
	pass out quick proto udp from any port = 500 to any port = 500
	pass out quick on gif0 from any to any</programlisting>

	<para>Finally, to allow the machine to start support for the
	<acronym>VPN</acronym> during system initialization, add the
	following lines to <filename>/etc/rc.conf</filename>:</para>

	<programlisting>ipsec_enable="YES"
	ipsec_program="/usr/local/sbin/setkey"
	ipsec_file="/usr/local/etc/racoon/setkey.conf" # allows setting up spd policies on boot
	racoon_enable="yes"</programlisting>
	</sect2>
	</sect1>

	<sect1 id="openssh">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Chern</firstname>
	<surname>Lee</surname>
	<contrib>Contributed by </contrib>
	</author>
	<!-- 21 April 2001 -->
	</authorgroup>
	</sect1info>

	<title>OpenSSH</title>

	<indexterm><primary>OpenSSH</primary></indexterm>
	<indexterm>
	<primary>security</primary>
	<secondary>OpenSSH</secondary>
	</indexterm>

	<para><application>OpenSSH</application> is a set of network
	connectivity tools used to access remote machines securely.
	It can be used as a direct replacement for
	<command>rlogin</command>, <command>rsh</command>,
	<command>rcp</command>, and <command>telnet</command>.
	Additionally, TCP/IP connections can be tunneled/forwarded
	securely through SSH. <application>OpenSSH</application>
	encrypts all traffic to effectively eliminate eavesdropping,
	connection hijacking, and other network-level attacks.</para>

	<para><application>OpenSSH</application> is maintained by the
	OpenBSD project, and is based upon SSH v1.2.12 with all the
	recent bug fixes and updates. It is compatible with both SSH
	protocols 1 and 2.</para>

	<sect2>
	<title>Advantages of Using OpenSSH</title>

	<para>Normally, when using &man.telnet.1; or &man.rlogin.1;,
	data is sent over the network in a clear, un-encrypted form.
	Network sniffers anywhere in between the client and server
	can steal your user/password information or data transferred
	in your session. <application>OpenSSH</application> offers
	a variety of authentication and encryption methods to
	prevent this from happening.</para>
	</sect2>

	<sect2>
	<title>Enabling <application>sshd</application></title>

	<indexterm>
	<primary>OpenSSH</primary>
	<secondary>enabling</secondary>
	</indexterm>

	<para>The <application>sshd</application> is an option
	presented during a <literal>Standard</literal> install of
	&os;. To see if <application>sshd</application> is enabled,
	check the <filename>rc.conf</filename> file for:</para>

	<programlisting>sshd_enable="YES"</programlisting>

	<para>This will load &man.sshd.8;, the daemon program for
	<application>OpenSSH</application>, the next time your
	system initializes. Alternatively, it is possible to use
	&man.service.8; to
	start <application>OpenSSH</application>:</para>

	<screen>&prompt.root; <userinput>service sshd start</userinput></screen>
	</sect2>

	<sect2>
	<title>SSH Client</title>

	<indexterm>
	<primary>OpenSSH</primary>
	<secondary>client</secondary>
	</indexterm>

	<para>The &man.ssh.1; utility works similarly to
	&man.rlogin.1;.</para>

	<screen>&prompt.root; <userinput>ssh <replaceable>user@example.com</replaceable></userinput>
	Host key not found from the list of known hosts.
	Are you sure you want to continue connecting (yes/no)? <userinput>yes</userinput>
	Host 'example.com' added to the list of known hosts.
	user@example.com's password: <userinput>*******</userinput></screen>

	<para>The login will continue just as it would have if a
	session was created using <command>rlogin</command> or
	<command>telnet</command>. SSH utilizes a key fingerprint
	system for verifying the authenticity of the server when the
	client connects. The user is prompted to enter
	<literal>yes</literal> only when connecting for the first
	time. Future attempts to login are all verified against the
	saved fingerprint key. The SSH client will alert you if the
	saved fingerprint differs from the received fingerprint on
	future login attempts. The fingerprints are saved in
	<filename>~/.ssh/known_hosts</filename>, or
	<filename>~/.ssh/known_hosts2</filename> for SSH v2
	fingerprints.</para>

	<para>By default, recent versions of the
	<application>OpenSSH</application> servers only accept SSH
	v2 connections. The client will use version 2 if possible
	and will fall back to version 1. The client can also be
	forced to use one or the other by passing it the
	<option>-1</option> or <option>-2</option> for version 1 or
	version 2, respectively. The version 1 compatibility is
	maintained in the client for backwards compatibility with
	older versions.</para>
	</sect2>

	<sect2>
	<title>Secure Copy</title>

	<indexterm>
	<primary>OpenSSH</primary>
	<secondary>secure copy</secondary>
	</indexterm>
	<indexterm>
	<primary><command>scp</command></primary>
	</indexterm>

	<para>The &man.scp.1; command works similarly to &man.rcp.1;;
	it copies a file to or from a remote machine, except in a
	secure fashion.</para>

	<screen>&prompt.root; <userinput> scp <replaceable>user@example.com:/COPYRIGHT COPYRIGHT</replaceable></userinput>
	user@example.com's password: <userinput>*******</userinput>
	COPYRIGHT 100% \|*****************************\| 4735
	00:00
	&prompt.root;</screen>

	<para>Since the fingerprint was already saved for this host in
	the previous example, it is verified when using &man.scp.1;
	here.</para>

	<para>The arguments passed to &man.scp.1; are similar to
	&man.cp.1;, with the file or files in the first argument,
	and the destination in the second. Since the file is
	fetched over the network, through SSH, one or more of the
	file arguments takes on the form
	<option>user@host:<path_to_remote_file></option>.</para>
	</sect2>

	<sect2>
	<title>Configuration</title>

	<indexterm>
	<primary>OpenSSH</primary>
	<secondary>configuration</secondary>
	</indexterm>

	<para>The system-wide configuration files for both the
	<application>OpenSSH</application> daemon and client reside
	within the <filename class="directory">/etc/ssh</filename>
	directory.</para>

	<para><filename>ssh_config</filename> configures the client
	settings, while <filename>sshd_config</filename> configures
	the daemon.</para>

	<para>Additionally, the <option>sshd_program</option>
	(<filename>/usr/sbin/sshd</filename> by default), and
	<option>sshd_flags</option> <filename>rc.conf</filename>
	options can provide more levels of configuration.</para>
	</sect2>

	<sect2 id="security-ssh-keygen">
	<title><application>ssh-keygen</application></title>

	<para>Instead of using passwords, &man.ssh-keygen.1; can
	be used to generate DSA or RSA keys to authenticate a
	user:</para>

	<screen>&prompt.user; <userinput>ssh-keygen -t <replaceable>dsa</replaceable></userinput>
	Generating public/private dsa key pair.
	Enter file in which to save the key (/home/user/.ssh/id_dsa):
	Created directory '/home/user/.ssh'.
	Enter passphrase (empty for no passphrase):
	Enter same passphrase again:
	Your identification has been saved in /home/user/.ssh/id_dsa.
	Your public key has been saved in /home/user/.ssh/id_dsa.pub.
	The key fingerprint is:
	bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8f:79:17 user@host.example.com</screen>

	<para>&man.ssh-keygen.1; will create a public and private key
	pair for use in authentication. The private key is stored
	in <filename>~/.ssh/id_dsa</filename> or
	<filename>~/.ssh/id_rsa</filename>, whereas the public key
	is stored in <filename>~/.ssh/id_dsa.pub</filename> or
	<filename>~/.ssh/id_rsa.pub</filename>, respectively for
	<acronym>DSA</acronym> and <acronym>RSA</acronym> key types.
	The public key must be placed in the
	<filename>~/.ssh/authorized_keys</filename> file of the
	remote machine for both <acronym>RSA</acronym> or
	<acronym>DSA</acronym> keys in order for the setup to
	work.</para>

	<para>This will allow connection to the remote machine based
	upon SSH keys instead of passwords.</para>

	<para>If a passphrase is used in &man.ssh-keygen.1;, the user
	will be prompted for a password each time in order to use
	the private key. &man.ssh-agent.1; can alleviate the strain
	of repeatedly entering long passphrases, and is explored in
	the <xref linkend="security-ssh-agent"/> section
	below.</para>

	<warning>
	<para>The various options and files can be different
	according to the <application>OpenSSH</application>
	version you have on your system; to avoid problems you
	should consult the &man.ssh-keygen.1; manual page.</para>
	</warning>
	</sect2>

	<sect2 id="security-ssh-agent">
	<title><application>ssh-agent</application> and <application>ssh-add</application></title>

	<para>The &man.ssh-agent.1; and &man.ssh-add.1; utilities
	provide methods for <application>SSH</application> keys to
	be loaded into memory for use, without needing to type the
	passphrase each time.</para>

	<para>The &man.ssh-agent.1; utility will handle the
	authentication using the private key(s) that are loaded into
	it. &man.ssh-agent.1; should be used to launch another
	application. At the most basic level, it could spawn a
	shell or at a more advanced level, a window manager.</para>

	<para>To use &man.ssh-agent.1; in a shell, first it will need
	to be spawned with a shell as an argument. Secondly, the
	identity needs to be added by running &man.ssh-add.1; and
	providing it the passphrase for the private key. Once these
	steps have been completed the user will be able to
	&man.ssh.1; to any host that has the corresponding public
	key installed. For example:</para>

	<screen>&prompt.user; ssh-agent <replaceable>csh</replaceable>
	&prompt.user; ssh-add
	Enter passphrase for /home/user/.ssh/id_dsa:
	Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa)
	&prompt.user;</screen>

	<para>To use &man.ssh-agent.1; in X11, a call to
	&man.ssh-agent.1; will need to be placed in
	<filename>~/.xinitrc</filename>. This will provide the
	&man.ssh-agent.1; services to all programs launched in X11.
	An example <filename>~/.xinitrc</filename> file might look
	like this:</para>

	<programlisting>exec ssh-agent <replaceable>startxfce4</replaceable></programlisting>

	<para>This would launch &man.ssh-agent.1;, which would in turn
	launch <application>XFCE</application>, every time X11
	starts. Then once that is done and X11 has been restarted so
	that the changes can take effect, simply run &man.ssh-add.1;
	to load all of your SSH keys.</para>
	</sect2>

	<sect2 id="security-ssh-tunneling">
	<title>SSH Tunneling</title>

	<indexterm>
	<primary>OpenSSH</primary>
	<secondary>tunneling</secondary>
	</indexterm>

	<para><application>OpenSSH</application> has the ability to
	create a tunnel to encapsulate another protocol in an
	encrypted session.</para>

	<para>The following command tells &man.ssh.1; to create a
	tunnel for <application>telnet</application>:</para>

	<screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5023:localhost:23 user@foo.example.com</replaceable></userinput>
	&prompt.user;</screen>

	<para>The <command>ssh</command> command is used with the
	following options:</para>

	<variablelist>
	<varlistentry>
	<term><option>-2</option></term>

	<listitem>
	<para>Forces <command>ssh</command> to use version 2 of
	the protocol. (Do not use if you are working with
	older SSH servers)</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-N</option></term>

	<listitem>
	<para>Indicates no command, or tunnel only. If omitted,
	<command>ssh</command> would initiate a normal
	session.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-f</option></term>

	<listitem>
	<para>Forces <command>ssh</command> to run in the
	background.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-L</option></term>

	<listitem>
	<para>Indicates a local tunnel in
	<replaceable>localport:remotehost:remoteport</replaceable>
	fashion.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>user@foo.example.com</option></term>

	<listitem>
	<para>The remote SSH server.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>An SSH tunnel works by creating a listen socket on
	<hostid>localhost</hostid> on the specified port. It then
	forwards any connection received on the local host/port via
	the SSH connection to the specified remote host and
	port.</para>

	<para>In the example, port <replaceable>5023</replaceable> on
	<hostid>localhost</hostid> is being forwarded to port
	<replaceable>23</replaceable> on <hostid>localhost</hostid>
	of the remote machine. Since <replaceable>23</replaceable>
	is <application>telnet</application>, this would create a
	secure <application>telnet</application> session through an
	SSH tunnel.</para>

	<para>This can be used to wrap any number of insecure TCP
	protocols such as SMTP, POP3, FTP, etc.</para>

	<example>
	<title>Using SSH to Create a Secure Tunnel for SMTP</title>

	<screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5025:localhost:25 user@mailserver.example.com</replaceable></userinput>
	user@mailserver.example.com's password: <userinput>*****</userinput>
	&prompt.user; <userinput>telnet localhost 5025</userinput>
	Trying 127.0.0.1...
	Connected to localhost.
	Escape character is '^]'.
	220 mailserver.example.com ESMTP</screen>

	<para>This can be used in conjunction with an
	&man.ssh-keygen.1; and additional user accounts to create
	a more seamless/hassle-free SSH tunneling environment.
	Keys can be used in place of typing a password, and the
	tunnels can be run as a separate user.</para>
	</example>

	<sect3>
	<title>Practical SSH Tunneling Examples</title>

	<sect4>
	<title>Secure Access of a POP3 Server</title>

	<para>At work, there is an SSH server that accepts
	connections from the outside. On the same office
	network resides a mail server running a POP3 server.
	The network, or network path between your home and
	office may or may not be completely trustable. Because
	of this, you need to check your e-mail in a secure
	manner. The solution is to create an SSH connection to
	your office's SSH server, and tunnel through to the mail
	server.</para>

	<screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>2110:mail.example.com:110 user@ssh-server.example.com</replaceable></userinput>
	user@ssh-server.example.com's password: <userinput>******</userinput></screen>

	<para>When the tunnel is up and running, you can point
	your mail client to send POP3 requests to

	<hostid>localhost</hostid> port 2110. A connection here
	will be forwarded securely across the tunnel to
	<hostid>mail.example.com</hostid>.</para>
	</sect4>

	<sect4>
	<title>Bypassing a Draconian Firewall</title>

	<para>Some network administrators impose extremely
	draconian firewall rules, filtering not only incoming
	connections, but outgoing connections. You may be only
	given access to contact remote machines on ports 22 and
	80 for SSH and web surfing.</para>

	<para>You may wish to access another (perhaps non-work
	related) service, such as an Ogg Vorbis server to stream
	music. If this Ogg Vorbis server is streaming on some
	other port than 22 or 80, you will not be able to access
	it.</para>

	<para>The solution is to create an SSH connection to a
	machine outside of your network's firewall, and use it
	to tunnel to the Ogg Vorbis server.</para>

	<screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>8888:music.example.com:8000 user@unfirewalled-system.example.org</replaceable></userinput>
	user@unfirewalled-system.example.org's password: <userinput>*******</userinput></screen>

	<para>Your streaming client can now be pointed to
	<hostid>localhost</hostid> port 8888, which will be
	forwarded over to <hostid>music.example.com</hostid>
	port 8000, successfully evading the firewall.</para>
	</sect4>
	</sect3>
	</sect2>

	<sect2>
	<title>The <varname>AllowUsers</varname> Option</title>

	<para>It is often a good idea to limit which users can log in
	and from where. The <literal>AllowUsers</literal> option is
	a good way to accomplish this. For example, to only allow
	the <username>root</username> user to log in from
	<hostid role="ipaddr">192.168.1.32</hostid>, something like
	this would be appropriate in the
	<filename>/etc/ssh/sshd_config</filename> file:</para>

	<programlisting>AllowUsers root@192.168.1.32</programlisting>

	<para>To allow the user <username>admin</username> to log in
	from anywhere, just list the username by itself:</para>

	<programlisting>AllowUsers admin</programlisting>

	<para>Multiple users should be listed on the same line, like
	so:</para>

	<programlisting>AllowUsers root@192.168.1.32 admin</programlisting>

	<note>
	<para>It is important that you list each user that needs to
	log in to this machine; otherwise they will be locked
	out.</para>
	</note>

	<para>After making changes to
	<filename>/etc/ssh/sshd_config</filename> you must tell
	&man.sshd.8; to reload its config files, by running:</para>

	<screen>&prompt.root; <userinput>service sshd reload</userinput></screen>
	</sect2>

	<sect2>
	<title>Further Reading</title>

	<para><ulink
	url="http://www.openssh.com/">OpenSSH</ulink></para>

	<para>&man.ssh.1; &man.scp.1; &man.ssh-keygen.1;
	&man.ssh-agent.1; &man.ssh-add.1; &man.ssh.config.5;</para>

	<para>&man.sshd.8; &man.sftp-server.8;
	&man.sshd.config.5;</para>
	</sect2>
	</sect1>

	<sect1 id="fs-acl">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>File System Access Control Lists
	(<acronym>ACL</acronym>s)</title>

	<indexterm>
	<primary>ACL</primary>
	</indexterm>

	<para>In conjunction with file system enhancements like
	snapshots, FreeBSD offers the security of File System Access
	Control Lists (<acronym>ACL</acronym>s).</para>

	<para>Access Control Lists extend the standard &unix; permission
	model in a highly compatible (&posix;.1e) way. This feature
	permits an administrator to make use of and take advantage of
	a more sophisticated security model.</para>

	<para>To enable <acronym>ACL</acronym> support for
	<acronym>UFS</acronym> file systems, the following:</para>

	<programlisting>options UFS_ACL</programlisting>

	<para>must be compiled into the kernel. If this option has not
	been compiled in, a warning message will be displayed when
	attempting to mount a file system supporting
	<acronym>ACL</acronym>s. This option is included in the
	<filename>GENERIC</filename> kernel. <acronym>ACL</acronym>s
	rely on extended attributes being enabled on the file system.
	Extended attributes are natively supported in the next
	generation &unix; file system, <acronym>UFS2</acronym>.</para>

	<note>
	<para>A higher level of administrative overhead is required to
	configure extended attributes on <acronym>UFS1</acronym>
	than on <acronym>UFS2</acronym>. The performance of
	extended attributes on <acronym>UFS2</acronym> is also
	substantially higher. As a result, <acronym>UFS2</acronym>
	is generally recommended in preference to
	<acronym>UFS1</acronym> for use with access control
	lists.</para>
	</note>

	<para><acronym>ACL</acronym>s are enabled by the mount-time
	administrative flag, <option>acls</option>, which may be added
	to <filename>/etc/fstab</filename>. The mount-time flag can
	also be automatically set in a persistent manner using
	&man.tunefs.8; to modify a superblock <acronym>ACL</acronym>s
	flag in the file system header. In general, it is preferred
	to use the superblock flag for several reasons:</para>

	<itemizedlist>
	<listitem>
	<para>The mount-time <acronym>ACL</acronym>s flag cannot be
	changed by a remount (&man.mount.8; <option>-u</option>),
	only by means of a complete &man.umount.8; and fresh
	&man.mount.8;. This means that <acronym>ACL</acronym>s
	cannot be enabled on the root file system after boot. It
	also means that you cannot change the disposition of a
	file system once it is in use.</para>
	</listitem>

	<listitem>
	<para>Setting the superblock flag will cause the file system
	to always be mounted with <acronym>ACL</acronym>s enabled
	even if there is not an <filename>fstab</filename> entry
	or if the devices re-order. This prevents accidental
	mounting of the file system without
	<acronym>ACL</acronym>s enabled, which can result in
	<acronym>ACL</acronym>s being improperly enforced, and
	hence security problems.</para>
	</listitem>
	</itemizedlist>

	<note>
	<para>We may change the <acronym>ACL</acronym>s behavior to
	allow the flag to be enabled without a complete fresh
	&man.mount.8;, but we consider it desirable to discourage
	accidental mounting without <acronym>ACL</acronym>s enabled,
	because you can shoot your feet quite nastily if you enable
	<acronym>ACL</acronym>s, then disable them, then re-enable
	them without flushing the extended attributes. In general,
	once you have enabled <acronym>ACL</acronym>s on a file
	system, they should not be disabled, as the resulting file
	protections may not be compatible with those intended by the
	users of the system, and re-enabling <acronym>ACL</acronym>s
	may re-attach the previous <acronym>ACL</acronym>s to files
	that have since had their permissions changed, resulting in
	other unpredictable behavior.</para>
	</note>

	<para>File systems with <acronym>ACL</acronym>s enabled will
	show a <literal>+</literal> (plus) sign in their permission
	settings when viewed. For example:</para>

	<programlisting>drwx------ 2 robert robert 512 Dec 27 11:54 private
	drwxrwx---+ 2 robert robert 512 Dec 23 10:57 directory1
	drwxrwx---+ 2 robert robert 512 Dec 22 10:20 directory2
	drwxrwx---+ 2 robert robert 512 Dec 27 11:57 directory3
	drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html</programlisting>

	<para>Here we see that the
	<filename class="directory">directory1</filename>,
	<filename class="directory">directory2</filename>, and
	<filename class="directory">directory3</filename> directories
	are all taking advantage of <acronym>ACL</acronym>s. The
	<filename class="directory">public_html</filename> directory
	is not.</para>

	<sect2>
	<title>Making Use of <acronym>ACL</acronym>s</title>

	<para>The file system <acronym>ACL</acronym>s can be viewed by
	the &man.getfacl.1; utility. For instance, to view the
	<acronym>ACL</acronym> settings on the
	<filename>test</filename> file, one would use the
	command:</para>

	<screen>&prompt.user; <userinput>getfacl <filename>test</filename></userinput>
	#file:test
	#owner:1001
	#group:1001
	user::rw-
	group::r--
	other::r--</screen>

	<para>To change the <acronym>ACL</acronym> settings on this
	file, invoke the &man.setfacl.1; utility. Observe:</para>

	<screen>&prompt.user; <userinput>setfacl -k <filename>test</filename></userinput></screen>

	<para>The <option>-k</option> flag will remove all of the
	currently defined <acronym>ACL</acronym>s from a file or
	file system. The more preferable method would be to use
	<option>-b</option> as it leaves the basic fields required
	for <acronym>ACL</acronym>s to work.</para>

	<screen>&prompt.user; <userinput>setfacl -m u:trhodes:rwx,group:web:r--,o::--- <filename>test</filename></userinput></screen>

	<para>In the aforementioned command, the <option>-m</option>
	option was used to modify the default <acronym>ACL</acronym>
	entries. Since there were no pre-defined entries, as they
	were removed by the previous command, this will restore the
	default options and assign the options listed. Take care to
	notice that if you add a user or group which does not exist
	on the system, an <errorname>Invalid argument</errorname>
	error will be printed to
	<devicename>stdout</devicename>.</para>
	</sect2>
	</sect1>

	<sect1 id="security-portaudit">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>Monitoring Third Party Security Issues</title>

	<indexterm>
	<primary>Portaudit</primary>
	</indexterm>

	<para>In recent years, the security world has made many
	improvements to how vulnerability assessment is handled. The
	threat of system intrusion increases as third party utilities
	are installed and configured for virtually any operating
	system available today.</para>

	<para>Vulnerability assessment is a key factor in security, and
	while &os; releases advisories for the base system, doing so
	for every third party utility is beyond the &os; Project's
	capability. There is a way to mitigate third party
	vulnerabilities and warn administrators of known security
	issues. A &os; add on utility known as
	<application>Portaudit</application> exists solely for this
	purpose.</para>

	<para>The
	<filename role="package">ports-mgmt/portaudit</filename>
	port polls a database, updated and maintained by the &os;
	Security Team and ports developers, for known security
	issues.</para>

	<para>To begin using <application>Portaudit</application>, one
	must install it from the Ports Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portaudit && make install clean</userinput></screen>

	<para>During the install process, the configuration files for
	&man.periodic.8; will be updated, permitting
	<application>Portaudit</application> output in the daily
	security runs. Ensure the daily security run emails, which
	are sent to <username>root</username>'s email account, are
	being read. No more configuration will be required
	here.</para>

	<para>After installation, an administrator can update the
	database and view known vulnerabilities in installed packages
	by invoking the following command:</para>

	<screen>&prompt.root; <userinput>portaudit -Fda</userinput></screen>

	<note>
	<para>The database will automatically be updated during the
	&man.periodic.8; run; thus, the previous command is
	completely optional. It is only required for the following
	examples.</para>
	</note>

	<para>To audit the third party utilities installed as part of
	the Ports Collection at anytime, an administrator need only
	run the following command:</para>

	<screen>&prompt.root; <userinput>portaudit -a</userinput></screen>

	<para><application>Portaudit</application> will produce
	something like this for vulnerable packages:</para>

	<programlisting>Affected package: cups-base-1.1.22.0_1
	Type of problem: cups-base -- HPGL buffer overflow vulnerability.
	Reference: <http://www.FreeBSD.org/ports/portaudit/40a3bca2-6809-11d9-a9e7-0001020eed82.html>

	1 problem(s) in your installed packages found.

	You are advised to update or deinstall the affected package(s) immediately.</programlisting>

	<para>By pointing a web browser to the <acronym>URL</acronym>
	shown, an administrator may obtain more information about the
	vulnerability in question. This will include versions
	affected, by &os; Port version, along with other web sites
	which may contain security advisories.</para>

	<para>In short, <application>Portaudit</application> is a
	powerful utility and extremely useful when coupled with the
	<application>Portupgrade</application> port.</para>
	</sect1>

	<sect1 id="security-advisories">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>&os; Security Advisories</title>

	<indexterm>
	<primary>FreeBSD Security Advisories</primary>
	</indexterm>

	<para>Like many production quality operating systems, &os;
	publishes <quote>Security Advisories</quote>. These
	advisories are usually mailed to the security lists and noted
	in the Errata only after the appropriate releases have been
	patched. This section will work to explain what an advisory
	is, how to understand it, and what measures to take in order
	to patch a system.</para>

	<sect2>
	<title>What Does an Advisory Look Like?</title>

	<para>The &os; security advisories look similar to the one
	below, taken from the &a.security-notifications.name;
	mailing list.</para>

	<programlisting>=============================================================================
	FreeBSD-SA-XX:XX.UTIL Security Advisory
	The FreeBSD Project

	Topic: denial of service due to some problem <co id="co-topic"/>

	Category: core <co id="co-category"/>
	Module: sys <co id="co-module"/>
	Announced: 2003-09-23 <co id="co-announce"/>
	Credits: Person <co id="co-credit"/>
	Affects: All releases of &os; <co id="co-affects"/>
	&os; 4-STABLE prior to the correction date
	Corrected: 2003-09-23 16:42:59 UTC (RELENG_4, 4.9-PRERELEASE)
	2003-09-23 20:08:42 UTC (RELENG_5_1, 5.1-RELEASE-p6)
	2003-09-23 20:07:06 UTC (RELENG_5_0, 5.0-RELEASE-p15)
	2003-09-23 16:44:58 UTC (RELENG_4_8, 4.8-RELEASE-p8)
	2003-09-23 16:47:34 UTC (RELENG_4_7, 4.7-RELEASE-p18)
	2003-09-23 16:49:46 UTC (RELENG_4_6, 4.6-RELEASE-p21)
	2003-09-23 16:51:24 UTC (RELENG_4_5, 4.5-RELEASE-p33)
	2003-09-23 16:52:45 UTC (RELENG_4_4, 4.4-RELEASE-p43)
	2003-09-23 16:54:39 UTC (RELENG_4_3, 4.3-RELEASE-p39) <co id="co-corrected"/>
	<acronym>CVE</acronym> Name: CVE-XXXX-XXXX <co id="co-cve"/>

	For general information regarding FreeBSD Security Advisories,
	including descriptions of the fields above, security branches, and the
	following sections, please visit
	http://www.FreeBSD.org/security/.

	I. Background <co id="co-backround"/>


	II. Problem Description <co id="co-descript"/>


	III. Impact <co id="co-impact"/>


	IV. Workaround <co id="co-workaround"/>


	V. Solution <co id="co-solution"/>


	VI. Correction details <co id="co-details"/>


	VII. References <co id="co-ref"/></programlisting>

	<calloutlist>
	<callout arearefs="co-topic">
	<para>The <literal>Topic</literal> field indicates exactly
	what the problem is. It is basically an introduction to
	the current security advisory and notes the utility with
	the vulnerability.</para>
	</callout>

	<callout arearefs="co-category">
	<para>The <literal>Category</literal> refers to the
	affected part of the system which may be one of
	<literal>core</literal>, <literal>contrib</literal>, or
	<literal>ports</literal>. The <literal>core</literal>
	category means that the vulnerability affects a core
	component of the &os; operating system. The
	<literal>contrib</literal> category means that the
	vulnerability affects software contributed to the &os;
	Project, such as <application>sendmail</application>.
	Finally the <literal>ports</literal> category indicates
	that the vulnerability affects add on software available
	as part of the Ports Collection.</para>
	</callout>

	<callout arearefs="co-module">
	<para>The <literal>Module</literal> field refers to the
	component location, for instance <literal>sys</literal>.
	In this example, we see that the module,
	<literal>sys</literal>, is affected; therefore, this
	vulnerability affects a component used within the
	kernel.</para>
	</callout>

	<callout arearefs="co-announce">
	<para>The <literal>Announced</literal> field reflects the
	date said security advisory was published, or announced
	to the world. This means that the security team has
	verified that the problem does exist and that a patch
	has been committed to the &os; source code
	repository.</para>
	</callout>

	<callout arearefs="co-credit">
	<para>The <literal>Credits</literal> field gives credit to
	the individual or organization who noticed the
	vulnerability and reported it.</para>
	</callout>

	<callout arearefs="co-affects">
	<para>The <literal>Affects</literal> field explains which
	releases of &os; are affected by this vulnerability.
	For the kernel, a quick look over the output from
	<command>ident</command> on the affected files will help
	in determining the revision. For ports, the version
	number is listed after the port name in
	<filename class="directory">/var/db/pkg</filename>. If
	the system does not sync with the &os;
	Subversion repository and rebuilt daily,
	chances are that it is affected.</para>
	</callout>

	<callout arearefs="co-corrected">
	<para>The <literal>Corrected</literal> field indicates the
	date, time, time offset, and release that was
	corrected.</para>
	</callout>

	<callout arearefs="co-cve">
	<para>Reserved for the identification information used to
	look up vulnerabilities in the Common Vulnerabilities
	Database system.</para>
	</callout>

	<callout arearefs="co-backround">
	<para>The <literal>Background</literal> field gives
	information on exactly what the affected utility is.
	Most of the time this is why the utility exists in &os;,
	what it is used for, and a bit of information on how the
	utility came to be.</para>
	</callout>

	<callout arearefs="co-descript">
	<para>The <literal>Problem Description</literal> field
	explains the security hole in depth. This can include
	information on flawed code, or even how the utility
	could be maliciously used to open a security
	hole.</para>
	</callout>

	<callout arearefs="co-impact">
	<para>The <literal>Impact</literal> field describes what
	type of impact the problem could have on a system. For
	example, this could be anything from a denial of service
	attack, to extra privileges available to users, or even
	giving the attacker superuser access.</para>
	</callout>

	<callout arearefs="co-workaround">
	<para>The <literal>Workaround</literal> field offers a
	feasible workaround to system administrators who may be
	incapable of upgrading the system. This may be due to
	time constraints, network availability, or a slew of
	other reasons. Regardless, security should not be taken
	lightly, and an affected system should either be patched
	or the security hole workaround should be
	implemented.</para>
	</callout>

	<callout arearefs="co-solution">
	<para>The <literal>Solution</literal> field offers
	instructions on patching the affected system. This is a
	step by step tested and verified method for getting a
	system patched and working securely.</para>
	</callout>

	<callout arearefs="co-details">
	<para>The <literal>Correction Details</literal> field
	displays the Subversion branch or release
	name with the periods changed to underscore characters.
	It also shows the revision number of the affected files
	within each branch.</para>
	</callout>

	<callout arearefs="co-ref">
	<para>The <literal>References</literal> field usually
	offers sources of other information. This can include
	web <acronym>URL</acronym>s, books, mailing lists, and
	newsgroups.</para>
	</callout>
	</calloutlist>
	</sect2>
	</sect1>

	<sect1 id="security-accounting">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Tom</firstname>
	<surname>Rhodes</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>

	<title>Process Accounting</title>

	<indexterm>
	<primary>Process Accounting</primary>
	</indexterm>

	<para>Process accounting is a security method in which an
	administrator may keep track of system resources used,
	their allocation among users, provide for system monitoring,
	and minimally track a user's commands.</para>

	<para>This indeed has its own positive and negative points. One
	of the positives is that an intrusion may be narrowed down to
	the point of entry. A negative is the amount of logs
	generated by process accounting, and the disk space they may
	require. This section will walk an administrator through the
	basics of process accounting.</para>

	<sect2>
	<title>Enabling and Utilizing Process Accounting</title>

	<para>Before making use of process accounting, it must be
	enabled. To do this, execute the following commands:</para>

	<screen>&prompt.root; <userinput>touch <filename>/var/account/acct</filename></userinput>

	&prompt.root; <userinput>accton <filename>/var/account/acct</filename></userinput>

	&prompt.root; <userinput>echo 'accounting_enable="YES"' >> <filename>/etc/rc.conf</filename></userinput></screen>

	<para>Once enabled, accounting will begin to track
	<acronym>CPU</acronym> stats, commands, etc. All accounting
	logs are in a non-human readable format and may be viewed
	using the &man.sa.8; utility. If issued without any
	options, <command>sa</command> will print information
	relating to the number of per user calls, the total elapsed
	time in minutes, total <acronym>CPU</acronym> and user time
	in minutes, average number of I/O operations, etc.</para>

	<para>To view information about commands being issued, one
	would use the &man.lastcomm.1; utility. The
	<command>lastcomm</command> command may be used to print out
	commands issued by users on specific &man.ttys.5;, for
	example:</para>

	<screen>&prompt.root; <userinput>lastcomm ls
	<username>trhodes</username> ttyp1</userinput></screen>

	<para>Would print out all known usage of the
	<command>ls</command> by <username>trhodes</username> on the
	<literal>ttyp1</literal> terminal.</para>

	<para>Many other useful options exist and are explained in the
	&man.lastcomm.1;, &man.acct.5; and &man.sa.8; manual
	pages.</para>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml (revision 41355)
	@@ -1,3068 +1,2870 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="serialcomms">
	<title>Serial Communications</title>

	<sect1 id="serial-synopsis">
	<title>Synopsis</title>

	<indexterm><primary>serial communications</primary></indexterm>

	- <para>&unix; has always had support for serial communications. In
	- fact, the very first &unix; machines relied on serial lines for
	- user input and output. Things have changed a lot from the days
	- when the average <quote>terminal</quote> consisted of a
	- 10-character-per-second serial printer and a keyboard. This
	- chapter will cover some of the ways in which FreeBSD uses serial
	- communications.</para>
	+ <para>&unix; has always had support for serial communications as
	+ the very first &unix; machines relied on serial lines for user
	+ input and output. Things have changed a lot from the days
	+ when the average terminal consisted of a 10-character-per-second
	+ serial printer and a keyboard. This chapter covers some of the
	+ ways serial communications can be used on &os;.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	- <para>How to connect terminals to your FreeBSD
	- system.</para>
	+ <para>How to connect terminals to a &os; system.</para>
	</listitem>
	<listitem>
	- <para>How to use a modem to dial out to remote
	- hosts.</para>
	+ <para>How to use a modem to dial out to remote hosts.</para>
	</listitem>
	<listitem>
	- <para>How to allow remote users to login to your
	- system with a modem.</para>
	+ <para>How to allow remote users to login to a &os; system
	+ with a modem.</para>
	</listitem>
	<listitem>
	- <para>How to boot your system from a serial console.</para>
	+ <para>How to boot a &os; system from a serial console.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	- <para>Know how to configure and install a new kernel (<xref
	- linkend="kernelconfig"/>).</para>
	+ <para>Know how to <link linkend="kernelconfig"> configure and
	+ install a custom kernel</link>.</para>
	</listitem>
	<listitem>
	- <para>Understand &unix; permissions and processes (<xref
	- linkend="basics"/>).</para>
	+ <para>Understand <link linkend="basics"> &os; permissions
	+ and processes</link>.</para>
	</listitem>
	<listitem>
	<para>Have access to the technical manual for the serial
	- hardware (modem or multi-port card) that you would like to
	- use with FreeBSD.</para>
	+ hardware to be used with &os;.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="serial">
	<title>Introduction</title>

	- <warning>
	- <para>As of &os; 8.0, device nodes for serial ports have been
	- renamed from
	- <filename>/dev/cuad<replaceable>N</replaceable></filename> to
	- <filename>/dev/cuau<replaceable>N</replaceable></filename> and
	- from
	- <filename>/dev/ttyd<replaceable>N</replaceable></filename> to
	- <filename>/dev/ttyu<replaceable>N</replaceable></filename>.
	- &os; 7.X users will have to adapt the following
	- documentation according to these changes.</para>
	- </warning>
	<!-- XXX Write me! -->

	<sect2 id="serial-terminology">
	<title>Terminology</title>

	<variablelist>
	<indexterm><primary>bits-per-second</primary></indexterm>
	<varlistentry>
	- <term>bps</term>
	+ <term><acronym>bps</acronym></term>
	<listitem>
	- <para>Bits per Second — the rate at which data is
	- transmitted</para>
	+ <para>Bits per Second (<acronym>bps</acronym>) is the rate
	+ at which data is transmitted.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	- <term>DTE</term>
	+ <term><acronym>DTE</acronym></term>
	<listitem>
	<indexterm><primary>DTE</primary></indexterm>

	- <para>Data Terminal Equipment — for example, your
	- computer</para>
	+ <para>An example of a Data Terminal Equipment
	+ (<acronym>DTE</acronym>) is a computer.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	- <term>DCE</term>
	+ <term><acronym>DCE</acronym></term>
	<listitem>
	<indexterm><primary>DCE</primary></indexterm>

	- <para>Data Communications Equipment — your
	- modem</para>
	+ <para>An example of a Data Communications Equipment
	+ (<acronym>DTE</acronym>) is a modem.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>RS-232</term>

	<listitem>
	<indexterm><primary>RS-232C cables</primary></indexterm>

	- <para>EIA standard for hardware serial
	- communications</para>
	+ <para>The original standard for hardware serial
	+ communications. It is now usually referred to as
	+ <acronym>TIA</acronym>-232</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>When talking about communications data rates, this section
	does not use the term <quote>baud</quote>. Baud refers to the
	number of electrical state transitions that may be made in a
	- period of time, while <quote>bps</quote> (bits per second) is
	- the <emphasis>correct</emphasis> term to use (at least it does
	- not seem to bother the curmudgeons quite as much).</para>
	+ period of time, while <acronym>bps</acronym> is the
	+ <emphasis>correct</emphasis> term to use.</para>
	</sect2>

	<sect2 id="serial-cables-ports">
	<title>Cables and Ports</title>

	- <para>To connect a modem or terminal to your FreeBSD system, you
	- will need a serial port on your computer and the proper cable
	- to connect to your serial device. If you are already familiar
	- with your hardware and the cable it requires, you can safely
	- skip this section.</para>
	+ <para>To connect a modem or serial terminal to a &os; system, a
	+ serial port on the computer and the proper cable to connect to
	+ the serial device are needed. Users who are already familiar
	+ with serial hardware and cabling can safely skip this
	+ section.</para>

	<sect3 id="term-cables">
	<title>Cables</title>

	<para>There are several different kinds of serial cables. The
	- two most common types for our purposes are null-modem cables
	- and standard (<quote>straight</quote>) RS-232 cables. The
	- documentation for your hardware should describe the type of
	- cable required.</para>
	+ two most common types are null-modem cables and standard
	+ RS-232 cables. The documentation for the hardware should
	+ describe the type of cable required.</para>

	<sect4 id="term-cables-null">
	<title>Null-modem Cables</title>

	<indexterm>
	<primary>null-modem cable</primary>
	</indexterm>

	<para>A null-modem cable passes some signals, such as
	<quote>Signal Ground</quote>, straight through, but
	switches other signals. For example, the
	<quote>Transmitted Data</quote> pin on one end goes to the
	<quote>Received Data</quote> pin on the other end.</para>

	- <para>You can also construct your own null-modem cable for
	- use with terminals (e.g., for quality purposes). This
	- table shows the RS-232C <link
	- linkend="serialcomms-signal-names">signals</link>
	- and the pin numbers on a DB-25 connector. Note that the
	- standard also calls for a straight-through pin 1 to pin 1
	- <emphasis>Protective Ground</emphasis> line, but it is
	- often omitted. Some terminals work OK using only pins 2,
	- 3 and 7, while others require different configurations
	- than the examples shown below.</para>
	+ <para>A null-modem cable can be constructed for use with
	+ terminals. The following table shows the RS-232C <link
	+ linkend="serialcomms-signal-names">signal names</link>
	+ and the pin numbers on a DB-25 connector. While the
	+ standard calls for a straight-through pin 1 to pin 1
	+ <emphasis>Protective Ground</emphasis> line, it is often
	+ omitted. Some terminals work using only pins 2, 3, and
	+ 7, while others require different configurations than
	+ the examples shown below.</para>

	<table frame="none" pgwide="1">
	<title>DB-25 to DB-25 Null-Modem Cable</title>

	<tgroup cols="5">
	<thead>
	<row>
	<entry align="left">Signal</entry>
	<entry align="left">Pin #</entry>
	<entry></entry>
	<entry align="left">Pin #</entry>
	<entry align="left">Signal</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>SG</entry>
	<entry>7</entry>
	<entry>connects to</entry>
	<entry>7</entry>
	<entry>SG</entry>
	</row>

	<row>
	<entry>TD</entry>
	<entry>2</entry>
	<entry>connects to</entry>
	<entry>3</entry>
	<entry>RD</entry>
	</row>

	<row>
	<entry>RD</entry>
	<entry>3</entry>
	<entry>connects to</entry>
	<entry>2</entry>
	<entry>TD</entry>
	</row>

	<row>
	<entry>RTS</entry>
	<entry>4</entry>
	<entry>connects to</entry>
	<entry>5</entry>
	<entry>CTS</entry>
	</row>

	<row>
	<entry>CTS</entry>
	<entry>5</entry>
	<entry>connects to</entry>
	<entry>4</entry>
	<entry>RTS</entry>
	</row>

	<row>
	<entry>DTR</entry>
	<entry>20</entry>
	<entry>connects to</entry>
	<entry>6</entry>
	<entry>DSR</entry>
	</row>

	<row>
	<entry>DTR</entry>
	<entry>20</entry>
	<entry>connects to</entry>
	<entry>8</entry>
	<entry>DCD</entry>
	</row>

	<row>
	<entry>DSR</entry>
	<entry>6</entry>
	<entry>connects to</entry>
	<entry>20</entry>
	<entry>DTR</entry>
	</row>

	<row>
	<entry>DCD</entry>
	<entry>8</entry>
	<entry>connects to</entry>
	<entry>20</entry>
	<entry>DTR</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	- <para>Here are two other schemes more common
	- nowadays.</para>
	+ <para>The next two tables show two other common
	+ schemes.</para>

	<table frame="none" pgwide="1">
	<title>DB-9 to DB-9 Null-Modem Cable</title>

	<tgroup cols="5">
	<thead>
	<row>
	<entry align="left">Signal</entry>
	<entry align="left">Pin #</entry>
	<entry></entry>
	<entry align="left">Pin #</entry>
	<entry align="left">Signal</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>RD</entry>
	<entry>2</entry>
	<entry>connects to</entry>
	<entry>3</entry>
	<entry>TD</entry>
	</row>

	<row>
	<entry>TD</entry>
	<entry>3</entry>
	<entry>connects to</entry>
	<entry>2</entry>
	<entry>RD</entry>
	</row>

	<row>
	<entry>DTR</entry>
	<entry>4</entry>
	<entry>connects to</entry>
	<entry>6</entry>
	<entry>DSR</entry>
	</row>

	<row>
	<entry>DTR</entry>
	<entry>4</entry>
	<entry>connects to</entry>
	<entry>1</entry>
	<entry>DCD</entry>
	</row>

	<row>
	<entry>SG</entry>
	<entry>5</entry>
	<entry>connects to</entry>
	<entry>5</entry>
	<entry>SG</entry>
	</row>

	<row>
	<entry>DSR</entry>
	<entry>6</entry>
	<entry>connects to</entry>
	<entry>4</entry>
	<entry>DTR</entry>
	</row>

	<row>
	<entry>DCD</entry>
	<entry>1</entry>
	<entry>connects to</entry>
	<entry>4</entry>
	<entry>DTR</entry>
	</row>

	<row>
	<entry>RTS</entry>
	<entry>7</entry>
	<entry>connects to</entry>
	<entry>8</entry>
	<entry>CTS</entry>
	</row>

	<row>
	<entry>CTS</entry>
	<entry>8</entry>
	<entry>connects to</entry>
	<entry>7</entry>
	<entry>RTS</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<table frame="none" pgwide="1">
	<title>DB-9 to DB-25 Null-Modem Cable</title>

	<tgroup cols="5">
	<thead>
	<row>
	<entry align="left">Signal</entry>
	<entry align="left">Pin #</entry>
	<entry></entry>
	<entry align="left">Pin #</entry>
	<entry align="left">Signal</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>RD</entry>
	<entry>2</entry>
	<entry>connects to</entry>
	<entry>2</entry>
	<entry>TD</entry>
	</row>

	<row>
	<entry>TD</entry>
	<entry>3</entry>
	<entry>connects to</entry>
	<entry>3</entry>
	<entry>RD</entry>
	</row>

	<row>
	<entry>DTR</entry>
	<entry>4</entry>
	<entry>connects to</entry>
	<entry>6</entry>
	<entry>DSR</entry>
	</row>

	<row>
	<entry>DTR</entry>
	<entry>4</entry>
	<entry>connects to</entry>
	<entry>8</entry>
	<entry>DCD</entry>
	</row>

	<row>
	<entry>SG</entry>
	<entry>5</entry>
	<entry>connects to</entry>
	<entry>7</entry>
	<entry>SG</entry>
	</row>

	<row>
	<entry>DSR</entry>
	<entry>6</entry>
	<entry>connects to</entry>
	<entry>20</entry>
	<entry>DTR</entry>
	</row>

	<row>
	<entry>DCD</entry>
	<entry>1</entry>
	<entry>connects to</entry>
	<entry>20</entry>
	<entry>DTR</entry>
	</row>

	<row>
	<entry>RTS</entry>
	<entry>7</entry>
	<entry>connects to</entry>
	<entry>5</entry>
	<entry>CTS</entry>
	</row>

	<row>
	<entry>CTS</entry>
	<entry>8</entry>
	<entry>connects to</entry>
	<entry>4</entry>
	<entry>RTS</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<note>
	<para>When one pin at one end connects to a pair of pins
	at the other end, it is usually implemented with one
	short wire between the pair of pins in their connector
	and a long wire to the other single pin.</para>
	</note>

	- <para>The above designs seems to be the most popular. In
	- another variation (explained in the book <emphasis>RS-232
	- Made Easy</emphasis>) SG connects to SG, TD connects to
	- RD, RTS and CTS connect to DCD, DTR connects to DSR, and
	+ <para>The above designs seem to be the most popular. In
	+ another variation, SG connects to SG, TD connects to RD,
	+ RTS and CTS connect to DCD, DTR connects to DSR, and
	vice-versa.</para>
	</sect4>

	<sect4 id="term-cables-std">
	<title>Standard RS-232C Cables</title>

	<indexterm><primary>RS-232C cables</primary></indexterm>

	<para>A standard serial cable passes all of the RS-232C
	- signals straight through. That is, the <quote>Transmitted
	+ signals straight through. The <quote>Transmitted
	Data</quote> pin on one end of the cable goes to the
	<quote>Transmitted Data</quote> pin on the other end.
	- This is the type of cable to use to connect a modem to
	- your FreeBSD system, and is also appropriate for some
	+ This is the type of cable used to connect a modem to
	+ the &os; system, and is also appropriate for some
	terminals.</para>
	</sect4>
	</sect3>

	<sect3 id="term-ports">
	<title>Ports</title>

	<para>Serial ports are the devices through which data is
	- transferred between the FreeBSD host computer and the
	+ transferred between the &os; host computer and the
	terminal. This section describes the kinds of ports that
	- exist and how they are addressed in FreeBSD.</para>
	+ exist and how they are addressed in &os;.</para>

	<sect4 id="term-portkinds">
	<title>Kinds of Ports</title>

	- <para>Several kinds of serial ports exist. Before you
	- purchase or construct a cable, you need to make sure it
	- will fit the ports on your terminal and on the FreeBSD
	+ <para>Several kinds of serial ports exist. Before
	+ purchasing or constructing a cable, make sure it will
	+ fit the ports on the terminal and on the &os;
	system.</para>

	- <para>Most terminals will have DB-25 ports. Personal
	- computers, including PCs running FreeBSD, will have DB-25
	- or DB-9 ports. If you have a multiport serial card for
	- your PC, you may have RJ-12 or RJ-45 ports.</para>
	+ <para>Most terminals have DB-25 ports. Personal computers
	+ may have DB-25 or DB-9 ports. A multiport serial card may
	+ have RJ-12 or RJ-45 ports.</para>

	<para>See the documentation that accompanied the hardware
	- for specifications on the kind of port in use. A visual
	- inspection of the port often works too.</para>
	+ for specifications on the kind of port or visually verify
	+ the type of port.</para>
	</sect4>

	<sect4 id="term-portnames">
	<title>Port Names</title>

	- <para>In FreeBSD, you access each serial port through an
	- entry in the <filename>/dev</filename> directory. There
	- are two different kinds of entries:</para>
	+ <para>In &os;, each serial port is accessed through an
	+ entry in <filename class="directory">/dev</filename>.
	+ There are two different kinds of entries:</para>

	<itemizedlist>
	<listitem>
	<para>Call-in ports are named
	<filename>/dev/ttyu<replaceable>N</replaceable></filename>
	where <replaceable>N</replaceable> is the port number,
	- starting from zero. Generally, you use the call-in
	- port for terminals. Call-in ports require that the
	- serial line assert the data carrier detect (DCD)
	- signal to work correctly.</para>
	+ starting from zero. Generally, the call-in port is
	+ used for terminals. Call-in ports require that the
	+ serial line assert the Data Carrier Detect
	+ (<acronym>DCD</acronym>) signal to work
	+ correctly.</para>
	</listitem>

	<listitem>
	<para>Call-out ports are named
	<filename>/dev/cuau<replaceable>N</replaceable></filename>.
	- You usually do not use the call-out port for
	- terminals, just for modems. You may use the call-out
	- port if the serial cable or the terminal does not
	- support the carrier detect signal.</para>
	+ Call-out ports are usually not used for terminals, but
	+ are used for modems. The call-out port can be used if
	+ the serial cable or the terminal does not support the
	+ carrier detect signal.</para>
	</listitem>
	</itemizedlist>

	- <para>If you have connected a terminal to the first serial
	- port(<devicename>COM1</devicename> in &ms-dos;), then you
	- will use <filename>/dev/ttyu0</filename> to refer to the
	+ <para>If a terminal is connected to the first serial
	+ port(<devicename>COM1</devicename>), use
	+ <filename>/dev/ttyu0</filename> to refer to the
	terminal. If the terminal is on the second serial port
	- (also known as <devicename>COM2</devicename>), use
	+ (<devicename>COM2</devicename>), use
	<filename>/dev/ttyu1</filename>, and so forth.</para>

	</sect4>
	</sect3>
	</sect2>

	<sect2>
	<title>Kernel Configuration</title>

	- <para>FreeBSD supports four serial ports by default. In the
	+ <para>&os; supports four serial ports by default. In the
	&ms-dos; world, these are known as
	<devicename>COM1</devicename>,
	<devicename>COM2</devicename>,
	<devicename>COM3</devicename>, and
	- <devicename>COM4</devicename>. FreeBSD currently supports
	+ <devicename>COM4</devicename>. &os; currently supports
	<quote>dumb</quote> multiport serial interface cards, such as
	- the BocaBoard 1008 and 2016, as well as more
	- intelligent multi-port cards such as those made by Digiboard
	- and Stallion Technologies. However, the default kernel only
	- looks for the standard COM ports.</para>
	+ the BocaBoard 1008 and 2016, as well as more intelligent
	+ multi-port cards such as those made by Digiboard and Stallion
	+ Technologies. However, the default kernel only looks for the
	+ standard COM ports.</para>

	- <para>To see if your kernel recognizes any of your serial ports,
	- watch for messages while the kernel is booting, or use the
	- <command>/sbin/dmesg</command> command to replay the kernel's
	- boot messages. In particular, look for messages that start
	- with the characters <literal>uart</literal> if you use
	- &os; 8.0 or higher, or <literal>sio</literal> for
	- &os; 7.4 or older.</para>
	+ <para>To see if the kernel recognizes the serial ports,
	+ watch for messages while the kernel is booting, or use
	+ <command>/sbin/dmesg</command> to replay the kernel's
	+ boot messages. Look for messages that start with the
	+ characters <literal>uart</literal>:</para>

	- <tip><para>To view just the messages that have the word
	- <literal>uart</literal> or <literal>sio</literal> depending
	- on the installed version of &os;, use the commands:</para>
	+ <screen>&prompt.root; <userinput>/sbin/dmesg \| grep 'uart'</userinput></screen>

	- <screen>&prompt.root; <userinput>/sbin/dmesg \| grep 'uart'</userinput>
	-&prompt.root; <userinput>/sbin/dmesg \| grep 'sio'</userinput></screen>
	- </tip>
	+ <para>If the kernel does not recognize all of the serial
	+ ports, configure <filename>/boot/device.hints</filename>.
	+ When editing this file, one can comment out or completely
	+ remove lines for devices that do not exist on the
	+ system.</para>

	- <para>For example, on a &os; 7.<replaceable>X</replaceable>
	- system with four serial ports, these are the serial-port
	- specific kernel boot messages:</para>
	-
	- <screen>sio0 at 0x3f8-0x3ff irq 4 on isa
	-sio0: type 16550A
	-sio1 at 0x2f8-0x2ff irq 3 on isa
	-sio1: type 16550A
	-sio2 at 0x3e8-0x3ef irq 5 on isa
	-sio2: type 16550A
	-sio3 at 0x2e8-0x2ef irq 9 on isa
	-sio3: type 16550A</screen>
	-
	- <para>If your kernel does not recognize all of your serial
	- ports, you will probably need to configure your kernel
	- in the <filename>/boot/device.hints</filename> file. You can
	- also comment-out or completely remove lines for devices you
	- do not have.</para>
	-
	- <para>Please refer to the &man.sio.4; manual page for
	- more information on serial ports and multiport boards
	- configuration. Be careful if you are using a configuration
	- file that was previously used for a different version of
	- FreeBSD because the device flags and the syntax have changed
	- between versions.</para>
	-
	<note>
	<para><literal>port IO_COM1</literal> is a substitution for
	<literal>port 0x3f8</literal>, <literal>IO_COM2</literal> is
	<literal>0x2f8</literal>, <literal>IO_COM3</literal> is
	<literal>0x3e8</literal>, and <literal>IO_COM4</literal> is
	- <literal>0x2e8</literal>, which are fairly common port
	- addresses for their respective serial ports; interrupts 4,
	- 3, 5, and 9 are fairly common interrupt request lines. Also
	- note that regular serial ports <emphasis>cannot</emphasis>
	- share interrupts on ISA-bus PCs (multiport boards have
	+ <literal>0x2e8</literal>. These are fairly common port
	+ addresses for their respective serial ports and interrupts
	+ 4, 3, 5, and 9 are fairly common interrupt request lines.
	+ Regular serial ports <emphasis>cannot</emphasis> share
	+ interrupts on ISA-bus PCs. Multiport boards have
	on-board electronics that allow all the 16550A's on the
	- board to share one or two interrupt request lines).</para>
	+ board to share one or two interrupt request lines.</para>
	</note>

	</sect2>

	<sect2>
	<title>Device Special Files</title>

	<para>Most devices in the kernel are accessed through
	- <quote>device special files</quote>, which are located in the
	- <filename>/dev</filename> directory. The
	+ <quote>device special files</quote> which are located in
	+ <filename class="directory">/dev</filename>. The
	<devicename>sio</devicename> devices are accessed through the
	<filename>/dev/ttyu<replaceable>N</replaceable></filename>
	(dial-in) and
	<filename>/dev/cuau<replaceable>N</replaceable></filename>
	- (call-out) devices. FreeBSD also provides initialization
	+ (call-out) devices. &os; also provides initialization
	devices
	(<filename>/dev/ttyu<replaceable>N</replaceable>.init</filename>
	and
	<filename>/dev/cuau<replaceable>N</replaceable>.init</filename>)
	and locking devices
	(<filename>/dev/ttyu<replaceable>N</replaceable>.lock</filename>
	and
	<filename>/dev/cuau<replaceable>N</replaceable>.lock</filename>).
	The initialization devices are used to initialize
	communications port parameters each time a port is opened,
	such as <literal>crtscts</literal> for modems which use
	<literal>RTS/CTS</literal> signaling for flow control. The
	locking devices are used to lock flags on ports to prevent
	- users or programs changing certain parameters; see the manual
	- pages &man.termios.4;, &man.sio.4;, and &man.stty.1; for
	- information on the terminal settings, locking and initializing
	+ users or programs changing certain parameters. Refer to
	+ &man.termios.4;, &man.sio.4;, and &man.stty.1; for
	+ information on terminal settings, locking and initializing
	devices, and setting terminal options, respectively.</para>
	</sect2>


	<sect2 id="serial-hw-config">
	<title>Serial Port Configuration</title>

	<indexterm><primary><devicename>ttyu</devicename></primary></indexterm>
	<indexterm><primary><devicename>cuau</devicename></primary></indexterm>

	<para>The
	<devicename>ttyu<replaceable>N</replaceable></devicename> (or
	<devicename>cuau<replaceable>N</replaceable></devicename>)
	- device is the regular device you will want to open for your
	- applications. When a process opens the device, it will have a
	- default set of terminal I/O settings. You can see these
	- settings with the command</para>
	+ is the regular device to open for applications. When a
	+ process opens the device, it will have a default set of
	+ terminal I/O settings. These settings can be viewed with the
	+ command:</para>

	<screen>&prompt.root; <userinput>stty -a -f /dev/ttyu1</userinput></screen>

	- <para>When you change the settings to this device, the settings
	- are in effect until the device is closed. When it is
	- reopened, it goes back to the default set. To make changes to
	- the default set, you can open and adjust the settings of the
	+ <para>When the settings are changed for a device, the settings
	+ are in effect until the device is closed. When the device is
	+ reopened, it goes back to the default set. To permanently
	+ change the default set, open and adjust the settings of the
	<quote>initial state</quote> device. For example, to turn on
	<option>CLOCAL</option> mode, 8 bit communication, and
	- <option>XON/XOFF</option> flow control by default for
	+ <option>XON/XOFF</option> flow control for
	<devicename>ttyu5</devicename>, type:</para>

	<screen>&prompt.root; <userinput>stty -f /dev/ttyu5.init clocal cs8 ixon ixoff</userinput></screen>

	<indexterm>
	<primary>rc files</primary>
	<secondary><filename>rc.serial</filename></secondary>
	</indexterm>

	- <para>System-wide initialization of the serial devices is
	- controlled in <filename>/etc/rc.d/serial</filename>. This
	+ <para>System-wide initialization of serial devices is
	+ controlled by <filename>/etc/rc.d/serial</filename>. This
	file affects the default settings of serial devices.</para>

	<para>To prevent certain settings from being changed by an
	application, make adjustments to the <quote>lock state</quote>
	device. For example, to lock the speed of
	<devicename>ttyu5</devicename> to 57600 bps, type:</para>

	<screen>&prompt.root; <userinput>stty -f /dev/ttyu5.lock 57600</userinput></screen>

	<para>Now, an application that opens
	<devicename>ttyu5</devicename> and tries to change the speed
	of the port will be stuck with 57600 bps.</para>

	- <para>Naturally, you should make the initial state and lock
	- state devices writable only by the <username>root</username>
	- account.</para>
	+ <para>The initial state and lock state devices should only be
	+ writable by <username>root</username>.</para>
	</sect2>
	</sect1>

	<sect1 id="term">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Sean</firstname>
	<surname>Kelly</surname>
	<contrib>Contributed by </contrib>
	</author>
	<!-- 28 July 1996 -->
	</authorgroup>
	</sect1info>
	<title>Terminals</title>

	- <warning>
	- <para>As of &os; 8.0, device nodes for serial ports have been
	- renamed from
	- <filename>/dev/cuad<replaceable>N</replaceable></filename> to
	- <filename>/dev/cuau<replaceable>N</replaceable></filename> and
	- from
	- <filename>/dev/ttyd<replaceable>N</replaceable></filename> to
	- <filename>/dev/ttyu<replaceable>N</replaceable></filename>.
	- &os; 7.X users will have to adapt the following
	- documentation according to these changes.</para>
	- </warning>
	-
	<indexterm><primary>terminals</primary></indexterm>

	<para>Terminals provide a convenient and low-cost way to access
	- your FreeBSD system when you are not at the computer's console
	- or on a connected network. This section describes how to use
	- terminals with FreeBSD.</para>
	+ a &os; system when not at the computer's console or on a
	+ connected network. This section describes how to use terminals
	+ with &os;.</para>

	<sect2 id="term-uses">
	<title>Uses and Types of Terminals</title>

	<para>The original &unix; systems did not have consoles.
	- Instead, people logged in and ran programs through terminals
	- that were connected to the computer's serial ports. It is
	- quite similar to using a modem and terminal software to dial
	- into a remote system to do text-only work.</para>
	+ Instead, users logged in and ran programs through terminals
	+ that were connected to the computer's serial ports.</para>

	- <para>Today's PCs have consoles capable of high quality
	- graphics, but the ability to establish a login session on a
	- serial port still exists in nearly every &unix; style
	- operating system today; FreeBSD is no exception. By using a
	- terminal attached to an unused serial port, you can log in and
	- run any text program that you would normally run on the
	- console or in an <command>xterm</command> window in the X
	- Window System.</para>
	+ <para>The ability to establish a login session on a serial port
	+ still exists in nearly every &unix;-like operating system
	+ today, including &os;. By using a terminal attached to an
	+ unused serial port, a user can log in and run any text program
	+ that can normally be run on the console or in an
	+ <command>xterm</command> window.</para>

	- <para>For the business user, you can attach many terminals to a
	- FreeBSD system and place them on your employees' desktops.
	- For a home user, a spare computer such as an older IBM PC or a
	- &macintosh; can be a terminal wired into a more powerful
	- computer running FreeBSD. You can turn what might otherwise be
	- a single-user computer into a powerful multiple user
	- system.</para>
	+ <para>Many terminals can be attached to a &os; system. An older
	+ spare computer can be used as a terminal wired into a more
	+ powerful computer running &os;. This can turn what might
	+ otherwise be a single-user computer into a powerful multiple
	+ user system.</para>

	- <para>For FreeBSD, there are three kinds of terminals:</para>
	+ <para>This section describes three kinds of terminals supported
	+ by &os;: dumb terminals, computers acting as terminals, and X
	+ terminals.</para>

	- <itemizedlist>
	- <listitem>
	- <para><link linkend="term-dumb">Dumb terminals</link></para>
	- </listitem>
	-
	- <listitem>
	- <para><link linkend="term-pcs">PCs acting as
	- terminals</link></para>
	- </listitem>
	-
	- <listitem>
	- <para><link linkend="term-x">X terminals</link></para>
	- </listitem>
	- </itemizedlist>
	-
	- <para>The remaining subsections describe each kind.</para>
	-
	<sect3 id="term-dumb">
	<title>Dumb Terminals</title>

	- <para>Dumb terminals are specialized pieces of hardware that
	- let you connect to computers over serial lines. They are
	- called <quote>dumb</quote> because they have only enough
	- computational power to display, send, and receive text. You
	- cannot run any programs on them. It is the computer to
	- which you connect them that has all the power to run text
	+ <para>Dumb terminals are specialized hardware that connect to
	+ computers over serial lines. They are called
	+ <quote>dumb</quote> because they have only enough
	+ computational power to display, send, and receive text. No
	+ programs can be run on these devices. Dumb terminals
	+ connect to a computer that has all the power to run text
	editors, compilers, email, games, and so forth.</para>

	<para>There are hundreds of kinds of dumb terminals made by
	- many manufacturers, including Digital Equipment
	- Corporation's VT-100 and Wyse's WY-75. Just about any kind
	- will work with FreeBSD. Some high-end terminals can even
	- display graphics, but only certain software packages can
	- take advantage of these advanced features.</para>
	+ many manufacturers, and just about any kind will work with
	+ &os;. Some high-end terminals can even display graphics,
	+ but only certain software packages can take advantage of
	+ these advanced features.</para>

	<para>Dumb terminals are popular in work environments where
	- workers do not need access to graphical applications such as
	- those provided by the X Window System.</para>
	+ workers do not need access to graphical applications.</para>
	</sect3>

	<sect3 id="term-pcs">
	- <title>PCs Acting as Terminals</title>
	+ <title>Computers Acting as Terminals</title>

	<para>If a <link linkend="term-dumb">dumb terminal</link> has
	- just enough ability to display, send, and receive text, then
	- certainly any spare personal computer can be a dumb
	- terminal. All you need is the proper cable and some
	- <emphasis>terminal emulation</emphasis> software to run on
	- the computer.</para>
	+ just enough ability to display, send, and receive text,
	+ any spare computer can be a dumb terminal. All that is
	+ needed is the proper cable and some <emphasis>terminal
	+ emulation</emphasis> software to run on the
	+ computer.</para>

	- <para>Such a configuration is popular in homes. For example,
	- if your spouse is busy working on your FreeBSD system's
	- console, you can do some text-only work at the same time
	- from a less powerful personal computer hooked up as a
	- terminal to the FreeBSD system.</para>
	+ <para>This configuration can be useful. For example, if one
	+ user is busy working at the &os; system's console, another
	+ user can do some text-only work at the same time from a
	+ less powerful personal computer hooked up as a terminal to
	+ the &os; system.</para>

	<para>There are at least two utilities in the base-system of
	&os; that can be used to work through a serial connection:
	&man.cu.1; and &man.tip.1;.</para>

	<para>To connect from a client system that runs &os; to the
	- serial connection of another system, you can use:</para>
	+ serial connection of another system, use:</para>

	<screen>&prompt.root; <userinput>cu -l <replaceable>serial-port-device</replaceable></userinput></screen>

	<para>Where <quote>serial-port-device</quote> is the name of a
	- special device file denoting a serial port of your system.
	+ special device file denoting a serial port on the system.
	These device files are called
	<devicename>/dev/cuau<replaceable>N</replaceable></devicename>.</para>

	<para>The <quote>N</quote>-part of a device name is the serial
	port number.</para>

	<note>
	<para>Note that device numbers in &os; start from zero and
	- not one (like they do, for instance in &ms-dos;-derived
	- systems). This means that what &ms-dos;-based systems
	- call <devicename>COM1</devicename> is usually
	+ not one. This means that <devicename>COM1</devicename> is
	<filename>/dev/cuau0</filename> in &os;.</para>
	</note>

	<note>
	- <para>Some people prefer to use other programs, available
	- through the Ports Collection. The Ports include quite a
	- few utilities which can work in ways similar to &man.cu.1;
	- and &man.tip.1;, i.e., <filename
	+ <para>Some people prefer to use other programs available
	+ through the Ports Collection, such as <filename
	role="package">comms/minicom</filename>.</para>
	</note>
	</sect3>

	<sect3 id="term-x">
	<title>X Terminals</title>

	<para>X terminals are the most sophisticated kind of terminal
	available. Instead of connecting to a serial port, they
	usually connect to a network like Ethernet. Instead of
	being relegated to text-only applications, they can display
	any X application.</para>

	- <para>We introduce X terminals just for the sake of
	- completeness. However, this chapter does
	- <emphasis>not</emphasis> cover setup, configuration, or use
	- of X terminals.</para>
	+ <para>This chapter does <emphasis>not</emphasis> cover the
	+ setup, configuration, or use of X terminals.</para>
	</sect3>
	</sect2>

	<sect2 id="term-config">
	<title>Configuration</title>

	- <para>This section describes what you need to configure on your
	- FreeBSD system to enable a login session on a terminal. It
	- assumes you have already configured your kernel to support the
	- serial port to which the terminal is connected—and that
	- you have connected it.</para>
	+ <para>This section describes how to configure a &os; system to
	+ enable a login session on a terminal. It assumes that the
	+ kernel is configured to support the serial port to which the
	+ terminal is connected and that the terminal is
	+ connected.</para>

	- <para>Recall from <xref linkend="boot"/> that the
	- <command>init</command> process is responsible for all process
	- control and initialization at system startup. One of the
	- tasks performed by <command>init</command> is to read the
	- <filename>/etc/ttys</filename> file and start a
	+ <para>The <command>init</command> process is responsible for all
	+ process control and initialization at system startup. One of
	+ the tasks performed by <command>init</command> is to read
	+ <filename>/etc/ttys</filename> and start a
	<command>getty</command> process on the available terminals.
	The <command>getty</command> process is responsible for
	reading a login name and starting the <command>login</command>
	program.</para>

	- <para>Thus, to configure terminals for your FreeBSD system the
	- following steps should be taken as
	- <username>root</username>:</para>
	+ <para>To configure terminals for a &os; system, the following
	+ steps should be taken as <username>root</username>:</para>

	<procedure>
	<step>
	<para>Add a line to <filename>/etc/ttys</filename> for the
	- entry in the <filename>/dev</filename> directory for the
	- serial port if it is not already there.</para>
	+ entry in <filename class="directory">/dev</filename> for
	+ the serial port if it is not already there.</para>
	</step>

	<step>
	<para>Specify that <command>/usr/libexec/getty</command>
	be run on the port, and specify the appropriate
	- <replaceable>getty</replaceable> type from the
	- <filename>/etc/gettytab</filename> file.</para>
	+ <replaceable>getty</replaceable> type from
	+ <filename>/etc/gettytab</filename>.</para>
	</step>

	<step>
	<para>Specify the default terminal type.</para>
	</step>

	<step>
	<para>Set the port to <quote>on.</quote></para>
	</step>

	<step>
	<para>Specify whether the port should be
	<quote>secure.</quote></para>
	</step>

	<step>
	- <para>Force <command>init</command> to reread the
	- <filename>/etc/ttys</filename> file.</para>
	+ <para>Force <command>init</command> to reread
	+ <filename>/etc/ttys</filename>.</para>
	</step>
	</procedure>

	- <para>As an optional step, you may wish to create a custom
	+ <para>As an optional step, create a custom
	<replaceable>getty</replaceable> type for use in step 2 by
	- making an entry in <filename>/etc/gettytab</filename>. This
	- chapter does not explain how to do so; you are encouraged to
	- see the &man.gettytab.5; and the &man.getty.8; manual pages
	- for more information.</para>
	+ making an entry in <filename>/etc/gettytab</filename>. For
	+ more information, refer to &man.gettytab.5; and
	+ &man.getty.8;.</para>

	<sect3 id="term-etcttys">
	<title>Adding an Entry to
	<filename>/etc/ttys</filename></title>

	- <para>The <filename>/etc/ttys</filename> file lists all of the
	- ports on your FreeBSD system where you want to allow logins.
	- For example, the first virtual console
	- <devicename>ttyv0</devicename> has an entry in this file.
	- You can log in on the console using this entry. This
	- file also contains entries for the other virtual consoles,
	- serial ports, and pseudo-ttys. For a hardwired terminal,
	- just list the serial port's <filename>/dev</filename> entry
	- without the <filename>/dev</filename> part (for example,
	+ <para><filename>/etc/ttys</filename> lists all of the ports
	+ on the &os; system which allow logins. For example, the
	+ first virtual console,
	+ <devicename>ttyv0</devicename>, has an entry in this file,
	+ allowing logins on the console. This file also contains
	+ entries for the other virtual consoles, serial ports, and
	+ pseudo-ttys. For a hardwired terminal,
	+ list the serial port's <filename
	+ class="directory">/dev</filename> entry without the
	+ <literal>/dev</literal> part. For example,
	<filename>/dev/ttyv0</filename> would be listed as
	- <devicename>ttyv0</devicename>).</para>
	+ <literal>ttyv0</literal>.</para>

	- <para>A default FreeBSD install includes an
	- <filename>/etc/ttys</filename> file with support for the
	+ <para>A default &os; install includes an
	+ <filename>/etc/ttys</filename> with support for the
	first four serial ports: <devicename>ttyu0</devicename>
	- through <devicename>ttyu3</devicename>. If you are
	- attaching a terminal to one of those ports, you do not need
	- to add another entry.</para>
	+ through <devicename>ttyu3</devicename>. When
	+ attaching a terminal to one of those ports, this file does
	+ not need to be edited.</para>

	<example id="ex-etc-ttys">
	<title>Adding Terminal Entries to
	<filename>/etc/ttys</filename></title>

	- <para>Suppose we would like to connect two terminals to the
	- system: a Wyse-50 and an old 286 IBM PC running
	+ <para>This example configures two terminals: a Wyse-50 and
	+ an old 286 IBM PC running
	<application>Procomm</application> terminal software
	- emulating a VT-100 terminal. We connect the Wyse to the
	- second serial port and the 286 to the sixth serial port (a
	- port on a multiport serial card). The corresponding
	- entries in the <filename>/etc/ttys</filename> file would
	- look like this:</para>
	+ emulating a VT-100 terminal. The Wyse is connected to the
	+ second serial port and the 286 to the sixth serial port on
	+ a multiport serial card. The corresponding entries in
	+ <filename>/etc/ttys</filename> would look like
	+ this:</para>

	<programlisting>ttyu1<co
	id="co-ttys-line1col1"/> "/usr/libexec/getty std.38400"<co
	id="co-ttys-line1col2"/> wy50<co
	id="co-ttys-line1col3"/> on<co
	id="co-ttys-line1col4"/> insecure<co
	id="co-ttys-line1col5"/>
	ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting>

	<calloutlist>
	<callout arearefs="co-ttys-line1col1">
	<para>The first field normally specifies the name of
	the terminal special file as it is found in
	- <filename>/dev</filename>.</para>
	+ <filename class="directory">/dev</filename>.</para>
	</callout>

	<callout arearefs="co-ttys-line1col2">
	<para>The second field is the command to execute for
	this line, which is usually &man.getty.8;.
	<command>getty</command> initializes and opens the
	- line, sets the speed, prompts for a user name and then
	- executes the &man.login.1; program.</para>
	+ line, sets the speed, prompts for a user name, and
	+ then executes &man.login.1;.</para>

	<para>The <command>getty</command> program accepts one
	(optional) parameter on its command line, the
	<replaceable>getty</replaceable> type. A
	<replaceable>getty</replaceable> type configures
	- characteristics on the terminal line, like bps rate
	- and parity. The <command>getty</command> program
	- reads these characteristics from the file
	- <filename>/etc/gettytab</filename>.</para>
	+ characteristics on the terminal line, like
	+ <acronym>bps</acronym> rate and parity.
	+ <command>getty</command> reads these characteristics
	+ from <filename>/etc/gettytab</filename>.</para>

	- <para>The file <filename>/etc/gettytab</filename>
	- contains lots of entries for terminal lines both old
	- and new. In almost all cases, the entries that start
	- with the text <literal>std</literal> will work for
	- hardwired terminals. These entries ignore parity.
	- There is a <literal>std</literal> entry for each bps
	- rate from 110 to 115200. Of course, you can add your
	- own entries to this file. The &man.gettytab.5; manual
	- page provides more information.</para>
	+ <para><filename>/etc/gettytab</filename> contains many
	+ entries for terminal lines, both old and new. In
	+ almost all cases, the entries that start with the
	+ text <literal>std</literal> will work for hardwired
	+ terminals as these entries ignore parity. There is
	+ a <literal>std</literal> entry for each
	+ <acronym>bps</acronym> rate from 110 to 115200.
	+ &man.gettytab.5; provides more information.</para>

	<para>When setting the <replaceable>getty</replaceable>
	- type in the <filename>/etc/ttys</filename> file, make
	- sure that the communications settings on the terminal
	+ type in <filename>/etc/ttys</filename>, make sure
	+ that the communications settings on the terminal
	match.</para>

	- <para>For our example, the Wyse-50 uses no parity and
	+ <para>For this example, the Wyse-50 uses no parity and
	connects at 38400 bps. The 286 PC uses no
	parity and connects at 19200 bps.</para>
	</callout>

	<callout arearefs="co-ttys-line1col3">
	<para>The third field is the type of terminal usually
	- connected to that tty line. For dial-up ports,
	+ connected to that terminal line. For dial-up ports,
	<literal>unknown</literal> or
	- <literal>dialup</literal> is typically used in this
	- field since users may dial up with practically any
	- type of terminal or software. For hardwired
	- terminals, the terminal type does not change, so you
	- can put a real terminal type from the &man.termcap.5;
	- database file in this field.</para>
	+ <literal>dialup</literal> is typically used since
	+ users may dial up with practically any type of
	+ terminal or software. Since the terminal type does
	+ not change for hardwired terminals, a real terminal
	+ type from &man.termcap.5; can be used in this
	+ field.</para>

	- <para>For our example, the Wyse-50 uses the real
	+ <para>For this example, the Wyse-50 uses the real
	terminal type while the 286 PC running
	<application>Procomm</application> will be set to
	emulate at VT-100. </para>
	</callout>

	<callout arearefs="co-ttys-line1col4">
	<para>The fourth field specifies if the port should be
	- enabled. Putting <literal>on</literal> here will have
	- the <command>init</command> process start the program
	- in the second field, <command>getty</command>. If you
	- put <literal>off</literal> in this field, there will
	- be no <command>getty</command>, and hence no logins on
	- the port.</para>
	+ enabled. If set to <literal>on</literal>, the
	+ <command>init</command> process will start the program
	+ in the second field, <command>getty</command>. If
	+ this field is set to <literal>off</literal>, there
	+ will be no <command>getty</command>, and hence no
	+ logins on the port.</para>
	</callout>

	<callout arearefs="co-ttys-line1col5">
	<para>The final field is used to specify whether the
	- port is secure. Marking a port as secure means that
	- you trust it enough to allow the
	- <username>root</username> account (or any account with
	- a user ID of 0) to login from that port. Insecure
	- ports do not allow <username>root</username> logins.
	- On an insecure port, users must login from
	- unprivileged accounts and then use &man.su.1; or a
	- similar mechanism to gain superuser privileges.</para>
	+ port is secure. Marking a port as
	+ <literal>secure</literal> means that it is trusted
	+ enough to allow <username>root</username>, or any
	+ account with a <acronym>UID</acronym> of 0, to login
	+ from that port. Insecure ports do not allow
	+ <username>root</username> logins. On an insecure
	+ port, users must login from unprivileged accounts and
	+ then use &man.su.1; or a similar mechanism to gain
	+ superuser privileges.</para>

	- <para>It is highly recommended that you use
	- <quote>insecure</quote>
	- even for terminals that are behind locked doors. It
	- is quite easy to login and use <command>su</command>
	- if you need superuser privileges.</para>
	+ <para>It is highly recommended to use
	+ <literal>insecure</literal>, even for terminals that
	+ are behind locked doors. It is quite easy to login
	+ and use <command>su</command> when superuser
	+ privileges are needed.</para>
	</callout>
	</calloutlist>
	</example>
	</sect3>

	<sect3 id="term-hup">
	<title>Force <command>init</command> to Reread
	<filename>/etc/ttys</filename></title>

	- <para>After making the necessary changes to the
	- <filename>/etc/ttys</filename> file you should send a SIGHUP
	+ <para>After making any changes to
	+ <filename>/etc/ttys</filename>, send a SIGHUP
	(hangup) signal to the <command>init</command> process to
	- force it to re-read its configuration file. For
	- example:</para>
	+ force it to re-read its configuration file:</para>

	<screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen>

	<note>
	<para><command>init</command> is always the first process
	- run on a system, therefore it will always have PID
	- 1.</para>
	+ run on a system, therefore it will always have a process
	+ ID of 1.</para>
	</note>

	<para>If everything is set up correctly, all cables are in
	place, and the terminals are powered up, then a
	<command>getty</command> process should be running on each
	- terminal and you should see login prompts on your terminals
	- at this point.</para>
	+ terminal and login prompts should be available on each
	+ terminal.</para>
	</sect3>
	</sect2>

	<sect2 id="term-debug">
	- <title>Troubleshooting Your Connection</title>
	+ <title>Troubleshooting the Connection</title>

	<para>Even with the most meticulous attention to detail,
	something could still go wrong while setting up a terminal.
	- Here is a list of symptoms and some suggested fixes.</para>
	+ Here is a list of common symptoms and some suggested
	+ fixes.</para>

	<sect3>
	<title>No Login Prompt Appears</title>

	<para>Make sure the terminal is plugged in and powered up. If
	it is a personal computer acting as a terminal, make sure it
	is running terminal emulation software on the correct serial
	port.</para>

	<para>Make sure the cable is connected firmly to both the
	- terminal and the FreeBSD computer. Make sure it is the
	+ terminal and the &os; computer. Make sure it is the
	right kind of cable.</para>

	- <para>Make sure the terminal and FreeBSD agree on the bps rate
	- and parity settings. If you have a video display terminal,
	- make sure the contrast and brightness controls are turned
	- up. If it is a printing terminal, make sure paper and ink
	- are in good supply.</para>
	+ <para>Make sure the terminal and &os; agree on the
	+ <acronym>bps</acronym> rate and parity settings. For a
	+ video display terminal, make sure the contrast and
	+ brightness controls are turned up. If it is a printing
	+ terminal, make sure paper and ink are in good supply.</para>

	<para>Make sure that a <command>getty</command> process is
	running and serving the terminal. For example, to get a
	list of running <command>getty</command> processes with
	<command>ps</command>, type:</para>

	<screen>&prompt.root; <userinput>ps -axww\|grep getty</userinput></screen>

	- <para>You should see an entry for the terminal. For
	- example, the following display shows that a
	+ <para>There should be an entry for the terminal. For example,
	+ the following display shows that a
	<command>getty</command> is running on the second serial
	- port <devicename>ttyu1</devicename> and is using the
	+ port, <devicename>ttyu1</devicename>, and is using the
	<literal>std.38400</literal> entry in
	<filename>/etc/gettytab</filename>:</para>

	<screen>22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyu1</screen>

	<para>If no <command>getty</command> process is running, make
	- sure you have enabled the port in
	- <filename>/etc/ttys</filename>. Also remember to run
	- <command>kill -HUP 1</command> after modifying the
	- <filename>ttys</filename> file.</para>
	+ sure the port is enabled in
	+ <filename>/etc/ttys</filename>. Remember to run
	+ <command>kill -HUP 1</command> after modifying
	+ <filename>/etc/ttys</filename>.</para>

	<para>If the <command>getty</command> process is running
	but the terminal still does not display a login prompt,
	- or if it displays a prompt but will not allow you to
	- type, your terminal or cable may not support hardware
	- handshaking. Try changing the entry in
	- <filename>/etc/ttys</filename> from
	- <literal>std.38400</literal> to
	- <literal>3wire.38400</literal> (remember to run
	+ or if it displays a prompt but will not accept typed input,
	+ the terminal or cable may not support hardware handshaking.
	+ Try changing the entry in <filename>/etc/ttys</filename>
	+ from <literal>std.38400</literal> to
	+ <literal>3wire.38400</literal>, then run
	<command>kill -HUP 1</command> after modifying
	- <filename>/etc/ttys</filename>). The
	+ <filename>/etc/ttys</filename>. The
	<literal>3wire</literal> entry is similar to
	<literal>std</literal>, but ignores hardware
	- handshaking. You may need to reduce the baud rate or
	- enable software flow control when using
	- <literal>3wire</literal> to prevent buffer
	- overflows.</para>
	+ handshaking. The baud rate may need to be reduced or
	+ software flow control enabled when using
	+ <literal>3wire</literal> to prevent buffer overflows.</para>

	</sect3>

	<sect3>
	<title>If Garbage Appears Instead of a Login Prompt</title>

	- <para>Make sure the terminal and FreeBSD agree on the bps rate
	- and parity settings. Check the <command>getty</command>
	- processes to make sure the correct
	+ <para>Make sure the terminal and &os; agree on the
	+ <acronym>bps</acronym> rate and parity settings. Check the
	+ <command>getty</command> processes to make sure the correct
	<replaceable>getty</replaceable> type is in use. If not,
	edit <filename>/etc/ttys</filename> and run <command>kill
	-HUP 1</command>.</para>

	</sect3>

	<sect3>
	- <title>Characters Appear Doubled; the Password Appears When
	+ <title>Characters Appear Doubled and the Password Appears When
	Typed</title>

	- <para>Switch the terminal (or the terminal emulation software)
	+ <para>Switch the terminal, or the terminal emulation software,
	from <quote>half duplex</quote> or <quote>local echo</quote>
	to <quote>full duplex.</quote></para>

	</sect3>
	</sect2>
	</sect1>

	<sect1 id="dialup">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Guy</firstname>
	<surname>Helmer</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Sean</firstname>
	<surname>Kelly</surname>
	<contrib>Additions by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Dial-in Service</title>

	- <warning>
	- <para>As of &os; 8.0, device nodes for serial ports have been
	- renamed from
	- <filename>/dev/cuad<replaceable>N</replaceable></filename> to
	- <filename>/dev/cuau<replaceable>N</replaceable></filename> and
	- from
	- <filename>/dev/ttyd<replaceable>N</replaceable></filename> to
	- <filename>/dev/ttyu<replaceable>N</replaceable></filename>.
	- &os; 7.X users will have to adapt the following
	- documentation according to these changes.</para>
	- </warning>
	-
	<indexterm><primary>dial-in service</primary></indexterm>

	- <para>Configuring your FreeBSD system for dial-in service is very
	- similar to connecting terminals except that you are dealing with
	- modems instead of terminals.</para>
	+ <para>Configuring a &os; system for dial-in service is similar
	+ to connecting terminals except that modems are used instead of
	+ terminal devices.</para>

	<sect2>
	<title>External Versus Internal Modems</title>

	- <para>External modems seem to be more convenient for dial-up,
	- because external modems often can be semi-permanently
	- configured via parameters stored in non-volatile RAM and they
	- usually provide lighted indicators that display the state of
	- important RS-232 signals. Blinking lights impress visitors,
	- but lights are also very useful to see whether a modem is
	- operating properly.</para>
	+ <para>External modems are more convenient for dial-up because
	+ they often can be semi-permanently configured via parameters
	+ stored in non-volatile RAM and they usually provide lighted
	+ indicators that display the state of important RS-232 signals,
	+ indicating whether the modem is operating properly.</para>

	<para>Internal modems usually lack non-volatile RAM, so their
	- configuration may be limited only to setting DIP switches.
	- If your internal modem has any signal indicator lights, it is
	- probably difficult to view the lights when the system's cover
	- is in place.</para>
	+ configuration may be limited to setting DIP switches. If the
	+ internal modem has any signal indicator lights, they are
	+ difficult to view when the system's cover is in place.</para>

	<sect3>
	<title>Modems and Cables</title>

	<indexterm><primary>modem</primary></indexterm>

	- <para>If you are using an external modem, then you will of
	- course need the proper cable. A standard RS-232C serial
	- cable should suffice as long as all of the normal signals
	- are wired:</para>
	+ <para>When using an external modem, a proper cable is needed.
	+ A standard RS-232C serial cable should suffice as long as
	+ all of the normal signals are wired:</para>

	<table frame="none" pgwide="1" id="serialcomms-signal-names">
	<title>Signal Names</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry align="left">Acronyms</entry>
	<entry align="left">Names</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><acronym>RD</acronym></entry>
	<entry>Received Data</entry>
	</row>

	<row>
	<entry><acronym>TD</acronym></entry>
	<entry>Transmitted Data</entry>
	</row>

	<row>
	<entry><acronym>DTR</acronym></entry>
	<entry>Data Terminal Ready</entry>
	</row>

	<row>
	<entry><acronym>DSR</acronym></entry>
	<entry>Data Set Ready</entry>
	</row>

	<row>
	<entry><acronym>DCD</acronym></entry>
	<entry>Data Carrier Detect (RS-232's Received Line
	Signal Detector)</entry>
	</row>

	<row>
	<entry><acronym>SG</acronym></entry>
	<entry>Signal Ground</entry>
	</row>

	<row>
	<entry><acronym>RTS</acronym></entry>
	<entry>Request to Send</entry>
	</row>

	<row>
	<entry><acronym>CTS</acronym></entry>
	<entry>Clear to Send</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	- <para>FreeBSD needs the <acronym>RTS</acronym> and
	+ <para>&os; needs the <acronym>RTS</acronym> and
	<acronym>CTS</acronym> signals for flow control at speeds
	above 2400 bps, the <acronym>CD</acronym> signal to
	detect when a call has been answered or the line has been
	hung up, and the <acronym>DTR</acronym> signal to reset the
	modem after a session is complete. Some cables are wired
	- without all of the needed signals, so if you have problems,
	- such as a login session not going away when the line hangs
	- up, you may have a problem with your cable.</para>
	+ without all of the needed signals, so if a login session
	+ does not go away when the line hangs up, there may be a
	+ problem with the cable.</para>

	- <para>Like other &unix; like operating systems, FreeBSD uses
	+ <para>Like other &unix;-like operating systems, &os; uses
	the hardware signals to find out when a call has been
	answered or a line has been hung up and to hangup and reset
	- the modem after a call. FreeBSD avoids sending commands to
	- the modem or watching for status reports from the modem. If
	- you are familiar with connecting modems to PC-based bulletin
	- board systems, this may seem awkward.</para>
	+ the modem after a call. &os; avoids sending commands to
	+ the modem or watching for status reports from the
	+ modem.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Serial Interface Considerations</title>

	- <para>FreeBSD supports NS8250-, NS16450-, NS16550-, and
	+ <para>&os; supports the NS8250-, NS16450-, NS16550-, and
	NS16550A-based EIA RS-232C (CCITT V.24) communications
	interfaces. The 8250 and 16450 devices have single-character
	buffers. The 16550 device provides a 16-character buffer,
	- which allows for better system performance. (Bugs in plain
	+ which allows for better system performance. Bugs in plain
	16550's prevent the use of the 16-character buffer, so use
	- 16550A's if possible). Because single-character-buffer
	+ 16550A's if possible. Because single-character-buffer
	devices require more work by the operating system than the
	16-character-buffer devices, 16550A-based serial interface
	- cards are much preferred. If the system has many active serial
	+ cards are preferred. If the system has many active serial
	ports or will have a heavy load, 16550A-based cards are better
	for low-error-rate communications.</para>
	</sect2>

	<sect2>
	<title>Quick Overview</title>

	<indexterm><primary>getty</primary></indexterm>
	<para>As with terminals, <command>init</command> spawns a
	<command>getty</command> process for each configured serial
	port for dial-in connections. For example, if a modem is
	- attached to <filename>/dev/ttyu0</filename>, the command
	+ attached to <filename>/dev/ttyu0</filename>,
	<command>ps ax</command> might show this:</para>

	<screen> 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyu0</screen>

	<para>When a user dials the modem's line and the modems connect,
	- the <acronym>CD</acronym> (Carrier Detect) line is reported by
	- the modem. The kernel notices that carrier has been detected
	- and completes <command>getty</command>'s open of the port.
	- <command>getty</command> sends a <prompt>login:</prompt>
	- prompt at the specified initial line speed.
	- <command>getty</command> watches to see if legitimate
	+ the Carrier Detect (<acronym>CD</acronym>) line is reported by
	+ the modem. The kernel notices that the carrier has been
	+ detected and instructs <command>getty</command> to open the
	+ port. <command>getty</command> sends a
	+ <prompt>login:</prompt> prompt at the specified initial line
	+ speed. <command>getty</command> watches to see if legitimate
	characters are received, and, in a typical configuration, if
	it finds junk (probably due to the modem's connection speed
	being different than <command>getty</command>'s speed),
	<command>getty</command> tries adjusting the line speeds until
	it receives reasonable characters.</para>

	<indexterm>
	<primary><command>/usr/bin/login</command></primary>
	</indexterm>
	- <para>After the user enters his/her login name,
	+ <para>After the user enters their login name,
	<command>getty</command> executes
	<filename>/usr/bin/login</filename>, which completes the login
	by asking for the user's password and then starting the user's
	shell.</para>
	</sect2>


	<sect2>
	<title>Configuration Files</title>

	- <para>There are three system configuration files in the
	- <filename>/etc</filename> directory that you will probably
	- need to edit to allow dial-up access to your FreeBSD system.
	- The first, <filename>/etc/gettytab</filename>, contains
	- configuration information for the
	- <filename>/usr/libexec/getty</filename> daemon. Second,
	- <filename>/etc/ttys</filename> holds information that tells
	- <filename>/sbin/init</filename> what <filename>tty</filename>
	- devices should have <command>getty</command> processes running
	- on them. Lastly, you can place port initialization commands
	- in the <filename>/etc/rc.d/serial</filename> script.</para>
	+ <para>There are three system configuration files in
	+ <filename class="directory">/etc</filename> that probably
	+ need to be edited to allow dial-up access to the &os; system.
	+ <filename>/etc/gettytab</filename> contains configuration
	+ information for the <filename>/usr/libexec/getty</filename>
	+ daemon. <filename>/etc/ttys</filename> holds information that
	+ tells <command>init</command> which
	+ <devicename>tty</devicename>s should have
	+ <command>getty</command> processes running on them. Lastly,
	+ port initialization commands can be placed in
	+ <filename>/etc/rc.d/serial</filename>.</para>

	<para>There are two schools of thought regarding dial-up modems
	on &unix;. One group likes to configure their modems and
	systems so that no matter at what speed a remote user dials
	in, the local computer-to-modem RS-232 interface runs at a
	locked speed. The benefit of this configuration is that the
	remote user always sees a system login prompt immediately.
	The downside is that the system does not know what a user's
	true data rate is, so full-screen programs like
	<application>Emacs</application> will not adjust their
	screen-painting methods to make their response better for
	slower connections.</para>

	- <para>The other school configures their modems' RS-232 interface
	+ <para>The other group configures their modems' RS-232 interface
	to vary its speed based on the remote user's connection speed.
	For example, V.32bis (14.4 Kbps) connections to the modem
	might make the modem run its RS-232 interface at
	19.2 Kbps, while 2400 bps connections make the
	modem's RS-232 interface run at 2400 bps. Because
	<command>getty</command> does not understand any particular
	modem's connection speed reporting, <command>getty</command>
	gives a <prompt>login:</prompt> message at an initial speed
	and watches the characters that come back in response. If the
	user sees junk, it is assumed that they know they should press
	- the <keycap>Enter</keycap> key until they see a recognizable
	- prompt. If the data rates do not match,
	- <command>getty</command> sees anything the user types as
	- <quote>junk</quote>, tries going to the next speed and gives
	- the <prompt>login:</prompt> prompt again. This procedure can
	- continue ad nauseam, but normally only takes a keystroke
	- or two before the user sees a good prompt. Obviously, this
	- login sequence does not look as clean as the former
	- <quote>locked-speed</quote> method, but a user on a low-speed
	- connection should receive better interactive response from
	- full-screen programs.</para>
	+ <keycap>Enter</keycap> until they see a recognizable prompt.
	+ If the data rates do not match, <command>getty</command> sees
	+ anything the user types as <quote>junk</quote>, tries going to
	+ the next speed and gives the <prompt>login:</prompt> prompt
	+ again. This procedure normally only takes a keystroke or two
	+ before the user sees a good prompt. This login sequence does
	+ not look as clean as the <quote>locked-speed</quote> method,
	+ but a user on a low-speed connection should receive better
	+ interactive response from full-screen programs.</para>

	<para>This section will try to give balanced configuration
	information, but is biased towards having the modem's data
	rate follow the connection rate.</para>

	<sect3>
	<title><filename>/etc/gettytab</filename></title>

	<indexterm>
	<primary><filename>/etc/gettytab</filename></primary>
	</indexterm>
	<para><filename>/etc/gettytab</filename> is a
	&man.termcap.5;-style file of configuration information for
	- &man.getty.8;. Please see the &man.gettytab.5; manual page
	- for complete information on the format of the file and the
	- list of capabilities.</para>
	+ &man.getty.8;. Refer to &man.gettytab.5; for complete
	+ information on the format of the file and the list of
	+ capabilities.</para>

	<sect4>
	<title>Locked-speed Config</title>

	- <para>If you are locking your modem's data communications
	- rate at a particular speed, you probably will not need to
	- make any changes to
	- <filename>/etc/gettytab</filename>.</para>
	+ <para>When locking a modem's data communications rate at a
	+ particular speed, no changes to
	+ <filename>/etc/gettytab</filename> should be
	+ needed.</para>
	</sect4>

	<sect4>
	<title>Matching-speed Config</title>

	- <para>You will need to set up an entry in
	+ <para>Set up an entry in
	<filename>/etc/gettytab</filename> to give
	- <command>getty</command> information about the speeds you
	- wish to use for your modem. If you have a 2400 bps
	- modem, you can probably use the existing
	- <literal>D2400</literal> entry.</para>
	+ <command>getty</command> information about the speeds to
	+ use for the modem. For a 2400 bps modem, use the
	+ existing <literal>D2400</literal> entry.</para>

	<programlisting>#
	# Fast dialup terminals, 2400/1200/300 rotary (can start either way)
	#
	D2400\|d2400\|Fast-Dial-2400:\
	:nx=D1200:tc=2400-baud:
	3\|D1200\|Fast-Dial-1200:\
	:nx=D300:tc=1200-baud:
	5\|D300\|Fast-Dial-300:\
	:nx=D2400:tc=300-baud:</programlisting>

	- <para>If you have a higher speed modem, you will probably
	- need to add an entry in
	- <filename>/etc/gettytab</filename>; here is an entry you
	- could use for a 14.4 Kbps modem with a top interface
	- speed of 19.2 Kbps:</para>
	+ <para>For a higher speed modem, add an entry in
	+ <filename>/etc/gettytab</filename>. This entry is for a
	+ 14.4 Kbps modem with a top interface speed of
	+ 19.2 Kbps:</para>

	<programlisting>#
	# Additions for a V.32bis Modem
	#
	um\|V300\|High Speed Modem at 300,8-bit:\
	:nx=V19200:tc=std.300:
	un\|V1200\|High Speed Modem at 1200,8-bit:\
	:nx=V300:tc=std.1200:
	uo\|V2400\|High Speed Modem at 2400,8-bit:\
	:nx=V1200:tc=std.2400:
	up\|V9600\|High Speed Modem at 9600,8-bit:\
	:nx=V2400:tc=std.9600:
	uq\|V19200\|High Speed Modem at 19200,8-bit:\
	:nx=V9600:tc=std.19200:</programlisting>

	<para>This will result in 8-bit, no parity
	connections.</para>

	<para>The example above starts the communications rate at
	19.2 Kbps (for a V.32bis connection), then cycles
	through 9600 bps (for V.32), 2400 bps,
	1200 bps, 300 bps, and back to 19.2 Kbps.
	Communications rate cycling is implemented with the
	<literal>nx=</literal> (<quote>next table</quote>)
	capability. Each of the lines uses a
	<literal>tc=</literal> (<quote>table continuation</quote>)
	entry to pick up the rest of the <quote>standard</quote>
	settings for a particular data rate.</para>

	- <para>If you have a 28.8 Kbps modem and/or you want to
	- take advantage of compression on a 14.4 Kbps modem,
	- you need to use a higher communications rate than
	- 19.2 Kbps. Here is an example of a
	- <filename>gettytab</filename> entry starting a
	- 57.6 Kbps:</para>
	+ <para>For a 28.8 Kbps modem or to take advantage of
	+ compression on a 14.4 Kbps modem, use a higher
	+ communications rate than 19.2 Kbps. Here is an
	+ example of a <filename>gettytab</filename> entry starting
	+ a 57.6 Kbps:</para>

	<programlisting>#
	# Additions for a V.32bis or V.34 Modem
	# Starting at 57.6 Kbps
	#
	vm\|VH300\|Very High Speed Modem at 300,8-bit:\
	:nx=VH57600:tc=std.300:
	vn\|VH1200\|Very High Speed Modem at 1200,8-bit:\
	:nx=VH300:tc=std.1200:
	vo\|VH2400\|Very High Speed Modem at 2400,8-bit:\
	:nx=VH1200:tc=std.2400:
	vp\|VH9600\|Very High Speed Modem at 9600,8-bit:\
	:nx=VH2400:tc=std.9600:
	vq\|VH57600\|Very High Speed Modem at 57600,8-bit:\
	:nx=VH9600:tc=std.57600:</programlisting>

	- <para>If you have a slow CPU or a heavily loaded system and
	- do not have 16550A-based serial ports, you may receive
	+ <para>For a slow CPU or a heavily loaded system without
	+ 16550A-based serial ports, there may be
	<errorname>sio</errorname>
	<quote>silo</quote> errors at 57.6 Kbps.</para>
	</sect4>
	</sect3>

	<sect3 id="dialup-ttys">
	<title><filename>/etc/ttys</filename></title>

	<indexterm>
	<primary><filename>/etc/ttys</filename></primary>
	</indexterm>

	- <para>Configuration of the <filename>/etc/ttys</filename> file
	- was covered in <xref linkend="ex-etc-ttys"/>.
	- Configuration for modems is similar but we must pass a
	- different argument to <command>getty</command> and specify a
	- different terminal type. The general format for both
	- locked-speed and matching-speed configurations is:</para>
	+ <para>Configuration of <filename>/etc/ttys</filename>
	+ is covered in <link linkend="ex-etc-ttys"></link>.
	+ Configuration for modems is similar, but a different
	+ argument is passed to <command>getty</command> and a
	+ different terminal type is specified. The general format
	+ for both locked-speed and matching-speed configurations
	+ is:</para>

	<programlisting>ttyu0 "/usr/libexec/getty <replaceable>xxx</replaceable>" dialup on</programlisting>

	<para>The first item in the above line is the device special
	- file for this entry — <devicename>ttyu0</devicename>
	- means <filename>/dev/ttyu0</filename> is the file that this
	- <command>getty</command> will be watching. The second item,
	- <literal>"/usr/libexec/getty
	- <replaceable>xxx</replaceable>"</literal>
	- (<replaceable>xxx</replaceable> will be replaced by the
	- initial <filename>gettytab</filename> capability) is the
	- process <command>init</command> will run on the device. The
	- third item, <literal>dialup</literal>, is the default
	- terminal type. The fourth parameter, <literal>on</literal>,
	+ file for this entry. <literal>ttyu0</literal> indicates
	+ that <command>getty</command> is watching
	+ <devicename>/dev/ttyu0</devicename>. The
	+ <replaceable>xxx</replaceable> will replace the initial
	+ <filename>gettytab</filename> capability and is the process
	+ <command>init</command> will run on the device. The third
	+ item, <literal>dialup</literal>, is the default terminal
	+ type. The fourth parameter, <literal>on</literal>,
	indicates to <command>init</command> that the line is
	operational. There can be a fifth parameter,
	<literal>secure</literal>, but it should only be used for
	- terminals which are physically secure (such as the system
	- console).</para>
	+ terminals which are physically secure, such as the system
	+ console.</para>

	- <para>The default terminal type (<literal>dialup</literal> in
	- the example above) may depend on local preferences.
	+ <para>The default terminal type, <literal>dialup</literal> in
	+ this example, may depend on local preferences.
	<literal>dialup</literal> is the traditional default
	terminal type on dial-up lines so that users may customize
	their login scripts to notice when the terminal is
	<literal>dialup</literal> and automatically adjust their
	- terminal type. However, the author finds it easier at his
	- site to specify <literal>vt102</literal> as the default
	- terminal type, since the users just use VT102 emulation on
	+ terminal type. Setting <literal>vt102</literal> as the
	+ default terminal type allows users to use VT102 emulation on
	their remote systems.</para>

	- <para>After you have made changes to
	- <filename>/etc/ttys</filename>, you may send the
	+ <para>After editing <filename>/etc/ttys</filename>, send the
	<command>init</command> process a <acronym>HUP</acronym>
	- signal to re-read the file. You can use the command
	+ signal to re-read the file:</para>

	<screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen>

	- to send the signal. If this is your first time setting up
	- the system, you may want to wait until your modem(s) are
	- properly configured and connected before signaling
	- <command>init</command>.</para>
	+ <para>Wait until the modem is properly configured and
	+ connected before signaling <command>init</command>.</para>

	<sect4>
	<title>Locked-speed Config</title>

	- <para>For a locked-speed configuration, your
	+ <para>For a locked-speed configuration, the
	<filename>ttys</filename> entry needs to have a
	fixed-speed entry provided to <command>getty</command>.
	For a modem whose port speed is locked at 19.2 Kbps,
	the <filename>ttys</filename> entry might look like
	this:</para>

	<programlisting>ttyu0 "/usr/libexec/getty std.19200" dialup on</programlisting>

	- <para>If your modem is locked at a different data rate,
	+ <para>If the modem is locked at a different data rate,
	substitute the appropriate value for
	<literal>std.<replaceable>speed</replaceable></literal>
	- instead of <literal>std.19200</literal>. Make sure that
	- you use a valid type listed in
	+ instead of <literal>std.19200</literal>. Make sure to use
	+ a valid type listed in
	<filename>/etc/gettytab</filename>.</para>
	</sect4>

	<sect4>
	<title>Matching-speed Config</title>

	- <para>In a matching-speed configuration, your
	+ <para>In a matching-speed configuration, the
	<filename>ttys</filename> entry needs to reference the
	- appropriate beginning <quote>auto-baud</quote> (sic) entry
	- in <filename>/etc/gettytab</filename>. For example, if
	- you added the above suggested entry for a matching-speed
	- modem that starts at 19.2 Kbps (the
	- <filename>gettytab</filename> entry containing the
	- <literal>V19200</literal> starting point), your
	- <filename>ttys</filename> entry might look like
	+ appropriate beginning <quote>auto-baud</quote> entry
	+ in <filename>/etc/gettytab</filename>. For example, for
	+ the above suggested entry for a matching-speed modem that
	+ starts at 19.2 Kbps, the
	+ <filename>/etc/ttys</filename> entry might look like
	this:</para>

	<programlisting>ttyu0 "/usr/libexec/getty V19200" dialup on</programlisting>
	</sect4>
	</sect3>

	<sect3>
	<title><filename>/etc/rc.d/serial</filename></title>

	<indexterm>
	<primary>rc files</primary>
	<secondary><filename>rc.serial</filename></secondary>
	</indexterm>

	<para>High-speed modems, like V.32, V.32bis, and V.34 modems,
	need to use hardware (<literal>RTS/CTS</literal>) flow
	- control. You can add <command>stty</command> commands to
	- <filename>/etc/rc.d/serial</filename> to set the hardware
	- flow control flag in the FreeBSD kernel for the modem
	+ control. <command>stty</command> can be used to set the
	+ hardware flow control flag in the &os; kernel for the modem
	ports.</para>

	- <para>For example to set the <literal>termios</literal> flag
	- <varname>crtscts</varname> on serial port #1's
	- (<devicename>COM2</devicename>) dial-in and dial-out
	+ <para>For example, to set the <literal>termios</literal> flag
	+ <varname>crtscts</varname> on
	+ <devicename>COM2</devicename>'s dial-in and dial-out
	initialization devices, the following lines could be added
	to <filename>/etc/rc.d/serial</filename>:</para>
	+
	<programlisting># Serial port initial configuration
	stty -f /dev/ttyu1.init crtscts
	stty -f /dev/cuau1.init crtscts</programlisting>

	</sect3>
	</sect2>

	<sect2>
	<title>Modem Settings</title>

	- <para>If you have a modem whose parameters may be permanently
	- set in non-volatile RAM, you will need to use a terminal
	- program (such as <application>Telix</application> under
	- &ms-dos; or <command>tip</command> under FreeBSD) to set the
	- parameters. Connect to the modem using the same
	- communications speed as the initial speed
	- <command>getty</command> will use and configure the modem's
	- non-volatile RAM to match these requirements:</para>
	+ <para>For a modem whose parameters may be permanently set in
	+ non-volatile RAM, a terminal program such as
	+ <command>tip</command> can be used to set the parameters.
	+ Connect to the modem using the same communications speed as
	+ the initial speed <command>getty</command> will use and
	+ configure the modem's non-volatile RAM to match these
	+ requirements:</para>

	<itemizedlist>
	<listitem>
	- <para><acronym>CD</acronym> asserted when connected</para>
	+ <para><acronym>CD</acronym> asserted when connected.</para>
	</listitem>

	<listitem>
	- <para><acronym>DTR</acronym> asserted for operation;
	- dropping DTR hangs up line and resets modem</para>
	+ <para><acronym>DTR</acronym> asserted for operation and
	+ dropping DTR hangs up the line and resets the
	+ modem.</para>
	</listitem>

	<listitem>
	<para><acronym>CTS</acronym> transmitted data flow
	- control</para>
	+ control.</para>
	</listitem>

	<listitem>
	<para>Disable <acronym>XON/XOFF</acronym> flow
	- control</para>
	+ control.</para>
	</listitem>

	<listitem>
	<para><acronym>RTS</acronym> received data flow
	- control</para>
	+ control.</para>
	</listitem>

	<listitem>
	- <para>Quiet mode (no result codes)</para>
	+ <para>Quiet mode (no result codes).</para>
	</listitem>

	<listitem>
	- <para>No command echo</para>
	+ <para>No command echo.</para>
	</listitem>
	</itemizedlist>

	- <para>Please read the documentation for your modem to find out
	- what commands and/or DIP switch settings you need to give
	- it.</para>
	+ <para>Read the documentation for the modem to find out
	+ which commands and/or DIP switch settings are needed.</para>

	<para>For example, to set the above parameters on a &usrobotics;
	- &sportster; 14,400 external modem, one could give these
	- commands to the modem:</para>
	+ &sportster; 14,400 external modem, give these commands to
	+ the modem:</para>

	<programlisting>ATZ
	AT&C1&D2&H1&I0&R2&W</programlisting>

	- <para>You might also want to take this opportunity to adjust
	- other settings in the modem, such as whether it will use
	- V.42bis and/or MNP5 compression.</para>
	+ <para>Other settings can be adjusted in the modem, such as
	+ whether it will use V.42bis and/or MNP5 compression.</para>

	<para>The &usrobotics; &sportster; 14,400 external modem also
	- has some DIP switches that need to be set; for other modems,
	- perhaps you can use these settings as an example:</para>
	+ has some DIP switches that need to be set. Other modems,
	+ may need these settings:</para>

	<itemizedlist>
	<listitem>
	<para>Switch 1: UP — DTR Normal</para>
	</listitem>

	<listitem>
	<para>Switch 2: N/A (Verbal Result Codes/Numeric Result
	Codes)</para>
	</listitem>

	<listitem>
	<para>Switch 3: UP — Suppress Result Codes</para>
	</listitem>

	<listitem>
	<para>Switch 4: DOWN — No echo, offline
	commands</para>
	</listitem>

	<listitem>
	<para>Switch 5: UP — Auto Answer</para>
	</listitem>

	<listitem>
	<para>Switch 6: UP — Carrier Detect Normal</para>
	</listitem>

	<listitem>
	<para>Switch 7: UP — Load NVRAM Defaults</para>
	</listitem>

	<listitem>
	<para>Switch 8: N/A (Smart Mode/Dumb Mode)</para>
	</listitem>
	</itemizedlist>

	<para>Result codes should be disabled/suppressed for dial-up
	modems to avoid problems that can occur if
	<command>getty</command> mistakenly gives a
	<prompt>login:</prompt> prompt to a modem that is in command
	mode and the modem echoes the command or returns a result
	- code. This sequence can result in a extended, silly
	+ code. This sequence can result in an extended, silly
	conversation between <command>getty</command> and the
	modem.</para>

	<sect3>
	<title>Locked-speed Config</title>

	- <para>For a locked-speed configuration, you will need to
	- configure the modem to maintain a constant modem-to-computer
	- data rate independent of the communications rate. On a
	- &usrobotics; &sportster; 14,400 external modem, these
	- commands will lock the modem-to-computer data rate at the
	- speed used to issue the commands:</para>
	+ <para>For a locked-speed configuration, configure the modem to
	+ maintain a constant modem-to-computer data rate independent
	+ of the communications rate. On a &usrobotics; &sportster;
	+ 14,400 external modem, these commands will lock the
	+ modem-to-computer data rate at the speed used to issue the
	+ commands:</para>

	<programlisting>ATZ
	AT&B1&W</programlisting>
	</sect3>

	<sect3>
	<title>Matching-speed Config</title>

	- <para>For a variable-speed configuration, you will need to
	- configure your modem to adjust its serial port data rate to
	- match the incoming call rate. On a &usrobotics; &sportster;
	- 14,400 external modem, these commands will lock the modem's
	- error-corrected data rate to the speed used to issue the
	- commands, but allow the serial port rate to vary for
	+ <para>For a variable-speed configuration, configure the modem
	+ to adjust its serial port data rate to match the incoming
	+ call rate. On a &usrobotics; &sportster; 14,400 external
	+ modem, these commands will lock the modem's error-corrected
	+ data rate to the speed used to issue the commands, while
	+ allowing the serial port rate to vary for
	non-error-corrected connections:</para>

	<programlisting>ATZ
	AT&B2&W</programlisting>
	</sect3>

	<sect3>
	<title>Checking the Modem's Configuration</title>

	<para>Most high-speed modems provide commands to view the
	modem's current operating parameters in a somewhat
	human-readable fashion. On the &usrobotics; &sportster;
	- 14,400 external modems, the command
	- <command>ATI5</command> displays the settings that are
	- stored in the non-volatile RAM. To see the true operating
	- parameters of the modem (as influenced by the modem's DIP
	- switch settings), use the commands <command>ATZ</command>
	+ 14,400 external modem, <command>ATI5</command> displays the
	+ settings that are stored in the non-volatile RAM. To see
	+ the true operating parameters of the modem, as influenced by
	+ the modem's DIP switch settings, use <command>ATZ</command>
	and then <command>ATI4</command>.</para>

	- <para>If you have a different brand of modem, check your
	- modem's manual to see how to double-check your modem's
	- configuration parameters.</para>
	+ <para>For a different brand of modem, check the modem's manual
	+ to see how to double-check the modem's configuration
	+ parameters.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Troubleshooting</title>

	- <para>Here are a few steps you can follow to check out the
	- dial-up modem on your system.</para>
	+ <para>Here are a few steps for troubleshooting a dial-up modem
	+ on a &os; system.</para>

	<sect3>
	- <title>Checking Out the FreeBSD System</title>
	+ <title>Checking Out the &os; System</title>

	- <para>Hook up your modem to your FreeBSD system, boot the
	- system, and, if your modem has status indication lights,
	+ <para>Hook up the modem to the &os; system, boot the
	+ system, and, if the modem has status indication lights,
	watch to see whether the modem's <acronym>DTR</acronym>
	indicator lights when the <prompt>login:</prompt> prompt
	- appears on the system's console — if it lights up,
	- that should mean that FreeBSD has started a
	+ appears on the system's console. If it lights up, that
	+ should mean that &os; has started a
	<command>getty</command> process on the appropriate
	communications port and is waiting for the modem to accept a
	call.</para>

	<para>If the <acronym>DTR</acronym> indicator does not light,
	- login to the FreeBSD system through the console and issue a
	- <command>ps ax</command> to see if FreeBSD is trying to run
	- a <command>getty</command> process on the correct port. You
	- should see lines like these among the processes
	- displayed:</para>
	+ login to the &os; system through the console and type
	+ <command>ps ax</command> to see if &os; is trying to run
	+ a <command>getty</command> process on the correct
	+ port:</para>

	<screen> 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyu0
	115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyu1</screen>

	- <para>If you see something different, like this:</para>
	+ <para>If something like this is displayed instead:</para>

	<screen> 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyu0</screen>

	<para>and the modem has not accepted a call yet, this means
	that <command>getty</command> has completed its open on the
	communications port. This could indicate a problem with the
	- cabling or a mis-configured modem, because
	+ cabling or a misconfigured modem, because
	<command>getty</command> should not be able to open the
	- communications port until <acronym>CD</acronym> (carrier
	- detect) has been asserted by the modem.</para>
	+ communications port until carrier detect has been asserted
	+ by the modem.</para>

	- <para>If you do not see any <command>getty</command> processes
	- waiting to open the desired
	+ <para>If no <command>getty</command> processes are waiting to
	+ open the desired
	<devicename>ttyu<replaceable>N</replaceable></devicename>
	- port, double-check your entries in
	+ port, double-check the entries in
	<filename>/etc/ttys</filename> to see if there are any
	- mistakes there. Also, check the log file
	+ mistakes. Also, check
	<filename>/var/log/messages</filename> to see if there are
	any log messages from <command>init</command> or
	- <command>getty</command> regarding any problems. If there
	- are any messages, triple-check the configuration files
	- <filename>/etc/ttys</filename> and
	+ <command>getty</command>. If there are any messages,
	+ triple-check <filename>/etc/ttys</filename> and
	<filename>/etc/gettytab</filename>, as well as the
	- appropriate device special files
	+ appropriate device special files,
	<filename>/dev/ttyuN</filename>, for any mistakes, missing
	entries, or missing device special files.</para>
	</sect3>

	<sect3>
	<title>Try Dialing In</title>

	- <para>Try dialing into the system; be sure to use 8 bits, no
	- parity, and 1 stop bit on the remote system. If you do not
	- get a prompt right away, or get garbage, try pressing
	- <keycap>Enter</keycap> about once per second. If you still
	- do not see a <prompt>login:</prompt> prompt after a while,
	- try sending a <command>BREAK</command>. If you are using a
	- high-speed modem to do the dialing, try dialing again after
	- locking the dialing modem's interface speed (via
	- <command>AT&B1</command> on a &usrobotics; &sportster;
	- modem, for example).</para>
	+ <para>Try dialing into the system. Be sure to use 8 bits, no
	+ parity, and 1 stop bit on the remote system. If a prompt
	+ does not appear right away, or the prompt shows garbage, try
	+ pressing <keycap>Enter</keycap> about once per second. If
	+ there is still no <prompt>login:</prompt> prompt after a
	+ while, try sending a <command>BREAK</command>. When using a
	+ high-speed modem, try dialing again after locking the
	+ dialing modem's interface speed.</para>

	- <para>If you still cannot get a <prompt>login:</prompt>
	+ <para>If there is still no <prompt>login:</prompt>
	prompt, check <filename>/etc/gettytab</filename> again and
	- double-check that</para>
	+ double-check that:</para>

	<itemizedlist>
	<listitem>
	- <para>The initial capability name specified in
	- <filename>/etc/ttys</filename> for the line matches a
	- name of a capability in
	- <filename>/etc/gettytab</filename></para>
	+ <para>The initial capability name specified in the entry
	+ in <filename>/etc/ttys</filename> matches the name of
	+ a capability in
	+ <filename>/etc/gettytab</filename>.</para>
	</listitem>

	<listitem>
	<para>Each <literal>nx=</literal> entry matches another
	- <filename>gettytab</filename> capability name</para>
	+ <filename>gettytab</filename> capability name.</para>
	</listitem>

	<listitem>
	<para>Each <literal>tc=</literal> entry matches another
	- <filename>gettytab</filename> capability name</para>
	+ <filename>gettytab</filename> capability name.</para>
	</listitem>
	</itemizedlist>

	- <para>If you dial but the modem on the FreeBSD system will not
	- answer, make sure that the modem is configured to answer the
	- phone when <acronym>DTR</acronym> is asserted. If the modem
	- seems to be configured correctly, verify that the
	+ <para>If the modem on the &os; system will not answer, make
	+ sure that the modem is configured to answer the phone when
	+ <acronym>DTR</acronym> is asserted. If the modem seems to
	+ be configured correctly, verify that the
	<acronym>DTR</acronym> line is asserted by checking the
	- modem's indicator lights (if it has any).</para>
	+ modem's indicator lights.</para>

	- <para>If you have gone over everything several times and it
	- still does not work, take a break and come back to it later.
	- If it still does not work, perhaps you can send an
	- electronic mail message to the &a.questions; describing your
	- modem and your problem, and the good folks on the list will
	- try to help.</para>
	+ <para>If it still does not work, take a break and come back to
	+ it later. If it still does not work, try sending an
	+ email message to the &a.questions; describing the modem
	+ and the problem.</para>
	</sect3>
	</sect2>

	</sect1>

	<sect1 id="dialout">
	<title>Dial-out Service</title>

	- <warning>
	- <para>As of &os; 8.0, device nodes for serial ports have been
	- renamed from
	- <filename>/dev/cuad<replaceable>N</replaceable></filename> to
	- <filename>/dev/cuau<replaceable>N</replaceable></filename>.
	- &os; 7.X users will have to adapt the following
	- documentation according to these changes.</para>
	- </warning>
	-
	<indexterm><primary>dial-out service</primary></indexterm>

	- <para>The following are tips for getting your host to be able to
	- connect over the modem to another computer. This is appropriate
	- for establishing a terminal session with a remote host.</para>
	+ <para>The following are tips for getting the host to connect over
	+ the modem to another computer. This is appropriate for
	+ establishing a terminal session with a remote host.</para>

	- <para>This is useful to log onto a BBS.</para>
	+ <para>This kind of connection can be helpful to get a file on the
	+ Internet if there are problems using PPP. If PPP is not
	+ working, use the terminal session to FTP the needed file. Then
	+ use zmodem to transfer it to the machine.</para>

	- <para>This kind of connection can be extremely helpful to get a
	- file on the Internet if you have problems with PPP. If you need
	- to FTP something and PPP is broken, use the terminal session to
	- FTP it. Then use zmodem to transfer it to your machine.</para>
	-
	<sect2 id="hayes-unsupported">
	- <title>My Stock Hayes Modem Is Not Supported, What Can I
	- Do?</title>
	+ <title>Using a Stock Hayes Modem</title>

	- <para>Actually, the manual page for <command>tip</command> is
	- out of date. There is a generic Hayes dialer already built
	- in. Just use <literal>at=hayes</literal> in your
	- <filename>/etc/remote</filename> file.</para>
	+ <para>A generic Hayes dialer is built into
	+ <command>tip</command>. Use <literal>at=hayes</literal> in
	+ <filename>/etc/remote</filename>.</para>

	<para>The Hayes driver is not smart enough to recognize some of
	- the advanced features of newer modems—messages like
	+ the advanced features of newer modems messages like
	<literal>BUSY</literal>, <literal>NO DIALTONE</literal>, or
	- <literal>CONNECT 115200</literal> will just confuse it. You
	- should turn those messages off when you use
	- <command>tip</command> (using
	- <command>ATX0&W</command>).</para>
	+ <literal>CONNECT 115200</literal>. Turn those messages off
	+ when using <command>tip</command> with
	+ <command>ATX0&W</command>.</para>

	- <para>Also, the dial timeout for <command>tip</command> is 60
	- seconds. Your modem should use something less, or else tip
	- will think there is a communication problem. Try
	- <command>ATS7=45&W</command>.</para>
	+ <para>The dial timeout for <command>tip</command> is 60
	+ seconds. The modem should use something less, or else
	+ <command>tip</command> will think there is a communication
	+ problem. Try <command>ATS7=45&W</command>.</para>
	</sect2>

	<sect2 id="direct-at">
	- <title>How Am I Expected to Enter These <literal>AT</literal>
	- Commands?</title>
	+ <title>Using <literal>AT</literal> Commands</title>

	<indexterm>
	<primary><filename>/etc/remote</filename></primary>
	</indexterm>
	- <para>Make what is called a <quote>direct</quote> entry in your
	- <filename>/etc/remote</filename> file. For example, if your
	+ <para>Create a <quote>direct</quote> entry in
	+ <filename>/etc/remote</filename>. For example, if the
	modem is hooked up to the first serial port,
	- <filename>/dev/cuau0</filename>, then put in the following
	+ <filename>/dev/cuau0</filename>, use the following
	line:</para>

	<programlisting>cuau0:dv=/dev/cuau0:br#19200:pa=none</programlisting>

	- <para>Use the highest bps rate your modem supports in the br
	- capability. Then, type <command>tip cuau0</command> and you
	- will be connected to your modem.</para>
	+ <para>Use the highest <acronym>bps</acronym> rate the modem
	+ supports in the <literal>br</literal> capability. Then, type
	+ <command>tip cuau0</command> to connect to the modem.</para>

	- <para>Or use <command>cu</command> as <username>root</username>
	+ <para>Or, use <command>cu</command> as <username>root</username>
	with the following command:</para>

	<screen>&prompt.root; <userinput>cu -l<replaceable>line</replaceable> -s<replaceable>speed</replaceable></userinput></screen>

	- <para><replaceable>line</replaceable> is the serial port
	- (e.g., <filename>/dev/cuau0</filename>) and
	- <replaceable>speed</replaceable> is the speed (e.g.,
	- <literal>57600</literal>). When you are done entering the AT
	- commands type <command>~.</command> to exit.</para>
	+ <para><replaceable>line</replaceable> is the serial port, such
	+ as <filename>/dev/cuau0</filename>, and
	+ <replaceable>speed</replaceable> is the speed, such as
	+ <literal>57600</literal>. When finished entering the AT
	+ commands, type <command>~.</command> to exit.</para>
	</sect2>

	<sect2 id="gt-failure">
	- <title>The <literal>@</literal> Sign for the pn Capability Does
	- Not Work!</title>
	+ <title>The <literal>@</literal> Sign Does Not Work</title>

	<para>The <literal>@</literal> sign in the phone number
	- capability tells tip to look in
	- <filename>/etc/phones</filename> for a phone number. But the
	+ capability tells <command>tip</command> to look in
	+ <filename>/etc/phones</filename> for a phone number. But, the
	<literal>@</literal> sign is also a special character in
	- capability files like <filename>/etc/remote</filename>.
	- Escape it with a backslash:</para>
	+ capability files like <filename>/etc/remote</filename>, so it
	+ needs to be escaped with a backslash:</para>

	<programlisting>pn=\@</programlisting>
	</sect2>

	<sect2 id="dial-command-line">
	- <title>How Can I Dial a Phone Number on the Command
	- Line?</title>
	+ <title>Dialing from the Command Line</title>

	- <para>Put what is called a <quote>generic</quote> entry in your
	- <filename>/etc/remote</filename> file. For example:</para>
	+ <para>Put a <quote>generic</quote> entry in
	+ <filename>/etc/remote</filename>. For example:</para>

	<programlisting>tip115200\|Dial any phone number at 115200 bps:\
	:dv=/dev/cuau0:br#115200:at=hayes:pa=none:du:
	tip57600\|Dial any phone number at 57600 bps:\
	:dv=/dev/cuau0:br#57600:at=hayes:pa=none:du:</programlisting>

	- <para>Then you can do things like:</para>
	+ <para>This should now work:</para>

	<screen>&prompt.root; <userinput>tip -115200 5551234</userinput></screen>

	- <para>If you prefer <command>cu</command> over
	- <command>tip</command>, use a generic <literal>cu</literal>
	- entry:</para>
	+ <para>Users who prefer <command>cu</command> over
	+ <command>tip</command>, can use a generic
	+ <literal>cu</literal> entry:</para>

	<programlisting>cu115200\|Use cu to dial any number at 115200bps:\
	:dv=/dev/cuau1:br#57600:at=hayes:pa=none:du:</programlisting>

	<para>and type:</para>

	<screen>&prompt.root; <userinput>cu 5551234 -s 115200</userinput></screen>
	</sect2>

	<sect2 id="set-bps">
	- <title>Do I Have to Type in the bps Rate Every Time I Do
	- That?</title>
	+ <title>Setting the <acronym>bps</acronym> Rate</title>

	<para>Put in an entry for <literal>tip1200</literal> or
	- <literal>cu1200</literal>, but go ahead and use whatever bps
	- rate is appropriate with the br capability.
	+ <literal>cu1200</literal>, but go ahead and use whatever
	+ <acronym>bps</acronym> rate is appropriate with the
	+ <literal>br</literal> capability.
	<command>tip</command> thinks a good default is 1200 bps
	which is why it looks for a <literal>tip1200</literal> entry.
	- You do not have to use 1200 bps, though.</para>
	+ 1200 bps does not have to be used, though.</para>
	</sect2>

	<sect2 id="terminal-server">
	- <title>I Access a Number of Hosts Through a Terminal
	+ <title>Accessing a Number of Hosts Through a Terminal
	Server</title>

	- <para>Rather than waiting until you are connected and typing
	+ <para>Rather than waiting until connected and typing
	<command>CONNECT <replaceable>host</replaceable></command>
	- each time, use tip's <literal>cm</literal> capability. For
	- example, these entries in
	- <filename>/etc/remote</filename>:</para>
	+ each time, use <command>tip</command>'s <literal>cm</literal>
	+ capability. For example, these entries in
	+ <filename>/etc/remote</filename> will let you type
	+ <command>tip pain</command> or
	+ <command>tip muffin</command> to connect to the hosts
	+ <hostid>pain</hostid> or <hostid>muffin</hostid>, and
	+ <command>tip deep13</command> to connect to the terminal
	+ server.</para>

	<programlisting>pain\|pain.deep13.com\|Forrester's machine:\
	:cm=CONNECT pain\n:tc=deep13:
	muffin\|muffin.deep13.com\|Frank's machine:\
	:cm=CONNECT muffin\n:tc=deep13:
	deep13:Gizmonics Institute terminal server:\
	:dv=/dev/cuau2:br#38400:at=hayes:du:pa=none:pn=5551234:</programlisting>

	- <para>will let you type <command>tip pain</command> or
	- <command>tip muffin</command> to connect to the hosts
	- <hostid>pain</hostid> or <hostid>muffin</hostid>, and
	- <command>tip deep13</command> to get to the terminal
	- server.</para>
	</sect2>

	<sect2 id="tip-multiline">
	- <title>Can Tip Try More Than One Line for Each Site?</title>
	+ <title>Using More Than One Line with
	+ <command>tip</command></title>

	<para>This is often a problem where a university has several
	modem lines and several thousand students trying to use
	them.</para>

	- <para>Make an entry for your university in
	- <filename>/etc/remote</filename> and use <literal>@</literal>
	- for the <literal>pn</literal> capability:</para>
	+ <para>Make an entry in <filename>/etc/remote</filename> and use
	+ <literal>@</literal> for the <literal>pn</literal>
	+ capability:</para>

	<programlisting>big-university:\
	:pn=\@:tc=dialout
	dialout:\
	:dv=/dev/cuau3:br#9600:at=courier:du:pa=none:</programlisting>

	- <para>Then, list the phone numbers for the university in
	+ <para>Then, list the phone numbers in
	<filename>/etc/phones</filename>:</para>

	<programlisting>big-university 5551111
	big-university 5551112
	big-university 5551113
	big-university 5551114</programlisting>

	- <para><command>tip</command> will try each one in the listed
	- order, then give up. If you want to keep retrying, run
	- <command>tip</command> in a while loop.</para>
	+ <para><command>tip</command> will try each number in the listed
	+ order, then give up. To keep retrying, run
	+ <command>tip</command> in a <literal>while</literal>
	+ loop.</para>
	</sect2>

	<sect2 id="multi-controlp">
	- <title>Why Do I Have to Hit
	- <keycombo action="simul">
	+ <title>Using the Force Character</title>
	+
	+ <para><keycombo action="simul">
	<keycap>Ctrl</keycap>
	<keycap>P</keycap>
	- </keycombo>
	- Twice to Send
	- <keycombo action="simul">
	- <keycap>Ctrl</keycap>
	- <keycap>P</keycap>
	- </keycombo>
	- Once?</title>
	+ </keycombo> is the default <quote>force</quote> character,
	+ used to tell <command>tip</command> that the next character is
	+ literal data. The force character can be set to any other
	+ character with the <command>~s</command> escape, which means
	+ <quote>set a variable.</quote></para>

	- <para><keycombo
	- action="simul"><keycap>Ctrl</keycap><keycap>P</keycap></keycombo>
	- is the default <quote>force</quote> character, used to tell
	- <command>tip</command> that the next character is literal
	- data. You can set the force character to any other character
	- with the <command>~s</command> escape, which means <quote>set
	- a variable.</quote></para>
	-
	<para>Type
	<command>~sforce=<replaceable>single-char</replaceable></command>
	followed by a newline. <replaceable>single-char</replaceable>
	- is any single character. If you leave out
	- <replaceable>single-char</replaceable>, then the force
	- character is the nul character, which you can get by typing
	+ is any single character. If
	+ <replaceable>single-char</replaceable> is left out, then the
	+ force character is the null character, which is accessed by
	+ typing
	<keycombo action="simul">
	<keycap>Ctrl</keycap><keycap>2</keycap>
	</keycombo>
	or <keycombo action="simul">
	<keycap>Ctrl</keycap><keycap>Space</keycap>
	</keycombo>. A pretty good value for
	<replaceable>single-char</replaceable> is
	<keycombo action="simul">
	<keycap>Shift</keycap>
	<keycap>Ctrl</keycap>
	<keycap>6</keycap>
	</keycombo>, which is only used on some terminal
	servers.</para>

	- <para>You can have the force character be whatever you want by
	- specifying the following in your
	- <filename>$HOME/.tiprc</filename> file:</para>
	+ <para>To change the force character, specify the following in
	+ <filename>~/.tiprc</filename>:</para>

	<programlisting>force=<replaceable>single-char</replaceable></programlisting>
	</sect2>

	<sect2 id="uppercase">
	- <title>Suddenly Everything I Type Is in Upper Case??</title>
	+ <title>Upper Case Characters</title>

	- <para>You must have pressed
	+ <para>This happens when
	<keycombo action="simul">
	<keycap>Ctrl</keycap>
	<keycap>A</keycap>
	- </keycombo>, <command>tip</command>'s
	- <quote>raise character,</quote> specially designed for people
	- with broken caps-lock keys. Use <command>~s</command> as
	- above and set the variable <literal>raisechar</literal> to
	- something reasonable. In fact, you can set it to the same as
	- the force character, if you never expect to use either of
	- these features.</para>
	+ </keycombo> is pressed, which is <command>tip</command>'s
	+ <quote>raise character</quote>, specially designed for people
	+ with broken caps-lock keys. Use <command>~s</command> to set
	+ <literal>raisechar</literal> to something reasonable. It can
	+ be set to be the same as the force character, if neither
	+ feature is used.</para>

	- <para>Here is a sample <filename>.tiprc</filename> file perfect
	- for <application>Emacs</application> users who need to type
	+ <para>Here is a sample <filename>~/.tiprc</filename> for
	+ <application>Emacs</application> users who need to type
	<keycombo action="simul">
	<keycap>Ctrl</keycap>
	<keycap>2</keycap>
	</keycombo> and <keycombo action="simul">
	<keycap>Ctrl</keycap>
	<keycap>A</keycap>
	- </keycombo> a lot:</para>
	+ </keycombo>:</para>

	<programlisting>force=^^
	raisechar=^^</programlisting>

	<para>The <literal>^^</literal> is
	<keycombo action="simul">
	<keycap>Shift</keycap><keycap>Ctrl</keycap><keycap>6</keycap>
	</keycombo>.</para>

	</sect2>

	<sect2 id="tip-filetransfer">
	- <title>How Can I Do File Transfers with
	- <command>tip</command>?</title>
	+ <title>File Transfers with <command>tip</command></title>

	- <para>If you are talking to another &unix; system, you can send
	- and receive files with <command>~p</command> (put) and
	- <command>~t</command> (take). These commands run
	+ <para>When talking to another &unix;-like operating system,
	+ files can be sent and received using <command>~p</command>
	+ (put) and <command>~t</command> (take). These commands run
	<command>cat</command> and <command>echo</command> on the
	remote system to accept and send files. The syntax is:</para>

	<cmdsynopsis>
	<command>~p</command>
	<arg choice="plain">local-file</arg>
	<arg choice="opt">remote-file</arg>
	</cmdsynopsis>

	<cmdsynopsis>
	<command>~t</command>
	<arg choice="plain">remote-file</arg>
	<arg choice="opt">local-file</arg>
	</cmdsynopsis>

	- <para>There is no error checking, so you probably should use
	- another protocol, like zmodem.</para>
	+ <para>There is no error checking, so another protocol, like
	+ zmodem, should probably be used.</para>
	</sect2>

	<sect2 id="zmodem-tip">
	- <title>How Can I Run <application>zmodem</application> with
	+ <title>Using <application>zmodem</application> with
	<command>tip</command>?</title>

	<para>To receive files, start the sending program on the remote
	end. Then, type <command>~C rz</command> to begin receiving
	them locally.</para>

	<para>To send files, start the receiving program on the remote
	end. Then, type <command>~C sz
	<replaceable>files</replaceable></command> to send them to the
	remote system.</para>
	</sect2>
	</sect1>

	<sect1 id="serialconsole-setup">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Kazutaka</firstname>
	<surname>YOKOTA</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<authorgroup>
	<author>
	<firstname>Bill</firstname>
	<surname>Paul</surname>
	<contrib>Based on a document by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Setting Up the Serial Console</title>

	- <warning>
	- <para>As of &os; 8.0, device nodes for serial ports have been
	- renamed from
	- <filename>/dev/ttyd<replaceable>N</replaceable></filename> to
	- <filename>/dev/ttyu<replaceable>N</replaceable></filename>.
	- &os; 7.X users will have to adapt the following
	- documentation according to these changes.</para>
	- </warning>
	-
	<indexterm><primary>serial console</primary></indexterm>

	<sect2 id="serialconsole-intro">
	<title>Introduction</title>

	- <para>FreeBSD has the ability to boot on a system with only
	- a dumb terminal on a serial port as a console. Such a
	- configuration should be useful for two classes of people:
	- system administrators who wish to install FreeBSD on machines
	- that have no keyboard or monitor attached, and developers who
	- want to debug the kernel or device drivers.</para>
	+ <para>&os; has the ability to boot a system with a dumb
	+ terminal on a serial port as a console. This configuration is
	+ useful for system administrators who wish to install &os; on
	+ machines that have no keyboard or monitor attached, and
	+ developers who want to debug the kernel or device
	+ drivers.</para>

	- <para>As described in <xref linkend="boot"/>, FreeBSD employs a
	- three stage bootstrap. The first two stages are in the boot
	- block code which is stored at the beginning of the FreeBSD
	- slice on the boot disk. The boot block will then load and run
	- the boot loader (<filename>/boot/loader</filename>) as the
	- third stage code.</para>
	+ <para>As described in <link linkend="boot"></link>, &os; employs
	+ a three stage bootstrap. The first two stages are in the boot
	+ block code which is stored at the beginning of the &os;
	+ slice on the boot disk. The boot block then loads and runs
	+ the boot loader as the third stage code.</para>

	- <para>In order to set up the serial console you must configure
	- the boot block code, the boot loader code and the
	- kernel.</para>
	+ <para>In order to set up booting from a serial console, the
	+ boot block code, the boot loader code, and the kernel need to
	+ be configured.</para>

	</sect2>

	<sect2 id="serialconsole-howto-fast">
	- <title>Serial Console Configuration, Terse Version</title>
	+ <title>Quick Serial Console Configuration</title>

	- <para>This section assumes that you are using the default setup
	- and just want a fast overview of setting up the serial
	- console.</para>
	+ <para>This section assumes the default setup and provides a fast
	+ overview of setting up the serial console.</para>

	<procedure>

	<step>
	<para>Connect the serial cable to
	<devicename>COM1</devicename> and the controlling
	terminal.</para>
	</step>

	<step>
	- <para>To see all boot messages on the serial console, issue
	- the following command while logged in as the
	- superuser:</para>
	+ <para>To see all the boot messages on the serial console,
	+ issue the following command as the superuser:</para>
	+
	<screen>&prompt.root; echo 'console="comconsole"' >> /boot/loader.conf</screen>
	</step>

	<step>
	<para>Edit <filename>/etc/ttys</filename> and change
	<literal>off</literal> to <literal>on</literal> and
	<literal>dialup</literal> to <literal>vt100</literal> for
	- the <devicename>ttyu0</devicename> entry. Otherwise a
	+ the <devicename>ttyu0</devicename> entry. Otherwise, a
	password will not be required to connect via the serial
	console, resulting in a potential security hole.</para>
	</step>

	<step>
	<para>Reboot the system to see if the changes took
	effect.</para>
	</step>

	</procedure>

	- <para>If a different configuration is required, a more in depth
	- configuration explanation exists in
	- <xref linkend="serialconsole-howto"/>.</para>
	+ <para>If a different configuration is required, see the next
	+ section for a more in-depth configuration explanation.</para>
	</sect2>

	<sect2 id="serialconsole-howto">
	- <title>Serial Console Configuration</title>
	+ <title>In-Depth Serial Console Configuration</title>

	<procedure>
	<step>
	<para>Prepare a serial cable.</para>

	<indexterm><primary>null-modem cable</primary></indexterm>
	- <para>You will need either a null-modem cable or a standard
	- serial cable and a null-modem adapter. See <xref
	- linkend="serial-cables-ports"/> for a discussion on
	- serial cables.</para>
	+
	+ <para>Use either a null-modem cable or a standard serial
	+ cable and a null-modem adapter. See <link
	+ linkend="serial-cables-ports"></link> for a discussion
	+ on serial cables.</para>
	</step>

	<step>
	- <para>Unplug your keyboard.</para>
	+ <para>Unplug the keyboard.</para>

	- <para>Most PC systems probe for the keyboard during the
	- Power-On Self-Test (POST) and will generate an error if
	- the keyboard is not detected. Some machines complain
	- loudly about the lack of a keyboard and will not continue
	- to boot until it is plugged in.</para>
	+ <para>Many PC systems probe for the keyboard during the
	+ Power-On Self-Test (<acronym>POST</acronym>) and will
	+ generate an error if the keyboard is not detected. Some
	+ machines will refuse to boot until the keyboard is plugged
	+ in.</para>

	- <para>If your computer complains about the error, but boots
	- anyway, then you do not have to do anything special.
	- (Some machines with Phoenix BIOS installed merely say
	- <errorname>Keyboard failed</errorname> and continue to
	- boot normally.)</para>
	+ <para>If the computer complains about the error, but boots
	+ anyway, no further configuration is needed.</para>

	- <para>If your computer refuses to boot without a keyboard
	- attached then you will have to configure the BIOS so that
	- it ignores this error (if it can). Consult your
	- motherboard's manual for details on how to do this.</para>
	+ <para>If the computer refuses to boot without a keyboard
	+ attached, the BIOS needs to be configured so that it
	+ ignores this error (if it can). Consult the motherboard's
	+ manual for details on how to do this.</para>

	<tip>
	- <para>Set the keyboard to <quote>Not installed</quote> in
	- the BIOS setup. You will still be able to use your
	- keyboard. All this does is tell the BIOS not to probe
	- for a keyboard at power-on. Your BIOS should not
	+ <para>Try setting the keyboard to <quote>Not
	+ installed</quote> in the BIOS. The keyboard can still
	+ be used as this setting just tells the BIOS not to probe
	+ for a keyboard at power-on. The BIOS should not
	complain if the keyboard is absent. You can leave the
	keyboard plugged in even with this flag set to
	<quote>Not installed</quote> and the keyboard will still
	work. If the above option is not present in the BIOS,
	look for an <quote>Halt on Error</quote> option instead.
	Setting this to <quote>All but Keyboard</quote> or even
	to <quote>No Errors</quote>, will have the same
	effect.</para>
	</tip>

	<note>
	- <para>If your system has a &ps2; mouse, chances are very
	- good that you may have to unplug your mouse as well as
	- your keyboard. This is because &ps2; mice share some
	- hardware with the keyboard and leaving the mouse plugged
	- in can fool the keyboard probe into thinking the
	- keyboard is still there. It is said that a Gateway 2000
	- Pentium 90 MHz system with an AMI BIOS that behaves
	- this way. In general, this is not a problem since the
	- mouse is not much good without the keyboard
	- anyway.</para>
	+ <para>If the system has a &ps2; mouse, chances are good
	+ that both the mouse and keyboard need to be unplugged.
	+ This is because &ps2; mice share some hardware with the
	+ keyboard and leaving the mouse plugged in can fool the
	+ keyboard probe into thinking the keyboard is still
	+ there.</para>
	</note>
	</step>

	<step>
	<para>Plug a dumb terminal into
	<devicename>COM1</devicename>
	(<devicename>sio0</devicename>).</para>

	- <para>If you do not have a dumb terminal, you can use an old
	- PC/XT with a modem program, or the serial port on another
	- &unix; box. If you do not have a
	+ <para>If a dumb terminal is not available, use an old
	+ computer with a modem program, or the serial port on
	+ another &unix; box. If there is no
	<devicename>COM1</devicename>
	(<devicename>sio0</devicename>), get one. At this time,
	there is no way to select a port other than
	<devicename>COM1</devicename> for the boot blocks without
	- recompiling the boot blocks. If you are already using
	- <devicename>COM1</devicename> for another device, you will
	- have to temporarily remove that device and install a new
	- boot block and kernel once you get FreeBSD up and running.
	- (It is assumed that <devicename>COM1</devicename> will
	- be available on a file/compute/terminal server anyway; if
	- you really need <devicename>COM1</devicename> for
	- something else (and you cannot switch that something else
	- to <devicename>COM2</devicename>
	- (<devicename>sio1</devicename>)), then you probably should
	- not even be bothering with all this in the first
	- place.)</para>
	+ recompiling the boot blocks. If
	+ <devicename>COM1</devicename> is being used by another
	+ device, temporarily remove that device and install a new
	+ boot block and kernel once &os; is up and running.</para>
	</step>

	<step>
	- <para>Make sure the configuration file of your kernel has
	- appropriate flags set for <devicename>COM1</devicename>
	+ <para>Make sure the configuration file of the custom kernel
	+ has appropriate flags set for
	+ <devicename>COM1</devicename>
	(<devicename>sio0</devicename>).</para>

	<para>Relevant flags are:</para>

	<variablelist>
	<varlistentry>
	<term><literal>0x10</literal></term>

	<listitem>
	<para>Enables console support for this unit. The
	other console flags are ignored unless this is set.
	Currently, at most one unit can have console
	- support; the first one (in config file order) with
	+ support. The first one, in config file order, with
	this flag set is preferred. This option alone will
	not make the serial port the console. Set the
	- following flag or use the <option>-h</option> option
	+ following flag or use <option>-h</option> as
	described below, together with this flag.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>0x20</literal></term>

	<listitem>
	- <para>Forces this unit to be the console (unless there
	- is another higher priority console), regardless of
	- the <option>-h</option> option discussed below.
	- The flag <literal>0x20</literal> must be used
	- together with the <option>0x10</option> flag.</para>
	+ <para>Forces this unit to be the console, unless there
	+ is another higher priority console, regardless of
	+ <option>-h</option> as discussed below. The flag
	+ <literal>0x20</literal> must be used together with
	+ the <option>0x10</option> flag.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>0x40</literal></term>

	<listitem>
	<para>Reserves this unit (in conjunction with
	<literal>0x10</literal>) and makes the unit
	- unavailable for normal access. You should not set
	- this flag to the serial port unit which you want to
	- use as the serial console. The only use of this
	- flag is to designate the unit for kernel remote
	- debugging. See <ulink
	- url="&url.books.developers-handbook;/index.html">The
	+ unavailable for normal access. This flag should
	+ not be set to the serial port to use as the serial
	+ console. The only use of this flag is to designate
	+ the unit for kernel remote debugging. See <ulink
	+ url="&url.books.developers-handbook;/index.html">The
	Developer's Handbook</ulink> for more information on
	remote debugging.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	- <para>Example:</para>
	+ <para>Here is an example setting:</para>

	<programlisting>device sio0 flags 0x10</programlisting>

	- <para>See the &man.sio.4; manual page for more
	- details.</para>
	+ <para>Refer to &man.sio.4; for more details.</para>

	- <para>If the flags were not set, you need to run UserConfig
	- (on a different console) or recompile the kernel.</para>
	+ <para>If the flags were not set, run UserConfig on a
	+ different console or recompile the kernel.</para>
	</step>

	<step>
	<para>Create <filename>boot.config</filename> in the root
	directory of the <literal>a</literal> partition on the
	boot drive.</para>

	- <para>This file will instruct the boot block code how you
	- would like to boot the system. In order to activate the
	- serial console, you need one or more of the following
	- options—if you want multiple options, include them
	- all on the same line:</para>
	+ <para>This file instructs the boot block code how to boot
	+ the system. In order to activate the serial console,
	+ one or more of the following options are needed. When
	+ using multiple options, include them all on the same
	+ line:</para>

	<variablelist>
	<varlistentry>
	<term><option>-h</option></term>

	<listitem>
	- <para>Toggles internal and serial consoles. You can
	- use this to switch console devices. For instance,
	- if you boot from the internal (video) console, you
	- can use <option>-h</option> to direct the boot
	- loader and the kernel to use the serial port as its
	- console device. Alternatively, if you boot from the
	- serial port, you can use the <option>-h</option> to
	- tell the boot loader and the kernel to use the video
	- display as the console instead.</para>
	+ <para>Toggles between the internal and serial
	+ consoles. Use this to switch console devices. For
	+ instance, to boot from the internal (video) console,
	+ use <option>-h</option> to direct the boot loader
	+ and the kernel to use the serial port as its console
	+ device. Alternatively, to boot from the serial
	+ port, use <option>-h</option> to tell the boot
	+ loader and the kernel to use the video display as
	+ the console instead.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-D</option></term>

	<listitem>
	- <para>Toggles single and dual console configurations.
	- In the single configuration the console will be
	- either the internal console (video display) or the
	- serial port, depending on the state of the
	- <option>-h</option> option above. In the dual
	- console configuration, both the video display and
	- the serial port will become the console at the same
	- time, regardless of the state of the
	- <option>-h</option> option. However, note that the
	- dual console configuration takes effect only during
	- the boot block is running. Once the boot loader
	- gets control, the console specified by the
	- <option>-h</option> option becomes the only
	+ <para>Toggles between the single and dual console
	+ configurations. In the single configuration, the
	+ console will be either the internal console (video
	+ display) or the serial port, depending on the state
	+ of <option>-h</option>. In the dual console
	+ configuration, both the video display and the
	+ serial port will become the console at the same
	+ time, regardless of the state of
	+ <option>-h</option>. However, the dual console
	+ configuration takes effect only while the boot
	+ block is running. Once the boot loader gets
	+ control, the console specified by
	+ <option>-h</option> becomes the only
	console.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-P</option></term>

	<listitem>
	<para>Makes the boot block probe the keyboard. If no
	keyboard is found, the <option>-D</option> and
	<option>-h</option> options are automatically
	set.</para>

	<note>
	<para>Due to space constraints in the current
	- version of the boot blocks, the
	- <option>-P</option> option is capable of
	- detecting extended keyboards only. Keyboards with
	- less than 101 keys (and without F11 and F12 keys)
	- may not be detected. Keyboards on some laptop
	- computers may not be properly found because of
	- this limitation. If this is the case with your
	- system, you have to abandon using the
	- <option>-P</option> option. Unfortunately there
	- is no workaround for this problem.</para>
	+ version of the boot blocks,
	+ <option>-P</option> is capable of detecting
	+ extended keyboards only. Keyboards with less
	+ than 101 keys and without F11 and F12 keys may
	+ not be detected. Keyboards on some laptops
	+ may not be properly found because of this
	+ limitation. If this is the case, do not use
	+ <option>-P</option>. Unfortunately there is no
	+ workaround for this problem.</para>
	</note>
	</listitem>
	</varlistentry>
	</variablelist>

	- <para>Use either the <option>-P</option> option to select
	- the console automatically, or the <option>-h</option>
	- option to activate the serial console.</para>
	+ <para>Use either <option>-P</option> to select the
	+ console automatically, or <option>-h</option> to
	+ activate the serial console.</para>

	- <para>You may include other options described in
	- &man.boot.8; as well.</para>
	+ <para>Other options are described in &man.boot.8;.</para>

	- <para>The options, except for <option>-P</option>, will be
	- passed to the boot loader
	- (<filename>/boot/loader</filename>). The boot loader will
	- determine which of the internal video or the serial port
	- should become the console by examining the state of the
	- <option>-h</option> option alone. This means that if you
	- specify the <option>-D</option> option but not the
	- <option>-h</option> option in
	- <filename>/boot.config</filename>, you can use the
	- serial port as the console only during the boot block;
	- the boot loader will use the internal video display as the
	+ <para>The options, except for <option>-P</option>, are
	+ passed to the boot loader. The boot loader will
	+ determine whether the internal video or the serial port
	+ should become the console by examining the state of
	+ <option>-h</option>. This means that if
	+ <option>-D</option> is specified but
	+ <option>-h</option> is not specified in
	+ <filename>/boot.config</filename>, the serial port can
	+ be used as the console only during the boot block as the
	+ boot loader will use the internal video display as the
	console.</para>
	</step>

	<step>
	<para>Boot the machine.</para>

	- <para>When you start your FreeBSD box, the boot blocks will
	- echo the contents of <filename>/boot.config</filename> to
	- the console. For example:</para>
	+ <para>When &os; starts, the boot blocks echo the contents of
	+ <filename>/boot.config</filename> to the console. For
	+ example:</para>

	<screen>/boot.config: -P
	Keyboard: no</screen>

	- <para>The second line appears only if you put
	- <option>-P</option> in <filename>/boot.config</filename>
	- and indicates presence/absence of the keyboard. These
	- messages go to either serial or internal console, or both,
	+ <para>The second line appears only if <option>-P</option> is
	+ in <filename>/boot.config</filename> and indicates the
	+ presence or absence of the keyboard. These messages go
	+ to either the serial or internal console, or both,
	depending on the option in
	<filename>/boot.config</filename>.</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry align="left">Options</entry>
	<entry align="left">Message goes to</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>none</entry>
	<entry>internal console</entry>
	</row>

	<row>
	<entry><option>-h</option></entry>
	<entry>serial console</entry>
	</row>

	<row>
	<entry><option>-D</option></entry>
	<entry>serial and internal consoles</entry>
	</row>

	<row>
	<entry><option>-Dh</option></entry>
	<entry>serial and internal consoles</entry>
	</row>

	<row>
	<entry><option>-P</option>, keyboard present</entry>
	<entry>internal console</entry>
	</row>

	<row>
	<entry><option>-P</option>, keyboard absent</entry>
	<entry>serial console</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	- <para>After the above messages, there will be a small pause
	- before the boot blocks continue loading the boot loader
	- and before any further messages printed to the console.
	- Under normal circumstances, you do not need to interrupt
	- the boot blocks, but you may want to do so in order to
	- make sure things are set up correctly.</para>
	+ <para>After the message, there will be a small pause before
	+ the boot blocks continue loading the boot loader and
	+ before any further messages are printed to the console.
	+ Under normal circumstances, there is no need to interrupt
	+ the boot blocks, but one can do so in order to make sure
	+ things are set up correctly.</para>

	- <para>Hit any key, other than <keycap>Enter</keycap>, at the
	- console to interrupt the boot process. The boot blocks
	- will then prompt you for further action. You should now
	- see something like:</para>
	+ <para>Press any key, other than <keycap>Enter</keycap>, at
	+ the console to interrupt the boot process. The boot
	+ blocks will then prompt for further action:</para>

	<screen>>> FreeBSD/i386 BOOT
	Default: 0:ad(0,a)/boot/loader
	boot:</screen>

	- <para>Verify the above message appears on either the serial
	- or internal console or both, according to the options you
	- put in <filename>/boot.config</filename>. If the message
	- appears in the correct console, hit <keycap>Enter</keycap>
	- to continue the boot process.</para>
	+ <para>Verify that the above message appears on either the
	+ serial or internal console, or both, according to the
	+ options in <filename>/boot.config</filename>. If the
	+ message appears in the correct console, press
	+ <keycap>Enter</keycap> to continue the boot
	+ process.</para>

	- <para>If you want the serial console but you do not see the
	- prompt on the serial terminal, something is wrong with
	- your settings. In the meantime, you enter
	- <option>-h</option> and hit <keycap>Enter</keycap> or
	- <keycap>Return</keycap> (if possible) to tell the boot
	- block (and then the boot loader and the kernel) to choose
	- the serial port for the console. Once the system is up,
	- go back and check what went wrong.</para>
	+ <para>If there is no prompt on the serial terminal,
	+ something is wrong with the settings. Enter
	+ <option>-h</option> then <keycap>Enter</keycap> or
	+ <keycap>Return</keycap> to tell the boot block (and then
	+ the boot loader and the kernel) to choose the serial port
	+ for the console. Once the system is up, go back and check
	+ what went wrong.</para>
	</step>
	</procedure>

	- <para>After the boot loader is loaded and you are in the third
	- stage of the boot process you can still switch between the
	- internal console and the serial console by setting appropriate
	- environment variables in the boot loader. See <xref
	- linkend="serialconsole-loader"/>.</para>
	+ <para>During the third stage of the boot process, one can still
	+ switch between the internal console and the serial console by
	+ setting appropriate environment variables in the boot loader.
	+ See <link linkend="serialconsole-loader"></link> for more
	+ information.</para>
	</sect2>

	<sect2 id="serialconsole-summary">
	<title>Summary</title>

	- <para>Here is the summary of various settings discussed in this
	- section and the console eventually selected.</para>
	+ <para>Here is the summary of the various settings discussed in
	+ this section:</para>

	<sect3>
	- <title>Case 1: You Set the Flags to 0x10 for
	+ <title>Case 1: Set the Flags to 0x10 for
	<devicename>sio0</devicename></title>

	<programlisting>device sio0 flags 0x10</programlisting>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="4">
	<thead>
	<row>
	<entry align="left">Options in /boot.config</entry>
	<entry align="left">Console during boot blocks</entry>
	<entry align="left">Console during boot loader</entry>
	<entry align="left">Console in kernel</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>nothing</entry>
	<entry>internal</entry>
	<entry>internal</entry>
	<entry>internal</entry>
	</row>

	<row>
	<entry><option>-h</option></entry>
	<entry>serial</entry>
	<entry>serial</entry>
	<entry>serial</entry>
	</row>

	<row>
	<entry><option>-D</option></entry>
	<entry>serial and internal</entry>
	<entry>internal</entry>
	<entry>internal</entry>
	</row>

	<row>
	<entry><option>-Dh</option></entry>
	<entry>serial and internal</entry>
	<entry>serial</entry>
	<entry>serial</entry>
	</row>

	<row>
	<entry><option>-P</option>, keyboard present</entry>
	<entry>internal</entry>
	<entry>internal</entry>
	<entry>internal</entry>
	</row>

	<row>
	<entry><option>-P</option>, keyboard absent</entry>
	<entry>serial and internal</entry>
	<entry>serial</entry>
	<entry>serial</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</sect3>

	<sect3>
	- <title>Case 2: You Set the Flags to 0x30 for
	+ <title>Case 2: Set the Flags to 0x30 for
	<devicename>sio0</devicename></title>

	<programlisting>device sio0 flags 0x30</programlisting>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="4">
	<thead>
	<row>
	<entry align="left">Options in /boot.config</entry>
	<entry align="left">Console during boot blocks</entry>
	<entry align="left">Console during boot loader</entry>
	<entry align="left">Console in kernel</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>nothing</entry>
	<entry>internal</entry>
	<entry>internal</entry>
	<entry>serial</entry>
	</row>

	<row>
	<entry><option>-h</option></entry>
	<entry>serial</entry>
	<entry>serial</entry>
	<entry>serial</entry>
	</row>

	<row>
	<entry><option>-D</option></entry>
	<entry>serial and internal</entry>
	<entry>internal</entry>
	<entry>serial</entry>
	</row>

	<row>
	<entry><option>-Dh</option></entry>
	<entry>serial and internal</entry>
	<entry>serial</entry>
	<entry>serial</entry>
	</row>

	<row>
	<entry><option>-P</option>, keyboard present</entry>
	<entry>internal</entry>
	<entry>internal</entry>
	<entry>serial</entry>
	</row>

	<row>
	<entry><option>-P</option>, keyboard absent</entry>
	<entry>serial and internal</entry>
	<entry>serial</entry>
	<entry>serial</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</sect3>
	</sect2>

	<sect2 id="serialconsole-tips">
	<title>Tips for the Serial Console</title>

	<sect3>
	<title>Setting a Faster Serial Port Speed</title>

	- <para>By default, the serial port settings are: 9600 baud, 8
	- bits, no parity, and 1 stop bit. If you wish to change the
	- default console speed, you have the following
	- options:</para>
	+ <para>By default, the serial port settings are 9600 baud, 8
	+ bits, no parity, and 1 stop bit. To change the default
	+ console speed, the following options are available:</para>

	<itemizedlist>
	<listitem>
	- <para>Recompile the boot blocks
	- with <makevar>BOOT_COMCONSOLE_SPEED</makevar> set to the
	- new console speed. See <xref
	- linkend="serialconsole-com2"/> for detailed
	+ <para>Recompile the boot blocks with
	+ <makevar>BOOT_COMCONSOLE_SPEED</makevar> set to the
	+ new console speed. See <link
	+ linkend="serialconsole-com2"></link> for detailed
	instructions about building and installing new boot
	blocks.</para>

	<para>If the serial console is configured in some other
	way than by booting with <option>-h</option>, or if the
	serial console used by the kernel is different from the
	- one used by the boot blocks, then you must also add the
	- following option to the kernel configuration file and
	- compile a new kernel:</para>
	+ one used by the boot blocks, add the following option
	+ to a custom kernel configuration file and compile a
	+ new kernel:</para>

	<programlisting>options CONSPEED=19200</programlisting>
	</listitem>

	<listitem>
	- <para>Use the <option>-S</option> boot option of the
	- kernel. The <option>-S</option> command line option can
	- be added to <filename>/boot.config</filename>. See the
	- &man.boot.8; manual page for a description of how to add
	- options to <filename>/boot.config</filename> and a list
	- of the supported options.</para>
	+ <para>Add the <option>-S</option> boot option to
	+ <filename>/boot.config</filename>. See &man.boot.8; for
	+ a description of how to add options to
	+ <filename>/boot.config</filename> and a list of the
	+ supported options.</para>
	</listitem>

	<listitem>
	- <para>Enable the <varname>comconsole_speed</varname>
	- option in your <filename>/boot/loader.conf</filename>
	- file.</para>
	-
	- <para>This option depends on <varname>console</varname>,
	+ <para>Enable <varname>comconsole_speed</varname> in
	+ <filename>/boot/loader.conf</filename>. This option
	+ depends on <varname>console</varname>,
	<varname>boot_serial</varname>, and
	<varname>boot_multicons</varname> being set in
	<filename>/boot/loader.conf</filename> too. An example
	of using <varname>comconsole_speed</varname> to change
	the serial console speed is:</para>

	<programlisting>boot_multicons="YES"
	boot_serial="YES"
	comconsole_speed="115200"
	console="comconsole,vidconsole"</programlisting>
	</listitem>
	</itemizedlist>
	</sect3>

	<sect3 id="serialconsole-com2">
	- <title>Using Serial Port Other Than
	+ <title>Using a Serial Port Other Than
	<devicename>sio0</devicename> for the Console</title>

	<para>Using a port other than <devicename>sio0</devicename> as
	- the console requires some recompiling. If you want to use
	- another serial port for whatever reasons, recompile the boot
	- blocks, the boot loader and the kernel as follows.</para>
	+ the console requires the boot blocks, the boot loader, and
	+ the kernel to be recompiled as follows.</para>

	<procedure>
	<step>
	- <para>Get the kernel source. (See <xref
	- linkend="updating-upgrading"/>)</para>
	+ <para>Get the kernel source as described in <link
	+ linkend="updating-upgrading"></link>.</para>
	</step>

	<step>
	<para>Edit <filename>/etc/make.conf</filename> and set
	<literal>BOOT_COMCONSOLE_PORT</literal> to the address
	- of the port you want to use (0x3F8, 0x2F8, 0x3E8 or
	- 0x2E8). Only <devicename>sio0</devicename> through
	+ of the port to use: 0x3F8, 0x2F8, 0x3E8 or 0x2E8. Only
	+ <devicename>sio0</devicename> through
	<devicename>sio3</devicename>
	(<devicename>COM1</devicename> through
	- <devicename>COM4</devicename>) can be used; multiport
	+ <devicename>COM4</devicename>) can be used as multiport
	serial cards will not work. No interrupt setting is
	needed.</para>
	</step>

	<step>
	<para>Create a custom kernel configuration file and add
	- appropriate flags for the serial port you want to use.
	- For example, if you want to make
	- <devicename>sio1</devicename>
	+ appropriate flags for the serial port to use. For
	+ example, to make <devicename>sio1</devicename>
	(<devicename>COM2</devicename>) the console:</para>

	<programlisting>device sio1 flags 0x10</programlisting>

	<para>or</para>

	<programlisting>device sio1 flags 0x30</programlisting>

	<para>The console flags for the other serial ports should
	not be set.</para>
	</step>

	<step>
	<para>Recompile and install the boot blocks and the boot
	loader:</para>

	<screen>&prompt.root; <userinput>cd /sys/boot</userinput>
	&prompt.root; <userinput>make clean</userinput>
	&prompt.root; <userinput>make</userinput>
	&prompt.root; <userinput>make install</userinput></screen>
	</step>

	<step>
	<para>Rebuild and install the kernel.</para>
	</step>

	<step>
	<para>Write the boot blocks to the boot disk with
	&man.bsdlabel.8; and boot from the new kernel.</para>
	</step>
	</procedure>
	</sect3>

	<sect3 id="serialconsole-ddb">
	<title>Entering the DDB Debugger from the Serial Line</title>

	- <para>If you wish to drop into the kernel debugger from the
	- serial console (useful for remote diagnostics, but also
	- dangerous if you generate a spurious BREAK on the serial
	- port!) then you should compile your kernel with the
	- following options:</para>
	+ <para>To drop into the kernel debugger from the serial
	+ console, compile a custom kernel with the following options.
	+ Note that while this is useful for remote diagnostics, it is
	+ also dangerous if a spurious BREAK is generated on the
	+ serial port.</para>

	<programlisting>options BREAK_TO_DEBUGGER
	options DDB</programlisting>
	</sect3>

	<sect3>
	<title>Getting a Login Prompt on the Serial Console</title>

	- <para>While this is not required, you may wish to get a
	- <emphasis>login</emphasis> prompt over the serial line, now
	- that you can see boot messages and can enter the kernel
	- debugging session through the serial console. Here is how
	- to do it.</para>
	+ <para>While this is not required, it is possible to get a
	+ <emphasis>login</emphasis> prompt over the serial line.
	+ First, make sure that the boot messages are displayed and it
	+ is possible to enter the kernel debugging session through
	+ the serial console.</para>

	- <para>Open the file <filename>/etc/ttys</filename> with an
	- editor and locate the lines:</para>
	+ <para>Open <filename>/etc/ttys</filename> with a text editor
	+ and locate the lines:</para>

	<programlisting>ttyu0 "/usr/libexec/getty std.9600" unknown off secure
	ttyu1 "/usr/libexec/getty std.9600" unknown off secure
	ttyu2 "/usr/libexec/getty std.9600" unknown off secure
	ttyu3 "/usr/libexec/getty std.9600" unknown off secure</programlisting>

	<para><devicename>ttyu0</devicename> through
	- <devicename>ttyu3</devicename> corresponds to
	+ <devicename>ttyu3</devicename> correspond to
	<devicename>COM1</devicename> through
	<devicename>COM4</devicename>. Change
	<literal>off</literal> to <literal>on</literal> for the
	- desired port. If you have changed the speed of the serial
	- port, you need to change <literal>std.9600</literal> to
	- match the current setting, e.g.,
	- <literal>std.19200</literal>.</para>
	+ desired port. If the speed of the serial port has been
	+ changed, change <literal>std.9600</literal> to match the
	+ new setting.</para>

	- <para>You may also want to change the terminal type from
	- <literal>unknown</literal> to the actual type of your serial
	+ <para>The terminal type can also be changed from
	+ <literal>unknown</literal> to the actual type of the serial
	terminal.</para>

	- <para>After editing the file, you must <command>kill -HUP
	+ <para>After editing the file, type <command>kill -HUP
	1</command> to make this change take effect.</para>
	</sect3>
	</sect2>

	<sect2 id="serialconsole-loader">
	<title>Changing Console from the Boot Loader</title>

	<para>Previous sections described how to set up the serial
	- console by tweaking the boot block. This section shows that
	- you can specify the console by entering some commands and
	+ console by tweaking the boot block. This section shows how to
	+ specify the console by entering some commands and
	environment variables in the boot loader. As the boot loader
	- is invoked at the third stage of the boot process, after the
	- boot block, the settings in the boot loader will override the
	- settings in the boot block.</para>
	+ is invoked at the third stage of the boot process, the
	+ settings in the boot loader will override the settings in the
	+ boot block.</para>

	<sect3>
	<title>Setting Up the Serial Console</title>

	- <para>You can easily specify the boot loader and the kernel to
	- use the serial console by writing just one line in
	+ <para>The boot loader and the kernel to use the serial console
	+ can be specified by writing one line in
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>console="comconsole"</programlisting>

	<para>This will take effect regardless of the settings in the
	boot block discussed in the previous section.</para>

	- <para>You had better put the above line as the first line of
	+ <para>This line should be the first line of
	<filename>/boot/loader.conf</filename> so as to see boot
	messages on the serial console as early as possible.</para>

	- <para>Likewise, you can specify the internal console
	- as:</para>
	+ <para>Likewise, to specify the internal console:</para>

	<programlisting>console="vidconsole"</programlisting>

	- <para>If you do not set the boot loader environment variable
	- <envar>console</envar>, the boot loader, and subsequently
	- the kernel, will use whichever console indicated by the
	- <option>-h</option> option in the boot block.</para>
	+ <para>If the boot loader environment variable
	+ <envar>console</envar> is not set, the boot loader, and
	+ subsequently the kernel, will use whichever console is
	+ indicated by <option>-h</option> in the boot block.</para>

	<para>The console can be specified in
	<filename>/boot/loader.conf.local</filename> or in
	<filename>/boot/loader.conf</filename>.</para>

	<para>See &man.loader.conf.5; for more information.</para>

	<note>
	<para>At the moment, the boot loader has no option
	- quivalent to the <option>-P</option> option in the boot
	- block, and there is no provision to automatically select
	- the internal console and the serial console based on the
	- presence of the keyboard.</para>
	+ equivalent to <option>-P</option> in the boot block, and
	+ there is no provision to automatically select the internal
	+ console and the serial console based on the presence of
	+ the keyboard.</para>
	</note>
	</sect3>

	<sect3>
	<title>Using a Serial Port Other Than
	<devicename>sio0</devicename> for the Console</title>

	- <para>You need to recompile the boot loader to use a serial
	- port other than <devicename>sio0</devicename> for the serial
	- console. Follow the procedure described in <xref
	- linkend="serialconsole-com2"/>.</para>
	+ <para>The boot loader needs to be compiled in order to use a
	+ serial port other than <devicename>sio0</devicename> for the
	+ serial console. Follow the procedure described in <link
	+ linkend="serialconsole-com2"></link>.</para>
	</sect3>
	</sect2>

	<sect2 id="serialconsole-caveats">
	<title>Caveats</title>

	- <para>The idea here is to allow people to set up dedicated
	- servers that require no graphics hardware or attached
	- keyboards. Unfortunately, while most systems will let you
	- boot without a keyboard, there are quite a few that will not
	- let you boot without a graphics adapter. Machines with AMI
	- BIOSes can be configured to boot with no graphics adapter
	+ <para>While most systems will boot without a keyboard, quite a
	+ few will not boot without a graphics adapter. Machines with
	+ AMI BIOSes can be configured to boot with no graphics adapter
	installed by changing the <quote>graphics adapter</quote>
	setting in the CMOS configuration to <quote>Not
	installed.</quote></para>

	<para>However, many machines do not support this option and will
	- refuse to boot if you have no display hardware in the system.
	- With these machines, you will have to leave some kind of
	- graphics card plugged in, (even if it is just a junky mono
	- board) although you will not have to attach a monitor. You
	- might also try installing an AMI BIOS.</para>
	+ refuse to boot if there is no display hardware in the system.
	+ With these machines, leave some kind of graphics card plugged
	+ in, even if it is just a junky mono board. A monitor does not
	+ need to be attached. One might also try installing an AMI
	+ BIOS.</para>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/users/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/users/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/users/chapter.xml (revision 41355)
	@@ -1,1071 +1,1037 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="users">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Neil</firstname>
	<surname>Blakey-Milner</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<!-- Feb 2000 -->
	</chapterinfo>

	<title>Users and Basic Account Management</title>

	<sect1 id="users-synopsis">
	<title>Synopsis</title>

	- <para>FreeBSD allows multiple users to use the computer at the
	- same time. Obviously, only one of those users can be sitting in
	- front of the screen and keyboard at any one time
	- <footnote><para>Well, unless you hook up multiple terminals, but
	- we will save that for <xref linkend="serialcomms"/>.</para>
	- </footnote>, but any number of users can log in through the
	- network to get their work done. To use the system every user
	- must have an account.</para>
	+ <para>&os; allows multiple users to use the computer at the same
	+ time. While only one user can sit in front of the screen and
	+ use the keyboard at any one time, any number of users can log
	+ in to the system through the network. To use the system, every
	+ user must have a user account.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>The differences between the various user accounts on a
	- FreeBSD system.</para>
	+ &os; system.</para>
	</listitem>

	<listitem>
	- <para>How to add user accounts.</para>
	+ <para>How to add and remove user accounts.</para>
	</listitem>

	<listitem>
	- <para>How to remove user accounts.</para>
	- </listitem>
	-
	- <listitem>
	<para>How to change account details, such as the user's full
	- name, or preferred shell.</para>
	+ name or preferred shell.</para>
	</listitem>

	<listitem>
	- <para>How to set limits on a per-account basis, to control the
	- resources such as memory and CPU time that accounts and
	+ <para>How to set limits on a per-account basis to control the
	+ resources, such as memory and CPU time, that accounts and
	groups of accounts are allowed to access.</para>
	</listitem>

	<listitem>
	<para>How to use groups to make account management
	easier.</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	- <para>Understand the basics of &unix; and FreeBSD (<xref
	- linkend="basics"/>).</para>
	+ <para>Understand the <link linkend="basics">basics of &unix;
	+ and &os;</link>.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="users-introduction">
	<title>Introduction</title>

	- <para>All access to the system is achieved via accounts, and all
	- processes are run by users, so user and account management are
	- of integral importance on FreeBSD systems.</para>
	+ <para>Since all access to the &os; system is achieved via accounts
	+ and all processes are run by users, user and account management
	+ is important.</para>

	- <para>Every account on a FreeBSD system has certain information
	+ <para>Every account on a &os; system has certain information
	associated with it to identify the account.</para>

	<variablelist>
	<varlistentry>
	<term>User name</term>

	<listitem>
	- <para>The user name as it would be typed at the
	- <prompt>login:</prompt> prompt. User names must be unique
	- across the computer; you may not have two users with the
	- same user name. There are a number of rules for creating
	- valid user names, documented in &man.passwd.5;; you would
	- typically use user names that consist of eight or fewer
	- all lower case characters.</para>
	+ <para>The user name is typed at the <prompt>login:</prompt>
	+ prompt. User names must be unique on the system as no two
	+ users can have the same user name. There are a number of
	+ rules for creating valid user names, documented in
	+ &man.passwd.5;. Typically user names consist of eight or
	+ fewer all lower case characters in order to maintain
	+ backwards compatibility with applications.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Password</term>

	<listitem>
	- <para>Each account has a password associated with it. The
	- password may be blank, in which case no password will be
	- required to access the system. This is normally a very
	- bad idea; every account should have a password.</para>
	+ <para>Each account has an associated password. While the
	+ password can be blank, this is highly discouraged and
	+ every account should have a password.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	- <term>User ID (UID)</term>
	+ <term>User ID (<acronym>UID</acronym>)</term>

	<listitem>
	- <para>The UID is a number, traditionally from 0 to
	- 65535<footnote id="users-largeuidgid">
	- <para>It is possible to use UID/GIDs as large as
	- 4294967295, but such IDs can cause serious problems
	- with software that makes assumptions about the values
	- of IDs.</para>
	+ <para>The User ID (<acronym>UID</acronym>) is a number,
	+ traditionally from 0 to 65535<footnote
	+ id="users-largeuidgid">
	+ <para>It is possible to use
	+ <acronym>UID</acronym>s/<acronym>GID</acronym>s as
	+ large as 4294967295, but such IDs can cause serious
	+ problems with software that makes assumptions about
	+ the values of IDs.</para>
	</footnote>, used to uniquely identify the user to the
	- system. Internally, FreeBSD uses the UID to
	- identify users—any FreeBSD commands that allow
	- you to specify a user name will convert it to the UID
	- before working with it. This means that you can have
	- several accounts with different user names but the
	- same UID. As far as FreeBSD is concerned these
	- accounts are one user. It is unlikely you will ever
	- need to do this.</para>
	+ system. Internally, &os; uses the
	+ <acronym>UID</acronym> to identify users. Commands that
	+ allow a user name to be specified will first convert it to
	+ the <acronym>UID</acronym>. Though unlikely, it is
	+ possible for several accounts with different user names to
	+ share the same <acronym>UID</acronym>. As far as &os; is
	+ concerned, these accounts are one user.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	- <term>Group ID (GID)</term>
	+ <term>Group ID (<acronym>GID</acronym>)</term>

	<listitem>
	- <para>The GID is a number, traditionally from 0 to
	- 65535<footnoteref linkend="users-largeuidgid"/>, used to
	- uniquely identify the primary group that the user belongs
	- to. Groups are a mechanism for controlling access to
	- resources based on a user's GID rather than their UID.
	- This can significantly reduce the size of some
	- configuration files. A user may also be in more than one
	- group.</para>
	+ <para>The Group ID (<acronym>GID</acronym>) is a number,
	+ traditionally from 0 to 65535<footnoteref
	+ linkend="users-largeuidgid"/>, used to uniquely identify
	+ the primary group that the user belongs to. Groups are a
	+ mechanism for controlling access to resources based on a
	+ user's <acronym>GID</acronym> rather than their
	+ <acronym>UID</acronym>. This can significantly reduce the
	+ size of some configuration files. A user may also be a
	+ member of more than one group.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Login class</term>

	<listitem>
	<para>Login classes are an extension to the group mechanism
	that provide additional flexibility when tailoring the
	system to different users.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Password change time</term>

	<listitem>
	- <para>By default FreeBSD does not force users to change
	- their passwords periodically. You can enforce this on a
	- per-user basis, forcing some or all of your users to
	+ <para>By default &os; does not force users to change their
	+ passwords periodically. Password expiration can be
	+ enforced on a per-user basis, forcing some or all users to
	change their passwords after a certain amount of time has
	elapsed.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Account expiry time</term>

	<listitem>
	- <para>By default FreeBSD does not expire accounts. If you
	- are creating accounts that you know have a limited
	- lifespan, for example, in a school where you have accounts
	- for the students, then you can specify when the account
	- expires. After the expiry time has elapsed the account
	+ <para>By default &os; does not expire accounts. When
	+ creating accounts that need a limited lifespan, such as
	+ student accounts in a school, specify the account expiry
	+ date. After the expiry time has elapsed, the account
	cannot be used to log in to the system, although the
	account's directories and files will remain.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>User's full name</term>

	<listitem>
	- <para>The user name uniquely identifies the account to
	- FreeBSD, but does not necessarily reflect the user's real
	- name. This information can be associated with the
	+ <para>The user name uniquely identifies the account to &os;,
	+ but does not necessarily reflect the user's real name.
	+ This information can be associated with the
	account.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>Home directory</term>

	<listitem>
	<para>The home directory is the full path to a directory on
	- the system in which the user will start when logging on to
	- the system. A common convention is to put all user home
	- directories under
	- <filename>/home/<replaceable>username</replaceable></filename>
	- or
	- <filename>/usr/home/<replaceable>username</replaceable></filename>.
	- The user would store their personal files in their home
	- directory, and any directories they may create in
	- there.</para>
	+ the system. This is the user's starting directory when
	+ the user logs in. A common convention is to put all user
	+ home directories under <filename
	+ class="directory">/home/<replaceable>username</replaceable></filename>
	+ or <filename
	+ class="directory">/usr/home/<replaceable>username</replaceable></filename>.
	+ Each user stores their personal files and subdirectories
	+ in their own home directory.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>User shell</term>

	<listitem>
	<para>The shell provides the default environment users use
	to interact with the system. There are many different
	kinds of shells, and experienced users will have their own
	preferences, which can be reflected in their account
	settings.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>There are three main types of accounts: the <link
	- linkend="users-superuser">Superuser</link>, <link
	- linkend="users-system">system users</link>, and <link
	- linkend="users-user">user accounts</link>. The Superuser
	+ linkend="users-superuser">superuser</link>, <link
	+ linkend="users-system">system accounts</link>, and <link
	+ linkend="users-user">user accounts</link>. The superuser
	account, usually called <username>root</username>, is used to
	manage the system with no limitations on privileges. System
	- users run services. Finally, user accounts are used by real
	- people, who log on, read mail, and so forth.</para>
	- </sect1>
	+ accounts are used to run services. User accounts are
	+ assigned to real people and are used to log in and use the
	+ system.</para>

	- <sect1 id="users-superuser">
	- <title>The Superuser Account</title>
	+ <sect2 id="users-superuser">
	+ <title>The Superuser Account</title>

	- <indexterm>
	- <primary>accounts</primary>
	- <secondary>superuser (root)</secondary>
	- </indexterm>
	- <para>The superuser account, usually called
	- <username>root</username>, comes preconfigured to facilitate
	- system administration, and should not be used for day-to-day
	- tasks like sending and receiving mail, general exploration of
	- the system, or programming.</para>
	+ <indexterm>
	+ <primary>accounts</primary>
	+ <secondary>superuser (root)</secondary>
	+ </indexterm>
	+ <para>The superuser account, usually called
	+ <username>root</username>, is used to perform system
	+ administration tasks and should not be used for day-to-day
	+ tasks like sending and receiving mail, general exploration of
	+ the system, or programming.</para>

	- <para>This is because the superuser, unlike normal user accounts,
	- can operate without limits, and misuse of the superuser account
	- may result in spectacular disasters. User accounts are unable
	- to destroy the system by mistake, so it is generally best to use
	- normal user accounts whenever possible, unless you especially
	- need the extra privilege.</para>
	+ <para>This is because the superuser, unlike normal user
	+ accounts, can operate without limits, and misuse of the
	+ superuser account may result in spectacular disasters. User
	+ accounts are unable to destroy the system by mistake, so it is
	+ generally best to use normal user accounts whenever possible,
	+ unless extra privilege is required.</para>

	- <para>You should always double and triple-check commands you issue
	- as the superuser, since an extra space or missing character can
	- mean irreparable data loss.</para>
	+ <para>Always double and triple-check any commands issued as the
	+ superuser, since an extra space or missing character can mean
	+ irreparable data loss.</para>

	- <para>So, the first thing you should do after reading this
	- chapter is to create an unprivileged user account for yourself
	- for general usage if you have not already. This applies equally
	- whether you are running a multi-user or single-user machine.
	- Later in this chapter, we discuss how to create additional
	- accounts, and how to change between the normal user and
	- superuser.</para>
	- </sect1>
	+ <para>Always create a user account for the system administrator
	+ and use this account to log in to the system for general
	+ usage. This applies equally to multi-user or single-user
	+ systems. Later sections will discuss how to create additional
	+ accounts and how to change between the normal user and
	+ superuser.</para>
	+ </sect2>

	- <sect1 id="users-system">
	- <title>System Accounts</title>
	+ <sect2 id="users-system">
	+ <title>System Accounts</title>

	- <indexterm>
	- <primary>accounts</primary>
	- <secondary>system</secondary>
	- </indexterm>
	- <para>System users are those used to run services such as DNS,
	- mail, web servers, and so forth. The reason for this is
	- security; if all services ran as the superuser, they could
	- act without restriction.</para>
	+ <indexterm>
	+ <primary>accounts</primary>
	+ <secondary>system</secondary>
	+ </indexterm>
	+ <para>System accounts are used to run services such as DNS,
	+ mail, and web servers. The reason for this is security; if
	+ all services ran as the superuser, they could act without
	+ restriction.</para>

	- <indexterm>
	- <primary>accounts</primary>
	- <secondary><username>daemon</username></secondary>
	- </indexterm>
	- <indexterm>
	- <primary>accounts</primary>
	- <secondary><username>operator</username></secondary>
	- </indexterm>
	- <para>Examples of system users are <username>daemon</username>,
	- <username>operator</username>, <username>bind</username> (for
	- the Domain Name Service), <username>news</username>, and
	- <username>www</username>.</para>
	+ <indexterm>
	+ <primary>accounts</primary>
	+ <secondary><username>daemon</username></secondary>
	+ </indexterm>
	+ <indexterm>
	+ <primary>accounts</primary>
	+ <secondary><username>operator</username></secondary>
	+ </indexterm>
	+ <para>Examples of system accounts are
	+ <username>daemon</username>, <username>operator</username>,
	+ <username>bind</username>, <username>news</username>, and
	+ <username>www</username>.</para>

	- <indexterm>
	- <primary>accounts</primary>
	- <secondary><username>nobody</username></secondary>
	- </indexterm>
	- <para><username>nobody</username> is the generic unprivileged
	- system user. However, it is important to keep in mind that the
	- more services that use <username>nobody</username>, the more
	- files and processes that user will become associated with, and
	- hence the more privileged that user becomes.</para>
	- </sect1>
	+ <indexterm>
	+ <primary>accounts</primary>
	+ <secondary><username>nobody</username></secondary>
	+ </indexterm>
	+ <para><username>nobody</username> is the generic unprivileged
	+ system account. However, the more services that use
	+ <username>nobody</username>, the more files and processes that
	+ user will become associated with, and hence the more
	+ privileged that user becomes.</para>
	+ </sect2>

	- <sect1 id="users-user">
	- <title>User Accounts</title>
	+ <sect2 id="users-user">
	+ <title>User Accounts</title>

	- <indexterm>
	- <primary>accounts</primary>
	- <secondary>user</secondary>
	- </indexterm>
	- <para>User accounts are the primary means of access for real
	- people to the system, and these accounts insulate the user and
	- the environment, preventing the users from damaging the system
	- or other users, and allowing users to customize their
	- environment without affecting others.</para>
	+ <indexterm>
	+ <primary>accounts</primary>
	+ <secondary>user</secondary>
	+ </indexterm>
	+ <para>User accounts are the primary means of access for real
	+ people to the system. User accounts insulate the user and
	+ the environment, preventing users from damaging the system
	+ or other users, and allowing users to customize their
	+ environment without affecting others.</para>

	- <para>Every person accessing your system should have a unique user
	- account. This allows you to find out who is doing what, prevent
	- people from clobbering each others' settings or reading each
	- others' mail, and so forth.</para>
	+ <para>Every person accessing the system should have a unique
	+ user account. This allows the administrator to find out who
	+ is doing what, prevents users from clobbering each others'
	+ settings or reading each others' mail, and so forth.</para>

	- <para>Each user can set up their own environment to accommodate
	- their use of the system, by using alternate shells, editors, key
	- bindings, and language.</para>
	+ <para>Each user can set up their own environment to accommodate
	+ their use of the system, by using alternate shells, editors,
	+ key bindings, and language.</para>
	+ </sect2>
	</sect1>

	<sect1 id="users-modifying">
	<title>Modifying Accounts</title>

	<indexterm>
	<primary>accounts</primary>
	<secondary>modifying</secondary>
	</indexterm>

	- <para>There are a variety of different commands available in the
	- &unix; environment to manipulate user accounts. The most common
	- commands are summarized below, followed by more detailed
	- examples of their usage.</para>
	+ <para>&os; provides a variety of different commands to manage
	+ user accounts. The most common commands are summarized below,
	+ followed by more detailed examples of their usage.</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<colspec colwidth="1*"/>
	<colspec colwidth="2*"/>

	<thead>
	<row>
	<entry>Command</entry>
	<entry>Summary</entry>
	</row>
	</thead>
	<tbody>
	<row>
	<entry>&man.adduser.8;</entry>
	<entry>The recommended command-line application for adding
	new users.</entry>
	</row>

	<row>
	<entry>&man.rmuser.8;</entry>
	<entry>The recommended command-line application for
	removing users.</entry>
	</row>

	<row>
	<entry>&man.chpass.1;</entry>
	- <entry>A flexible tool to change user database
	+ <entry>A flexible tool for changing user database
	information.</entry>
	</row>

	<row>
	<entry>&man.passwd.1;</entry>
	<entry>The simple command-line tool to change user
	passwords.</entry>
	</row>

	<row>
	<entry>&man.pw.8;</entry>
	- <entry>A powerful and flexible tool to modify all aspects
	- of user accounts.</entry>
	+ <entry>A powerful and flexible tool for modifying all
	+ aspects of user accounts.</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<sect2 id="users-adduser">
	<title><command>adduser</command></title>

	<indexterm>
	<primary>accounts</primary>
	<secondary>adding</secondary>
	</indexterm>
	<indexterm>
	<primary><command>adduser</command></primary>
	</indexterm>
	<indexterm>
	<primary><filename
	class="directory">/usr/share/skel</filename></primary>
	</indexterm>
	<indexterm><primary>skeleton directory</primary></indexterm>
	- <para>&man.adduser.8; is a simple program for
	- adding new users. It creates entries in the system
	- <filename>passwd</filename> and <filename>group</filename>
	- files. It will also create a home directory for the new user,
	- copy in the default configuration files
	- (<quote>dotfiles</quote>) from
	- <filename>/usr/share/skel</filename>, and can optionally mail
	- the new user a welcome message.</para>
	+ <para>&man.adduser.8; is a simple program for adding new users
	+ When a new user is added, this program automatically updates
	+ <filename>/etc/passwd</filename> and
	+ <filename>/etc/group</filename>. It also creates a home
	+ directory for the new user, copies in the default
	+ configuration files from <filename
	+ class="directory">/usr/share/skel</filename>, and can
	+ optionally mail the new user a welcome message.</para>

	<example>
	<title>Adding a User on &os;</title>

	<screen>&prompt.root; <userinput>adduser</userinput>
	Username: <userinput>jru</userinput>
	Full name: <userinput>J. Random User</userinput>
	Uid (Leave empty for default):
	Login group [jru]:
	Login group is jru. Invite jru into other groups? []: <userinput>wheel</userinput>
	Login class [default]:
	Shell (sh csh tcsh zsh nologin) [sh]: <userinput>zsh</userinput>
	Home directory [/home/jru]:
	Home directory permissions (Leave empty for default):
	Use password-based authentication? [yes]:
	Use an empty password? (yes/no) [no]:
	Use a random password? (yes/no) [no]:
	Enter password:
	Enter password again:
	Lock out the account after creation? [no]:
	Username : jru
	Password : ****
	Full Name : J. Random User
	Uid : 1001
	Class :
	Groups : jru wheel
	Home : /home/jru
	Shell : /usr/local/bin/zsh
	Locked : no
	OK? (yes/no): <userinput>yes</userinput>
	adduser: INFO: Successfully added (jru) to the user database.
	Add another user? (yes/no): <userinput>no</userinput>
	Goodbye!
	&prompt.root;</screen>
	</example>

	<note>
	- <para>The password you type in is not echoed, nor are
	- asterisks displayed. Make sure that you do not mistype the
	- password.</para>
	+ <para>Since the password is not echoed when typed, be careful
	+ to not mistype the password when creating the user
	+ account.</para>
	</note>
	</sect2>

	<sect2 id="users-rmuser">
	<title><command>rmuser</command></title>

	<indexterm><primary><command>rmuser</command></primary></indexterm>
	<indexterm>
	<primary>accounts</primary>
	<secondary>removing</secondary>
	</indexterm>

	- <para>You can use &man.rmuser.8; to completely remove a user
	- from the system. &man.rmuser.8; performs the following
	+ <para>To completely remove a user from the system use
	+ &man.rmuser.8;. This command performs the following
	steps:</para>

	<procedure>
	<step>
	- <para>Removes the user's &man.crontab.1; entry (if
	- any).</para>
	+ <para>Removes the user's &man.crontab.1; entry if one
	+ exists.</para>
	</step>

	<step>
	<para>Removes any &man.at.1; jobs belonging to the
	user.</para>
	</step>

	<step>
	<para>Kills all processes owned by the user.</para>
	</step>

	<step>
	<para>Removes the user from the system's local password
	file.</para>
	</step>

	<step>
	- <para>Removes the user's home directory (if it is owned by
	- the user).</para>
	+ <para>Removes the user's home directory, if it is owned by
	+ the user.</para>
	</step>

	<step>
	<para>Removes the incoming mail files belonging to the user
	- from <filename>/var/mail</filename>.</para>
	+ from <filename
	+ class="directory">/var/mail</filename>.</para>
	</step>

	<step>
	<para>Removes all files owned by the user from temporary
	- file storage areas such as
	- <filename>/tmp</filename>.</para>
	+ file storage areas such as <filename
	+ class="directory">/tmp</filename>.</para>
	</step>

	<step>
	<para>Finally, removes the username from all groups to which
	it belongs in <filename>/etc/group</filename>.</para>

	<note>
	<para>If a group becomes empty and the group name is the
	- same as the username, the group is removed; this
	+ same as the username, the group is removed. This
	complements the per-user unique groups created by
	&man.adduser.8;.</para>
	</note>
	</step>
	</procedure>

	<para>&man.rmuser.8; cannot be used to remove superuser
	- accounts, since that is almost always an indication of massive
	+ accounts since that is almost always an indication of massive
	destruction.</para>

	- <para>By default, an interactive mode is used, which attempts to
	- make sure you know what you are doing.</para>
	+ <para>By default, an interactive mode is used, as shown
	+ in the following example.</para>

	<example>
	<title><command>rmuser</command> Interactive Account
	Removal</title>

	<screen>&prompt.root; <userinput>rmuser jru</userinput>
	Matching password entry:
	jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh
	Is this the entry you wish to remove? <userinput>y</userinput>
	Remove user's home directory (/home/jru)? <userinput>y</userinput>
	Updating password file, updating databases, done.
	Updating group file: trusted (removing group jru -- personal group is empty) done.
	Removing user's incoming mail file /var/mail/jru: done.
	Removing files belonging to jru from /tmp: done.
	Removing files belonging to jru from /var/tmp: done.
	Removing files belonging to jru from /var/tmp/vi.recover: done.
	&prompt.root;</screen>
	</example>
	</sect2>

	<sect2 id="users-chpass">
	<title><command>chpass</command></title>

	<indexterm><primary><command>chpass</command></primary></indexterm>
	- <para>&man.chpass.1; changes user database
	+ <para>&man.chpass.1; can be used to change user database
	information such as passwords, shells, and personal
	information.</para>

	- <para>Only system administrators, as the superuser, may change
	- other users' information and passwords with
	- &man.chpass.1;.</para>
	+ <para>Only the superuser can change other users' information and
	+ passwords with &man.chpass.1;.</para>

	<para>When passed no options, aside from an optional username,
	- &man.chpass.1; displays an editor
	- containing user information. When the user exists from the
	- editor, the user database is updated with the new
	- information.</para>
	+ &man.chpass.1; displays an editor containing user information.
	+ When the user exists from the editor, the user database is
	+ updated with the new information.</para>

	<note>
	- <para>You will be asked for your password
	- after exiting the editor if you are not the
	- superuser.</para>
	+ <para>You will be asked for your password after exiting the
	+ editor if you are not the superuser.</para>
	</note>

	<example>
	<title>Interactive <command>chpass</command> by
	Superuser</title>

	<screen>#Changing user database information for jru.
	Login: jru
	Password: *
	Uid [#]: 1001
	Gid [# or name]: 1001
	Change [month day year]:
	Expire [month day year]:
	Class:
	Home directory: /home/jru
	Shell: /usr/local/bin/zsh
	Full Name: J. Random User
	Office Location:
	Office Phone:
	Home Phone:
	Other information:</screen>
	</example>

	- <para>The normal user can change only a small subset of this
	- information, and only for themselves.</para>
	+ <para>A user can change only a small subset of this
	+ information, and only for their own user account.</para>

	<example>
	<title>Interactive <command>chpass</command> by Normal
	User</title>

	<screen>#Changing user database information for jru.
	Shell: /usr/local/bin/zsh
	Full Name: J. Random User
	Office Location:
	Office Phone:
	Home Phone:
	Other information:</screen>
	</example>

	<note>
	- <para>&man.chfn.1; and &man.chsh.1; are
	- just links to &man.chpass.1;, as
	- are &man.ypchpass.1;,
	- &man.ypchfn.1;, and
	- &man.ypchsh.1;. NIS support is automatic, so
	- specifying the <literal>yp</literal> before the command is
	- not necessary. If this is confusing to you, do not worry,
	- NIS will be covered in <xref
	- linkend="network-servers"/>.</para>
	+ <para>&man.chfn.1; and &man.chsh.1; are links to
	+ &man.chpass.1;, as are &man.ypchpass.1;, &man.ypchfn.1;, and
	+ &man.ypchsh.1;. <acronym>NIS</acronym> support is
	+ automatic, so specifying the <literal>yp</literal> before
	+ the command is not necessary. How to configure NIS is
	+ covered in <link linkend="network-servers"></link>.</para>
	</note>
	</sect2>
	<sect2 id="users-passwd">
	<title><command>passwd</command></title>

	<indexterm><primary><command>passwd</command></primary></indexterm>
	<indexterm>
	<primary>accounts</primary>
	<secondary>changing password</secondary>
	</indexterm>
	- <para>&man.passwd.1; is the usual way to
	- change your own password as a user, or another user's password
	- as the superuser.</para>
	+ <para>&man.passwd.1; is the usual way to change your own
	+ password as a user, or another user's password as the
	+ superuser.</para>

	<note>
	- <para>To prevent accidental or unauthorized changes, the
	- original password must be entered before a new password can
	- be set.</para>
	+ <para>To prevent accidental or unauthorized changes, the user
	+ must enter their original password before a new password can
	+ be set. This is not the case when the superuser changes a
	+ user's password.</para>
	</note>

	<example>
	<title>Changing Your Password</title>

	<screen>&prompt.user; <userinput>passwd</userinput>
	Changing local password for jru.
	Old password:
	New password:
	Retype new password:
	passwd: updating the database...
	passwd: done</screen>
	</example>

	<example>
	<title>Changing Another User's Password as the
	Superuser</title>

	<screen>&prompt.root; <userinput>passwd jru</userinput>
	Changing local password for jru.
	New password:
	Retype new password:
	passwd: updating the database...
	passwd: done</screen>
	</example>

	<note>
	- <para>As with &man.chpass.1;,
	- &man.yppasswd.1; is just a link to
	- &man.passwd.1;, so NIS works with either
	- command.</para>
	+ <para>As with &man.chpass.1;, &man.yppasswd.1; is a link to
	+ &man.passwd.1;, so NIS works with either command.</para>
	</note>
	</sect2>


	<sect2 id="users-pw">
	<title><command>pw</command></title>

	<indexterm><primary><command>pw</command></primary></indexterm>

	<para>&man.pw.8; is a command line utility to create, remove,
	modify, and display users and groups. It functions as a front
	- end to the system user and group files. &man.pw.8;
	- has a very powerful set of command line options that make it
	- suitable for use in shell scripts, but new users may find it
	- more complicated than the other commands presented
	- here.</para>
	+ end to the system user and group files. &man.pw.8; has a very
	+ powerful set of command line options that make it suitable for
	+ use in shell scripts, but new users may find it more
	+ complicated than the other commands presented in this
	+ section.</para>
	</sect2>


	</sect1>

	<sect1 id="users-limiting">
	<title>Limiting Users</title>

	<indexterm><primary>limiting users</primary></indexterm>
	<indexterm>
	<primary>accounts</primary>
	<secondary>limiting</secondary>
	</indexterm>
	- <para>If you have users, the ability to limit their system use may
	- have come to mind. FreeBSD provides
	- several ways an administrator can limit the amount of system
	- resources an individual may use. These limits are
	- divided into two sections: disk quotas, and other resource
	- limits.</para>
	+ <para>&os; provides several methods for an administrator to limit
	+ the amount of system resources an individual may use. These
	+ limits are discussed in two sections: disk quotas and other
	+ resource limits.</para>

	<indexterm><primary>quotas</primary></indexterm>
	<indexterm>
	<primary>limiting users</primary>
	<secondary>quotas</secondary>
	</indexterm>
	<indexterm><primary>disk quotas</primary></indexterm>
	- <para>Disk quotas limit disk usage to users, and
	- they
	- provide a way to quickly check that usage without
	- calculating it every time. Quotas are discussed in <xref
	- linkend="quotas"/>.</para>
	+ <para>Disk quotas limit the amount of disk space available to
	+ users and provide a way to quickly check that usage without
	+ calculating it every time. Quotas are discussed in <link
	+ linkend="quotas"></link>.</para>

	<para>The other resource limits include ways to limit the amount
	of CPU, memory, and other resources a user may consume. These
	are defined using login classes and are discussed here.</para>

	<indexterm>
	<primary><filename>/etc/login.conf</filename></primary>
	</indexterm>
	<para>Login classes are defined in
	- <filename>/etc/login.conf</filename>. The precise semantics are
	- beyond the scope of this section, but are described in detail in
	- the &man.login.conf.5; manual page. It is sufficient to say
	- that each user is assigned to a login class
	- (<literal>default</literal> by default), and that each login
	+ <filename>/etc/login.conf</filename> and are described in detail
	+ in &man.login.conf.5;. Each user account is assigned to a login
	+ class, <literal>default</literal> by default, and each login
	class has a set of login capabilities associated with it. A
	login capability is a
	<literal><replaceable>name</replaceable>=<replaceable>value</replaceable></literal>
	pair, where <replaceable>name</replaceable> is a well-known
	identifier and <replaceable>value</replaceable> is an arbitrary
	- string processed accordingly depending on the name. Setting up
	- login classes and capabilities is rather straight-forward and is
	- also described in &man.login.conf.5;.</para>
	+ string which is processed accordingly depending on the
	+ <replaceable>name</replaceable>. Setting up login classes and
	+ capabilities is rather straightforward and is also described in
	+ &man.login.conf.5;.</para>

	<note>
	- <para>The system does not normally read the configuration in
	- <filename>/etc/login.conf</filename> directly, but reads the
	- database file <filename>/etc/login.conf.db</filename> which
	- provides faster lookups. To generate
	- <filename>/etc/login.conf.db</filename> from
	- <filename>/etc/login.conf</filename>, execute the following
	- command:</para>
	+ <para>&os; does not normally read the configuration in
	+ <filename>/etc/login.conf</filename> directly, but instead
	+ reads the <filename>/etc/login.conf.db</filename> database
	+ which provides faster lookups. Whenever
	+ <filename>/etc/login.conf</filename> is edited, the
	+ <filename>/etc/login.conf.db</filename> must be updated by
	+ executing the following command:</para>

	<screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>
	</note>

	- <para>Resource limits are different from plain vanilla login
	- capabilities in two ways. First, for every limit, there is a
	- soft (current) and hard limit. A soft limit may be adjusted by
	- the user or application, but may be no higher than the hard
	- limit. The latter may be lowered by the user, but never raised.
	- Second, most resource limits apply per process to a specific
	- user, not the user as a whole. Note, however, that these
	+ <para>Resource limits differ from the default login capabilities
	+ in two ways. First, for every limit, there is a soft (current)
	+ and hard limit. A soft limit may be adjusted by the user or
	+ application, but may not be set higher than the hard limit. The
	+ hard limit may be lowered by the user, but can only be raised
	+ by the superuser. Second, most resource limits apply per
	+ process to a specific user, not to the user as a whole. These
	differences are mandated by the specific handling of the limits,
	- not by the implementation of the login capability framework
	- (i.e., they are not <emphasis>really</emphasis> a special case
	- of login capabilities).</para>
	+ not by the implementation of the login capability
	+ framework.</para>

	- <para>And so, without further ado, below are the most commonly
	- used resource limits (the rest, along with all the other login
	- capabilities, may be found in &man.login.conf.5;).</para>
	+ <para>Below are the most commonly used resource limits. The rest
	+ of the limits, along with all the other login capabilities, can
	+ be found in &man.login.conf.5;.</para>

	<variablelist>
	<varlistentry>
	<term><literal>coredumpsize</literal></term>

	<listitem>
	<indexterm><primary>coredumpsize</primary></indexterm>
	<indexterm><primary>limiting users</primary>
	<secondary>coredumpsize</secondary>
	</indexterm>
	<para>The limit on the size of a core file generated by a
	- program is, for obvious reasons, subordinate to other
	- limits on disk usage (e.g., <literal>filesize</literal>,
	- or disk quotas). Nevertheless, it is often used as a
	- less-severe method of controlling disk space consumption:
	- since users do not generate core files themselves, and
	- often do not delete them, setting this may save them from
	- running out of disk space should a large program (e.g.,
	- <application>emacs</application>) crash.</para>
	+ program is subordinate to other limits on disk usage, such
	+ as <literal>filesize</literal>, or disk quotas.
	+ This limit is often used as a less-severe method of
	+ controlling disk space consumption. Since users do not
	+ generate core files themselves, and often do not delete
	+ them, setting this may save them from running out of disk
	+ space should a large program crash.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>cputime</literal></term>

	<listitem>
	<indexterm><primary>cputime</primary></indexterm>
	<indexterm>
	<primary>limiting users</primary>
	<secondary>cputime</secondary>
	</indexterm>
	- <para>This is the maximum amount of CPU time a user's
	- process may consume. Offending processes will be killed
	- by the kernel.</para>
	+ <para>The maximum amount of CPU time a user's process may
	+ consume. Offending processes will be killed by the
	+ kernel.</para>

	<note>
	<para>This is a limit on CPU <emphasis>time</emphasis>
	consumed, not percentage of the CPU as displayed in
	- some fields by &man.top.1; and &man.ps.1;. A limit on
	- the latter is, at the time of this writing, not
	- possible, and would be rather useless: a
	- compiler—probably a legitimate task—can
	- easily use almost 100% of a CPU for some time.</para>
	+ some fields by &man.top.1; and &man.ps.1;.</para>
	</note>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>filesize</literal></term>

	<listitem>
	<indexterm><primary>filesize</primary></indexterm>
	<indexterm>
	<primary>limiting users</primary>
	<secondary>filesize</secondary>
	</indexterm>
	- <para>This is the maximum size of a file the user may
	- possess. Unlike <link linkend="quotas">disk
	- quotas</link>, this limit is enforced on individual
	- files, not the set of all files a user owns.</para>
	+ <para>The maximum size of a file the user may own. Unlike
	+ <link linkend="quotas">disk quotas</link>, this limit is
	+ enforced on individual files, not the set of all files a
	+ user owns.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>maxproc</literal></term>

	<listitem>
	<indexterm><primary>maxproc</primary></indexterm>
	<indexterm>
	<primary>limiting users</primary>
	<secondary>maxproc</secondary>
	</indexterm>
	- <para>This is the maximum number of processes a user may be
	- running. This includes foreground and background
	- processes alike. For obvious reasons, this may not be
	- larger than the system limit specified by the
	- <varname>kern.maxproc</varname> &man.sysctl.8;. Also note
	- that setting this too small may hinder a user's
	- productivity: it is often useful to be logged in multiple
	- times or execute pipelines. Some tasks, such as
	- compiling a large program, also spawn multiple processes
	- (e.g., &man.make.1;, &man.cc.1;, and other intermediate
	- preprocessors).</para>
	+ <para>The maximum number of processes a user can run. This
	+ includes foreground and background processes. This limit
	+ may not be larger than the system limit specified by the
	+ <varname>kern.maxproc</varname> &man.sysctl.8;. Setting
	+ this limit too small may hinder a user's productivity as
	+ it is often useful to be logged in multiple times or to
	+ execute pipelines. Some tasks, such as compiling a large
	+ program, spawn multiple processes and other intermediate
	+ preprocessors.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>memorylocked</literal></term>

	<listitem>
	<indexterm><primary>memorylocked</primary></indexterm>
	<indexterm>
	<primary>limiting users</primary>
	<secondary>memorylocked</secondary>
	</indexterm>
	- <para>This is the maximum amount a memory a process may have
	- requested to be locked into main memory (e.g., see
	- &man.mlock.2;). Some system-critical programs, such as
	- &man.amd.8;, lock into main memory such that in the event
	- of being swapped out, they do not contribute to
	- a system's thrashing in time of trouble.</para>
	+ <para>The maximum amount of memory a process may request
	+ to be locked into main memory using &man.mlock.2;. Some
	+ system-critical programs, such as &man.amd.8;, lock into
	+ main memory so that if the system begins to swap, they do
	+ not contribute to disk thrashing.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>memoryuse</literal></term>

	<listitem>
	<indexterm><primary>memoryuse</primary></indexterm>
	<indexterm><primary>limiting users</primary>
	- <secondary>memoryuse</secondary>
	- </indexterm>
	- <para>This is the maximum amount of memory a process may
	- consume at any given time. It includes both core memory and
	- swap usage. This is not a catch-all limit for restricting
	- memory consumption, but it is a good start.</para>
	+ <secondary>memoryuse</secondary></indexterm>
	+ <para>The maximum amount of memory a process may consume at
	+ any given time. It includes both core memory and swap
	+ usage. This is not a catch-all limit for restricting
	+ memory consumption, but is a good start.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>openfiles</literal></term>

	<listitem>
	<indexterm><primary>openfiles</primary></indexterm>
	<indexterm><primary>limiting users</primary>
	<secondary>openfiles</secondary>
	</indexterm>
	- <para>This is the maximum amount of files a process may have
	- open. In FreeBSD, files are also used to represent
	- sockets and IPC channels; thus, be careful not to set this
	- too low. The system-wide limit for this is defined by the
	+ <para>The maximum number of files a process may have open.
	+ In &os;, files are used to represent sockets and IPC
	+ channels, so be careful not to set this too low. The
	+ system-wide limit for this is defined by the
	<varname>kern.maxfiles</varname> &man.sysctl.8;.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>sbsize</literal></term>

	<listitem>
	<indexterm><primary>sbsize</primary></indexterm>
	<indexterm><primary>limiting users</primary>
	<secondary>sbsize</secondary>
	</indexterm>
	- <para>This is the limit on the amount of network memory, and
	- thus mbufs, a user may consume. This originated as a
	- response to an old DoS attack by creating a lot of
	- sockets, but can be generally used to limit network
	+ <para>The limit on the amount of network memory, and
	+ thus mbufs, a user may consume in order to limit network
	communications.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><literal>stacksize</literal></term>

	<listitem>
	<indexterm><primary>stacksize</primary></indexterm>
	<indexterm><primary>limiting users</primary>
	<secondary>stacksize</secondary>
	</indexterm>
	- <para>This is the maximum size a process' stack may grow to.
	- This alone is not sufficient to limit the amount of memory
	- a program may use; consequently, it should be used in
	- conjunction with other limits.</para>
	+ <para>The maximum size of a process stack. This alone is
	+ not sufficient to limit the amount of memory a program
	+ may use so it should be used in conjunction with other
	+ limits.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>There are a few other things to remember when setting
	resource limits. Following are some general tips, suggestions,
	and miscellaneous comments.</para>

	<itemizedlist>
	<listitem>
	<para>Processes started at system startup by
	<filename>/etc/rc</filename> are assigned to the
	<literal>daemon</literal> login class.</para>
	</listitem>

	<listitem>
	<para>Although the <filename>/etc/login.conf</filename> that
	comes with the system is a good source of reasonable values
	- for most limits, only you, the administrator, can know what
	- is appropriate for your system. Setting a limit too high
	- may open your system up to abuse, while setting it too low
	- may put a strain on productivity.</para>
	+ for most limits, they may not be appropriate for every
	+ system. Setting a limit too high may open the system up to
	+ abuse, while setting it too low may put a strain on
	+ productivity.</para>
	</listitem>

	<listitem>
	- <para>Users of the X Window System (X11) should probably be
	- granted more resources than other users. X11 by itself
	- takes a lot of resources, but it also encourages users to
	- run more programs simultaneously.</para>
	+ <para>Users of <application>&xorg;</application> should
	+ probably be granted more resources than other users.
	+ <application>&xorg;</application> by itself takes a lot of
	+ resources, but it also encourages users to run more programs
	+ simultaneously.</para>
	</listitem>

	<listitem>
	- <para>Remember that many limits apply to individual processes,
	- not the user as a whole. For example, setting
	+ <para>Many limits apply to individual processes, not the user
	+ as a whole. For example, setting
	<varname>openfiles</varname> to 50 means that each process
	- the user runs may open up to 50 files. Thus, the gross
	- amount of files a user may open is the value of
	+ the user runs may open up to 50 files. The total amount
	+ of files a user may open is the value of
	<literal>openfiles</literal> multiplied by the value of
	<literal>maxproc</literal>. This also applies to memory
	consumption.</para>
	</listitem>
	</itemizedlist>

	<para>For further information on resource limits and login classes
	- and capabilities in general, please consult the relevant manual
	- pages: &man.cap.mkdb.1;, &man.getrlimit.2;,
	- &man.login.conf.5;.</para>
	+ and capabilities in general, refer to &man.cap.mkdb.1;,
	+ &man.getrlimit.2;, and &man.login.conf.5;.</para>
	</sect1>

	<sect1 id="users-groups">
	<title>Groups</title>

	<indexterm><primary>groups</primary></indexterm>
	<indexterm>
	<primary><filename>/etc/groups</filename></primary>
	</indexterm>
	<indexterm>
	<primary>accounts</primary>
	<secondary>groups</secondary>
	</indexterm>
	- <para>A group is simply a list of users. Groups are identified by
	- their group name and GID (Group ID). In FreeBSD (and most other
	- &unix; like systems), the two factors the kernel uses to decide
	- whether a process is allowed to do something is its user ID and
	- list of groups it belongs to. Unlike a user ID, a process has a
	- list of groups associated with it. You may hear some things
	- refer to the <quote>group ID</quote> of a user or process; most
	- of the time, this just means the first group in the list.</para>
	+ <para>A group is a list of users. A group is identified by its
	+ group name and <acronym>GID</acronym>. In &os;, the
	+ kernel uses the <acronym>UID</acronym> of a process, and the
	+ list of groups it belongs to, to determine what the process is
	+ allowed to do. Most of the time, the <acronym>GID</acronym> of
	+ a user or process usually means the first group in the
	+ list.</para>

	- <para>The group name to group ID map is in
	- <filename>/etc/group</filename>. This is a plain text file with
	- four colon-delimited fields. The first field is the group name,
	- the second is the encrypted password, the third the group ID,
	- and the fourth the comma-delimited list of members. It can
	- safely be edited by hand (assuming, of course, that you do not
	- make any syntax errors!). For a more complete description of
	- the syntax, see the &man.group.5; manual page.</para>
	+ <para>The group name to <acronym>GID</acronym> mapping is listed
	+ in <filename>/etc/group</filename>. This is a plain text file
	+ with four colon-delimited fields. The first field is the group
	+ name, the second is the encrypted password, the third the
	+ <acronym>GID</acronym>, and the fourth the comma-delimited list
	+ of members. For a more complete description of the syntax,
	+ refer to &man.group.5;.</para>

	- <para>If you do not want to edit <filename>/etc/group</filename>
	- manually, you can use the &man.pw.8; command to add and edit
	- groups. For example, to add a group called
	- <groupname>teamtwo</groupname> and then confirm that it exists
	- you can use:</para>
	+ <para>The superuser can modify <filename>/etc/group</filename>
	+ using a text editor. Alternatively, &man.pw.8; can be used to
	+ add and edit groups. For example, to add a group called
	+ <groupname>teamtwo</groupname> and then confirm that it
	+ exists:</para>

	<example>
	<title>Adding a Group Using &man.pw.8;</title>

	<screen>&prompt.root; <userinput>pw groupadd teamtwo</userinput>
	&prompt.root; <userinput>pw groupshow teamtwo</userinput>
	teamtwo:*:1100:</screen>
	</example>

	- <para>The number <literal>1100</literal> above is the group ID of
	- the group <groupname>teamtwo</groupname>. Right now,
	- <groupname>teamtwo</groupname> has no members, and is thus
	- rather useless. Let's change that by inviting
	- <username>jru</username> to the <groupname>teamtwo</groupname>
	- group.</para>
	+ <para>In this example, <literal>1100</literal> is the
	+ <acronym>GID</acronym> of <groupname>teamtwo</groupname>. Right
	+ now, <groupname>teamtwo</groupname> has no members. This
	+ command will add <username>jru</username> as a member of
	+ <groupname>teamtwo</groupname>.</para>

	<example>
	- <title>Setting the List of Members of a Group Using
	+ <title>Adding User Accounts to a New Group Using
	&man.pw.8;</title>

	<screen>&prompt.root; <userinput>pw groupmod teamtwo -M jru</userinput>
	&prompt.root; <userinput>pw groupshow teamtwo</userinput>
	teamtwo:*:1100:jru</screen>
	</example>

	- <para>The argument to the <option>-M</option> option is a
	- comma-delimited list of users who are to be in the group. From
	- the preceding sections, we know that the password file also
	- contains a group for each user. The latter (the user) is
	- automatically added to the group list by the system; the user
	- will not show up as a member when using the
	- <option>groupshow</option> command to &man.pw.8;, but will show
	- up when the information is queried via &man.id.1; or similar
	- tool. In other words, &man.pw.8; only manipulates the
	- <filename>/etc/group</filename> file; it will never attempt to
	- read additionally data from
	+ <para>The argument to <option>-M</option> is a comma-delimited
	+ list of users to be added to a new (empty) group or to replace
	+ the members of an existing group. To the user, this group
	+ membership is different from (and in addition to) the user's
	+ primary group listed in the password file. This means that
	+ the user will not show up as a member when using
	+ <option>groupshow</option> with &man.pw.8;, but will show up
	+ when the information is queried via &man.id.1; or a similar
	+ tool. When &man.pw.8; is used to add a user to a group, it only
	+ manipulates <filename>/etc/group</filename> and does not attempt
	+ to read additional data from
	<filename>/etc/passwd</filename>.</para>

	<example>
	<title>Adding a New Member to a Group Using &man.pw.8;</title>

	<screen>&prompt.root; <userinput>pw groupmod teamtwo -m db</userinput>
	&prompt.root; <userinput>pw groupshow teamtwo</userinput>
	teamtwo:*:1100:jru,db</screen>
	</example>

	- <para>The argument to the <option>-m</option> option is a
	+ <para>In this example, the argument to <option>-m</option> is a
	comma-delimited list of users who are to be added to the group.
	- Unlike the previous example, these users are added to the group
	- and do not replace the list of users in the group.</para>
	+ Unlike the previous example, these users are appended to the
	+ group list and do not replace the list of existing users in the
	+ group.</para>

	<example>
	<title>Using &man.id.1; to Determine Group Membership</title>

	<screen>&prompt.user; <userinput>id jru</userinput>
	uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)</screen>
	</example>

	- <para>As you can see, <username>jru</username> is a member of the
	+ <para>In this example, <username>jru</username> is a member of the
	groups <groupname>jru</groupname> and
	<groupname>teamtwo</groupname>.</para>

	- <para>For more information about &man.pw.8;, see its manual page,
	- and for more information on the format of
	- <filename>/etc/group</filename>, consult the &man.group.5;
	- manual page.</para>
	+ <para>For more information about this command and the format of
	+ <filename>/etc/group</filename>, refer to &man.pw.8; and
	+ &man.group.5;.</para>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/vinum/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/vinum/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/vinum/chapter.xml (revision 41355)
	@@ -1,1297 +1,1251 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The Vinum Volume Manager
	By Greg Lehey (grog at lemis dot com)

	Added to the Handbook by Hiten Pandya <hmp@FreeBSD.org>
	and Tom Rhodes <trhodes@FreeBSD.org>

	For the FreeBSD Documentation Project
	$FreeBSD$
	-->

	<chapter id="vinum-vinum">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Greg</firstname>
	<surname>Lehey</surname>
	<contrib>Originally written by </contrib>
	</author>
	</authorgroup>
	</chapterinfo>

	- <title>The Vinum Volume Manager</title>
	+ <title>The <devicename>vinum</devicename> Volume Manager</title>

	<sect1 id="vinum-synopsis">
	<title>Synopsis</title>

	- <para>No matter what disks you have, there are always potential
	- problems:</para>
	+ <para>No matter the type of disks, there are always potential
	+ problems. The disks can be too small, too slow, or too
	+ unreliable to meet the system's requirements. While disks are
	+ getting bigger, so are data storage requirements. Often a file
	+ system is needed that is bigger than a disk's capacity. Various
	+ solutions to these problems have been proposed and
	+ implemented.</para>

	- <itemizedlist>
	- <listitem>
	- <para>They can be too small.</para>
	- </listitem>
	-
	- <listitem>
	- <para>They can be too slow.</para>
	- </listitem>
	-
	- <listitem>
	- <para>They can be too unreliable.</para>
	- </listitem>
	- </itemizedlist>
	-
	- <para>Various solutions to these problems have been proposed and
	- implemented. One way some users safeguard themselves against
	- such issues is through the use of multiple, and sometimes
	+ <para>One method is through the use of multiple, and sometimes
	redundant, disks. In addition to supporting various cards and
	- controllers for hardware RAID systems, the base &os; system
	- includes the Vinum Volume Manager, a block device driver that
	- implements virtual disk drives. <emphasis>Vinum</emphasis> is a
	- so-called <emphasis>Volume Manager</emphasis>, a virtual disk
	- driver that addresses these three problems. Vinum provides more
	- flexibility, performance, and reliability than traditional disk
	- storage, and implements RAID-0, RAID-1, and RAID-5 models both
	- individually and in combination.</para>
	+ controllers for hardware Redundant Array of Independent
	+ Disks <acronym>RAID</acronym> systems, the base &os; system
	+ includes the <devicename>vinum</devicename> volume manager, a
	+ block device driver that implements virtual disk drives and
	+ addresses these three problems. <devicename>vinum</devicename>
	+ provides more flexibility, performance, and reliability than
	+ traditional disk storage and implements
	+ <acronym>RAID</acronym>-0, <acronym>RAID</acronym>-1, and
	+ <acronym>RAID</acronym>-5 models, both individually and in
	+ combination.</para>

	<para>This chapter provides an overview of potential problems with
	- traditional disk storage, and an introduction to the Vinum
	- Volume Manager.</para>
	+ traditional disk storage, and an introduction to the
	+ <devicename>vinum</devicename> volume manager.</para>

	<note>
	- <para>Starting with &os; 5, Vinum has been rewritten in
	- order to fit into the GEOM architecture (<xref
	- linkend="GEOM"/>), retaining the original ideas,
	- terminology, and on-disk metadata. This rewrite is called
	- <emphasis>gvinum</emphasis> (for <emphasis> GEOM
	- vinum</emphasis>). The following text usually refers to
	- <emphasis>Vinum</emphasis> as an abstract name, regardless of
	- the implementation variant. Any command invocations should
	- now be done using the <command>gvinum</command> command, and
	- the name of the kernel module has been changed from
	+ <para>Starting with &os; 5, <devicename>vinum</devicename>
	+ has been rewritten in order to fit into the <link
	+ linkend="GEOM">GEOM architecture</link>, while retaining the
	+ original ideas, terminology, and on-disk metadata. This
	+ rewrite is called <emphasis>gvinum</emphasis> (for <emphasis>
	+ GEOM vinum</emphasis>). While this chapter uses the term
	+ <devicename>vinum</devicename>, any command invocations should
	+ be performed with <command>gvinum</command>. The name of the
	+ kernel module has changed from the original
	<filename>vinum.ko</filename> to
	<filename>geom_vinum.ko</filename>, and all device nodes
	reside under <filename
	class="directory">/dev/gvinum</filename> instead of
	<filename class="directory">/dev/vinum</filename>. As of
	- &os; 6, the old Vinum implementation is no longer
	- available in the code base.</para>
	+ &os; 6, the original <devicename>vinum</devicename>
	+ implementation is no longer available in the code base.</para>
	</note>
	-
	</sect1>

	- <sect1 id="vinum-intro">
	- <title>Disks Are Too Small</title>
	-
	- <indexterm><primary>Vinum</primary></indexterm>
	- <indexterm><primary>RAID</primary>
	- <secondary>software</secondary></indexterm>
	-
	- <para>Disks are getting bigger, but so are data storage
	- requirements. Often you will find you want a file system that
	- is bigger than the disks you have available. Admittedly, this
	- problem is not as acute as it was ten years ago, but it still
	- exists. Some systems have solved this by creating an abstract
	- device which stores its data on a number of disks.</para>
	- </sect1>
	-
	<sect1 id="vinum-access-bottlenecks">
	<title>Access Bottlenecks</title>

	<para>Modern systems frequently need to access data in a highly
	concurrent manner. For example, large FTP or HTTP servers can
	maintain thousands of concurrent sessions and have multiple
	100 Mbit/s connections to the outside world, well beyond
	the sustained transfer rate of most disks.</para>

	<para>Current disk drives can transfer data sequentially at up to
	70 MB/s, but this value is of little importance in an
	- environment where many independent processes access a drive,
	+ environment where many independent processes access a drive, and
	where they may achieve only a fraction of these values. In such
	- cases it is more interesting to view the problem from the
	- viewpoint of the disk subsystem: the important parameter is the
	- load that a transfer places on the subsystem, in other words the
	- time for which a transfer occupies the drives involved in the
	+ cases, it is more interesting to view the problem from the
	+ viewpoint of the disk subsystem. The important parameter is the
	+ load that a transfer places on the subsystem, or the time for
	+ which a transfer occupies the drives involved in the
	transfer.</para>

	<para>In any disk transfer, the drive must first position the
	heads, wait for the first sector to pass under the read head,
	and then perform the transfer. These actions can be considered
	- to be atomic: it does not make any sense to interrupt
	+ to be atomic as it does not make any sense to interrupt
	them.</para>

	<para><anchor id="vinum-latency"/> Consider a typical transfer of
	about 10 kB: the current generation of high-performance
	disks can position the heads in an average of 3.5 ms. The
	fastest drives spin at 15,000 rpm, so the average
	rotational latency (half a revolution) is 2 ms. At
	70 MB/s, the transfer itself takes about 150 μs,
	almost nothing compared to the positioning time. In such a
	case, the effective transfer rate drops to a little over
	1 MB/s and is clearly highly dependent on the transfer
	size.</para>

	<para>The traditional and obvious solution to this bottleneck is
	- <quote>more spindles</quote>: rather than using one large disk,
	- it uses several smaller disks with the same aggregate storage
	+ <quote>more spindles</quote>: rather than using one large disk,
	+ use several smaller disks with the same aggregate storage
	space. Each disk is capable of positioning and transferring
	independently, so the effective throughput increases by a factor
	close to the number of disks used.</para>

	- <para>The exact throughput improvement is, of course, smaller than
	- the number of disks involved: although each drive is capable of
	+ <para>The actual throughput improvement is smaller than the
	+ number of disks involved. Although each drive is capable of
	transferring in parallel, there is no way to ensure that the
	requests are evenly distributed across the drives. Inevitably
	the load on one drive will be higher than on another.</para>

	<indexterm>
	<primary>disk concatenation</primary>
	</indexterm>
	<indexterm>
	<primary>Vinum</primary>
	<secondary>concatenation</secondary>
	</indexterm>

	<para>The evenness of the load on the disks is strongly dependent
	on the way the data is shared across the drives. In the
	following discussion, it is convenient to think of the disk
	storage as a large number of data sectors which are addressable
	by number, rather like the pages in a book. The most obvious
	method is to divide the virtual disk into groups of consecutive
	sectors the size of the individual physical disks and store them
	in this manner, rather like taking a large book and tearing it
	into smaller sections. This method is called
	<emphasis>concatenation</emphasis> and has the advantage that
	the disks are not required to have any specific size
	relationships. It works well when the access to the virtual
	disk is spread evenly about its address space. When access is
	concentrated on a smaller area, the improvement is less marked.
	- <xref linkend="vinum-concat"/> illustrates the sequence in which
	- storage units are allocated in a concatenated
	+ <link linkend="vinum-concat"></link> illustrates the sequence in
	+ which storage units are allocated in a concatenated
	organization.</para>

	<para>
	<figure id="vinum-concat">
	<title>Concatenated Organization</title>

	<graphic fileref="vinum/vinum-concat"/>
	</figure></para>

	<indexterm>
	<primary>disk striping</primary>
	</indexterm>
	<indexterm>
	<primary>Vinum</primary>
	<secondary>striping</secondary>
	</indexterm>
	<indexterm>
	- <primary>RAID</primary>
	+ <primary><acronym>RAID</acronym></primary>
	</indexterm>

	<para>An alternative mapping is to divide the address space into
	smaller, equal-sized components and store them sequentially on
	different devices. For example, the first 256 sectors may be
	stored on the first disk, the next 256 sectors on the next disk
	and so on. After filling the last disk, the process repeats
	until the disks are full. This mapping is called
	- <emphasis>striping</emphasis> or <acronym>RAID-0</acronym>
	+ <emphasis>striping</emphasis> or
	+ <acronym>RAID-0</acronym>.</para>

	- <footnote>
	- <para><acronym>RAID</acronym> stands for <emphasis>Redundant
	- Array of Inexpensive Disks</emphasis> and offers various
	- forms of fault tolerance, though the latter term is somewhat
	- misleading: it provides no redundancy.</para> </footnote>.
	+ <para><acronym>RAID</acronym> offers various forms of fault
	+ tolerance, though <acronym>RAID-0</acronym> is somewhat
	+ misleading as it provides no redundancy. Striping requires
	+ somewhat more effort to locate the data, and it can cause
	+ additional I/O load where a transfer is spread over multiple
	+ disks, but it can also provide a more constant load across the
	+ disks. <link linkend="vinum-striped"></link> illustrates the
	+ sequence in which storage units are allocated in a striped
	+ organization.</para>

	- Striping requires somewhat more effort to locate the
	- data, and it can cause additional I/O load where a transfer is
	- spread over multiple disks, but it can also provide a more
	- constant load across the disks. <xref linkend="vinum-striped"/>
	- illustrates the sequence in which storage units are allocated in
	- a striped organization.</para>
	-
	<para>
	<figure id="vinum-striped">
	<title>Striped Organization</title>

	<graphic fileref="vinum/vinum-striped"/>
	</figure></para>
	</sect1>

	<sect1 id="vinum-data-integrity">
	<title>Data Integrity</title>

	- <para>The final problem with current disks is that they are
	- unreliable. Although disk drive reliability has increased
	- tremendously over the last few years, they are still the most
	- likely core component of a server to fail. When they do, the
	- results can be catastrophic: replacing a failed disk drive and
	- restoring data to it can take days.</para>
	+ <para>The final problem with disks is that they are unreliable.
	+ Although reliability has increased tremendously over the last
	+ few years, disk drives are still the most likely core component
	+ of a server to fail. When they do, the results can be
	+ catastrophic and replacing a failed disk drive and restoring
	+ data can result in server downtime.</para>

	<indexterm>
	<primary>disk mirroring</primary>
	</indexterm>
	- <indexterm><primary>Vinum</primary>
	+ <indexterm><primary>vinum</primary>
	<secondary>mirroring</secondary>
	</indexterm>
	- <indexterm><primary>RAID-1</primary>
	+ <indexterm><primary><acronym>RAID</acronym>-1</primary>
	</indexterm>

	- <para>The traditional way to approach this problem has been
	- <emphasis>mirroring</emphasis>, keeping two copies of the data
	- on different physical hardware. Since the advent of the
	- <acronym>RAID</acronym> levels, this technique has also been
	- called <acronym>RAID level 1</acronym> or
	- <acronym>RAID-1</acronym>. Any write to the volume writes to
	- both locations; a read can be satisfied from either, so if one
	- drive fails, the data is still available on the other
	+ <para>One approach to this problem is
	+ <emphasis>mirroring</emphasis>, or
	+ <acronym>RAID-1</acronym>, which keeps two copies of the
	+ data on different physical hardware. Any write to the volume
	+ writes to both disks; a read can be satisfied from either, so if
	+ one drive fails, the data is still available on the other
	drive.</para>

	<para>Mirroring has two problems:</para>

	<itemizedlist>
	<listitem>
	- <para>The price. It requires twice as much disk storage as
	- a non-redundant solution.</para>
	+ <para>It requires twice as much disk storage as a
	+ non-redundant solution.</para>
	</listitem>

	<listitem>
	- <para>The performance impact. Writes must be performed to
	- both drives, so they take up twice the bandwidth of a
	- non-mirrored volume. Reads do not suffer from a
	- performance penalty: it even looks as if they are
	+ <para>Writes must be performed to both drives, so they take up
	+ twice the bandwidth of a non-mirrored volume. Reads do not
	+ suffer from a performance penalty and can even be
	faster.</para>
	</listitem>
	</itemizedlist>

	- <para><indexterm><primary>RAID-5</primary></indexterm>An
	- alternative solution is <emphasis>parity</emphasis>, implemented
	- in the <acronym>RAID</acronym> levels 2, 3, 4 and 5. Of these,
	- <acronym>RAID-5</acronym> is the most interesting. As
	- implemented in Vinum, it is a variant on a striped organization
	- which dedicates one block of each stripe to parity one of the
	- other blocks. As implemented by Vinum, a
	+ <indexterm><primary><acronym>RAID</acronym>-5</primary></indexterm>
	+
	+ <para>An alternative solution is <emphasis>parity</emphasis>,
	+ implemented in <acronym>RAID</acronym> levels 2, 3, 4 and 5.
	+ Of these, <acronym>RAID-5</acronym> is the most interesting. As
	+ implemented in <devicename>vinum</devicename>, it is a variant
	+ on a striped organization which dedicates one block of each
	+ stripe to parity one of the other blocks. As implemented by
	+ <devicename>vinum</devicename>, a
	<acronym>RAID-5</acronym> plex is similar to a striped plex,
	except that it implements <acronym>RAID-5</acronym> by
	including a parity block in each stripe. As required by
	<acronym>RAID-5</acronym>, the location of this parity block
	changes from one stripe to the next. The numbers in the data
	blocks indicate the relative block numbers.</para>

	<para>
	<figure id="vinum-raid5-org">
	- <title>RAID-5 Organization</title>
	+ <title><acronym>RAID</acronym>-5 Organization</title>

	<graphic fileref="vinum/vinum-raid5-org"/>
	</figure></para>

	<para>Compared to mirroring, <acronym>RAID-5</acronym> has the
	advantage of requiring significantly less storage space. Read
	access is similar to that of striped organizations, but write
	access is significantly slower, approximately 25% of the read
	performance. If one drive fails, the array can continue to
	- operate in degraded mode: a read from one of the remaining
	+ operate in degraded mode where a read from one of the remaining
	accessible drives continues normally, but a read from the
	failed drive is recalculated from the corresponding block from
	all the remaining drives.</para>
	</sect1>

	<sect1 id="vinum-objects">
	- <title>Vinum Objects</title>
	+ <title><devicename>vinum</devicename> Objects</title>

	- <para>In order to address these problems, Vinum implements a
	- four-level hierarchy of objects:</para>
	+ <para>In order to address these problems,
	+ <devicename>vinum</devicename> implements a four-level hierarchy
	+ of objects:</para>

	<itemizedlist>
	<listitem>
	<para>The most visible object is the virtual disk, called a
	<emphasis>volume</emphasis>. Volumes have essentially the
	same properties as a &unix; disk drive, though there are
	- some minor differences. They have no size
	+ some minor differences. For one, they have no size
	limitations.</para>
	</listitem>

	<listitem>
	<para>Volumes are composed of <emphasis>plexes</emphasis>,
	each of which represent the total address space of a
	- volume. This level in the hierarchy thus provides
	- redundancy. Think of plexes as individual disks in a
	- mirrored array, each containing the same data.</para>
	+ volume. This level in the hierarchy provides redundancy.
	+ Think of plexes as individual disks in a mirrored array,
	+ each containing the same data.</para>
	</listitem>

	<listitem>
	- <para>Since Vinum exists within the &unix; disk storage
	- framework, it would be possible to use &unix; partitions
	- as the building block for multi-disk plexes, but in fact
	- this turns out to be too inflexible: &unix; disks can have
	- only a limited number of partitions. Instead, Vinum
	- subdivides a single &unix; partition (the
	- <emphasis>drive</emphasis>) into contiguous areas called
	- <emphasis>subdisks</emphasis>, which it uses as building
	- blocks for plexes.</para>
	+ <para>Since <devicename>vinum</devicename> exists within the
	+ &unix; disk storage framework, it would be possible to use
	+ &unix; partitions as the building block for multi-disk
	+ plexes. In fact, this turns out to be too inflexible as
	+ &unix; disks can have only a limited number of partitions.
	+ Instead, <devicename>vinum</devicename> subdivides a single
	+ &unix; partition, the <emphasis>drive</emphasis>, into
	+ contiguous areas called <emphasis>subdisks</emphasis>, which
	+ are used as building blocks for plexes.</para>
	</listitem>

	<listitem>
	- <para>Subdisks reside on Vinum <emphasis>drives</emphasis>,
	- currently &unix; partitions. Vinum drives can contain any
	+ <para>Subdisks reside on <devicename>vinum</devicename>
	+ <emphasis>drives</emphasis>, currently &unix; partitions.
	+ <devicename>vinum</devicename> drives can contain any
	number of subdisks. With the exception of a small area at
	the beginning of the drive, which is used for storing
	configuration and state information, the entire drive is
	available for data storage.</para>
	</listitem>
	</itemizedlist>

	<para>The following sections describe the way these objects
	- provide the functionality required of Vinum.</para>
	+ provide the functionality required of
	+ <devicename>vinum</devicename>.</para>

	<sect2>
	<title>Volume Size Considerations</title>

	<para>Plexes can include multiple subdisks spread over all
	- drives in the Vinum configuration. As a result, the size of
	- an individual drive does not limit the size of a plex, and
	- thus of a volume.</para>
	+ drives in the <devicename>vinum</devicename> configuration.
	+ As a result, the size of an individual drive does not limit
	+ the size of a plex or a volume.</para>
	</sect2>

	<sect2>
	<title>Redundant Data Storage</title>

	- <para>Vinum implements mirroring by attaching multiple plexes to
	- a volume. Each plex is a representation of the data in a
	- volume. A volume may contain between one and eight
	- plexes.</para>
	+ <para><devicename>vinum</devicename> implements mirroring by
	+ attaching multiple plexes to a volume. Each plex is a
	+ representation of the data in a volume. A volume may contain
	+ between one and eight plexes.</para>

	<para>Although a plex represents the complete data of a volume,
	it is possible for parts of the representation to be
	physically missing, either by design (by not defining a
	subdisk for parts of the plex) or by accident (as a result of
	the failure of a drive). As long as at least one plex can
	provide the data for the complete address range of the volume,
	the volume is fully functional.</para>
	</sect2>

	<sect2>
	- <title>Performance Issues</title>
	+ <title>Which Plex Organization?</title>

	- <para>Vinum implements both concatenation and striping at the
	- plex level:</para>
	+ <para><devicename>vinum</devicename> implements both
	+ concatenation and striping at the plex level:</para>

	<itemizedlist>
	<listitem>
	<para>A <emphasis>concatenated plex</emphasis> uses the
	- address space of each subdisk in turn.</para>
	+ address space of each subdisk in turn. Concatenated
	+ plexes are the most flexible as they can contain any
	+ number of subdisks, and the subdisks may be of different
	+ length. The plex may be extended by adding additional
	+ subdisks. They require less <acronym>CPU</acronym>
	+ time than striped plexes, though the difference in
	+ <acronym>CPU</acronym> overhead is not measurable. On
	+ the other hand, they are most susceptible to hot spots,
	+ where one disk is very active and others are idle.</para>
	</listitem>

	<listitem>
	<para>A <emphasis>striped plex</emphasis> stripes the data
	- across each subdisk. The subdisks must all have the same
	- size, and there must be at least two subdisks in order to
	- distinguish it from a concatenated plex.</para>
	+ across each subdisk. The subdisks must all be the same
	+ size and there must be at least two subdisks in order to
	+ distinguish it from a concatenated plex. The greatest
	+ advantage of striped plexes is that they reduce hot spots.
	+ By choosing an optimum sized stripe, about 256 kB,
	+ the load can be evened out on the component drives.
	+ Extending a plex by adding new subdisks is so complicated
	+ that <devicename>vinum</devicename> does not implement
	+ it.</para>
	</listitem>
	</itemizedlist>
	- </sect2>

	- <sect2>
	- <title>Which Plex Organization?</title>
	-
	- <para>The version of Vinum supplied with &os; &rel.current;
	- implements two kinds of plex:</para>
	-
	- <itemizedlist>
	- <listitem>
	- <para>Concatenated plexes are the most flexible: they can
	- contain any number of subdisks, and the subdisks may be of
	- different length. The plex may be extended by adding
	- additional subdisks. They require less
	- <acronym>CPU</acronym> time than striped plexes, though
	- the difference in <acronym>CPU</acronym> overhead is not
	- measurable. On the other hand, they are most susceptible
	- to hot spots, where one disk is very active and others are
	- idle.</para>
	- </listitem>
	-
	- <listitem>
	- <para>The greatest advantage of striped
	- (<acronym>RAID-0</acronym>) plexes is that they reduce hot
	- spots: by choosing an optimum sized stripe (about
	- 256 kB), you can even out the load on the component
	- drives. The disadvantages of this approach are
	- (fractionally) more complex code and restrictions on
	- subdisks: they must be all the same size, and extending a
	- plex by adding new subdisks is so complicated that Vinum
	- currently does not implement it. Vinum imposes an
	- additional, trivial restriction: a striped plex must have
	- at least two subdisks, since otherwise it is
	- indistinguishable from a concatenated plex.</para>
	- </listitem>
	- </itemizedlist>
	-
	- <para><xref linkend="vinum-comparison"/> summarizes the
	+ <para><link linkend="vinum-comparison"></link> summarizes the
	advantages and disadvantages of each plex organization.</para>

	<table id="vinum-comparison" frame="none">
	- <title>Vinum Plex Organizations</title>
	+ <title><devicename>vinum</devicename> Plex
	+ Organizations</title>

	<tgroup cols="5">
	<thead>
	<row>
	<entry>Plex type</entry>
	<entry>Minimum subdisks</entry>
	<entry>Can add subdisks</entry>
	<entry>Must be equal size</entry>
	<entry>Application</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>concatenated</entry>
	<entry>1</entry>
	<entry>yes</entry>
	<entry>no</entry>
	<entry>Large data storage with maximum placement
	flexibility and moderate performance</entry>
	</row>

	<row>
	<entry>striped</entry>
	<entry>2</entry>
	<entry>no</entry>
	<entry>yes</entry>
	<entry>High performance in combination with highly
	concurrent access</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect2>
	</sect1>

	<sect1 id="vinum-examples">
	<title>Some Examples</title>

	- <para>Vinum maintains a <emphasis>configuration
	- database</emphasis> which describes the objects known to an
	- individual system. Initially, the user creates the
	- configuration database from one or more configuration files with
	- the aid of the &man.gvinum.8; utility program. Vinum stores a
	- copy of its configuration database on each disk slice (which
	- Vinum calls a <emphasis>device</emphasis>) under its control.
	- This database is updated on each state change, so that a restart
	- accurately restores the state of each Vinum object.</para>
	+ <para><devicename>vinum</devicename> maintains a
	+ <emphasis>configuration database</emphasis> which describes the
	+ objects known to an individual system. Initially, the user
	+ creates the configuration database from one or more
	+ configuration files using &man.gvinum.8;.
	+ <devicename>vinum</devicename> stores a copy of its
	+ configuration database on each disk
	+ <emphasis>device</emphasis> under its control. This database is
	+ updated on each state change, so that a restart accurately
	+ restores the state of each
	+ <devicename>vinum</devicename> object.</para>

	<sect2>
	<title>The Configuration File</title>

	- <para>The configuration file describes individual Vinum objects.
	- The definition of a simple volume might be:</para>
	+ <para>The configuration file describes individual
	+ <devicename>vinum</devicename> objects. The definition of a
	+ simple volume might be:</para>

	<programlisting> drive a device /dev/da3h
	volume myvol
	plex org concat
	sd length 512m drive a</programlisting>

	- <para>This file describes four Vinum objects:</para>
	+ <para>This file describes four <devicename>vinum</devicename>
	+ objects:</para>

	<itemizedlist>
	<listitem>
	<para>The <emphasis>drive</emphasis> line describes a disk
	partition (<emphasis>drive</emphasis>) and its location
	relative to the underlying hardware. It is given the
	symbolic name <emphasis>a</emphasis>. This separation of
	- the symbolic names from the device names allows disks to
	- be moved from one location to another without
	- confusion.</para>
	+ symbolic names from device names allows disks to be moved
	+ from one location to another without confusion.</para>
	</listitem>

	<listitem>
	<para>The <emphasis>volume</emphasis> line describes a
	volume. The only required attribute is the name, in this
	case <emphasis>myvol</emphasis>.</para>
	</listitem>

	<listitem>
	<para>The <emphasis>plex</emphasis> line defines a plex.
	The only required parameter is the organization, in this
	- case <emphasis>concat</emphasis>. No name is necessary:
	+ case <emphasis>concat</emphasis>. No name is necessary as
	the system automatically generates a name from the volume
	name by adding the suffix
	<emphasis>.p</emphasis><emphasis>x</emphasis>, where
	<emphasis>x</emphasis> is the number of the plex in the
	volume. Thus this plex will be called
	<emphasis>myvol.p0</emphasis>.</para>
	</listitem>

	<listitem>
	<para>The <emphasis>sd</emphasis> line describes a subdisk.
	The minimum specifications are the name of a drive on
	- which to store it, and the length of the subdisk. As with
	- plexes, no name is necessary: the system automatically
	- assigns names derived from the plex name by adding the
	- suffix <emphasis>.s</emphasis><emphasis>x</emphasis>,
	- where <emphasis>x</emphasis> is the number of the subdisk
	- in the plex. Thus Vinum gives this subdisk the name
	- <emphasis>myvol.p0.s0</emphasis>.</para>
	+ which to store it, and the length of the subdisk. No name
	+ is necessary as the system automatically assigns names
	+ derived from the plex name by adding the suffix
	+ <emphasis>.s</emphasis><emphasis>x</emphasis>, where
	+ <emphasis>x</emphasis> is the number of the subdisk in
	+ the plex. Thus <devicename>vinum</devicename> gives this
	+ subdisk the name <emphasis>myvol.p0.s0</emphasis>.</para>
	</listitem>
	</itemizedlist>

	<para>After processing this file, &man.gvinum.8; produces the
	following output:</para>

	<programlisting width="97">
	&prompt.root; gvinum -> <userinput>create config1</userinput>
	Configuration summary
	Drives: 1 (4 configured)
	Volumes: 1 (4 configured)
	Plexes: 1 (8 configured)
	Subdisks: 1 (16 configured)

	- D a State: up Device /dev/da3h Avail: 2061/2573 MB (80%)
	+ D a State: up Device /dev/da3h Avail: 2061/2573 MB (80%)

	- V myvol State: up Plexes: 1 Size: 512 MB
	+ V myvol State: up Plexes: 1 Size: 512 MB

	- P myvol.p0 C State: up Subdisks: 1 Size: 512 MB
	+ P myvol.p0 C State: up Subdisks: 1 Size: 512 MB

	- S myvol.p0.s0 State: up PO: 0 B Size: 512 MB</programlisting>
	+ S myvol.p0.s0 State: up PO: 0 B Size: 512 MB</programlisting>

	<para>This output shows the brief listing format of
	- &man.gvinum.8;. It is represented graphically in <xref
	- linkend="vinum-simple-vol"/>.</para>
	+ &man.gvinum.8;. It is represented graphically in <link
	+ linkend="vinum-simple-vol"></link>.</para>

	<para>
	<figure id="vinum-simple-vol">
	- <title>A Simple Vinum Volume</title>
	+ <title>A Simple <devicename>vinum</devicename>
	+ Volume</title>

	<graphic fileref="vinum/vinum-simple-vol"/>
	</figure></para>

	<para>This figure, and the ones which follow, represent a
	- volume, which contains the plexes, which in turn contain the
	- subdisks. In this trivial example, the volume contains one
	- plex, and the plex contains one subdisk.</para>
	+ volume, which contains the plexes, which in turn contains the
	+ subdisks. In this example, the volume contains one plex, and
	+ the plex contains one subdisk.</para>

	<para>This particular volume has no specific advantage over a
	conventional disk partition. It contains a single plex, so it
	is not redundant. The plex contains a single subdisk, so
	there is no difference in storage allocation from a
	conventional disk partition. The following sections
	illustrate various more interesting configuration
	methods.</para>
	</sect2>

	<sect2>
	<title>Increased Resilience: Mirroring</title>

	<para>The resilience of a volume can be increased by mirroring.
	When laying out a mirrored volume, it is important to ensure
	that the subdisks of each plex are on different drives, so
	that a drive failure will not take down both plexes. The
	following configuration mirrors a volume:</para>

	<programlisting> drive b device /dev/da4h
	volume mirror
	plex org concat
	sd length 512m drive a
	plex org concat
	sd length 512m drive b</programlisting>

	<para>In this example, it was not necessary to specify a
	- definition of drive <emphasis>a</emphasis> again, since Vinum
	- keeps track of all objects in its configuration database.
	- After processing this definition, the configuration looks
	- like:</para>
	+ definition of drive <emphasis>a</emphasis> again, since
	+ <devicename>vinum</devicename> keeps track of all objects in
	+ its configuration database. After processing this definition,
	+ the configuration looks like:</para>

	-
	<programlisting width="97">
	Drives: 2 (4 configured)
	Volumes: 2 (4 configured)
	Plexes: 3 (8 configured)
	Subdisks: 3 (16 configured)

	- D a State: up Device /dev/da3h Avail: 1549/2573 MB (60%)
	- D b State: up Device /dev/da4h Avail: 2061/2573 MB (80%)
	+ D a State: up Device /dev/da3h Avail: 1549/2573 MB (60%)
	+ D b State: up Device /dev/da4h Avail: 2061/2573 MB (80%)

	V myvol State: up Plexes: 1 Size: 512 MB
	V mirror State: up Plexes: 2 Size: 512 MB

	P myvol.p0 C State: up Subdisks: 1 Size: 512 MB
	P mirror.p0 C State: up Subdisks: 1 Size: 512 MB
	P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB

	S myvol.p0.s0 State: up PO: 0 B Size: 512 MB
	S mirror.p0.s0 State: up PO: 0 B Size: 512 MB
	S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB</programlisting>

	- <para><xref linkend="vinum-mirrored-vol"/> shows the structure
	- graphically.</para>
	+ <para><link linkend="vinum-mirrored-vol"></link> shows the
	+ structure graphically.</para>

	<para>
	<figure id="vinum-mirrored-vol">
	- <title>A Mirrored Vinum Volume</title>
	+ <title>A Mirrored <devicename>vinum</devicename>
	+ Volume</title>

	<graphic fileref="vinum/vinum-mirrored-vol"/>
	</figure></para>

	<para>In this example, each plex contains the full 512 MB
	of address space. As in the previous example, each plex
	contains only a single subdisk.</para>
	</sect2>

	<sect2>
	<title>Optimizing Performance</title>

	<para>The mirrored volume in the previous example is more
	resistant to failure than an unmirrored volume, but its
	- performance is less: each write to the volume requires a write
	- to both drives, using up a greater proportion of the total
	- disk bandwidth. Performance considerations demand a different
	- approach: instead of mirroring, the data is striped across as
	- many disk drives as possible. The following configuration
	- shows a volume with a plex striped across four disk
	- drives:</para>
	+ performance is less as each write to the volume requires a
	+ write to both drives, using up a greater proportion of the
	+ total disk bandwidth. Performance considerations demand a
	+ different approach: instead of mirroring, the data is striped
	+ across as many disk drives as possible. The following
	+ configuration shows a volume with a plex striped across four
	+ disk drives:</para>

	- <programlisting> drive c device /dev/da5h
	+ <programlisting> drive c device /dev/da5h
	drive d device /dev/da6h
	volume stripe
	plex org striped 512k
	sd length 128m drive a
	sd length 128m drive b
	sd length 128m drive c
	sd length 128m drive d</programlisting>

	<para>As before, it is not necessary to define the drives which
	- are already known to Vinum. After processing this definition,
	- the configuration looks like:</para>
	+ are already known to <devicename>vinum</devicename>. After
	+ processing this definition, the configuration looks
	+ like:</para>

	<programlisting width="92">
	Drives: 4 (4 configured)
	Volumes: 3 (4 configured)
	Plexes: 4 (8 configured)
	Subdisks: 7 (16 configured)

	D a State: up Device /dev/da3h Avail: 1421/2573 MB (55%)
	D b State: up Device /dev/da4h Avail: 1933/2573 MB (75%)
	D c State: up Device /dev/da5h Avail: 2445/2573 MB (95%)
	D d State: up Device /dev/da6h Avail: 2445/2573 MB (95%)

	V myvol State: up Plexes: 1 Size: 512 MB
	V mirror State: up Plexes: 2 Size: 512 MB
	V striped State: up Plexes: 1 Size: 512 MB

	P myvol.p0 C State: up Subdisks: 1 Size: 512 MB
	P mirror.p0 C State: up Subdisks: 1 Size: 512 MB
	P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB
	P striped.p1 State: up Subdisks: 1 Size: 512 MB

	S myvol.p0.s0 State: up PO: 0 B Size: 512 MB
	S mirror.p0.s0 State: up PO: 0 B Size: 512 MB
	S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB
	S striped.p0.s0 State: up PO: 0 B Size: 128 MB
	S striped.p0.s1 State: up PO: 512 kB Size: 128 MB
	S striped.p0.s2 State: up PO: 1024 kB Size: 128 MB
	S striped.p0.s3 State: up PO: 1536 kB Size: 128 MB</programlisting>

	<para>
	<figure id="vinum-striped-vol">
	- <title>A Striped Vinum Volume</title>
	+ <title>A Striped <devicename>vinum</devicename>
	+ Volume</title>

	<graphic fileref="vinum/vinum-striped-vol"/>
	</figure></para>

	- <para>This volume is represented in
	- <xref linkend="vinum-striped-vol"/>. The darkness of the
	- stripes indicates the position within the plex address space:
	- the lightest stripes come first, the darkest last.</para>
	+ <para>This volume is represented in <link
	+ linkend="vinum-striped-vol"></link>. The darkness of the
	+ stripes indicates the position within the plex address space,
	+ where the lightest stripes come first and the darkest
	+ last.</para>
	</sect2>

	<sect2>
	<title>Resilience and Performance</title>

	<para><anchor id="vinum-resilience"/>With sufficient hardware,
	it is possible to build volumes which show both increased
	resilience and increased performance compared to standard
	&unix; partitions. A typical configuration file might
	be:</para>

	<programlisting> volume raid10
	plex org striped 512k
	sd length 102480k drive a
	sd length 102480k drive b
	sd length 102480k drive c
	sd length 102480k drive d
	sd length 102480k drive e
	plex org striped 512k
	sd length 102480k drive c
	sd length 102480k drive d
	sd length 102480k drive e
	sd length 102480k drive a
	sd length 102480k drive b</programlisting>

	<para>The subdisks of the second plex are offset by two drives
	- from those of the first plex: this helps ensure that writes do
	- not go to the same subdisks even if a transfer goes over two
	- drives.</para>
	+ from those of the first plex. This helps to ensure that
	+ writes do not go to the same subdisks even if a transfer goes
	+ over two drives.</para>

	- <para><xref linkend="vinum-raid10-vol"/> represents the
	+ <para><link linkend="vinum-raid10-vol"></link> represents the
	structure of this volume.</para>

	<para>
	<figure id="vinum-raid10-vol">
	- <title>A Mirrored, Striped Vinum Volume</title>
	+ <title>A Mirrored, Striped <devicename>vinum</devicename>
	+ Volume</title>

	<graphic fileref="vinum/vinum-raid10-vol"/>
	</figure></para>
	</sect2>
	</sect1>

	<sect1 id="vinum-object-naming">
	<title>Object Naming</title>

	- <para>As described above, Vinum assigns default names to plexes
	- and subdisks, although they may be overridden. Overriding the
	- default names is not recommended: experience with the VERITAS
	- volume manager, which allows arbitrary naming of objects, has
	- shown that this flexibility does not bring a significant
	- advantage, and it can cause confusion.</para>
	+ <para><devicename>vinum</devicename> assigns default names to
	+ plexes and subdisks, although they may be overridden.
	+ Overriding the default names is not recommended as it does not
	+ bring a significant advantage and it can cause
	+ confusion.</para>

	<para>Names may contain any non-blank character, but it is
	recommended to restrict them to letters, digits and the
	- underscore characters. The names of volumes, plexes and
	+ underscore characters. The names of volumes, plexes, and
	subdisks may be up to 64 characters long, and the names of
	drives may be up to 32 characters long.</para>

	- <para>Vinum objects are assigned device nodes in the hierarchy
	- <filename class="directory">/dev/gvinum</filename>. The
	- configuration shown above would cause Vinum to create the
	- following device nodes:</para>
	+ <para><devicename>vinum</devicename> objects are assigned device
	+ nodes in the hierarchy <filename
	+ class="directory">/dev/gvinum</filename>. The configuration
	+ shown above would cause <devicename>vinum</devicename> to create
	+ the following device nodes:</para>

	<itemizedlist>
	<listitem>
	- <para>Device entries for each volume.
	- These are the main devices used by Vinum. Thus the
	+ <para>Device entries for each volume. These are the main
	+ devices used by <devicename>vinum</devicename>. The
	configuration above would include the devices
	<filename class="devicefile">/dev/gvinum/myvol</filename>,
	<filename class="devicefile">/dev/gvinum/mirror</filename>,
	<filename class="devicefile">/dev/gvinum/striped</filename>,
	<filename class="devicefile">/dev/gvinum/raid5</filename>
	and <filename
	class="devicefile">/dev/gvinum/raid10</filename>.</para>
	</listitem>

	<listitem>
	<para>All volumes get direct entries under
	<filename class="directory">/dev/gvinum/</filename>.</para>
	</listitem>

	<listitem>
	<para>The directories
	<filename class="directory">/dev/gvinum/plex</filename>, and
	<filename class="directory">/dev/gvinum/sd</filename>, which
	contain device nodes for each plex and for each subdisk,
	respectively.</para>
	</listitem>
	</itemizedlist>

	<para>For example, consider the following configuration
	file:</para>
	+
	<programlisting> drive drive1 device /dev/sd1h
	drive drive2 device /dev/sd2h
	drive drive3 device /dev/sd3h
	drive drive4 device /dev/sd4h
	volume s64 setupstate
	plex org striped 64k
	sd length 100m drive drive1
	sd length 100m drive drive2
	sd length 100m drive drive3
	sd length 100m drive drive4</programlisting>

	<para>After processing this file, &man.gvinum.8; creates the
	following structure in <filename
	class="directory">/dev/gvinum</filename>:</para>

	- <programlisting> drwxr-xr-x 2 root wheel 512 Apr 13 16:46 plex
	+ <programlisting> drwxr-xr-x 2 root wheel 512 Apr 13
	+16:46 plex
	crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64
	drwxr-xr-x 2 root wheel 512 Apr 13 16:46 sd

	/dev/vinum/plex:
	total 0
	crwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0

	/dev/vinum/sd:
	total 0
	crwxr-xr-- 1 root wheel 91, 0x20000002 Apr 13 16:46 s64.p0.s0
	crwxr-xr-- 1 root wheel 91, 0x20100002 Apr 13 16:46 s64.p0.s1
	crwxr-xr-- 1 root wheel 91, 0x20200002 Apr 13 16:46 s64.p0.s2
	crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3</programlisting>

	<para>Although it is recommended that plexes and subdisks should
	- not be allocated specific names, Vinum drives must be named.
	- This makes it possible to move a drive to a different location
	- and still recognize it automatically. Drive names may be up to
	- 32 characters long.</para>
	+ not be allocated specific names,
	+ <devicename>vinum</devicename> drives must be named. This makes
	+ it possible to move a drive to a different location and still
	+ recognize it automatically. Drive names may be up to 32
	+ characters long.</para>

	<sect2>
	<title>Creating File Systems</title>

	- <para>Volumes appear to the system to be identical to disks,
	- with one exception. Unlike &unix; drives, Vinum does
	- not partition volumes, which thus do not contain a partition
	- table. This has required modification to some disk
	- utilities, notably &man.newfs.8;, which previously tried to
	- interpret the last letter of a Vinum volume name as a
	- partition identifier. For example, a disk drive may have a
	- name like <filename class="devicefile">/dev/ad0a</filename>
	- or <filename class="devicefile">/dev/da2h</filename>. These
	- names represent the first partition
	- (<devicename>a</devicename>) on the first (0) IDE disk
	- (<devicename>ad</devicename>) and the eighth partition
	- (<devicename>h</devicename>) on the third (2) SCSI disk
	- (<devicename>da</devicename>) respectively. By contrast, a
	- Vinum volume might be called <filename
	- class="devicefile">/dev/gvinum/concat</filename>, a name
	- which has no relationship with a partition name.</para>
	+ <para>Volumes appear to the system to be identical to disks,
	+ with one exception. Unlike &unix; drives,
	+ <devicename>vinum</devicename> does not partition volumes,
	+ which thus do not contain a partition table. This has
	+ required modification to some disk utilities, notably
	+ &man.newfs.8;, so that it does not try to interpret the last
	+ letter of a <devicename>vinum</devicename> volume name as a
	+ partition identifier. For example, a disk drive may have a
	+ name like <filename class="devicefile">/dev/ad0a</filename>
	+ or <filename class="devicefile">/dev/da2h</filename>. These
	+ names represent the first partition
	+ (<devicename>a</devicename>) on the first (0) IDE disk
	+ (<devicename>ad</devicename>) and the eighth partition
	+ (<devicename>h</devicename>) on the third (2) SCSI disk
	+ (<devicename>da</devicename>) respectively. By contrast, a
	+ <devicename>vinum</devicename> volume might be called
	+ <filename class="devicefile">/dev/gvinum/concat</filename>,
	+ which has no relationship with a partition name.</para>

	- <para>In order to create a file system on this volume, use
	- &man.newfs.8;:</para>
	+ <para>In order to create a file system on this volume, use
	+ &man.newfs.8;:</para>

	- <screen>&prompt.root; <userinput>newfs /dev/gvinum/concat</userinput></screen>
	+ <screen>&prompt.root; <userinput>newfs /dev/gvinum/concat</userinput></screen>
	</sect2>
	</sect1>

	<sect1 id="vinum-config">
	- <title>Configuring Vinum</title>
	+ <title>Configuring <devicename>vinum</devicename></title>

	<para>The <filename>GENERIC</filename> kernel does not contain
	- Vinum. It is possible to build a special kernel which includes
	- Vinum, but this is not recommended. The standard way to start
	- Vinum is as a kernel module (<acronym>kld</acronym>). You do
	- not even need to use &man.kldload.8; for Vinum: when you start
	- &man.gvinum.8;, it checks whether the module has been loaded,
	- and if it is not, it loads it automatically.</para>
	+ <devicename>vinum</devicename>. It is possible to build a
	+ custom kernel which includes <devicename>vinum</devicename>, but
	+ this is not recommended. The standard way to start
	+ <devicename>vinum</devicename> is as a kernel module.
	+ &man.kldload.8; is not needed because when &man.gvinum.8;
	+ starts, it checks whether the module has been loaded, and if it
	+ is not, it loads it automatically.</para>


	<sect2>
	<title>Startup</title>

	- <para>Vinum stores configuration information on the disk slices
	- in essentially the same form as in the configuration files.
	- When reading from the configuration database, Vinum recognizes
	- a number of keywords which are not allowed in the
	+ <para><devicename>vinum</devicename> stores configuration
	+ information on the disk slices in essentially the same form as
	+ in the configuration files. When reading from the
	+ configuration database, <devicename>vinum</devicename>
	+ recognizes a number of keywords which are not allowed in the
	configuration files. For example, a disk configuration might
	contain the following text:</para>

	<programlisting width="119">volume myvol state up
	volume bigraid state down
	plex name myvol.p0 state up org concat vol myvol
	plex name myvol.p1 state up org concat vol myvol
	plex name myvol.p2 state init org striped 512b vol myvol
	plex name bigraid.p0 state initializing org raid5 512b vol bigraid
	sd name myvol.p0.s0 drive a plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 0b
	sd name myvol.p0.s1 drive b plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 1048576b
	sd name myvol.p1.s0 drive c plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 0b
	sd name myvol.p1.s1 drive d plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 1048576b
	sd name myvol.p2.s0 drive a plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 0b
	sd name myvol.p2.s1 drive b plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 524288b
	sd name myvol.p2.s2 drive c plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1048576b
	sd name myvol.p2.s3 drive d plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1572864b
	sd name bigraid.p0.s0 drive a plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 0b
	sd name bigraid.p0.s1 drive b plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 4194304b
	sd name bigraid.p0.s2 drive c plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 8388608b
	sd name bigraid.p0.s3 drive d plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 12582912b
	sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 16777216b</programlisting>

	<para>The obvious differences here are the presence of
	- explicit location information and naming (both of which are
	- also allowed, but discouraged, for use by the user) and the
	- information on the states (which are not available to the
	- user). Vinum does not store information about drives in the
	- configuration information: it finds the drives by scanning
	- the configured disk drives for partitions with a Vinum
	- label. This enables Vinum to identify drives correctly even
	- if they have been assigned different &unix; drive
	+ explicit location information and naming, both of which are
	+ allowed but discouraged, and the information on the states.
	+ <devicename>vinum</devicename> does not store information
	+ about drives in the configuration information. It finds the
	+ drives by scanning the configured disk drives for partitions
	+ with a <devicename>vinum</devicename> label. This enables
	+ <devicename>vinum</devicename> to identify drives correctly
	+ even if they have been assigned different &unix; drive
	IDs.</para>

	<sect3 id="vinum-rc-startup">
	<title>Automatic Startup</title>

	<para><emphasis>Gvinum</emphasis> always features an
	automatic startup once the kernel module is loaded, via
	&man.loader.conf.5;. To load the
	<emphasis>Gvinum</emphasis> module at boot time, add
	<literal>geom_vinum_load="YES"</literal> to
	<filename>/boot/loader.conf</filename>.</para>

	- <para>When you start Vinum with the <command>gvinum
	- start</command> command, Vinum reads the configuration
	- database from one of the Vinum drives. Under normal
	- circumstances, each drive contains an identical copy of
	- the configuration database, so it does not matter which
	- drive is read. After a crash, however, Vinum must
	- determine which drive was updated most recently and read
	- the configuration from this drive. It then updates the
	- configuration if necessary from progressively older
	+ <para>When <devicename>vinum</devicename> is started with
	+ <command>gvinum start</command>,
	+ <devicename>vinum</devicename> reads the configuration
	+ database from one of the <devicename>vinum</devicename>
	+ drives. Under normal circumstances, each drive contains
	+ an identical copy of the configuration database, so it
	+ does not matter which drive is read. After a crash,
	+ however, <devicename>vinum</devicename> must determine
	+ which drive was updated most recently and read the
	+ configuration from this drive. It then updates the
	+ configuration, if necessary, from progressively older
	drives.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="vinum-root">
	- <title>Using Vinum for the Root Filesystem</title>
	+ <title>Using <devicename>vinum</devicename> for the Root
	+ File System</title>

	- <para>For a machine that has fully-mirrored filesystems using
	- Vinum, it is desirable to also mirror the root filesystem.
	- Setting up such a configuration is less trivial than mirroring
	- an arbitrary filesystem because:</para>
	+ <para>For a machine that has fully-mirrored file systems using
	+ <devicename>vinum</devicename>, it is desirable to also
	+ mirror the root file system. Setting up such a configuration
	+ is less trivial than mirroring an arbitrary file system
	+ because:</para>

	<itemizedlist>
	<listitem>
	- <para>The root filesystem must be available very early
	- during the boot process, so the Vinum infrastructure must
	- alrqeady be available at this time.</para>
	+ <para>The root file system must be available very early
	+ during the boot process, so the
	+ <devicename>vinum</devicename> infrastructure must
	+ already be available at this time.</para>
	</listitem>
	<listitem>
	- <para>The volume containing the root filesystem also
	- contains the system bootstrap and the kernel, which must
	- be read using the host system's native utilities (e. g.
	- the BIOS on PC-class machines) which often cannot be
	- taught about the details of Vinum.</para>
	+ <para>The volume containing the root file system also
	+ contains the system bootstrap and the kernel. These must
	+ be read using the host system's native utilities, such as
	+ the BIOS, which often cannot be taught about the details
	+ of <devicename>vinum</devicename>.</para>
	</listitem>
	</itemizedlist>

	<para>In the following sections, the term <quote>root
	- volume</quote> is generally used to describe the Vinum
	- volume that contains the root filesystem. It is probably a
	- good idea to use the name <literal>"root"</literal> for this
	- volume, but this is not technically required in any way. All
	- command examples in the following sections assume this name
	- though.</para>
	+ volume</quote> is generally used to describe the
	+ <devicename>vinum</devicename> volume that contains the root
	+ file system.</para>

	<sect2>
	- <title>Starting up Vinum Early Enough for the Root
	- Filesystem</title>
	+ <title>Starting up <devicename>vinum</devicename> Early
	+ Enough for the Root File System</title>

	- <para>There are several measures to take for this to
	- happen:</para>
	+ <para><devicename>vinum</devicename> must be available early
	+ in the system boot as &man.loader.8; must be able to load
	+ the vinum kernel module before starting the kernel. This
	+ can be accomplished by putting this line in
	+ <filename>/boot/loader.conf</filename>:</para>

	- <itemizedlist>
	- <listitem>
	- <para>Vinum must be available in the kernel at boot-time.
	- Thus, the method to start Vinum automatically described
	- in <xref linkend="vinum-rc-startup"/> is not applicable
	- to accomplish this task, and the
	- <literal>start_vinum</literal> parameter must actually
	- <emphasis>not</emphasis> be set when the following setup
	- is being arranged. The first option would be to compile
	- Vinum statically into the kernel, so it is available all
	- the time, but this is usually not desirable. There is
	- another option as well, to have
	- <filename>/boot/loader</filename> (<xref
	- linkend="boot-loader"/>) load the vinum kernel module
	- early, before starting the kernel. This can be
	- accomplished by putting the line:</para>
	-
	<programlisting>geom_vinum_load="YES"</programlisting>

	- <para>into the file
	- <filename>/boot/loader.conf</filename>.</para>
	- </listitem>
	-
	- <listitem>
	- <para>For <emphasis>Gvinum</emphasis>, all startup is done
	- automatically once the kernel module has been loaded, so
	- the procedure described above is all that is
	- needed.</para>
	- </listitem>
	- </itemizedlist>
	</sect2>

	<sect2>
	- <title>Making a Vinum-based Root Volume Accessible to the
	- Bootstrap</title>
	+ <title>Making a <devicename>vinum</devicename>-based Root
	+ Volume Accessible to the Bootstrap</title>

	- <para>Since the current &os; bootstrap is only 7.5 KB of
	- code, and already has the burden of reading files (like
	- <filename>/boot/loader</filename>) from the UFS filesystem, it
	- is sheer impossible to also teach it about internal Vinum
	- structures so it could parse the Vinum configuration data, and
	- figure out about the elements of a boot volume itself. Thus,
	- some tricks are necessary to provide the bootstrap code with
	- the illusion of a standard <literal>"a"</literal> partition
	- that contains the root filesystem.</para>
	+ <para>The current &os; bootstrap is only 7.5 KB of code and
	+ does not understand the internal
	+ <devicename>vinum</devicename> structures. This means that it
	+ cannot parse the <devicename>vinum</devicename> configuration
	+ data or figure out the elements of a boot volume. Thus, some
	+ workarounds are necessary to provide the bootstrap code with
	+ the illusion of a standard <literal>a</literal> partition
	+ that contains the root file system.</para>

	- <para>For this to be possible at all, the following requirements
	- must be met for the root volume:</para>
	+ <para>For this to be possible, the following requirements must
	+ be met for the root volume:</para>

	<itemizedlist>
	<listitem>
	- <para>The root volume must not be striped or RAID-5.</para>
	+ <para>The root volume must not be a stripe or
	+ <acronym>RAID</acronym>-5.</para>
	</listitem>

	<listitem>
	<para>The root volume must not contain more than one
	concatenated subdisk per plex.</para>
	</listitem>
	</itemizedlist>

	- <para>Note that it is desirable and possible that there are
	- multiple plexes, each containing one replica of the root
	- filesystem. The bootstrap process will, however, only use one
	- of these replica for finding the bootstrap and all the files,
	- until the kernel will eventually mount the root filesystem
	- itself. Each single subdisk within these plexes will then
	- need its own <literal>"a"</literal> partition illusion, for
	- the respective device to become bootable. It is not strictly
	- needed that each of these faked <literal>"a"</literal>
	+ <para>Note that it is desirable and possible to use multiple
	+ plexes, each containing one replica of the root file system.
	+ The bootstrap process will only use one replica for finding
	+ the bootstrap and all boot files, until the kernel mounts the
	+ root file system. Each single subdisk within these plexes
	+ needs its own <literal>a</literal> partition illusion, for
	+ the respective device to be bootable. It is not strictly
	+ needed that each of these faked <literal>a</literal>
	partitions is located at the same offset within its device,
	compared with other devices containing plexes of the root
	volume. However, it is probably a good idea to create the
	- Vinum volumes that way so the resulting mirrored devices are
	- symmetric, to avoid confusion.</para>
	+ <devicename>vinum</devicename> volumes that way so the
	+ resulting mirrored devices are symmetric, to avoid
	+ confusion.</para>

	- <para>In order to set up these <literal>"a"</literal>
	- partitions, for each device containing part of the root
	- volume, the following needs to be done:</para>
	+ <para>In order to set up these <literal>a</literal>
	+ partitions for each device containing part of the root
	+ volume, the following is required:</para>

	<procedure>
	<step>
	- <para>The location (offset from the beginning of the device)
	+ <para>The location, offset from the beginning of the device,
	and size of this device's subdisk that is part of the root
	- volume need to be examined, using the command:</para>
	+ volume needs to be examined, using the command:</para>

	<screen>&prompt.root; <userinput>gvinum l -rv root</userinput></screen>

	- <para>Note that Vinum offsets and sizes are measured in
	- bytes. They must be divided by 512 in order to obtain the
	- block numbers that are to be used in the
	- <command>bsdlabel</command> command.</para>
	+ <para><devicename>vinum</devicename> offsets and sizes are
	+ measured in bytes. They must be divided by 512 in order
	+ to obtain the block numbers that are to be used by
	+ <command>bsdlabel</command>.</para>
	</step>

	<step>
	- <para>Run the command:</para>
	+ <para>Run this command for each device that participates in
	+ the root volume:</para>

	<screen>&prompt.root; <userinput>bsdlabel -e <replaceable>devname</replaceable></userinput></screen>

	- <para>for each device that participates in the root volume.
	- <replaceable>devname</replaceable> must be either the name
	- of the disk (like <devicename>da0</devicename>) for disks
	- without a slice (aka. fdisk) table, or the name of the
	- slice (like <devicename>ad0s1</devicename>).</para>
	+ <para><replaceable>devname</replaceable> must be either the
	+ name of the disk, like <devicename>da0</devicename> for
	+ disks without a slice table, or the name of the
	+ slice, like <devicename>ad0s1</devicename>.</para>

	- <para>If there is already an <literal>"a"</literal>
	- partition on the device (presumably, containing a
	- pre-Vinum root filesystem), it should be renamed to
	- something else, so it remains accessible (just in case),
	- but will no longer be used by default to bootstrap the
	- system. Note that active partitions (like a root
	- filesystem currently mounted) cannot be renamed, so this
	- must be executed either when being booted from a
	- <quote>Fixit</quote> medium, or in a two-step process,
	- where (in a mirrored situation) the disk that has not been
	- currently booted is being manipulated first.</para>
	+ <para>If there is already an <literal>a</literal>
	+ partition on the device from a
	+ pre-<devicename>vinum</devicename> root file system, it
	+ should be renamed to something else so that it remains
	+ accessible (just in case), but will no longer be used by
	+ default to bootstrap the system. A currently mounted root
	+ file system cannot be renamed, so this must be executed
	+ either when being booted from a <quote>Fixit</quote>
	+ media, or in a two-step process where, in a mirror, the
	+ disk that is not been currently booted is manipulated
	+ first.</para>

	- <para>Then, the offset of the Vinum partition on this
	- device (if any) must be added to the offset of the
	- respective root volume subdisk on this device. The
	- resulting value will become the
	- <literal>"offset"</literal> value for the new
	- <literal>"a"</literal> partition. The
	- <literal>"size"</literal> value for this partition can be
	+ <para>The offset of the <devicename>vinum</devicename>
	+ partition on this device (if any) must be added to the
	+ offset of the respective root volume subdisk on this
	+ device. The resulting value will become the
	+ <literal>offset</literal> value for the new
	+ <literal>a</literal> partition. The
	+ <literal>size</literal> value for this partition can be
	taken verbatim from the calculation above. The
	- <literal>"fstype"</literal> should be
	+ <literal>fstype</literal> should be
	<literal>4.2BSD</literal>. The
	- <literal>"fsize"</literal>, <literal>"bsize"</literal>,
	- and <literal>"cpg"</literal> values should best be chosen
	- to match the actual filesystem, though they are fairly
	+ <literal>fsize</literal>, <literal>bsize</literal>,
	+ and <literal>cpg</literal> values should be chosen
	+ to match the actual file system, though they are fairly
	unimportant within this context.</para>

	- <para>That way, a new <literal>"a"</literal> partition will
	- be established that overlaps the Vinum partition on this
	- device. Note that the <command>bsdlabel</command> will
	- only allow for this overlap if the Vinum partition has
	- properly been marked using the <literal>"vinum"</literal>
	- fstype.</para>
	+ <para>That way, a new <literal>a</literal> partition will
	+ be established that overlaps the
	+ <devicename>vinum</devicename> partition on this device.
	+ <command>bsdlabel</command> will only allow for this
	+ overlap if the <devicename>vinum</devicename> partition
	+ has properly been marked using the
	+ <literal>vinum</literal> fstype.</para>
	</step>

	<step>
	- <para>That's all! A faked <literal>"a"</literal> partition
	- does exist now on each device that has one replica of the
	- root volume. It is highly recommendable to verify the
	- result again, using a command like:</para>
	+ <para>A faked <literal>a</literal> partition now exists
	+ on each device that has one replica of the root volume.
	+ It is highly recommendable to verify the result using a
	+ command like:</para>

	<screen>&prompt.root; <userinput>fsck -n /dev/<replaceable>devname</replaceable>a</userinput></screen>
	</step>
	</procedure>

	<para>It should be remembered that all files containing control
	- information must be relative to the root filesystem in the
	- Vinum volume which, when setting up a new Vinum root volume,
	- might not match the root filesystem that is currently active.
	- So in particular, the files <filename>/etc/fstab</filename>
	- and <filename>/boot/loader.conf</filename> need to be taken
	- care of.</para>
	+ information must be relative to the root file system in the
	+ <devicename>vinum</devicename> volume which, when setting up
	+ a new <devicename>vinum</devicename> root volume, might not
	+ match the root file system that is currently active. So in
	+ particular, <filename>/etc/fstab</filename> and
	+ <filename>/boot/loader.conf</filename> need to be taken care
	+ of.</para>

	<para>At next reboot, the bootstrap should figure out the
	- appropriate control information from the new Vinum-based root
	- filesystem, and act accordingly. At the end of the kernel
	- initialization process, after all devices have been announced,
	- the prominent notice that shows the success of this setup is a
	- message like:</para>
	+ appropriate control information from the new
	+ <devicename>vinum</devicename>-based root file system, and act
	+ accordingly. At the end of the kernel initialization process,
	+ after all devices have been announced, the prominent notice
	+ that shows the success of this setup is a message like:</para>

	<screen>Mounting root from ufs:/dev/gvinum/root</screen>
	</sect2>

	<sect2>
	- <title>Example of a Vinum-based Root Setup</title>
	+ <title>Example of a <devicename>vinum</devicename>-based Root
	+ Setup</title>

	- <para>After the Vinum root volume has been set up, the output of
	- <command>gvinum l -rv root</command> could look like:</para>
	+ <para>After the <devicename>vinum</devicename> root volume has
	+ been set up, the output of <command>gvinum l -rv
	+ root</command> could look like:</para>

	<screen>...
	Subdisk root.p0.s0:
	Size: 125829120 bytes (120 MB)
	State: up
	Plex root.p0 at offset 0 (0 B)
	Drive disk0 (/dev/da0h) at offset 135680 (132 kB)

	Subdisk root.p1.s0:
	Size: 125829120 bytes (120 MB)
	State: up
	Plex root.p1 at offset 0 (0 B)
	Drive disk1 (/dev/da1h) at offset 135680 (132 kB)</screen>

	<para>The values to note are <literal>135680</literal> for the
	- offset (relative to partition
	- <filename class="devicefile">/dev/da0h</filename>). This
	+ offset, relative to partition
	+ <filename class="devicefile">/dev/da0h</filename>. This
	translates to 265 512-byte disk blocks in
	<command>bsdlabel</command>'s terms. Likewise, the size of
	- this root volume is 245760 512-byte blocks. <filename
	+ this root volume is 245760 512-byte blocks. <filename
	class="devicefile">/dev/da1h</filename>, containing the
	second replica of this root volume, has a symmetric
	setup.</para>

	<para>The bsdlabel for these devices might look like:</para>

	<screen>...
	8 partitions:
	# size offset fstype [fsize bsize bps/cpg]
	a: 245760 281 4.2BSD 2048 16384 0 # (Cyl. 0- 15)
	c: 71771688 0 unused 0 0 # (Cyl. 0 - 4467*)
	h: 71771672 16 vinum # (Cyl. 0- 4467)</screen>

	- <para>It can be observed that the <literal>"size"</literal>
	- parameter for the faked <literal>"a"</literal> partition
	+ <para>It can be observed that the <literal>size</literal>
	+ parameter for the faked <literal>a</literal> partition
	matches the value outlined above, while the
	- <literal>"offset"</literal> parameter is the sum of the offset
	- within the Vinum partition <literal>"h"</literal>, and the
	- offset of this partition within the device (or slice). This
	- is a typical setup that is necessary to avoid the problem
	- described in <xref linkend="vinum-root-panic"/>. It can also
	- be seen that the entire <literal>"a"</literal> partition is
	- completely within the <literal>"h"</literal> partition
	- containing all the Vinum data for this device.</para>
	+ <literal>offset</literal> parameter is the sum of the offset
	+ within the <devicename>vinum</devicename> partition
	+ <literal>h</literal>, and the offset of this partition
	+ within the device or slice. This is a typical setup that is
	+ necessary to avoid the problem described in <link
	+ linkend="vinum-root-panic"></link>. The entire
	+ <literal>a</literal> partition is completely within the
	+ <literal>h</literal> partition containing all the
	+ <devicename>vinum</devicename> data for this device.</para>

	- <para>Note that in the above example, the entire device is
	- dedicated to Vinum, and there is no leftover pre-Vinum root
	- partition, since this has been a newly set-up disk that was
	- only meant to be part of a Vinum configuration, ever.</para>
	+ <para>In the above example, the entire device is dedicated to
	+ <devicename>vinum</devicename> and there is no leftover
	+ pre-<devicename>vinum</devicename> root partition.</para>
	</sect2>

	<sect2>
	<title>Troubleshooting</title>

	- <para>If something goes wrong, a way is needed to recover from
	- the situation. The following list contains few known pitfalls
	- and solutions.</para>
	+ <para>The following list contains a few known pitfalls and
	+ solutions.</para>

	<sect3>
	<title>System Bootstrap Loads, but System Does Not
	Boot</title>

	<para>If for any reason the system does not continue to boot,
	- the bootstrap can be interrupted with by pressing the
	- <keycap>space</keycap> key at the 10-seconds warning. The
	- loader variables (like <literal>vinum.autostart</literal>)
	- can be examined using the <command>show</command>, and
	- manipulated using <command>set</command> or
	- <command>unset</command> commands.</para>
	+ the bootstrap can be interrupted by pressing
	+ <keycap>space</keycap> at the 10-seconds warning. The
	+ loader variable <literal>vinum.autostart</literal> can be
	+ examined by typing <command>show</command> and manipulated
	+ using <command>set</command> or
	+ <command>unset</command>.</para>

	- <para>If the only problem was that the Vinum kernel module was
	- not yet in the list of modules to load automatically, a
	- simple <command>load geom_vinum</command> will help.</para>
	+ <para>If the <devicename>vinum</devicename> kernel module was
	+ not yet in the list of modules to load automatically, type
	+ <command>load geom_vinum</command>.</para>

	- <para>When ready, the boot process can be continued with a
	- <command>boot -as</command>. The options
	- <option>-as</option> will request the kernel to ask for the
	- root filesystem to mount (<option>-a</option>), and make the
	+ <para>When ready, the boot process can be continued by typing
	+ <command>boot -as</command> which
	+ <option>-as</option> requests the kernel to ask for the
	+ root file system to mount (<option>-a</option>) and make the
	boot process stop in single-user mode (<option>-s</option>),
	- where the root filesystem is mounted read-only. That way,
	+ where the root file system is mounted read-only. That way,
	even if only one plex of a multi-plex volume has been
	mounted, no data inconsistency between plexes is being
	risked.</para>

	- <para>At the prompt asking for a root filesystem to mount, any
	- device that contains a valid root filesystem can be entered.
	- If <filename>/etc/fstab</filename> had been set up
	+ <para>At the prompt asking for a root file system to mount,
	+ any device that contains a valid root file system can be
	+ entered. If <filename>/etc/fstab</filename> is set up
	correctly, the default should be something like
	<literal>ufs:/dev/gvinum/root</literal>. A typical
	alternate choice would be something like
	<literal>ufs:da0d</literal> which could be a
	- hypothetical partition that contains the pre-Vinum root
	- filesystem. Care should be taken if one of the alias
	- <literal>"a"</literal> partitions are entered here that are
	- actually reference to the subdisks of the Vinum root device,
	- because in a mirrored setup, this would only mount one piece
	- of a mirrored root device. If this filesystem is to be
	- mounted read-write later on, it is necessary to remove the
	- other plex(es) of the Vinum root volume since these plexes
	- would otherwise carry inconsistent data.</para>
	+ hypothetical partition containing the
	+ pre-<devicename>vinum</devicename> root file system. Care
	+ should be taken if one of the alias
	+ <literal>a</literal> partitions is entered here, that it
	+ actually references the subdisks of the
	+ <devicename>vinum</devicename> root device, because in a
	+ mirrored setup, this would only mount one piece of a
	+ mirrored root device. If this file system is to be mounted
	+ read-write later on, it is necessary to remove the other
	+ plex(es) of the <devicename>vinum</devicename> root volume
	+ since these plexes would otherwise carry inconsistent
	+ data.</para>
	</sect3>

	<sect3>
	<title>Only Primary Bootstrap Loads</title>

	<para>If <filename>/boot/loader</filename> fails to load, but
	the primary bootstrap still loads (visible by a single dash
	in the left column of the screen right after the boot
	process starts), an attempt can be made to interrupt the
	- primary bootstrap at this point, using the
	- <keycap>space</keycap> key. This will make the bootstrap
	- stop in stage two, see <xref linkend="boot-boot1"/>. An
	- attempt can be made here to boot off an alternate partition,
	- like the partition containing the previous root filesystem
	- that has been moved away from <literal>"a"</literal>
	- above.</para>
	+ primary bootstrap by pressing
	+ <keycap>space</keycap>. This will make the bootstrap stop
	+ in <link linkend="boot-boot1">stage two</link>. An attempt
	+ can be made here to boot off an alternate partition, like
	+ the partition containing the previous root file system that
	+ has been moved away from <literal>a</literal>.</para>
	</sect3>

	<sect3 id="vinum-root-panic">
	<title>Nothing Boots, the Bootstrap
	Panics</title>

	<para>This situation will happen if the bootstrap had been
	- destroyed by the Vinum installation. Unfortunately, Vinum
	- accidentally currently leaves only 4 KB at the beginning of
	- its partition free before starting to write its Vinum header
	- information. However, the stage one and two bootstraps plus
	- the bsdlabel embedded between them currently require 8 KB.
	- So if a Vinum partition was started at offset 0 within a
	- slice or disk that was meant to be bootable, the Vinum setup
	- will trash the bootstrap.</para>
	+ destroyed by the <devicename>vinum</devicename>
	+ installation. Unfortunately, <devicename>vinum</devicename>
	+ accidentally leaves only 4 KB at the beginning of its
	+ partition free before starting to write its
	+ <devicename>vinum</devicename> header information. However,
	+ the stage one and two bootstraps plus the bsdlabel require 8
	+ KB. So if a <devicename>vinum</devicename> partition was
	+ started at offset 0 within a slice or disk that was meant to
	+ be bootable, the <devicename>vinum</devicename> setup will
	+ trash the bootstrap.</para>

	<para>Similarly, if the above situation has been recovered,
	- for example by booting from a <quote>Fixit</quote> medium,
	- and the bootstrap has been re-installed using
	- <command>bsdlabel -B</command> as described in <xref
	- linkend="boot-boot1"/>, the bootstrap will trash the Vinum
	- header, and Vinum will no longer find its disk(s). Though
	- no actual Vinum configuration data or data in Vinum volumes
	- will be trashed by this, and it would be possible to recover
	- all the data by entering exact the same Vinum configuration
	- data again, the situation is hard to fix at all. It would
	- be necessary to move the entire Vinum partition by at least
	- 4 KB off, in order to have the Vinum header and the system
	- bootstrap no longer collide.</para>
	+ by booting from a <quote>Fixit</quote> media, and the
	+ bootstrap has been re-installed using
	+ <command>bsdlabel -B</command> as described in <link
	+ linkend="boot-boot1"></link>, the bootstrap will trash the
	+ <devicename>vinum</devicename> header, and
	+ <devicename>vinum</devicename> will no longer find its
	+ disk(s). Though no actual <devicename>vinum</devicename>
	+ configuration data or data in <devicename>vinum</devicename>
	+ volumes will be trashed, and it would be possible to recover
	+ all the data by entering exactly the same
	+ <devicename>vinum</devicename> configuration data again, the
	+ situation is hard to fix. It is necessary to move the
	+ entire <devicename>vinum</devicename> partition by at least
	+ 4 KB, in order to have the <devicename>vinum</devicename>
	+ header and the system bootstrap no longer collide.</para>
	</sect3>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/virtualization/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/virtualization/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/virtualization/chapter.xml (revision 41355)
	@@ -1,1312 +1,1290 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="virtualization">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Murray</firstname>
	<surname>Stokely</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	<!-- Mar 2007 -->
	</chapterinfo>

	<title>Virtualization</title>

	<sect1 id="virtualization-synopsis">
	<title>Synopsis</title>

	<para>Virtualization software allows multiple operating systems
	to run simultaneously on the same computer. Such software
	systems for PCs often involve a host operating system which runs
	the virtualization software and supports any number of guest
	operating systems.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>The difference between a host operating system and a
	guest operating system.</para>
	</listitem>

	<listitem>
	<para>How to install &os; on an &intel;-based &apple;
	&macintosh; computer.</para>
	</listitem>

	<!--
	Note: There is no working/end-user ready Xen support for FreeBSD as of 07-2010.
	Hide all information regarding Xen under FreeBSD.

	<listitem>
	<para>How to install &os; on Linux with
	<application>&xen;</application>.</para>
	</listitem>
	-->
	<listitem>
	<para>How to install &os; on &microsoft.windows; with
	<application>Virtual PC</application>.</para>
	</listitem>

	<listitem>
	<para>How to tune a &os; system for best performance under
	virtualization.</para>
	</listitem>

	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	- <para>Understand the basics of &unix; and &os; (<xref
	- linkend="basics"/>).</para>
	+ <para>Understand the <link linkend="basics">basics of &unix;
	+ and &os;</link>.</para>
	</listitem>

	<listitem>
	- <para>Know how to install &os; (<xref
	- linkend="install"/>).</para>
	+ <para>Know how to <link linkend="install">install
	+ &os;</link>.</para>
	</listitem>

	<listitem>
	- <para>Know how to set up your network connection (<xref
	- linkend="advanced-networking"/>).</para>
	+ <para>Know how to <link linkend="advanced-networking">set up a
	+ network connection</link>.</para>
	</listitem>

	<listitem>
	- <para>Know how to install additional third-party
	- software (<xref linkend="ports"/>).</para>
	+ <para>Know how to <link linkend="ports">install additional
	+ third-party software</link>.</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="virtualization-guest">
	<title>&os; as a Guest OS</title>

	<sect2 id="virtualization-guest-parallels">
	- <title>Parallels on MacOS</title>
	+ <title><application>Parallels</application> on &macos; X</title>

	<para><application>Parallels Desktop</application> for &mac; is
	a commercial software product available for &intel; based
	&apple; &mac; computers running &macos; 10.4.6 or higher.
	&os; is a fully supported guest operating system. Once
	<application>Parallels</application> has been installed on
	&macos; X, the user must configure a virtual machine and then
	install the desired guest operating system.</para>

	<sect3 id="virtualization-guest-parallels-install">
	<title>Installing &os; on Parallels/&macos; X</title>

	- <para>The first step in installing &os; on &macos;
	- X/<application>Parallels</application> is to create a new
	+ <para>The first step in installing &os; on
	+ <application>Parallels</application> is to create a new
	virtual machine for installing &os;. Select
	<guimenuitem>&os;</guimenuitem> as the <guimenu>Guest OS
	Type</guimenu> when prompted:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd1"/>
	</imageobject>
	</mediaobject>

	- <para>And choose a reasonable amount of disk and memory
	- depending on your plans for this virtual &os; instance.
	+ <para>Choose a reasonable amount of disk and memory
	+ depending on the plans for this virtual &os; instance.
	4GB of disk space and 512MB of RAM work well for most uses
	of &os; under <application>Parallels</application>:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd2"/>
	</imageobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd3"/>
	</imageobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd4"/>
	</imageobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd5"/>
	</imageobject>
	</mediaobject>

	<para>Select the type of networking and a network
	interface:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd6"/>
	</imageobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd7"/>
	</imageobject>
	</mediaobject>

	<para>Save and finish the configuration:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd8"/>
	</imageobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd9"/>
	</imageobject>
	</mediaobject>

	- <para>After your &os; virtual machine has been created, you
	- will need to install &os; on it. This is best done with an
	- official &os; CDROM or with an ISO image downloaded from an
	- official FTP site. When you have the appropriate ISO image
	- on your local &mac; filesystem or a CDROM in your &mac;'s CD
	- drive, click on the disc icon in the bottom right corner of
	- your &os; <application>Parallels</application> window. This
	- will bring up a window that allows you to associate the
	- CDROM drive in your virtual machine with an ISO file on disk
	- or with your real CDROM drive.</para>
	+ <para>After the &os; virtual machine has been created, &os;
	+ can be installed on it. This is best done with an
	+ official &os; CD/DVD or with an ISO image downloaded from an
	+ official FTP site. Copy the appropriate ISO image to the
	+ local &mac; filesystem or insert a CD/DVD in the &mac;'s CD
	+ drive. Click on the disc icon in the bottom right corner of
	+ the &os; <application>Parallels</application> window. This
	+ will bring up a window that can be used to associate the
	+ CDROM drive in the virtual machine with the ISO file on disk
	+ or with the real CDROM drive.</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd11"/>
	</imageobject>
	</mediaobject>

	- <para>Once you have made this association with your CDROM
	- source, reboot your &os; virtual machine as normal by
	- clicking the reboot icon.
	- <application>Parallels</application> will reboot with a
	- special BIOS that first checks if you have a CDROM just as a
	- normal BIOS would do.</para>
	+ <para>Once this association with the CDROM source has been
	+ made, reboot the &os; virtual machine by clicking the reboot
	+ icon. <application>Parallels</application> will reboot with
	+ a special BIOS that first checks if there is a CDROM.</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd10"/>
	</imageobject>
	</mediaobject>

	<para>In this case it will find the &os; installation media
	- and begin a normal <application>sysinstall</application>
	- based installation as described in <xref
	- linkend="install"/>. You may install, but do not attempt
	- to configure X11 at this time.</para>
	+ and begin a normal &os; installation. Perform the
	+ installation, but do not attempt to configure
	+ <application>&xorg;</application> at this time.</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd12"/>
	</imageobject>
	</mediaobject>

	- <para>When you have finished the installation, reboot into
	- your newly installed &os; virtual machine.</para>
	+ <para>When the installation is finished, reboot into the
	+ newly installed &os; virtual machine.</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/parallels-freebsd13"/>
	</imageobject>
	</mediaobject>
	</sect3>

	<sect3 id="virtualization-guest-parallels-configure">
	- <title>Configuring &os; on &macos; X/Parallels</title>
	+ <title>Configuring &os; on
	+ <application>Parallels</application> </title>

	<para>After &os; has been successfully installed on &macos;
	X with <application>Parallels</application>, there are a
	number of configuration steps that can be taken to
	optimize the system for virtualized operation.</para>

	<procedure>
	<step>
	<title>Set Boot Loader Variables</title>

	<para>The most important step is to reduce the
	<option>kern.hz</option> tunable to reduce the CPU
	utilization of &os; under the <application>Parallels
	</application> environment. This is accomplished by
	adding the following line to <filename>
	/boot/loader.conf</filename>:</para>

	<programlisting>kern.hz=100</programlisting>

	<para>Without this setting, an idle &os;
	- <application>Parallels</application> guest
	- OS will use roughly 15% of the CPU of a single
	- processor &imac;. After this change the usage will be
	- closer to a mere 5%.</para>
	+ <application>Parallels</application> guest will use
	+ roughly 15% of the CPU of a single processor &imac;.
	+ After this change the usage will be closer to 5%.</para>
	</step>

	<step>
	<title>Create a New Kernel Configuration File</title>

	- <para>You can remove all of the SCSI, FireWire, and USB
	- device drivers. <application>Parallels</application>
	- provides a virtual network
	- adapter used by the &man.ed.4; driver, so
	- all other network devices except for
	- &man.ed.4; and &man.miibus.4; can be
	- removed from the kernel.</para>
	+ <para>All of the SCSI, FireWire, and USB device drivers
	+ can be removed from a custom kernel configuration file.
	+ <application>Parallels</application> provides a virtual
	+ network adapter used by the &man.ed.4; driver, so all
	+ network devices except for &man.ed.4; and &man.miibus.4;
	+ can be removed from the kernel.</para>
	</step>

	<step>
	<title>Configure Networking</title>

	- <para>The most basic networking setup involves simply
	- using DHCP to connect your virtual machine to the same
	- local area network as your host &mac;. This can be
	- accomplished by adding
	+ <para>The most basic networking setup uses DHCP to connect
	+ the virtual machine to the same local area network as
	+ the host &mac;. This can be accomplished by adding
	<literal>ifconfig_ed0="DHCP"</literal> to
	<filename>/etc/rc.conf</filename>. More advanced
	- networking setups are described in
	- <xref linkend="advanced-networking"/>.</para>
	+ networking setups are described in <link
	+ linkend="advanced-networking"></link>.</para>
	</step>
	</procedure>
	</sect3>
	</sect2>
	<!--
	Deactive/hide this section as the instructions in there do NOT work anymore:
	- FreeBSD 7.0 has reached its EOL a long time ago.
	- The needed files from www.fsmware.com are not available anymore, as the
	server is dead. So it is impossible to follow the instructions in here.

	jkois@FreeBSD.org, 2010-06-18

	<sect2 id="virtualization-guest-xen">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Fukang</firstname>
	<surname>Chen (Loader)</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect2info>

	<title>&os; with &xen; on Linux</title>

	<para>The <application>&xen;</application> hypervisor is an
	open source paravirtualization product which is now
	supported by the commercial XenSource company. Guest
	operating systems are known as domU domains, and the host
	operating system is known as dom0. The first step in
	running a virtual &os; instance under Linux is to install
	<application>&xen;</application> for Linux dom0. The host
	operating system will be a Slackware Linux
	distribution.</para>

	<sect3 id="xen-slackware-dom0">
	<title>Setup &xen; 3 on Linux dom0</title>

	<procedure>
	<step>
	<title>Download &xen; 3.0 from XenSource</title>

	<para>Download <ulink
	url="http://bits.xensource.com/oss-xen/release/3.0.4-1/src.tgz/xen-3.0.4_1-src.tgz">xen-3.0.4_1-src.tgz</ulink>
	from <ulink
	url="http://www.xensource.com/"></ulink>.</para>
	</step>

	<step>
	<title>Unpack the tarball</title>

	<screen>&prompt.root; <userinput>cd xen-3.0.4_1-src</userinput>
	&prompt.root; <userinput>KERNELS="linux-2.6-xen0 linux-2.6-xenU" make world</userinput>
	&prompt.root; <userinput>make install</userinput></screen>

	<note>
	<para>To re-compile the kernel for dom0:</para>

	<screen>&prompt.root; <userinput>cd xen-3.0.4_1-src/linux-2.6.16.33-xen0</userinput>
	&prompt.root; <userinput>make menuconfig</userinput>
	&prompt.root; <userinput>make</userinput>
	&prompt.root; <userinput>make install</userinput></screen>

	<para>Older version of
	<application>&xen;</application> may need to specify
	<command>make ARCH=xen menuconfig</command></para>
	</note>
	</step>

	<step>
	<title>Add a menu entry into Grub menu.lst</title>

	<para>Edit <filename>/boot/grub/menu.lst</filename> and
	add the following lines:</para>

	<programlisting>title Xen-3.0.4
	root (hd0,0)
	kernel /boot/xen-3.0.4-1.gz dom0_mem=262144
	module /boot/vmlinuz-2.6.16.33-xen0 root=/dev/hda1 ro</programlisting>
	</step>

	<step>
	<title>Reboot your computer into &xen;</title>

	<para>First, edit
	<filename>/etc/xen/xend-config.sxp</filename>, and add
	the following line:</para>

	<programlisting>(network-script 'network-bridge netdev=eth0')</programlisting>

	<para>Then, we can launch
	<application>&xen;</application>:</para>

	<screen>&prompt.root; <userinput>/etc/init.d/xend start</userinput>
	&prompt.root; <userinput>/etc/init.d/xendomains start</userinput></screen>

	<para>Our dom0 is running:</para>

	<screen>&prompt.root; <userinput>xm list</userinput>
	Name ID Mem VCPUs State Time(s)
	Domain-0 0 256 1 r––––– 54452.9</screen>
	</step>
	</procedure>
	</sect3>

	<sect3>
	<title>&os; 7-CURRENT domU</title>

	<para>Download the &os; domU kernel for
	<application>&xen; 3.0</application> and disk image from
	<ulink
	url="http://www.fsmware.com/">http://www.fsmware.com/</ulink></para>

	<itemizedlist>
	<listitem>
	<para><ulink
	url="http://www.fsmware.com/xenofreebsd/7.0/download/kernel-current">kernel-current</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="http://www.fsmware.com/xenofreebsd/7.0/download/mdroot-7.0.bz2">mdroot-7.0.bz2</ulink></para>
	</listitem>

	<listitem>
	<para><ulink
	url="http://www.fsmware.com/xenofreebsd/7.0/download/config/xmexample1.bsd">xmexample1.bsd</ulink></para>
	</listitem>
	</itemizedlist>

	<para>Put the configuration file
	<filename>xmexample1.bsd</filename> into
	<filename>/etc/xen/</filename> and modify the related
	entries about where the kernel and the disk image are
	stored. It should look like the following:</para>

	<programlisting>kernel = "/opt/kernel-current"
	memory = 256
	name = "freebsd"
	vif = [ '' ]
	disk = [ 'file:/opt/mdroot-7.0,hda1,w' ]
	#on_crash = 'preserve'
	extra = "boot_verbose"
	extra += ",boot_single"
	extra += ",kern.hz=100"
	extra += ",vfs.root.mountfrom=ufs:/dev/xbd769a"</programlisting>

	<para>The <filename>mdroot-7.0.bz2</filename> file should
	be uncompressed.</para>

	<para>Next, the __xen_guest section in
	<filename>kernel-current</filename> needs to be altered to
	add the VIRT_BASE that
	<application>&xen; 3.0.3</application> requires:</para>

	<screen>&prompt.root; <userinput>objcopy kernel-current -R __xen_guest</userinput>
	&prompt.root; <userinput>perl -e 'print "LOADER=generic,GUEST_OS=freebsd,GUEST_VER=7.0,XEN_VER=xen-3.0,BSD_SYMTAB,VIRT_BASE=0xC0000000\x00"' > tmp</userinput>
	&prompt.root; <userinput>objcopy kernel-current ––add-section __xen_guest=tmp</userinput></screen>

	<screen>&prompt.root; <userinput>objdump -j __xen_guest -s kernel-current</userinput>

	kernel-current: file format elf32-i386

	Contents of section __xen_guest:
	0000 4c4f4144 45523d67 656e6572 69632c47 LOADER=generic,G
	0010 55455354 5f4f533d 66726565 6273642c UEST_OS=freebsd,
	0020 47554553 545f5645 523d372e 302c5845 GUEST_VER=7.0,XE
	0030 4e5f5645 523d7865 6e2d332e 302c4253 N_VER=xen-3.0,BS
	0040 445f5359 4d544142 2c564952 545f4241 D_SYMTAB,VIRT_BA
	0050 53453d30 78433030 30303030 3000 SE=0xC0000000. </screen>

	<para>We are, now, ready to create and launch our
	domU:</para>

	<screen>&prompt.root; <userinput>xm create /etc/xen/xmexample1.bsd -c</userinput>
	Using config file "/etc/xen/xmexample1.bsd".
	Started domain freebsd
	WARNING: loader(8) metadata is missing!
	Copyright (c) 1992-2006 The FreeBSD Project.
	Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994
	The Regents of the University of California. All rights reserved.
	FreeBSD 7.0-CURRENT #113: Wed Jan 4 06:25:43 UTC 2006
	kmacy@freebsd7.gateway.2wire.net:/usr/home/kmacy/p4/freebsd7_xen3/src/sys/i386-xen/compile/XENCONF
	WARNING: DIAGNOSTIC option enabled, expect reduced performance.
	Xen reported: 1796.927 MHz processor.
	Timecounter "ixen" frequency 1796927000 Hz quality 0
	CPU: Intel(R) Pentium(R) 4 CPU 1.80GHz (1796.93-MHz 686-class CPU)
	Origin = "GenuineIntel" Id = 0xf29 Stepping = 9
	Features=0xbfebfbff<FPU,VME,DE,PSE,TSC,MSR,PAE,MCE,CX8,APIC,SEP,MTRR,PGE,MCA,CMOV,PAT,PSE36,CLFLUSH,
	DTS,ACPI,MMX,FXSR,SSE,SSE2,SS,HTT,TM,PBE>
	Features2=0x4400<CNTX-ID,<b14>>
	real memory = 265244672 (252 MB)
	avail memory = 255963136 (244 MB)
	xc0: <Xen Console> on motherboard
	cpu0 on motherboard
	Timecounters tick every 10.000 msec
	[XEN] Initialising virtual ethernet driver.
	xn0: Ethernet address: 00:16:3e:6b:de:3a
	[XEN]
	Trying to mount root from ufs:/dev/xbd769a
	WARNING: / was not properly dismounted
	Loading configuration files.
	No suitable dump device was found.
	Entropy harvesting: interrupts ethernet point_to_point kickstart.
	Starting file system checks:
	/dev/xbd769a: 18859 files, 140370 used, 113473 free (10769 frags, 12838 blocks, 4.2% fragmentation)
	Setting hostname: demo.freebsd.org.
	lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384
	inet6 ::1 prefixlen 128
	inet6 fe80::1%lo0 prefixlen 64 scopeid 0x2
	inet 127.0.0.1 netmask 0xff000000
	Additional routing options:.
	Mounting NFS file systems:.
	Starting syslogd.
	/etc/rc: WARNING: Dump device does not exist. Savecore not run.
	ELF ldconfig path: /lib /usr/lib /usr/lib/compat /usr/X11R6/lib /usr/local/lib
	a.out ldconfig path: /usr/lib/aout /usr/lib/compat/aout /usr/X11R6/lib/aout
	Starting usbd.
	usb: Kernel module not available: No such file or directory
	Starting local daemons:.
	Updating motd.
	Starting sshd.
	Initial i386 initialization:.
	Additional ABI support: linux.
	Starting cron.
	Local package initialization:.
	Additional TCP options:.
	Starting background file system checks in 60 seconds.

	Sun Apr 1 02:11:43 UTC 2007

	FreeBSD/i386 (demo.freebsd.org) (xc0)

	login: </screen>

	<para>The domU should run the &os; 7.0-CURRENT
	kernel:</para>

	<screen>&prompt.root; <userinput>uname -a</userinput>
	FreeBSD demo.freebsd.org 7.0-CURRENT FreeBSD 7.0-CURRENT #113: Wed Jan 4 06:25:43 UTC 2006
	kmacy@freebsd7.gateway.2wire.net:/usr/home/kmacy/p4/freebsd7_xen3/src/sys/i386-xen/compile/XENCONF i386</screen>

	<para>The network can now be configured on the domU. The
	&os; domU will use a specific interface called
	<devicename>xn0</devicename>:</para>

	<screen>&prompt.root; <userinput>ifconfig xn0 10.10.10.200 netmask 255.0.0.0</userinput>
	&prompt.root; <userinput>ifconfig</userinput>
	xn0: flags=843<UP,BROADCAST,RUNNING,SIMPLEX> mtu 1500
	inet 10.10.10.200 netmask 0xff000000 broadcast 10.255.255.255
	ether 00:16:3e:6b:de:3a
	lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384
	inet6 ::1 prefixlen 128
	inet6 fe80::1%lo0 prefixlen 64 scopeid 0x2
	inet 127.0.0.1 netmask 0xff000000 </screen>

	<para>On dom0 Slackware, some
	<application>&xen;</application> dependant network
	interfaces should show up:</para>

	<screen>&prompt.root; <userinput>ifconfig</userinput>
	eth0 Link encap:Ethernet HWaddr 00:07:E9:A0:02:C2
	inet addr:10.10.10.130 Bcast:0.0.0.0 Mask:255.0.0.0
	UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
	RX packets:815 errors:0 dropped:0 overruns:0 frame:0
	TX packets:1400 errors:0 dropped:0 overruns:0 carrier:0
	collisions:0 txqueuelen:0
	RX bytes:204857 (200.0 KiB) TX bytes:129915 (126.8 KiB)

	lo Link encap:Local Loopback
	inet addr:127.0.0.1 Mask:255.0.0.0
	UP LOOPBACK RUNNING MTU:16436 Metric:1
	RX packets:99 errors:0 dropped:0 overruns:0 frame:0
	TX packets:99 errors:0 dropped:0 overruns:0 carrier:0
	collisions:0 txqueuelen:0
	RX bytes:9744 (9.5 KiB) TX bytes:9744 (9.5 KiB)

	peth0 Link encap:Ethernet HWaddr FE:FF:FF:FF:FF:FF
	UP BROADCAST RUNNING NOARP MTU:1500 Metric:1
	RX packets:1853349 errors:0 dropped:0 overruns:0 frame:0
	TX packets:952923 errors:0 dropped:0 overruns:0 carrier:0
	collisions:0 txqueuelen:1000
	RX bytes:2432115831 (2.2 GiB) TX bytes:86528526 (82.5 MiB)
	Base address:0xc000 Memory:ef020000-ef040000

	vif0.1 Link encap:Ethernet HWaddr FE:FF:FF:FF:FF:FF
	UP BROADCAST RUNNING NOARP MTU:1500 Metric:1
	RX packets:1400 errors:0 dropped:0 overruns:0 frame:0
	TX packets:815 errors:0 dropped:0 overruns:0 carrier:0
	collisions:0 txqueuelen:0
	RX bytes:129915 (126.8 KiB) TX bytes:204857 (200.0 KiB)

	vif1.0 Link encap:Ethernet HWaddr FE:FF:FF:FF:FF:FF
	UP BROADCAST RUNNING NOARP MTU:1500 Metric:1
	RX packets:3 errors:0 dropped:0 overruns:0 frame:0
	TX packets:2 errors:0 dropped:157 overruns:0 carrier:0
	collisions:0 txqueuelen:1
	RX bytes:140 (140.0 b) TX bytes:158 (158.0 b)

	xenbr1 Link encap:Ethernet HWaddr FE:FF:FF:FF:FF:FF
	UP BROADCAST RUNNING NOARP MTU:1500 Metric:1
	RX packets:4 errors:0 dropped:0 overruns:0 frame:0
	TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
	collisions:0 txqueuelen:0
	RX bytes:112 (112.0 b) TX bytes:0 (0.0 b)</screen>

	<screen>&prompt.root; <userinput>brctl show</userinput>
	bridge name bridge id STP enabled interfaces
	xenbr1 8000.feffffffffff no vif0.1
	peth0
	vif1.0</screen>
	</sect3>
	</sect2>
	-->
	<sect2 id="virtualization-guest-virtualpc">
	- <title>Virtual PC on &windows;</title>
	+ <title><application>Virtual PC</application> on
	+ &windows;</title>

	<para><application>Virtual PC</application> for &windows; is a
	&microsoft; software product available for free download.
	- See <ulink
	+ See this website for the <ulink
	url="http://www.microsoft.com/windows/downloads/virtualpc/sysreq.mspx">
	system requirements</ulink>. Once <application> Virtual PC
	</application> has been installed on &microsoft.windows;,
	- the user must configure a virtual machine and then install
	+ the user can configure a virtual machine and then install
	the desired guest operating system.</para>

	<sect3 id="virtualization-guest-virtualpc-install">
	- <title>Installing &os; on Virtual
	- PC/&microsoft.windows;</title>
	+ <title>Installing &os; on <application>Virtual
	+ PC</application></title>

	<para>The first step in installing &os; on
	- &microsoft.windows; /<application>Virtual PC
	- </application> is to create a new virtual machine for
	- installing &os;. Select <guimenuitem>Create a virtual
	- machine</guimenuitem> when prompted:</para>
	+ <application>Virtual PC </application> is to create a new
	+ virtual machine for installing &os;. Select
	+ <guimenuitem>Create a virtual machine</guimenuitem> when
	+ prompted:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd1"/>
	</imageobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd2"/>
	</imageobject>
	</mediaobject>

	- <para>And select <guimenuitem>Other</guimenuitem> as the
	+ <para>Select <guimenuitem>Other</guimenuitem> as the
	<guimenuitem>Operating system</guimenuitem> when
	prompted:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd3"/>
	</imageobject>
	</mediaobject>

	<para>Then, choose a reasonable amount of disk and memory
	- depending on your plans for this virtual &os;
	- instance. 4GB of disk space and 512MB of RAM work well
	- for most uses of &os; under
	- <application>Virtual PC</application>:</para>
	+ depending on the plans for this virtual &os; instance.
	+ 4GB of disk space and 512MB of RAM work well for most uses
	+ of &os; under <application>Virtual PC</application>:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd4"/>
	</imageobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd5"/>
	</imageobject>
	</mediaobject>

	<para>Save and finish the configuration:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd6"/>
	</imageobject>
	</mediaobject>

	- <para>Select your &os; virtual machine and click
	+ <para>Select the &os; virtual machine and click
	<guimenu>Settings</guimenu>, then set the type of networking
	and a network interface:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd7"/>
	</imageobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd8"/>
	</imageobject>
	</mediaobject>

	- <para>After your &os; virtual machine has been created, you
	- will need to install &os; on it. This is best done with an
	- official &os; CDROM or with an ISO image downloaded from an
	- official FTP site. When you have the appropriate ISO image
	- on your local &windows; filesystem or a CDROM in your CD
	- drive, double click on your &os; virtual machine to boot.
	- Then, click <guimenu>CD</guimenu> and choose
	- <guimenu>Capture ISO Image...</guimenu> on
	+ <para>After the &os; virtual machine has been created, &os;
	+ can be installed on it. This is best done with an
	+ official &os; CD/DVD or with an ISO image downloaded from an
	+ official FTP site. Copy the appropriate ISO image to the
	+ local &windows; filesystem or insert a CD/DVD in the CD
	+ drive, then double click on the &os; virtual machine to
	+ boot. Then, click <guimenu>CD</guimenu> and choose
	+ <guimenu>Capture ISO Image...</guimenu> on the
	<application>Virtual PC</application> window. This will
	- bring up a window that allows you to associate the CDROM
	- drive in your virtual machine with an ISO file on disk or
	- with your real CDROM drive.</para>
	+ bring up a window where the CDROM drive in the virtual
	+ machine can be associated with an ISO file on disk or
	+ with the real CDROM drive.</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd9"/>
	</imageobject>
	</mediaobject>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd10"/>
	</imageobject>
	</mediaobject>

	- <para>Once you have made this association with your CDROM
	- source, reboot your &os; virtual machine as normal by
	- clicking the <guimenu>Action</guimenu> and
	- <guimenu>Reset</guimenu>.
	+ <para>Once this association with the CDROM source has been
	+ made, reboot the &os; virtual machine by clicking
	+ <guimenu>Action</guimenu> and <guimenu>Reset</guimenu>.
	<application>Virtual PC</application> will reboot with a
	- special BIOS that first checks if you have a CDROM just as a
	- normal BIOS would do.</para>
	+ special BIOS that first checks for a CDROM.</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd11"/>
	</imageobject>
	</mediaobject>

	<para>In this case it will find the &os; installation media
	- and begin a normal <application>sysinstall</application>
	- based installation as described in
	- <xref linkend="install"/>. You may install, but do not
	- attempt to configure X11 at this time.</para>
	+ and begin a normal &os; installation. Continue with the
	+ installation, but do not attempt to configure
	+ <application>&xorg;</application> at this time.</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd12"/>
	</imageobject>
	</mediaobject>

	- <para>When you have finished the installation, remember to
	- eject CDROM or release ISO image. Finally, reboot into your
	- newly installed &os; virtual machine.</para>
	+ <para>When the installation is finished, remember to eject
	+ the CD/DVD or release the ISO image. Finally, reboot into
	+ the newly installed &os; virtual machine.</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/virtualpc-freebsd13"/>
	</imageobject>
	</mediaobject>
	</sect3>

	<sect3 id="virtualization-guest-virtualpc-configure">
	- <title>Configuring &os; on &microsoft.windows;/Virtual
	- PC</title>
	+ <title>Configuring &os; on <application>Virtual
	+ PC</application></title>

	<para>After &os; has been successfully installed on
	&microsoft.windows; with <application>Virtual PC
	</application>, there are a number of configuration
	steps that can be taken to optimize the system for
	virtualized operation.</para>

	<procedure>
	<step>
	<title>Set Boot Loader Variables</title>

	<para>The most important step is to reduce the
	<option>kern.hz</option> tunable to reduce the CPU
	- utilization of &os; under the
	- <application>Virtual PC</application> environment.
	- This is accomplished by adding the following line to
	+ utilization of &os; under the <application>Virtual
	+ PC</application> environment. This is accomplished
	+ by adding the following line to
	<filename> /boot/loader.conf</filename>:</para>

	<programlisting>kern.hz=100</programlisting>

	<para>Without this setting, an idle &os;
	<application>Virtual PC</application> guest OS will
	use roughly 40% of the CPU of a single processor
	- computer. After this change the usage will be
	- closer to a mere 3%.</para>
	+ computer. After this change, the usage will be
	+ closer to 3%.</para>
	</step>

	<step>
	<title>Create a New Kernel Configuration File</title>

	- <para>You can remove all of the SCSI, FireWire, and USB
	- device drivers. <application>Virtual PC</application>
	- provides a virtual network adapter used by the
	- &man.de.4; driver, so all other network devices except
	- for &man.de.4; and &man.miibus.4; can be removed from
	- the kernel.</para>
	+ <para>All of the SCSI, FireWire, and USB device drivers
	+ can be removed from a custom kernel configuration file.
	+ <application>Virtual PC</application> provides a virtual
	+ network adapter used by the &man.de.4; driver, so all
	+ network devices except for &man.de.4; and &man.miibus.4;
	+ can be removed from the kernel.</para>
	</step>

	<step>
	<title>Configure Networking</title>

	- <para>The most basic networking setup involves simply
	- using DHCP to connect your virtual machine to the same
	- local area network as your host &microsoft.windows;.
	- This can be accomplished by adding
	- <literal>ifconfig_de0="DHCP"</literal> to
	+ <para>The most basic networking setup uses DHCP to connect
	+ the virtual machine to the same local area network as
	+ the &microsoft.windows; host. This can be accomplished
	+ by adding <literal>ifconfig_de0="DHCP"</literal> to
	<filename>/etc/rc.conf</filename>. More advanced
	- networking setups are described in
	- <xref linkend="advanced-networking"/>.</para>
	+ networking setups are described in <link
	+ linkend="advanced-networking"></link>.</para>
	</step>
	</procedure>
	</sect3>
	</sect2>

	<sect2 id="virtualization-guest-vmware">
	- <title>VMware on MacOS</title>
	+ <title><application>VMware Fusion</application> on
	+ &macos;</title>

	<para><application>VMware Fusion</application> for &mac; is a
	commercial software product available for &intel; based
	&apple; &mac; computers running &macos; 10.4.9 or higher.
	&os; is a fully supported guest operating system. Once
	<application>VMware Fusion</application> has been
	- installed on &macos; X, the user must configure a virtual
	+ installed on &macos; X, the user can configure a virtual
	machine and then install the desired guest operating
	system.</para>

	<sect3 id="virtualization-guest-vmware-install">
	- <title>Installing &os; on VMware/&macos; X</title>
	+ <title>Installing &os; on <application>VMware
	+ Fusion</application></title>

	- <para>The first step is to start VMware Fusion, the Virtual
	- Machine Library will load. Click "New" to create the
	- VM:</para>
	+ <para>The first step is to start <application>VMware
	+ Fusion</application> which will load the Virtual
	+ Machine Library. Click <guimenuitem>New</guimenuitem> to
	+ create the virtual machine:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/vmware-freebsd01"/>
	</imageobject>
	</mediaobject>

	- <para>This will load the New Virtual Machine Assistant to help
	- you create the VM, click Continue to proceed:</para>
	+ <para>This will load the New Virtual Machine Assistant. Click
	+ <guimenuitem>Continue</guimenuitem> to proceed:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/vmware-freebsd02"/>
	</imageobject>
	</mediaobject>

	<para>Select <guimenuitem>Other</guimenuitem> as the
	- <guimenuitem>Operating System</guimenuitem> and
	+ <guimenuitem>Operating System</guimenuitem> and either
	<guimenuitem>&os;</guimenuitem> or
	- <guimenuitem>&os; 64-bit</guimenuitem>, depending on if
	- you want 64-bit support, as the <guimenu>Version</guimenu>
	- when prompted:</para>
	+ <guimenuitem>&os; 64-bit</guimenuitem>, as the
	+ <guimenu>Version</guimenu> when prompted:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/vmware-freebsd03"/>
	</imageobject>
	</mediaobject>

	- <para>Choose the Name of the VM Image and the Directory where
	- you would like it saved:</para>
	+ <para>Choose the name of the virtual machine and the directory
	+ where it should be saved:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/vmware-freebsd04"/>
	</imageobject>
	</mediaobject>

	- <para>Choose the size of the Virtual Hard Disk for the
	- VM:</para>
	+ <para>Choose the size of the Virtual Hard Disk for the virtual
	+ machine:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/vmware-freebsd05"/>
	</imageobject>
	</mediaobject>

	- <para>Choose the method you would like to install the VM,
	- either from an ISO image or from a CD:</para>
	+ <para>Choose the method to install the virtual machine,
	+ either from an ISO image or from a CD/DVD:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/vmware-freebsd06"/>
	</imageobject>
	</mediaobject>

	- <para>Once you click Finish, the VM will boot:</para>
	+ <para>Click <guimenuitem>Finish</guimenuitem> and the virtual
	+ machine will boot:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/vmware-freebsd07"/>
	</imageobject>
	</mediaobject>

	- <para>Install &os; like you normally would, or by following
	- the directions in <xref linkend="install"/>:</para>
	+ <para>Install &os; as usual:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/vmware-freebsd08"/>
	</imageobject>
	</mediaobject>

	- <para>Once the install is complete you can modify the settings
	- of the VM, such as Memory Usage:</para>
	+ <para>Once the install is complete, the settings
	+ of the virtual machine can be modified, such as memory
	+ usage:</para>

	<note>
	- <para>The System Hardware settings of the VM cannot be
	- modified while the VM is running.</para>
	+ <para>The System Hardware settings of the virtual machine
	+ cannot be modified while the virtual machine is
	+ running.</para>
	</note>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/vmware-freebsd09"/>
	</imageobject>
	</mediaobject>

	- <para>The number of CPUs the VM will have access to:</para>
	+ <para>The number of CPUs the virtual machine will have access
	+ to:</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/vmware-freebsd10"/>
	</imageobject>
	</mediaobject>

	- <para>The status of the CD-Rom Device. Normally you can
	- disconnect the CD-Rom/ISO from the VM if you will not be
	- needing it anymore.</para>
	+ <para>The status of the CDROM device. Normally the
	+ CD/DVD/ISO is disconnected from the virtual machine when it
	+ is no longer needed.</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/vmware-freebsd11"/>
	</imageobject>
	</mediaobject>

	- <para>The last thing to change is how the VM will connect to
	- the Network. If you want to allow connections to the VM
	- from other machines besides the Host, make sure you choose
	- the <guimenuitem>Connect directly to the physical network
	- (Bridged)</guimenuitem>. Otherwise <guimenuitem>Share the
	+ <para>The last thing to change is how the virtual machine will
	+ connect to the network. To allow connections to the virtual
	+ machine from other machines besides the host, choose
	+ <guimenuitem>Connect directly to the physical network
	+ (Bridged)</guimenuitem>. Otherwise, <guimenuitem>Share the
	host's internet connection (NAT)</guimenuitem> is
	- preferred so that the VM can have access to the Internet,
	- but the network cannot access the VM.</para>
	+ preferred so that the virtual machine can have access to the
	+ Internet, but the network cannot access the virtual
	+ machine.</para>

	<mediaobject>
	<imageobject>
	<imagedata fileref="virtualization/vmware-freebsd12"/>
	</imageobject>
	</mediaobject>

	- <para>After you have finished modifying the settings, boot the
	- newly installed &os; virtual machine.</para>
	+ <para>After modifying the settings, boot the newly installed
	+ &os; virtual machine.</para>
	</sect3>

	<sect3 id="virtualization-guest-vmware-configure">
	- <title>Configuring &os; on &macos; X/VMware</title>
	+ <title>Configuring &os; on <application>VMware
	+ Fusion</application></title>

	<para>After &os; has been successfully installed on &macos; X
	- with <application>VMware</application>, there are a number
	- of configuration steps that can be taken to optimize the
	- system for virtualized operation.</para>
	+ with <application>VMware Fusion</application>, there are a
	+ number of configuration steps that can be taken to optimize
	+ the system for virtualized operation.</para>

	<procedure>
	<step>
	<title>Set Boot Loader Variables</title>

	<para>The most important step is to reduce the
	<option>kern.hz</option> tunable to reduce the CPU
	utilization of &os; under the
	- <application>VMware</application> environment. This is
	- accomplished by adding the following line to
	+ <application>VMware Fusion</application> environment.
	+ This is accomplished by adding the following line to
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>kern.hz=100</programlisting>

	<para>Without this setting, an idle &os;
	- <application>VMware</application> guest
	- OS will use roughly 15% of the CPU of a single
	- processor &imac;. After this change the usage will be
	- closer to a mere 5%.</para>
	+ <application>VMware Fusion</application> guest will use
	+ roughly 15% of the CPU of a single processor &imac;.
	+ After this change, the usage will be closer to
	+ 5%.</para>
	</step>

	<step>
	<title>Create a New Kernel Configuration File</title>

	- <para>You can remove all of the FireWire, and USB device
	- drivers. <application>VMware</application> provides a
	+ <para>All of the FireWire, and USB device drivers can be
	+ removed from a custom kernel configuration file.
	+ <application>VMware Fusion</application> provides a
	virtual network adapter used by the &man.em.4; driver,
	- so all other network devices except for &man.em.4; can
	- be removed from the kernel.</para>
	+ so all network devices except for &man.em.4; can be
	+ removed from the kernel.</para>
	</step>

	<step>
	<title>Configure Networking</title>

	- <para>The most basic networking setup involves simply
	- using DHCP to connect your virtual machine to the
	- same local area network as your host &mac;. This
	- can be accomplished by adding
	+ <para>The most basic networking setup uses DHCP to connect
	+ the virtual machine to the same local area network as
	+ the host &mac;. This can be accomplished by adding
	<literal>ifconfig_em0="DHCP"</literal> to
	<filename>/etc/rc.conf</filename>. More advanced
	- networking setups are described in
	- <xref linkend="advanced-networking"/>.</para>
	+ networking setups are described in <link
	+ linkend="advanced-networking"></link>.</para>
	</step>
	</procedure>
	</sect3>
	</sect2>

	<sect2 id="virtualization-guest-virtualbox-guest-additions">
	<title>&virtualbox; Guest Additions on a &os; Guest</title>

	<para>The <application>&virtualbox;</application> guest
	additions provide support for:</para>

	<itemizedlist>
	<listitem>
	- <para>Clipboard sharing</para>
	+ <para>Clipboard sharing.</para>
	</listitem>

	<listitem>
	- <para>Mouse pointer integration</para>
	+ <para>Mouse pointer integration.</para>
	</listitem>

	<listitem>
	- <para>Host time synchronization</para>
	+ <para>Host time synchronization.</para>
	</listitem>

	<listitem>
	- <para>Window scaling</para>
	+ <para>Window scaling.</para>
	</listitem>

	<listitem>
	- <para>Seamless mode</para>
	+ <para>Seamless mode.</para>
	</listitem>
	</itemizedlist>

	<note>
	<para>The following commands are run in the &os; guest.</para>
	</note>

	<para>First, install the <filename
	role="package">emulators/virtualbox-ose-additions</filename>
	- package in the &os; guest.</para>
	+ package or port in the &os; guest. This will install
	+ the port:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/emulators/virtualbox-ose-additions && make install clean</userinput></screen>

	<para>Add these lines to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>vboxguest_enable="YES"
	vboxservice_enable="YES"</programlisting>

	- <para>If &man.ntpd.8; or &man.ntpdate.8; will be used, host time
	+ <para>If &man.ntpd.8; or &man.ntpdate.8; is used, host time
	synchronization should be disabled:</para>

	<programlisting>vboxservice_flags="--disable-timesync"</programlisting>

	- <para>The <literal>vboxvideo_drv</literal> should be recognized
	- by <command>Xorg -configure</command>. If not, modify
	- <filename>xorg.conf</filename> for the
	+ <para>The <literal>vboxvideo</literal> driver should be
	+ automatically recognized by <command>Xorg
	+ -configure</command>. If not, modify
	+ <filename>/etc/X11/xorg.conf</filename> for the
	<application>&virtualbox;</application> video card:</para>

	<programlisting>Section "Device"
	### Available Driver options are:-
	### Values: <i>: integer, <f>: float, <bool>: "True"/"False",
	### <string>: "String", <freq>: "<f> Hz/kHz/MHz"
	### [arg]: arg optional
	Identifier "Card0"
	Driver "vboxvideo"
	VendorName "InnoTek Systemberatung GmbH"
	BoardName "VirtualBox Graphics Adapter"
	BusID "PCI:0:2:0"
	EndSection</programlisting>

	- <para>To use <literal>vboxmouse_drv</literal>, adjust the mouse
	- section in your <filename>xorg.conf</filename>:</para>
	+ <para>To use the <literal>vboxmouse</literal> driver, adjust the
	+ mouse section in
	+ <filename>/etc/X11/xorg.conf</filename>:</para>

	<programlisting>Section "InputDevice"
	Identifier "Mouse0"
	Driver "vboxmouse"
	EndSection</programlisting>

	- <para><acronym>HAL</acronym> users should create this file at
	+ <para><acronym>HAL</acronym> users should create the following
	<filename>/usr/local/etc/hal/fdi/policy/90-vboxguest.fdi</filename>
	or copy it from
	<filename>/usr/local/share/hal/fdi/policy/10osvendor/90-vboxguest.fdi</filename>:</para>

	<programlisting><?xml version="1.0" encoding="utf-8"?>
	<!--
	# Sun VirtualBox
	# Hal driver description for the vboxmouse driver
	# $Id: chapter.xml,v 1.33 2012-03-17 04:53:52 eadler Exp $

	Copyright (C) 2008-2009 Sun Microsystems, Inc.

	This file is part of VirtualBox Open Source Edition (OSE, as
	available from http://www.virtualbox.org. This file is free software;
	you can redistribute it and/or modify it under the terms of the GNU
	General Public License (GPL) as published by the Free Software
	Foundation, in version 2 as it comes in the "COPYING" file of the
	VirtualBox OSE distribution. VirtualBox OSE is distributed in the
	hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.

	Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
	Clara, CA 95054 USA or visit http://www.sun.com if you need
	additional information or have any questions.
	-->
	<deviceinfo version="0.2">
	<device>
	<match key="info.subsystem" string="pci">
	<match key="info.product" string="VirtualBox guest Service">
	<append key="info.capabilities" type="strlist">input</append>
	<append key="info.capabilities" type="strlist">input.mouse</append>
	<merge key="input.x11_driver" type="string">vboxmouse</merge>
	<merge key="input.device" type="string">/dev/vboxguest</merge>
	</match>
	</match>
	</device>
	</deviceinfo></programlisting>
	</sect2>
	</sect1>

	<sect1 id="virtualization-host">
	- <title>&os; as a Host OS</title>
	+ <title>&os; as a Host</title>

	- <para>For a number of years, &os; was not officially supported as
	- a host OS by any of the available virtualization solutions.
	- Some people were using older and mostly obsolete versions of
	- <application>VMware</application> (like
	- <filename role="package">emulators/vmware3</filename>), which
	- utilized the &linux; binary compatibility layer. Shortly after
	- the release of &os; 7.2, Sun's
	- <application>&virtualbox;</application> appeared in the
	- Ports Collection as a native &os; program.</para>
	-
	<para><application>&virtualbox;</application> is an actively
	developed, complete virtualization package, that is available
	for most operating systems including &windows;, &macos;, &linux;
	- and &os;. It is equally capable at running &windows; or &unix;
	- like guests. It is released as open source software, but with
	- closed-source components available in a separate extension pack.
	- These components include support for USB 2.0 devices, among
	- others. More information may be found on the
	- <quote>Downloads</quote> page of the
	- <application>&virtualbox;</application> wiki, at <ulink
	- url="http://www.virtualbox.org/wiki/Downloads"></ulink>.
	+ and &os;. It is equally capable of running &windows; or
	+ &unix;-like guests. It is released as open source software, but
	+ with closed-source components available in a separate extension
	+ pack. These components include support for USB 2.0 devices.
	+ More information may be found on the <ulink
	+ url="http://www.virtualbox.org/wiki/Downloads">
	+ <quote>Downloads</quote> page of the
	+ <application>&virtualbox;</application> wiki</ulink>.
	Currently, these extensions are not available for &os;.</para>

	<sect2 id="virtualization-virtualbox-install">
	<title>Installing &virtualbox;</title>

	<para><application>&virtualbox;</application> is available as a
	- &os; port in
	- <filename role="package">emulators/virtualbox-ose</filename>.
	- As &virtualbox; is very actively developed, make sure your
	- ports tree is up to date before installing. Install using
	- these commands:</para>
	+ &os; package or port in <filename
	+ role="package">emulators/virtualbox-ose</filename>. The
	+ port can be installed using these commands:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/emulators/virtualbox-ose</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	- <para>One useful option in the configuration dialog is the
	+ <para>One useful option in the port's configuration menu is the
	<literal>GuestAdditions</literal> suite of programs. These
	provide a number of useful features in guest operating
	systems, like mouse pointer integration (allowing the mouse to
	be shared between host and guest without the need to press a
	special keyboard shortcut to switch) and faster video
	rendering, especially in &windows; guests. The guest
	additions are available in the <guimenu>Devices</guimenu>
	- menu, after the installation of the guest OS is
	- finished.</para>
	+ menu, after the installation of the guest is finished.</para>

	<para>A few configuration changes are needed before
	<application>&virtualbox;</application> is started for the
	first time. The port installs a kernel module in
	<filename class="directory">/boot/modules</filename> which
	must be loaded into the running kernel:</para>

	<screen>&prompt.root; <userinput>kldload vboxdrv</userinput></screen>

	<para>To ensure the module always gets loaded after a reboot,
	add the following line to
	<filename>/boot/loader.conf</filename>:</para>

	<programlisting>vboxdrv_load="YES"</programlisting>

	<para>To use the kernel modules that allow bridged or host-only
	networking, add the following to
	<filename>/etc/rc.conf</filename> and reboot the
	computer:</para>

	<programlisting>vboxnet_enable="YES"</programlisting>

	<para>The <groupname>vboxusers</groupname> group is created
	during installation of
	<application>&virtualbox;</application>. All users that need
	access to <application>&virtualbox;</application> will have to
	- be added as members of this group. The <command>pw</command>
	- command may be used to add new members:</para>
	+ be added as members of this group. <command>pw</command>
	+ can be used to add new members:</para>

	<screen>&prompt.root; <userinput>pw groupmod vboxusers -m <replaceable>yourusername</replaceable></userinput></screen>

	- <para>The default permissions for
	- <filename class="devicefile">/dev/vboxnetctl</filename> are
	+ <para>The default permissions for <filename
	+ class="devicefile">/dev/vboxnetctl</filename> are
	restrictive and need to be changed for bridged
	- networking.</para>
	+ networking:</para>

	- <para>To test it temporarily:</para>
	-
	<screen>&prompt.root; <userinput>chown root:vboxusers /dev/vboxnetctl</userinput>
	&prompt.root; <userinput>chmod 0660 /dev/vboxnetctl</userinput></screen>

	- <para>To make the permissions change permanent, add these
	+ <para>To make this permissions change permanent, add these
	lines to <filename>/etc/devfs.conf</filename>:</para>

	<programlisting>own vboxnetctl root:vboxusers
	perm vboxnetctl 0660</programlisting>

	- <para>To launch <application>&virtualbox;</application>, either
	- select the <guimenuitem>Sun VirtualBox</guimenuitem> item from
	- the graphic environment's menu, or type the following in a
	- terminal:</para>
	+ <para>To launch <application>&virtualbox;</application>,
	+ type from a <application>&xorg;</application> session:</para>

	<screen>&prompt.user; <userinput>VirtualBox</userinput></screen>

	<para>For more information on configuring and using
	- <application>&virtualbox;</application>, please visit the
	- official website at
	- <ulink url="http://www.virtualbox.org"></ulink>. As the &os;
	- port is very recent, it is under heavy development. For the
	- latest information and troubleshooting instructions, please
	- visit the relevant page in the &os; wiki, at <ulink
	- url="http://wiki.FreeBSD.org/VirtualBox"></ulink>.</para>
	+ <application>&virtualbox;</application>, refer to the
	+ <ulink url="http://www.virtualbox.org">official
	+ website</ulink>. For &os;-specific information and
	+ troubleshooting instructions, refer to the <ulink
	+ url="http://wiki.FreeBSD.org/VirtualBox">relevant page in
	+ the &os; wiki</ulink>.</para>
	</sect2>

	<sect2 id="virtualization-virtualbox-usb-support">
	<title>&virtualbox; USB Support</title>

	- <note>
	- <para>These steps require VirtualBox 4.0.0 or later.</para>
	- </note>
	-
	<para>In order to be able to read and write to USB devices,
	- users need to be members of the operator group:</para>
	+ users need to be members of
	+ <groupname>operator</groupname>:</para>

	<screen>&prompt.root; <userinput>pw groupmod operator -m <replaceable>jerry</replaceable></userinput></screen>

	<para>Then, add the following to
	- <filename>/etc/devfs.rules</filename> (create it if it does
	- not exist yet):</para>
	+ <filename>/etc/devfs.rules</filename>, or create this file if
	+ it does not exist yet:</para>

	<programlisting>[system=10]
	add path 'usb/*' mode 0660 group operator</programlisting>

	<para>To load these new rules, add the following to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>devfs_system_ruleset="system"</programlisting>

	<para>Then, restart devfs:</para>

	<screen>&prompt.root; <userinput>service devfs restart</userinput></screen>

	<para>USB can now be enabled in the guest operating system. USB
	devices should be visible in the &virtualbox;
	preferences.</para>
	</sect2>

	<sect2 id="virtualization-virtualbox-host-dvd-cd-access">
	<title>&virtualbox; Host DVD/CD Access</title>

	<para>Access to the host DVD/CD drives from guests is achieved
	- through the sharing of the physical drives. In GUI this is
	- set up from the Storage window in the Settings of the virtual
	- machine. Create an empty IDE CD/DVD device first.
	- Then choose the Host Drive from the popup menu for the virtual
	- CD/DVD drive selection. A checkbox labeled
	- <literal>Passthrough</literal> check box will appear.
	- This allows the virtual machine to use the hardware directly.
	- For example, audio CDs or the burner only function if
	- this option is selected.</para>
	+ through the sharing of the physical drives. Within
	+ &virtualbox;, this is set up from the Storage window in the
	+ Settings of the virtual machine. If needed, create an empty
	+ IDE CD/DVD device first. Then choose the Host Drive from the
	+ popup menu for the virtual CD/DVD drive selection. A checkbox
	+ labeled <literal>Passthrough</literal> will appear. This
	+ allows the virtual machine to use the hardware directly. For
	+ example, audio CDs or the burner will only function if this
	+ option is selected.</para>

	<para><acronym>HAL</acronym> needs to run for
	<application>&virtualbox;</application> DVD/CD functions to
	work, so enable it in <filename>/etc/rc.conf</filename> and
	- start it (if it is not already running):</para>
	+ start it if it is not already running:</para>

	<programlisting>hald_enable="YES"</programlisting>

	<screen>&prompt.root; <userinput>service hald start</userinput></screen>

	<para>In order for users to be able to use
	<application>&virtualbox;</application> DVD/CD functions, they
	- need access to
	- <filename class="devicefile">/dev/xpt0</filename>, <filename
	+ need access to <filename
	+ class="devicefile">/dev/xpt0</filename>, <filename
	class="devicefile">/dev/cd<replaceable>N</replaceable></filename>,
	and <filename
	class="devicefile">/dev/pass<replaceable>N</replaceable></filename>.
	- This is usually achieved by making the user of
	- <application>&virtualbox;</application>
	- a member of the operator group, which is also the default
	- group of the above mentioned devices. Permissions of these
	- devices have to be corrected by adding the following lines to
	+ This is usually achieved by making the user a member of
	+ <groupname>operator</groupname>. Permissions to these devices
	+ have to be corrected by adding the following lines to
	<filename>/etc/devfs.conf</filename>:</para>

	<programlisting>perm cd* 0600
	perm xpt0 0660
	perm pass* 0660</programlisting>

	<screen>&prompt.root; <userinput>service devfs restart</userinput></screen>
	</sect2>

	<!--
	Note: There is no working/end-user ready Xen support for FreeBSD as of 07-2010.
	Hide all information regarding Xen under FreeBSD.

	<sect2 id="virtualization-other">
	<title>Other Virtualization Options</title>

	<para>There is ongoing work in getting
	<application>&xen;</application>
	to work as a host environment on &os;.</para>
	</sect2>
	-->
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/handbook/x11/chapter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/handbook/x11/chapter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/handbook/x11/chapter.xml (revision 41355)
	@@ -1,1810 +1,1795 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<chapter id="x11">
	<chapterinfo>
	<authorgroup>
	<author>
	<firstname>Ken</firstname>
	<surname>Tom</surname>
	<contrib>Updated for X.Org's X11 server by </contrib>
	</author>
	<author>
	<firstname>Marc</firstname>
	<surname>Fonvieille</surname>
	</author>
	</authorgroup>
	</chapterinfo>

	<title>The X Window System</title>

	<sect1 id="x11-synopsis">
	<title>Synopsis</title>

	<para>FreeBSD uses X11 to provide users with
	a powerful graphical user interface. X11
	is a freely available version of the X Window System that
	is implemented in <application>&xorg;</application>
	(and other software packages not discussed here). The
	default and official flavor of X11 in &os; is
	<application>&xorg;</application>, the X11 server developed by
	the X.Org Foundation under a license very similar to the one
	- used by &os;. Commercial X servers for &os; are also
	- available.</para>
	+ used by &os;.</para>

	<para>For more information on the video hardware that X11
	supports, check the <ulink
	url="http://www.x.org/">&xorg;</ulink> web site.</para>

	<para>After reading this chapter, you will know:</para>

	<itemizedlist>
	<listitem>
	<para>The various components of the X Window System, and how
	they interoperate.</para>
	</listitem>

	<listitem>
	<para>How to install and configure X11.</para>
	</listitem>

	<listitem>
	<para>How to install and use different window managers.</para>
	</listitem>

	<listitem>
	<para>How to use &truetype; fonts in X11.</para>
	</listitem>

	<listitem>
	<para>How to set up your system for graphical logins
	(<application>XDM</application>).</para>
	</listitem>
	</itemizedlist>

	<para>Before reading this chapter, you should:</para>

	<itemizedlist>
	<listitem>
	<para>Know how to install additional third-party
	software (<xref linkend="ports"/>).</para>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="x-understanding">
	<title>Understanding X</title>

	<para>Using X for the first time can be somewhat of a shock to
	someone familiar with other graphical environments, such as
	&microsoft.windows; or &macos;.</para>

	<para>While it is not necessary to understand all of the details
	of various X components and how they interact, some basic
	knowledge makes it possible to take advantage of X's
	strengths.</para>

	<sect2>
	<title>Why X?</title>

	<para>X is not the first window system written for &unix;, but
	it is the most popular of them. X's original development team
	had worked on another window system prior to writing X. That
	system's name was <quote>W</quote> (for
	<quote>Window</quote>). X was just the next letter in the
	Roman alphabet.</para>

	<para>X can be called <quote>X</quote>, <quote>X Window
	System</quote>, <quote>X11</quote>, and a number of other
	terms. You may find that using the term <quote>X
	Windows</quote> to describe X11 can be offensive to some
	people; for a bit more insight on this, see &man.X.7;.</para>
	</sect2>

	<sect2>
	<title>The X Client/Server Model</title>

	<para>X was designed from the beginning to be network-centric,
	and adopts a <quote>client-server</quote> model.</para>

	<para>In the X model, the
	<quote>X server</quote> runs on the computer that has the
	keyboard, monitor, and mouse attached. The server's
	responsibility includes tasks such as managing the
	display, handling input from the keyboard and mouse, and
	other input or output devices (i.e., a <quote>tablet</quote>
	can be used as an input device, and a video projector
	may be an alternative output device). Each X application
	- (such as <application>XTerm</application>, or
	- <application>&netscape;</application>) is a
	+ (such as <application>XTerm</application> or
	+ <application>Firefox</application>) is a
	<quote>client</quote>. A client sends messages to the server
	such as <quote>Please draw a window at these
	coordinates</quote>, and the server sends back messages such
	as <quote>The user just clicked on the OK
	button</quote>.</para>

	<para>In a home or small office environment, the X server and
	the X clients commonly run on the same computer. However, it
	is perfectly possible to run the X server on a less powerful
	desktop computer, and run X applications (the clients) on,
	say, the powerful and expensive machine that serves the
	office. In this scenario the communication between the X
	client and server takes place over the network.</para>

	<para>This confuses some people, because the X terminology is
	exactly backward to what they expect. They expect the
	<quote>X server</quote> to be the big powerful machine down
	the hall, and the <quote>X client</quote> to be the machine
	on their desk.</para>

	<para>It is important to remember that the X server is the
	machine with the monitor and keyboard, and the X clients are
	the programs that display the windows.</para>

	<para>There is nothing in the protocol that forces the client
	and server machines to be running the same operating system,
	or even to be running on the same type of computer. It is
	certainly possible to run an X server on &microsoft.windows;
	or Apple's &macos;, and there are various free and commercial
	applications available that do exactly that.</para>
	</sect2>

	<sect2>
	<title>The Window Manager</title>

	<para>The X design philosophy is much like the &unix; design
	philosophy, <quote>tools, not policy</quote>. This means
	that X does not try to dictate how a task is to be
	accomplished. Instead, tools are provided to the user, and
	it is the user's responsibility to decide how to use those
	tools.</para>

	<para>This philosophy extends to X not dictating what windows
	should look like on screen, how to move them around with the
	mouse, what keystrokes should be used to move between windows
	(i.e.,
	<keycombo action="simul">
	<keycap>Alt</keycap>
	<keycap>Tab</keycap>
	</keycombo>, in the case of &microsoft.windows;), what the
	title bars on each window should look like, whether or not
	they have close buttons on them, and so on.</para>

	<para>Instead, X delegates this responsibility to an
	application called a <quote>Window Manager</quote>. There
	- are dozens of window managers available for X:
	- <application>AfterStep</application>,
	- <application>Blackbox</application>,
	- <application>ctwm</application>,
	- <application>Enlightenment</application>,
	- <application>fvwm</application>,
	- <application>Sawfish</application>,
	- <application>twm</application>,
	- <application>Window Maker</application>, and more. Each of
	+ are <ulink
	+ url="http://xwinman.org/">dozens of window managers</ulink>
	+ available for X. Each of
	these window managers provides a different look and feel;
	some of them support <quote>virtual desktops</quote>; some
	of them allow customized keystrokes to manage the desktop;
	some have a <quote>Start</quote> button or similar device;
	some are <quote>themeable</quote>, allowing a complete change
	- of look-and-feel by applying a new theme. These window
	- managers, and many more, are available in the
	+ of look-and-feel by applying a new theme. Window managers
	+ are available in the
	<filename>x11-wm</filename> category of the Ports
	Collection.</para>

	<para>In addition, the <application>KDE</application> and
	<application>GNOME</application> desktop environments both
	have their own window managers which integrate with the
	desktop.</para>

	<para>Each window manager also has a different configuration
	mechanism; some expect configuration file written by hand,
	others feature GUI tools for most of the configuration tasks;
	at least one (<application>Sawfish</application>) has a
	configuration file written in a dialect of the Lisp
	language.</para>

	<note>
	<title>Focus Policy</title>

	<para>Another feature the window manager is responsible for
	is the mouse <quote>focus policy</quote>. Every windowing
	system needs some means of choosing a window to be actively
	receiving keystrokes, and should visibly indicate which
	window is active as well.</para>

	<para>A familiar focus policy is called
	<quote>click-to-focus</quote>. This is the model utilized
	by &microsoft.windows;, in which a window becomes active
	upon receiving a mouse click.</para>

	<para>X does not support any particular focus policy.
	Instead, the window manager controls which window has the
	focus at any one time. Different window managers will
	support different focus methods. All of them support
	click to focus, and the majority of them support several
	others.</para>

	<para>The most popular focus policies are:</para>

	<variablelist>
	<varlistentry>
	<term>focus-follows-mouse</term>

	<listitem>
	<para>The window that is under the mouse pointer is
	the window that has the focus. This may not
	necessarily be the window that is on top of all the
	other windows. The focus is changed by pointing at
	another window, there is no need to click in it as
	well.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>sloppy-focus</term>

	<listitem>
	<para>This policy is a small extension to
	focus-follows-mouse. With focus-follows-mouse, if
	the mouse is moved over the root window (or
	background) then no window has the focus, and
	keystrokes are simply lost. With sloppy-focus, focus
	is only changed when the cursor enters a new
	window, and not when exiting the current
	window.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term>click-to-focus</term>

	<listitem>
	<para>The active window is selected by mouse click.
	The window may then be <quote>raised</quote>, and
	appear in front of all other windows. All keystrokes
	will now be directed to this window, even if the
	cursor is moved to another window.</para>
	</listitem>
	</varlistentry>
	</variablelist>

	<para>Many window managers support other policies, as well
	as variations on these. Be sure to consult the
	documentation for the window manager itself.</para>
	</note>
	</sect2>

	<sect2>
	<title>Widgets</title>

	<para>The X approach of providing tools and not policy
	extends to the widgets seen on screen in each
	application.</para>

	<para><quote>Widget</quote> is a term for all the items in
	the user interface that can be clicked or manipulated in
	some way; buttons, check boxes, radio buttons, icons, lists,
	and so on. &microsoft.windows; calls these
	<quote>controls</quote>.</para>

	<para>&microsoft.windows; and Apple's &macos; both have a
	very rigid widget policy. Application developers are
	supposed to ensure that their applications share a common
	look and feel. With X, it was not considered sensible to
	mandate a particular graphical style, or set of widgets to
	adhere to.</para>

	<para>As a result, do not expect X applications to have a
	common look and feel. There are several popular widget sets
	- and variations, including the original Athena widget set from
	- MIT, <application>&motif;</application> (on which the widget
	- set in &microsoft.windows; was modeled, all bevelled edges and
	- three shades of grey), <application>OpenLook</application>,
	- and others.</para>
	-
	- <para>Most newer X applications today will use a
	- modern-looking widget set, either Qt, used by
	- <application>KDE</application>, or GTK+, used by the
	+ and variations, including Qt, used by
	+ <application>KDE</application>, and GTK+, used by the
	<application>GNOME</application> project. In this respect,
	there is some convergence in look-and-feel of the &unix;
	desktop, which certainly makes things easier for the novice
	user.</para>
	</sect2>
	</sect1>

	<sect1 id="x-install">
	<title>Installing X11</title>

	- <para><application>&xorg;</application> is the default X11
	+ <para><application>&xorg;</application> is the X11
	implementation for &os;. <application>&xorg;</application>
	is the X server of the open source X Window System
	implementation released by the X.Org Foundation.
	<application>&xorg;</application> is based on the code of
	<application>&xfree86; 4.4RC2</application> and X11R6.6.
	The version of <application>&xorg;</application> currently
	available in the &os; Ports Collection is &xorg.version;.</para>

	<para>To build and install <application>&xorg;</application>
	from the Ports Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/x11/xorg</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<note>
	<para>To build <application>&xorg;</application> in its
	entirety, be sure to have at least 4 GB of free space
	available.</para>
	</note>

	<para>Alternatively, X11
	can be installed directly from packages.
	Binary packages to use with &man.pkg.add.1; tool are also
	available for X11. When the remote fetching feature of
	&man.pkg.add.1; is used, the version number of the package
	must be removed. &man.pkg.add.1; will automatically fetch
	the latest version of the application.</para>

	<para>So to fetch and install the package of
	<application>&xorg;</application>, simply type:</para>

	<screen>&prompt.root; <userinput>pkg_add -r xorg</userinput></screen>

	<note><para>The examples above will install the complete
	X11 distribution including the
	servers, clients, fonts etc. Separate packages and ports of X11
	are also
	available.</para>

	<para>To install a minimal X11 distribution you can
	alternatively install
	<filename role="package">x11/xorg-minimal</filename>.</para>
	</note>

	<para>The rest of this chapter will explain how to configure
	X11, and how to set up a productive desktop
	environment.</para>
	</sect1>

	<sect1 id="x-config">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Christopher</firstname>
	<surname>Shumway</surname>
	<contrib>Contributed by </contrib>
	<!-- July 2001 -->
	</author>
	</authorgroup>
	</sect1info>
	<title>X11 Configuration</title>


	<indexterm><primary>&xorg;</primary></indexterm>
	<indexterm><primary>X11</primary></indexterm>

	<sect2>
	<title>Before Starting</title>

	<para>In most cases, X11 is self-configuring. Those with older
	or unusual equipment may find it helpful to gather some
	hardware information before beginning configuration.</para>

	<itemizedlist>
	<listitem><para>Monitor sync frequencies</para></listitem>
	<listitem><para>Video card chipset</para></listitem>
	<listitem><para>Video card memory</para></listitem>
	</itemizedlist>

	<indexterm>
	<primary>horizontal sync frequency</primary>
	</indexterm>
	<indexterm>
	<primary>horizontal scan rate</primary>
	<see>horizontal sync frequency</see>
	</indexterm>
	<indexterm><primary>refresh rate</primary></indexterm>
	<indexterm>
	<primary>vertical sync frequency</primary>
	<see>refresh rate</see>
	</indexterm>
	<indexterm>
	<primary>vertical scan rate</primary>
	<see>refresh rate</see>
	</indexterm>

	<para>Screen resolution and refresh rate are determined by the
	monitor's horizontal and vertical sync frequencies. Almost
	all monitors support electronic autodetection of these values.
	A few monitors do not provide these values, and the
	specifications must be determined from the printed manual
	or manufacturer web site.</para>

	<para>The video card chipset is also autodetected, and used to
	select the proper video driver. It is beneficial for the user
	to be aware of which chipset is installed for when
	autodetection does not provide the desired result.</para>

	<para>Video card memory determines the maximum resolution and
	color depth which can be displayed.</para>
	</sect2>

	<sect2>
	<title>Configuring X11</title>

	<para><application>&xorg;</application>
	uses <acronym>HAL</acronym> to autodetect keyboards and mice.
	The <filename role="package">sysutils/hal</filename> and
	<filename role="package">devel/dbus</filename> ports are
	installed as dependencies of <filename
	role="package">x11/xorg</filename>, but must be enabled by
	the following entries in the
	<filename>/etc/rc.conf</filename> file:</para>

	<programlisting>hald_enable="YES"
	dbus_enable="YES"</programlisting>

	<para>These services should be started (either manually or by
	rebooting) before further <application>&xorg;</application>
	configuration or use is attempted.</para>

	<para><application>&xorg;</application> can
	often work without any further configuration steps by
	simply typing at prompt:</para>

	<screen>&prompt.user; <userinput>startx</userinput></screen>

	<para>The automatic configuration may fail to work with some
	hardware, or may not set things up quite as desired. In
	these cases, manual configuration will be necessary.</para>

	<note>
	<para>Desktop environments like
	<application>GNOME</application>,
	<application>KDE</application> or
	<application>Xfce</application> have tools allowing the user
	to easily set the screen parameters such as the resolution.
	So if the default configuration is not acceptable and you
	planned to install a desktop environment then just continue
	with the installation of the desktop environment and use the
	appropriate screen settings tool.</para>
	</note>

	<para>Configuration of X11 is a multi-step process. The first
	step is to build an initial configuration file. As the super
	user, simply run:</para>

	<screen>&prompt.root; <userinput>Xorg -configure</userinput></screen>

	<para>This will generate an
	X11 configuration skeleton file in the
	<filename>/root</filename> directory called
	<filename>xorg.conf.new</filename> (whether you &man.su.1; or
	do a direct login affects the inherited supervisor
	<envar>$HOME</envar> directory variable). The
	X11 program will attempt to probe
	the graphics hardware on the system and write a
	configuration file to load the proper drivers for the detected
	hardware on the target system.</para>

	<para>The next step is to test the existing
	configuration to verify that <application>&xorg;</application>
	can work with the graphics
	hardware on the target system. Type:</para>

	<screen>&prompt.root; <userinput>Xorg -config xorg.conf.new -retro</userinput></screen>

	<para>If a black and grey grid and an X mouse cursor appear,
	the configuration was successful. To exit the test, switch
	to the virtual console used to start it by pressing
	<keycombo action="simul">
	<keycap>Ctrl</keycap>
	<keycap>Alt</keycap>
	<keycap>F<replaceable>n</replaceable></keycap>
	</keycombo> (<keycap>F1</keycap> for the first virtual
	console) and press
	<keycombo action="simul">
	<keycap>Ctrl</keycap>
	<keycap>C</keycap>
	</keycombo>.</para>

	<note>
	<para>The
	<keycombo action="simul">
	<keycap>Ctrl</keycap>
	<keycap>Alt</keycap>
	<keycap>Backspace</keycap>
	</keycombo> key combination may also be used to break out of
	<application>&xorg;</application>. To enable it,
	you can either type the following
	command from any X terminal emulator:</para>

	<screen>&prompt.user; <userinput>setxkbmap -option terminate:ctrl_alt_bksp</userinput></screen>

	<para>or create a keyboard configuration file for
	<application>hald</application> called
	<filename>x11-input.fdi</filename> and saved in the
	<filename
	class="directory">/usr/local/etc/hal/fdi/policy</filename>
	directory. This file should contain the following
	lines:</para>

	<programlisting><?xml version="1.0" encoding="iso-8859-1"?>
	<deviceinfo version="0.2">
	<device>
	<match key="info.capabilities" contains="input.keyboard">
	<merge key="input.x11_options.XkbOptions" type="string">terminate:ctrl_alt_bksp</merge>
	</match>
	</device>
	</deviceinfo></programlisting>

	<para>You will have to reboot your machine to force
	<application>hald</application> to read this file.</para>

	<para>The following line will also have to be added to
	<filename>xorg.conf.new</filename>, in the
	<literal>ServerLayout</literal> or
	<literal>ServerFlags</literal> section:</para>

	<programlisting>Option "DontZap" "off"</programlisting>
	</note>

	<para>If the mouse does not work, you will need to first
	configure it before proceeding. See <xref linkend="mouse"/>
	in the &os; install chapter. In recent
	<application>Xorg</application> versions,
	the <literal>InputDevice</literal> sections in
	<filename>xorg.conf</filename> are ignored in favor of the
	autodetected devices. To restore the old behavior, add the
	following line to the <literal>ServerLayout</literal> or
	<literal>ServerFlags</literal> section of this file:</para>

	<programlisting>Option "AutoAddDevices" "false"</programlisting>

	<para>Input devices may then be configured as in previous
	versions, along with any other options needed (e.g.,
	keyboard layout switching).</para>

	<note>
	<para>As previously explained
	the <application>hald</application> daemon will, by default,
	automatically detect your keyboard. There are chances that
	your keyboard layout or model will not be correct, desktop
	environments like <application>GNOME</application>,
	<application>KDE</application> or
	<application>Xfce</application> provide tools to configure
	the keyboard. However, it is possible to set the keyboard
	properties directly either with the help of the
	&man.setxkbmap.1; utility or with a
	<application>hald</application>'s configuration rule.</para>

	<para>For example if one wants to use a PC 102 keys keyboard
	coming with a french layout, we have to create a keyboard
	configuration file for <application>hald</application>
	called <filename>x11-input.fdi</filename> and saved in the
	<filename
	class="directory">/usr/local/etc/hal/fdi/policy</filename>
	directory. This file should contain the following
	lines:</para>

	<programlisting><?xml version="1.0" encoding="iso-8859-1"?>
	<deviceinfo version="0.2">
	<device>
	<match key="info.capabilities" contains="input.keyboard">
	<merge key="input.x11_options.XkbModel" type="string">pc102</merge>
	<merge key="input.x11_options.XkbLayout" type="string">fr</merge>
	</match>
	</device>
	</deviceinfo></programlisting>

	<para>If this file already exists, just copy and add to your
	file the lines regarding the keyboard configuration.</para>

	<para>You will have to reboot your machine to force
	<application>hald</application> to read this file.</para>

	<para>It is possible to do the same configuration from an X
	terminal or a script with this command line:</para>

	<screen>&prompt.user; <userinput>setxkbmap -model pc102 -layout fr</userinput></screen>

	<para>The
	<filename>/usr/local/share/X11/xkb/rules/base.lst</filename>
	file lists the various keyboard, layouts and options
	available.</para>
	</note>

	<indexterm><primary>X11 tuning</primary></indexterm>

	<para>The <filename>xorg.conf.new</filename>
	configuration file may now be tuned to taste. Open the
	file in a text editor such as &man.emacs.1; or &man.ee.1;.
	If the monitor is an older or unusual model that does not
	support autodetection of sync frequencies, those settings
	can be added to <filename>xorg.conf.new</filename>
	under the <literal>"Monitor"</literal> section:</para>

	<programlisting>Section "Monitor"
	Identifier "Monitor0"
	VendorName "Monitor Vendor"
	ModelName "Monitor Model"
	HorizSync 30-107
	VertRefresh 48-120
	EndSection</programlisting>

	<para>Most monitors support sync frequency autodetection,
	making manual entry of these values unnecessary. For the
	few monitors that do not support autodetection, avoid
	potential damage by only entering values provided by the
	manufacturer.</para>

	<para>X allows DPMS (Energy Star) features to be used with
	capable monitors. The &man.xset.1; program controls the
	time-outs and can force standby, suspend, or off modes. If
	you wish to enable DPMS features for your monitor, you must
	add the following line to the monitor section:</para>

	<programlisting>Option "DPMS"</programlisting>

	<indexterm>
	<primary><filename>xorg.conf</filename></primary>
	</indexterm>

	<para>While the <filename>xorg.conf.new</filename>
	configuration file is still open in an editor, select
	the default resolution and color depth desired. This is
	defined in the <literal>"Screen"</literal> section:</para>

	<programlisting>Section "Screen"
	Identifier "Screen0"
	Device "Card0"
	Monitor "Monitor0"
	DefaultDepth 24
	SubSection "Display"
	Viewport 0 0
	Depth 24
	Modes "1024x768"
	EndSubSection
	EndSection</programlisting>

	<para>The <literal>DefaultDepth</literal> keyword describes
	the color depth to run at by default. This can be overridden
	with the <option>-depth</option> command line switch to
	&man.Xorg.1;.
	The <literal>Modes</literal> keyword
	describes the resolution to run at for the given color depth.
	Note that only VESA standard modes are supported as defined by
	the target system's graphics hardware.
	In the example above, the default color depth is twenty-four
	bits per pixel. At this color depth, the accepted
	resolution is 1024 by 768 pixels.</para>

	<para>Finally, write the configuration file and test it using
	the test mode given above.</para>

	<note>
	<para>One of the tools available to assist you during
	troubleshooting process are the X11 log files, which
	contain information on each device that the X11 server
	attaches to. <application>&xorg;</application> log file
	names are in the format of
	<filename>/var/log/Xorg.0.log</filename>. The exact name
	of the log can vary from <filename>Xorg.0.log</filename>
	to <filename>Xorg.8.log</filename> and so forth.</para>
	</note>

	<para>If all is well, the configuration
	file needs to be installed in a common location where
	&man.Xorg.1; can find it.
	This is typically <filename>/etc/X11/xorg.conf</filename> or
	<filename>/usr/local/etc/X11/xorg.conf</filename>.</para>

	<screen>&prompt.root; <userinput>cp xorg.conf.new /etc/X11/xorg.conf</userinput></screen>

	<para>The X11 configuration process is now
	complete. <application>&xorg;</application> may be now
	started with the &man.startx.1; utility.
	The X11 server may also be started with the use of
	&man.xdm.1;.</para>
	</sect2>

	<sect2>
	<title>Advanced Configuration Topics</title>

	<sect3>
	<title>Configuration with &intel; <literal>i810</literal>
	Graphics Chipsets</title>

	<indexterm><primary>Intel i810 graphic chipset</primary></indexterm>

	<para>Configuration with &intel; i810 integrated chipsets
	requires the <devicename>agpgart</devicename>
	AGP programming interface for X11
	to drive the card. See the &man.agp.4; driver manual page
	for more information.</para>

	<para>This will allow configuration of the hardware as any
	other graphics board. Note on systems without the
	&man.agp.4; driver compiled in the kernel, trying to load
	the module with &man.kldload.8; will not work. This
	driver has to be in the kernel at boot time through being
	compiled in or using
	<filename>/boot/loader.conf</filename>.</para>
	</sect3>

	<sect3>
	<title>Adding a Widescreen Flatpanel to the Mix</title>

	<indexterm><primary>widescreen flatpanel configuration</primary></indexterm>

	<para>This section assumes a bit of advanced configuration
	knowledge. If attempts to use the standard configuration
	tools above have not resulted in a working configuration,
	there is information enough in the log files to be of use
	in getting the setup working. Use of a text editor will
	be necessary.</para>

	<para>Current widescreen (WSXGA, WSXGA+, WUXGA, WXGA,
	WXGA+, et.al.) formats support 16:10 and 10:9 formats or
	aspect ratios that can be problematic. Examples of some
	common screen resolutions for 16:10 aspect ratios
	are:</para>

	<itemizedlist>
	<listitem><para>2560x1600</para></listitem>
	<listitem><para>1920x1200</para></listitem>
	<listitem><para>1680x1050</para></listitem>
	<listitem><para>1440x900</para></listitem>
	<listitem><para>1280x800</para></listitem>
	</itemizedlist>

	<para>At some point, it will be as easy as adding one of these
	resolutions as a possible <literal>Mode</literal> in the
	<literal>Section "Screen"</literal> as such:</para>

	<programlisting>Section "Screen"
	Identifier "Screen0"
	Device "Card0"
	Monitor "Monitor0"
	DefaultDepth 24
	SubSection "Display"
	Viewport 0 0
	Depth 24
	Modes "1680x1050"
	EndSubSection
	EndSection</programlisting>

	<para><application>&xorg;</application> is smart enough to
	pull the resolution information from the widescreen via
	I2C/DDC information so it knows what the monitor can
	handle as far as frequencies and resolutions.</para>

	<para>If those <literal>ModeLines</literal> do not exist in
	the drivers, one might need to give
	<application>&xorg;</application> a little hint. Using
	<filename>/var/log/Xorg.0.log</filename> one can extract
	enough information to manually create a
	<literal>ModeLine</literal> that will work. Simply look
	for information resembling this:</para>

	<programlisting>(II) MGA(0): Supported additional Video Mode:
	(II) MGA(0): clock: 146.2 MHz Image Size: 433 x 271 mm
	(II) MGA(0): h_active: 1680 h_sync: 1784 h_sync_end 1960 h_blank_end 2240 h_border: 0
	(II) MGA(0): v_active: 1050 v_sync: 1053 v_sync_end 1059 v_blanking: 1089 v_border: 0
	(II) MGA(0): Ranges: V min: 48 V max: 85 Hz, H min: 30 H max: 94 kHz, PixClock max 170 MHz</programlisting>

	<para>This information is called EDID information. Creating a
	<literal>ModeLine</literal> from this is just a matter of
	putting the numbers in the correct order:</para>

	<programlisting>ModeLine <name> <clock> <4 horiz. timings> <4 vert. timings></programlisting>

	<para>So that the <literal>ModeLine</literal> in
	<literal>Section "Monitor"</literal>
	for this example would look like this:</para>

	<programlisting>Section "Monitor"
	Identifier "Monitor1"
	VendorName "Bigname"
	ModelName "BestModel"
	ModeLine "1680x1050" 146.2 1680 1784 1960 2240 1050 1053 1059 1089
	Option "DPMS"
	EndSection</programlisting>

	<para>Now having completed these simple editing steps, X
	should start on your new widescreen monitor.</para>
	</sect3>
	</sect2>
	</sect1>

	<sect1 id="x-fonts">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Murray</firstname>
	<surname>Stokely</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>Using Fonts in X11</title>

	<sect2 id="type1">
	<title>Type1 Fonts</title>

	<para>The default fonts that ship with X11 are less than ideal
	for typical desktop publishing applications. Large
	presentation fonts show up jagged and unprofessional looking,
	- and small fonts in <application>&netscape;</application> are
	+ and small fonts are
	almost completely unintelligible. However, there are several
	free, high quality Type1 (&postscript;) fonts available which
	can be readily used with X11. For instance, the URW font
	collection (<filename
	role="package">x11-fonts/urwfonts</filename>) includes high
	quality versions of standard type1 fonts (<trademark
	class="registered">Times Roman</trademark>,
	<trademark class="registered">Helvetica</trademark>, <trademark
	class="registered">Palatino</trademark> and others). The
	Freefonts collection (<filename
	role="package">x11-fonts/freefonts</filename>) includes
	many more fonts, but most of them are intended for use in
	graphics software such as the <application>Gimp</application>,
	and are not complete enough to serve as screen fonts. In
	addition, X11 can be configured to use &truetype; fonts with
	a minimum of effort. For more details on this, see the
	&man.X.7; manual page or the <link linkend="truetype">section
	on &truetype; fonts</link>.</para>

	<para>To install the above Type1 font collections from the
	Ports Collection, run the following commands:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/x11-fonts/urwfonts</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>And likewise with the freefont or other collections. To
	have the X server detect these fonts, add an appropriate line
	to the X server configuration file
	(<filename>/etc/X11/xorg.conf</filename>), which reads:</para>

	<programlisting>FontPath "/usr/local/lib/X11/fonts/URW/"</programlisting>

	<para>Alternatively, at the command line in the X session
	run:</para>

	<screen>&prompt.user; <userinput>xset fp+ /usr/local/lib/X11/fonts/URW</userinput>
	&prompt.user; <userinput>xset fp rehash</userinput></screen>

	<para>This will work but will be lost when the X session is
	closed, unless it is added to the startup file
	(<filename>~/.xinitrc</filename> for a normal
	<command>startx</command> session, or
	<filename>~/.xsession</filename> when logging in through a
	graphical login manager like <application>XDM</application>).
	A third way is to use the new
	<filename>/usr/local/etc/fonts/local.conf</filename> file: see
	the section on <link
	linkend="antialias">anti-aliasing</link>.</para>
	</sect2>

	<sect2 id="truetype">
	<title>&truetype; Fonts</title>

	<indexterm><primary>TrueType Fonts</primary></indexterm>
	<indexterm><primary>fonts</primary>
	<secondary>TrueType</secondary>
	</indexterm>

	<para><application>&xorg;</application> has built in support
	for rendering &truetype; fonts. There are two different
	modules that can enable this functionality. The freetype
	module is used in this example because it is more consistent
	with the other font rendering back-ends. To enable the
	freetype module just add the following line to the
	<literal>"Module"</literal> section of the
	<filename>/etc/X11/xorg.conf</filename> file.</para>

	<programlisting>Load "freetype"</programlisting>

	<para>Now make a directory for the &truetype; fonts (for
	example,
	<filename>/usr/local/lib/X11/fonts/TrueType</filename>)
	and copy all of the &truetype; fonts into this directory.
	Keep in mind that &truetype; fonts cannot be directly taken
	from a &macintosh;; they must be in &unix;/&ms-dos;/&windows;
	format for use by X11. Once the files have been copied into
	this directory, use <application>ttmkfdir</application> to
	create a <filename>fonts.dir</filename> file, so that the X
	font renderer knows that these new files have been installed.
	<command>ttmkfdir</command> is available from the FreeBSD
	Ports Collection as
	<filename role="package">x11-fonts/ttmkfdir</filename>.</para>

	<screen>&prompt.root; <userinput>cd /usr/local/lib/X11/fonts/TrueType</userinput>
	&prompt.root; <userinput>ttmkfdir -o fonts.dir</userinput></screen>

	<para>Now add the &truetype; directory to the font
	path. This is just the same as described above for <link
	linkend="type1">Type1</link> fonts, that is, use</para>

	<screen>&prompt.user; <userinput>xset fp+ /usr/local/lib/X11/fonts/TrueType</userinput>
	&prompt.user; <userinput>xset fp rehash</userinput></screen>

	<para>or add a <literal>FontPath</literal> line to the
	<filename>xorg.conf</filename> file.</para>

	- <para>That's it. Now <application>&netscape;</application>,
	- <application>Gimp</application>,
	- <application>&staroffice;</application>, and all of the
	+ <para>That's it. Now <application>Gimp</application>,
	+ <application>Apache OpenOffice</application>, and all of the
	other X applications should now recognize the installed
	&truetype; fonts. Extremely small fonts (as with text in a
	high resolution display on a web page) and extremely large
	fonts (within <application>&staroffice;</application>) will
	look much better now.</para>
	</sect2>

	<sect2 id="antialias">
	<sect2info>
	<authorgroup>
	<author>
	<firstname>Joe Marcus</firstname>
	<surname>Clarke</surname>
	<contrib>Updated by </contrib>
	<!-- May 2003 -->
	</author>
	</authorgroup>
	</sect2info>
	<title>Anti-Aliased Fonts</title>

	<indexterm><primary>anti-aliased fonts</primary></indexterm>
	<indexterm><primary>fonts</primary>
	<secondary>anti-aliased</secondary></indexterm>

	<para>All fonts in X11 that are found
	in <filename>/usr/local/lib/X11/fonts/</filename> and
	<filename>~/.fonts/</filename> are automatically
	made available for anti-aliasing to Xft-aware applications.
	Most recent applications are Xft-aware, including
	<application>KDE</application>,
	<application>GNOME</application>, and
	<application>Firefox</application>.</para>

	<para>In order to control which fonts are anti-aliased, or to
	configure anti-aliasing properties, create (or edit, if it
	already exists) the file
	<filename>/usr/local/etc/fonts/local.conf</filename>. Several
	advanced features of the Xft font system can be tuned using
	this file; this section describes only some simple
	possibilities. For more details, please see
	&man.fonts-conf.5;.</para>

	<indexterm><primary>XML</primary></indexterm>

	<para>This file must be in XML format. Pay careful attention
	to case, and make sure all tags are properly closed. The
	file begins with the usual XML header followed by a DOCTYPE
	definition, and then the <literal><fontconfig></literal>
	tag:</para>

	<programlisting>
	<?xml version="1.0"?>
	<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
	<fontconfig></programlisting>

	<para>As previously stated, all fonts in
	<filename>/usr/local/lib/X11/fonts/</filename> as well as
	<filename>~/.fonts/</filename> are already made available to
	Xft-aware applications. If you wish to add another directory
	outside of these two directory trees, add a line similar to the
	following to
	<filename>/usr/local/etc/fonts/local.conf</filename>:</para>

	<programlisting><dir>/path/to/my/fonts</dir></programlisting>

	<para>After adding new fonts, and especially new font directories,
	you should run the following command to rebuild the font
	caches:</para>

	<screen>&prompt.root; <userinput>fc-cache -f</userinput></screen>

	<para>Anti-aliasing makes borders slightly fuzzy, which makes
	very small text more readable and removes
	<quote>staircases</quote> from large text, but can cause
	eyestrain if applied to normal text. To exclude font sizes
	smaller than 14 point from anti-aliasing, include these
	lines:</para>

	<programlisting> <match target="font">
	<test name="size" compare="less">
	<double>14</double>
	</test>
	<edit name="antialias" mode="assign">
	<bool>false</bool>
	</edit>
	</match>
	<match target="font">
	<test name="pixelsize" compare="less" qual="any">
	<double>14</double>
	</test>
	<edit mode="assign" name="antialias">
	<bool>false</bool>
	</edit>
	</match></programlisting>

	<indexterm><primary>fonts</primary>
	<secondary>spacing</secondary></indexterm>

	<para>Spacing for some monospaced fonts may also be inappropriate
	with anti-aliasing. This seems to be an issue with
	<application>KDE</application>, in particular. One possible
	fix for this is to force the spacing for such fonts to be 100.
	Add the following lines:</para>

	<programlisting> <match target="pattern" name="family">
	<test qual="any" name="family">
	<string>fixed</string>
	</test>
	<edit name="family" mode="assign">
	<string>mono</string>
	</edit>
	</match>
	<match target="pattern" name="family">
	<test qual="any" name="family">
	<string>console</string>
	</test>
	<edit name="family" mode="assign">
	<string>mono</string>
	</edit>
	</match></programlisting>

	<para>(this aliases the other common names for fixed fonts as
	<literal>"mono"</literal>), and then add:</para>

	<programlisting> <match target="pattern" name="family">
	<test qual="any" name="family">
	<string>mono</string>
	</test>
	<edit name="spacing" mode="assign">
	<int>100</int>
	</edit>
	</match> </programlisting>

	<para>Certain fonts, such as Helvetica, may have a problem when
	anti-aliased. Usually this manifests itself as a font that
	seems cut in half vertically. At worst, it may cause
	applications to
	crash. To avoid this, consider adding the following to
	<filename>local.conf</filename>:</para>

	<programlisting> <match target="pattern" name="family">
	<test qual="any" name="family">
	<string>Helvetica</string>
	</test>
	<edit name="family" mode="assign">
	<string>sans-serif</string>
	</edit>
	</match> </programlisting>

	<para>Once you have finished editing
	<filename>local.conf</filename> make sure you end the file
	with the <literal></fontconfig></literal> tag. Not
	doing this will cause your changes to be ignored.</para>

	<para>Finally, users can add their own settings via their
	personal <filename>.fonts.conf</filename> files. To do
	this, each user should simply create a
	<filename>~/.fonts.conf</filename>. This file must also be
	in XML format.</para>

	<indexterm><primary>LCD screen</primary></indexterm>
	<indexterm><primary>Fonts</primary>
	<secondary>LCD screen</secondary></indexterm>

	<para>One last point: with an LCD screen, sub-pixel sampling
	may be desired. This basically treats the (horizontally
	separated) red, green and blue components separately to
	improve the horizontal resolution; the results can be
	dramatic. To enable this, add the line somewhere in the
	<filename>local.conf</filename> file:</para>

	<programlisting>
	<match target="font">
	<test qual="all" name="rgba">
	<const>unknown</const>
	</test>
	<edit name="rgba" mode="assign">
	<const>rgb</const>
	</edit>
	</match></programlisting>

	<note>
	<para>Depending on the sort of display,
	<literal>rgb</literal> may need to be changed to
	<literal>bgr</literal>, <literal>vrgb</literal> or
	<literal>vbgr</literal>: experiment and see which works
	best.</para>
	</note>
	</sect2>
	</sect1>

	<sect1 id="x-xdm">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Seth</firstname>
	<surname>Kingsley</surname>
	<contrib>Contributed by </contrib>
	</author>
	</authorgroup>
	</sect1info>
	<title>The X Display Manager</title>
	<sect2>

	<title>Overview</title>

	<indexterm><primary>X Display Manager</primary></indexterm>
	<para>The X Display Manager (<application>XDM</application>)
	is an optional part of the X Window System that is used for
	login session management. This is useful for several types
	of situations, including minimal <quote>X Terminals</quote>,
	desktops, and large network display servers. Since the X
	Window System is network and protocol independent, there are
	a wide variety of possible configurations for running X
	clients and servers on different machines connected by a
	network. <application>XDM</application> provides a graphical
	interface for choosing which display server to connect to,
	and entering authorization information such as a login and
	password combination.</para>

	<para>Think of <application>XDM</application> as
	providing the same functionality to the user as the
	&man.getty.8; utility (see <xref linkend="term-config"/> for
	details). That is, it performs system logins to the display
	being connected to and then runs a session manager on
	behalf of the user (usually an X window manager).
	<application>XDM</application> then waits for this program to
	exit, signaling that the user is done and should be logged out
	of the display. At this point, <application>XDM</application>
	can display the login and display chooser screens for the next
	user to login.</para>
	</sect2>

	<sect2>
	<title>Using XDM</title>

	<para>To start using <application>XDM</application>, install
	the <filename role="package">x11/xdm</filename> port (it is
	not installed by default in recent versions of
	<application>&xorg;</application>). The
	<application>XDM</application> daemon program may then be
	found in <filename>/usr/local/bin/xdm</filename>. This
	program can be run at any time as <username>root</username>
	and it will start managing the X display on the local machine.
	If <application>XDM</application> is to be run every
	time the machine boots up, a convenient way to do this is by
	adding an entry to <filename>/etc/ttys</filename>. For more
	information about the format and usage of this file, see <xref
	linkend="term-etcttys"/>. There is a line in the default
	<filename>/etc/ttys</filename> file for running the
	<application>XDM</application> daemon on a virtual
	terminal:</para>

	<screen>ttyv8 "/usr/local/bin/xdm -nodaemon" xterm off secure</screen>

	<para>By default this entry is disabled; in order to enable it
	change field 5 from <literal>off</literal> to
	<literal>on</literal> and restart &man.init.8; using the
	directions in <xref linkend="term-hup"/>. The first field,
	the name of the terminal this program will manage, is
	<literal>ttyv8</literal>. This means that
	<application>XDM</application> will start running on the 9th
	virtual terminal.</para>
	</sect2>

	<sect2>
	<title>Configuring XDM</title>

	<para>The <application>XDM</application> configuration directory
	is located in <filename>/usr/local/lib/X11/xdm</filename>.
	In this directory there are several files used to change the
	behavior and appearance of
	<application>XDM</application>. Typically these files will
	be found:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>File</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><filename>Xaccess</filename></entry>
	<entry>Client authorization ruleset.</entry>
	</row>

	<row>
	<entry><filename>Xresources</filename></entry>
	<entry>Default X resource values.</entry>
	</row>

	<row>
	<entry><filename>Xservers</filename></entry>
	<entry>List of remote and local displays to
	manage.</entry>
	</row>

	<row>
	<entry><filename>Xsession</filename></entry>
	<entry>Default session script for logins.</entry>
	</row>

	<row>
	<entry><filename>Xsetup_</filename>*</entry>
	<entry>Script to launch applications before the login
	interface.</entry>
	</row>

	<row>
	<entry><filename>xdm-config</filename></entry>
	<entry>Global configuration for all displays running
	on this machine.</entry>
	</row>

	<row>
	<entry><filename>xdm-errors</filename></entry>
	<entry>Errors generated by the server program.</entry>
	</row>

	<row>
	<entry><filename>xdm-pid</filename></entry>
	<entry>The process ID of the currently running
	XDM.</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>Also in this directory are a few scripts and programs
	used to set up the desktop when <application>XDM</application>
	is running. The purpose of each of these files will be
	briefly described. The exact syntax and usage of all of
	these files is described in &man.xdm.1;.</para>

	<para>The default configuration is a simple rectangular login
	window with the hostname of the machine displayed at the
	top in a large font and <quote>Login:</quote> and
	<quote>Password:</quote> prompts below. This is a good
	starting point for changing the look and feel of
	<application>XDM</application> screens.</para>

	<sect3>
	<title>Xaccess</title>

	<para>The protocol for connecting to
	<application>XDM</application>-controlled displays is
	called the X Display Manager Connection Protocol (XDMCP).
	This file is a ruleset for controlling XDMCP connections
	from remote machines. It is ignored unless the
	<filename>xdm-config</filename> is changed to listen for
	remote connections. By default, it does not allow any
	clients to connect.</para>
	</sect3>

	<sect3>
	<title>Xresources</title>

	<para>This is an application-defaults file for the display
	chooser and login screens. In it, the appearance
	of the login program can be modified. The format is
	identical to the app-defaults file described in the
	X11 documentation.</para>
	</sect3>

	<sect3>
	<title>Xservers</title>

	<para>This is a list of the remote displays the chooser should
	provide as choices.</para>
	</sect3>

	<sect3>
	<title>Xsession</title>

	<para>This is the default session script for
	<application>XDM</application> to run after a user has
	logged in. Normally each user will have a customized
	session script in <filename>~/.xsession</filename> that
	overrides this script.</para>
	</sect3>

	<sect3>
	<title>Xsetup_*</title>

	<para>These will be run automatically before displaying the
	chooser or login interfaces. There is a script for each
	display being used, named <filename>Xsetup_</filename>
	followed by the local display number (for instance
	<filename>Xsetup_0</filename>). Typically these scripts
	will run one or two programs in the background such as
	<command>xconsole</command>.</para>
	</sect3>

	<sect3>
	<title>xdm-config</title>

	<para>This contains settings in the form of app-defaults
	that are applicable to every display that this installation
	manages.</para>
	</sect3>

	<sect3>
	<title>xdm-errors</title>

	<para>This contains the output of the X servers that
	<application>XDM</application> is trying to run. If a
	display that <application>XDM</application> is trying to
	start hangs for some reason, this is a good place to look
	for error messages. These messages are also written to the
	user's <filename>~/.xsession-errors</filename> file on a
	per-session basis.</para>
	</sect3>
	</sect2>

	<sect2>
	<title>Running a Network Display Server</title>

	<para>In order for other clients to connect to the display
	server, you must edit the access control rules and enable
	the connection listener. By default these are set to
	conservative values. To make <application>XDM</application>
	listen for connections, first comment out a line in the
	<filename>xdm-config</filename> file:</para>

	<screen>! SECURITY: do not listen for XDMCP or Chooser requests
	! Comment out this line if you want to manage X terminals with xdm
	DisplayManager.requestPort: 0</screen>

	<para>and then restart <application>XDM</application>.
	Remember that comments in app-defaults files begin with a
	<quote>!</quote> character, not the usual <quote>#</quote>.
	More strict access controls may be desired — look at the
	example entries in <filename>Xaccess</filename>, and refer to
	the &man.xdm.1; manual page for further information.</para>
	</sect2>

	<sect2>
	<title>Replacements for XDM</title>

	<para>Several replacements for the default
	<application>XDM</application> program exist. One of them,
	<application>KDM</application> (bundled with
	<application>KDE</application>) is described later in this
	chapter. The <application>KDM</application> display
	manager offers many visual improvements and cosmetic frills,
	as well as the functionality to allow users to choose their
	window manager of choice at login time.</para>
	</sect2>
	</sect1>

	<sect1 id="x11-wm">
	<sect1info>
	<authorgroup>
	<author>
	<firstname>Valentino</firstname>
	<surname>Vaschetto</surname>
	<contrib>Contributed by </contrib>
	</author>
	<!-- June 2001 -->
	</authorgroup>
	</sect1info>

	<title>Desktop Environments</title>

	<para>This section describes the different desktop environments
	available for X on FreeBSD. A <quote>desktop
	environment</quote> can mean anything ranging from a simple
	window manager to a complete suite of desktop applications, such
	as <application>KDE</application> or
	<application>GNOME</application>.</para>

	<sect2 id="x11-wm-gnome">
	<title>GNOME</title>

	<sect3 id="x11-wm-gnome-about">
	<title>About GNOME</title>

	<indexterm><primary>GNOME</primary></indexterm>
	<para><application>GNOME</application> is a user-friendly
	desktop environment that enables users to easily use and
	configure their computers. <application>GNOME</application>
	includes a panel (for starting applications and displaying
	status), a desktop (where data and applications can be
	placed), a set of standard desktop tools and applications,
	anda set of conventions that make it easy for applications
	to cooperate and be consistent with each other. Users of
	other operating systems or environments should feel right
	at home using the powerful graphics-driven environment that
	<application>GNOME</application> provides. More
	information regarding <application>GNOME</application> on
	FreeBSD can be found on the <ulink
	url="http://www.FreeBSD.org/gnome">FreeBSD GNOME
	Project</ulink>'s web site. The web site also contains
	fairly comprehensive FAQs about installing, configuring,
	and managing <application>GNOME</application>.</para>
	</sect3>

	<sect3 id="x11-wm-gnome-install">
	<title>Installing GNOME</title>

	<para>The software can be easily installed from a package
	or the Ports Collection:</para>

	<para>To install the <application>GNOME</application> package
	from the network, simply type:</para>

	<screen>&prompt.root; <userinput>pkg_add -r gnome2</userinput></screen>

	<para>To build <application>GNOME</application> from source,
	use the ports tree:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome2</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>For proper operation, <application>GNOME</application>
	requires the <filename>/proc</filename> filesystem to be
	mounted. Add</para>

	<programlisting>proc /proc procfs rw 0 0</programlisting>

	<para>to <filename>/etc/fstab</filename> to mount
	&man.procfs.5; automatically during
	startup.</para>

	<para>Once <application>GNOME</application> is installed,
	the X server must be told to start
	<application>GNOME</application> instead of a default window
	manager.</para>

	<para>The easiest way to start
	<application>GNOME</application> is with
	<application>GDM</application>, the GNOME Display Manager.
	<application>GDM</application> is installed as part
	of the <application>GNOME</application> desktop, although
	it is disabled by default. It can be enabled by adding this
	line to <filename>/etc/rc.conf</filename>:</para>

	<programlisting>gdm_enable="YES"</programlisting>

	<para>Once you have rebooted,
	<application>GDM</application> will start
	automatically.</para>

	<para>It is often desirable to start all
	<application>GNOME</application> services together with
	<application>GDM</application>. To achieve this, add the
	following line to <filename>/etc/rc.conf</filename>:</para>

	<programlisting>gnome_enable="YES"</programlisting>

	<para><application>GNOME</application> may also be started
	from the command-line by properly configuring a file named
	<filename>.xinitrc</filename>.
	If a custom <filename>.xinitrc</filename> is already in
	place, simply replace the line that starts the current
	window manager with one that starts
	<application>/usr/local/bin/gnome-session</application>
	instead. If nothing special has been done to the
	configuration file, then it is enough simply to type:</para>

	<screen>&prompt.user; <userinput>echo "/usr/local/bin/gnome-session" > ~/.xinitrc</userinput></screen>

	<para>Next, type <command>startx</command>, and the
	<application>GNOME</application> desktop environment will
	be started.</para>

	<note><para>If an older display manager, like
	<application>XDM</application>, is being used, this will
	not work. Instead, create an executable
	<filename>.xsession</filename> file with the same command
	in it. To do this, edit the file and replace the existing
	window manager command with
	<application>/usr/local/bin/gnome-session</application>:
	</para></note>

	<screen>&prompt.user; <userinput>echo "#!/bin/sh" > ~/.xsession</userinput>
	&prompt.user; <userinput>echo "/usr/local/bin/gnome-session" >> ~/.xsession</userinput>
	&prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>

	<para>Yet another option is to configure the display manager
	to allow choosing the window manager at login time; the
	section on
	<link linkend="x11-wm-kde-details">KDE details</link>
	explains how to do this for <application>KDM</application>,
	the display manager of
	<application>KDE</application>.</para>
	</sect3>
	</sect2>

	<sect2 id="x11-wm-kde">
	<title>KDE</title>

	<indexterm><primary>KDE</primary></indexterm>
	<sect3 id="x11-wm-kde-about">
	<title>About KDE</title>

	<para><application>KDE</application> is an easy to use
	contemporary desktop environment. Some of the things
	that <application>KDE</application> brings to the user
	are:</para>

	<itemizedlist>
	<listitem>
	<para>A beautiful contemporary desktop</para>
	</listitem>

	<listitem>
	<para>A desktop exhibiting complete network
	transparency</para>
	</listitem>

	<listitem>
	<para>An integrated help system allowing for convenient,
	consistent access to help on the use of the
	<application>KDE</application> desktop and its
	applications</para>
	</listitem>

	<listitem>
	<para>Consistent look and feel of all
	<application>KDE</application> applications</para>
	</listitem>

	<listitem>
	<para>Standardized menu and toolbars, keybindings,
	color-schemes, etc.</para>
	</listitem>

	<listitem>
	<para>Internationalization: <application>KDE</application>
	is available in more than 55 languages</para>
	</listitem>

	<listitem>
	<para>Centralized, consistent, dialog-driven desktop
	configuration</para>
	</listitem>

	<listitem>
	<para>A great number of useful
	<application>KDE</application> applications</para>
	</listitem>
	</itemizedlist>

	<para><application>KDE</application> comes with a web
	browser called <application>Konqueror</application>, which
	is a solid competitor to other existing web browsers on
	&unix; systems. More information on
	<application>KDE</application> can be found on the <ulink
	url="http://www.kde.org/">KDE website</ulink>. For FreeBSD
	specific information and resources on
	<application>KDE</application>, consult the <ulink
	url="http://freebsd.kde.org/">KDE/FreeBSD
	initiative</ulink>'s website.</para>

	<para>There are two versions of
	<application>KDE</application> available on FreeBSD.
	Version 3 has been around for a long time, and is still
	available in the Ports Collection though it's now
	unmaintained and partially broken. Version 4 is
	punctually updated and is the default choice for
	<application>KDE</application> users. They can even be
	installed side by side.</para>
	</sect3>

	<sect3 id="x11-wm-kde-install">
	<title>Installing KDE</title>

	<para>Just as with <application>GNOME</application> or any
	other desktop environment, the software can be easily
	installed from a package or the Ports Collection:</para>

	<para>To install the <application>KDE 3</application> package
	from the network, type:</para>

	<screen>&prompt.root; <userinput>pkg_add -r kde</userinput></screen>

	<para>To install the <application>KDE 4</application> package
	from the network, type:</para>

	<screen>&prompt.root; <userinput>pkg_add -r kde4</userinput></screen>

	<para>&man.pkg.add.1; will automatically fetch the latest
	version of the application.</para>

	<para>To build <application>KDE 3</application> from source,
	use the ports tree:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/x11/kde3</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>To build <application>KDE 4</application> from source,
	use the ports tree:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/x11/kde4</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>After <application>KDE</application> has been installed,
	the X server must be told to launch this application
	instead of the default window manager. This is accomplished
	by editing the <filename>.xinitrc</filename> file:</para>

	<para>For <application>KDE 3</application>:</para>

	<screen>&prompt.user; <userinput>echo "exec startkde" > ~/.xinitrc</userinput></screen>

	<para>For <application>KDE 4</application>:</para>

	<screen>&prompt.user; <userinput>echo "exec /usr/local/kde4/bin/startkde" > ~/.xinitrc</userinput></screen>

	<para>Now, whenever the X Window System is invoked with
	<command>startx</command>,
	<application>KDE</application> will be the desktop.</para>

	<para>If a display manager such as
	<application>XDM</application> is being used, the
	configuration is slightly different. Edit the
	<filename>.xsession</filename> file instead. Instructions
	for <application>KDM</application> are described later in
	this chapter.</para>
	</sect3>
	</sect2>

	<sect2 id="x11-wm-kde-details">
	<title>More Details on KDE</title>

	<para>Now that <application>KDE</application> is installed
	on the system, most things can be discovered through the
	help pages, or just by pointing and clicking at various
	menus. &windows; or &mac; users will feel quite at
	home.</para>

	<para>The best reference for <application>KDE</application>
	is the on-line documentation.
	<application>KDE</application> comes with its own web
	browser, <application>Konqueror</application>, dozens of
	useful applications, and extensive documentation. The
	remainder of this section discusses the technical items
	that are difficult to learn by random exploration.</para>

	<sect3 id="x11-wm-kde-kdm">
	<title>The KDE Display Manager</title>

	<indexterm><primary>KDE</primary>
	<secondary>display manager</secondary></indexterm>
	<para>An administrator of a multi-user system may wish to
	have a graphical login screen to welcome users.
	<link linkend="x-xdm">XDM</link> can be used, as described
	earlier. However, <application>KDE</application> includes
	an alternative, <application>KDM</application>, which is
	designed to look more attractive and include more login-time
	options. In particular, users can easily choose (via a
	menu) which desktop environment
	(<application>KDE</application>,
	<application>GNOME</application>, or something else) to
	run after logging on.</para>

	<para>To enable <application>KDM</application>, different
	files need to be edited depending on the version of
	<application>KDE</application>.</para>

	<para>For <application>KDE 3</application>, the
	<literal>ttyv8</literal> entry in
	<filename>/etc/ttys</filename> has to be adapted as
	follows:</para>

	<programlisting>ttyv8 "/usr/local/bin/kdm -nodaemon" xterm on secure</programlisting>

	<para>For <application>KDE 4</application>, you have to mount
	&man.procfs.5; and add the following line to
	<filename>/etc/rc.conf</filename>:</para>

	<programlisting>kdm4_enable="YES"</programlisting>
	</sect3>

	</sect2>

	<sect2 id="x11-wm-xfce">
	<title>Xfce</title>
	<sect3 id="x11-wm-xfce-about">

	<title>About Xfce</title>

	<para><application>Xfce</application> is a desktop environment
	based on the GTK+
	toolkit used by <application>GNOME</application>, but is
	much more lightweight and meant for those who want a simple,
	efficient desktop which is nevertheless easy to use and
	configure. Visually, it looks very much like
	<application>CDE</application>, found on commercial &unix;
	systems. Some of <application>Xfce</application>'s features
	are:</para>

	<itemizedlist>
	<listitem>
	<para>A simple, easy-to-handle desktop</para>
	</listitem>

	<listitem>
	<para>Fully configurable via mouse, with drag and
	drop, etc.</para>
	</listitem>

	<listitem>
	<para>Main panel similar to
	<application>CDE</application>, with menus, applets
	and applications launchers</para>
	</listitem>

	<listitem>
	<para>Integrated window manager, file manager, sound
	manager, <application>GNOME</application> compliance
	module, and more</para>
	</listitem>

	<listitem>
	<para>Themeable (since it uses GTK+)</para>
	</listitem>

	<listitem>
	<para>Fast, light and efficient: ideal for older/slower
	machines or machines with memory limitations</para>
	</listitem>
	</itemizedlist>

	<para>More information on <application>Xfce</application>
	can be found on the <ulink url="http://www.xfce.org/">Xfce
	website</ulink>.</para>
	</sect3>

	<sect3 id="x11-wm-xfce-install">
	<title>Installing Xfce</title>

	<para>A binary package for <application>Xfce</application>
	exists (at the time of writing). To install, simply
	type:</para>

	<screen>&prompt.root; <userinput>pkg_add -r xfce4</userinput></screen>

	<para>Alternatively, to build from source, use the
	Ports Collection:</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/xfce4</userinput>
	&prompt.root; <userinput>make install clean</userinput></screen>

	<para>Now, tell the X server to launch
	<application>Xfce</application> the next time X is started.
	Simply type this:</para>

	<screen>&prompt.user; <userinput>echo "/usr/local/bin/startxfce4" > ~/.xinitrc</userinput></screen>

	<para>The next time X is started,
	<application>Xfce</application> will be the desktop.
	As before, if a display manager like
	<application>XDM</application> is being used, create an
	<filename>.xsession</filename>, as described in the
	section on <link linkend="x11-wm-gnome">GNOME</link>, but
	with the <filename>/usr/local/bin/startxfce4</filename>
	command; or, configure the display manager to allow
	choosing a desktop at login time, as explained in
	the section on
	<link linkend="x11-wm-kde-kdm">kdm</link>.</para>
	</sect3>
	</sect2>
	</sect1>
	</chapter>
	Index: projects/entities/en_US.ISO8859-1/books/porters-handbook/Makefile
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/porters-handbook/Makefile (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/porters-handbook/Makefile (revision 41355)
	@@ -1,54 +1,55 @@
	#
	# $FreeBSD$
	#
	# Build the FreeBSD Porter's Handbook.
	#

	MAINTAINER=doc@FreeBSD.org

	DOC?= book

	FORMATS?= html-split

	INSTALL_COMPRESSED?= gz
	INSTALL_ONLY_COMPRESSED?=

	#
	# SRCS lists the individual XML files that make up the document. Changes
	# to any of these files will force a rebuild
	#

	# XML content
	SRCS= book.xml
	+SRCS+= uses.xml

	# Use the local DSSSL file
	DSLHTML?= ${.CURDIR}/freebsd.dsl
	DSLPRINT?= ${.CURDIR}/freebsd.dsl

	# Images from the cross-document image library
	IMAGES_LIB+= callouts/1.png
	IMAGES_LIB+= callouts/2.png
	IMAGES_LIB+= callouts/3.png
	IMAGES_LIB+= callouts/4.png
	IMAGES_LIB+= callouts/5.png
	IMAGES_LIB+= callouts/6.png
	IMAGES_LIB+= callouts/7.png
	IMAGES_LIB+= callouts/8.png
	IMAGES_LIB+= callouts/9.png
	IMAGES_LIB+= callouts/10.png
	IMAGES_LIB+= callouts/11.png
	IMAGES_LIB+= callouts/12.png
	IMAGES_LIB+= callouts/13.png
	IMAGES_LIB+= callouts/14.png
	IMAGES_LIB+= callouts/15.png
	IMAGES_LIB+= callouts/16.png
	IMAGES_LIB+= callouts/17.png
	IMAGES_LIB+= callouts/18.png
	IMAGES_LIB+= callouts/19.png
	IMAGES_LIB+= callouts/20.png
	IMAGES_LIB+= callouts/21.png

	URL_RELPREFIX?= ../../../..
	DOC_PREFIX?= ${.CURDIR}/../../..

	.include "${DOC_PREFIX}/share/mk/doc.project.mk"
	Index: projects/entities/en_US.ISO8859-1/books/porters-handbook/book.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/porters-handbook/book.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/books/porters-handbook/book.xml (revision 41355)
	@@ -1,16842 +1,17047 @@
	<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
	<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/xml/freebsd42.dtd" [
	<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/xml/entities.ent">
	%entities;
	+
	+<!ENTITY values.uses SYSTEM "uses.xml">
	]>

	<!--
	The FreeBSD Documentation Project

	$FreeBSD$
	-->

	<book lang='en'>
	<bookinfo>
	<title>FreeBSD Porter's Handbook</title>

	<authorgroup>
	<corpauthor>The FreeBSD Documentation Project</corpauthor>
	</authorgroup>

	<pubdate>April 2000</pubdate>

	<copyright>
	<year>2000</year>
	<year>2001</year>
	<year>2002</year>
	<year>2003</year>
	<year>2004</year>
	<year>2005</year>
	<year>2006</year>
	<year>2007</year>
	<year>2008</year>
	<year>2009</year>
	<year>2010</year>
	<year>2011</year>
	<year>2012</year>
	+ <year>2013</year>
	<holder role="mailto:doc@FreeBSD.org">The FreeBSD Documentation
	Project</holder>
	</copyright>

	&trademarks;

	&legalnotice;

	<releaseinfo>$FreeBSD$</releaseinfo>
	</bookinfo>

	<chapter id="why-port">
	<title>Introduction</title>

	<para>The FreeBSD ports collection is the way almost everyone
	installs applications ("ports") on FreeBSD. Like everything
	else about FreeBSD, it is primarily a volunteer effort.
	It is important to keep this in mind when reading this
	document.</para>

	<para>In FreeBSD, anyone may submit a new port, or volunteer
	to maintain an existing port if it is unmaintained—you
	do not need any special commit privileges to do so.</para>

	</chapter>

	<chapter id="own-port">
	<title>Making a New Port Yourself</title>

	<para>So, you are interested in making your own port or
	upgrading an existing one? Great!</para>

	<para>What follows are some guidelines for creating a new port for
	FreeBSD. If you want to upgrade an existing port, you should
	read this and then read <xref linkend="port-upgrading"/>.</para>

	<para>When this document is not sufficiently detailed, you should
	refer to <filename>/usr/ports/Mk/bsd.port.mk</filename>, which
	all port Makefiles include. Even if you do not hack Makefiles
	daily, it is well commented, and you will still gain much
	knowledge from it. Additionally, you may send specific
	questions to the &a.ports;.</para>

	<note>
	<para>Only a fraction of the variables
	(<makevar><replaceable>VAR</replaceable></makevar>) that can
	be overridden are mentioned in this document. Most (if not
	all) are documented at the start of
	<filename>/usr/ports/Mk/bsd.port.mk</filename>; the others
	probably ought to be. Note that this file uses a non-standard
	tab setting: <application>Emacs</application> and
	<application>Vim</application> should recognize the setting on
	loading the file. Both &man.vi.1; and &man.ex.1; can be set
	to use the correct value by typing <command>:set
	tabstop=4</command> once the file has been loaded.</para>
	</note>

	<para>
	Looking for something easy to start with? Take a look at the
	<ulink url="http://wiki.freebsd.org/WantedPorts">list of
	requested ports</ulink> and see if you can work on one (or
	more).</para>
	</chapter>

	<chapter id="quick-porting">
	<title>Quick Porting</title>

	<para>This section tells you how to quickly create a new port. In
	many cases, it is not sufficient, so you will have to read
	further on into the document.</para>

	<para>First, get the original tarball and put it into
	<makevar>DISTDIR</makevar>, which defaults to
	<filename>/usr/ports/distfiles</filename>.</para>

	<note>
	<para>The following assumes that the software compiled
	out-of-the-box, i.e., there was absolutely no change required
	for the port to work on your FreeBSD box. If you needed to
	change something, you will have to refer to the next section
	too.</para>
	</note>

	<sect1 id="porting-makefile">
	<title>Writing the <filename>Makefile</filename></title>

	<para>The minimal <filename>Makefile</filename> would look
	something like this:</para>

	<programlisting># &dollar;FreeBSD&dollar;

	PORTNAME= oneko
	PORTVERSION= 1.1b
	CATEGORIES= games
	MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/

	MAINTAINER= asami@FreeBSD.org
	COMMENT= Cat chasing a mouse all over the screen

	MAN1= oneko.1
	MANCOMPRESSED= yes
	USE_IMAKE= yes

	.include <bsd.port.mk></programlisting>

	<note>
	<para>In some cases, the <filename>Makefile</filename> of an
	existing port may contain additional lines in the header,
	such as the name of the port and the date it was created.
	This additional information has been declared obsolete, and
	is being phased out.</para>
	</note>

	<para>See if you can figure it out. Do not worry about the
	contents of the <literal>&dollar;FreeBSD&dollar;</literal>
	line, it will be filled in automatically by SVN when the port
	is imported to our main ports tree. You can find a more
	detailed example in the <link
	linkend="porting-samplem">sample Makefile</link>
	section.</para>
	</sect1>

	<sect1 id="porting-desc">
	<title>Writing the Description Files</title>

	<para>There are two description files that are required for
	any port, whether they actually package or not. They are
	<filename>pkg-descr</filename> and
	<filename>pkg-plist</filename>. Their
	<filename>pkg-</filename> prefix distinguishes them from
	other files.</para>

	<sect2>
	<title><filename>pkg-descr</filename></title>

	<para>This is a longer description of the port. One to a few
	paragraphs concisely explaining what the port does is
	sufficient.</para>

	<note>
	<para>This is <emphasis>not</emphasis> a manual or an
	in-depth description on how to use or compile the port!
	<emphasis>Please be careful if you are copying from the
	<filename>README</filename> or manpage</emphasis>; too
	often they are not a concise description of the port or
	are in an awkward format (e.g., manpages have justified
	spacing, as it looks particularly bad with monospaced
	fonts).</para>
	</note>

	<para>A well-written <filename>pkg-descr</filename> describes
	the port completely enough that users would not have to
	consult the documentation or visit the website to understand
	what the software does, how it can be useful, or what
	particularly nice features it has. Mentioning certain
	requirements like a graphical toolkit, heavy dependencies,
	runtime environment, or implementation languages help users
	decide whether this port will work for them.</para>

	<para>Include a URL to the official WWW homepage.
	Prepend <emphasis>one</emphasis> of
	the websites (pick the most common one) with
	<literal>WWW:</literal> (followed by single space) so that
	automated tools will work correctly. If the URI is the root
	of the website or directory, it should be terminated with a
	slash.</para>

	<note>
	<para>If the listed webpage for a port is not available, try
	to search the Internet first to see if the official site
	moved, was renamed, or is hosted elsewhere.</para>
	</note>

	<para>The following example shows how your
	<filename>pkg-descr</filename> should look:</para>

	<programlisting>This is a port of oneko, in which a cat chases a poor mouse all over
	the screen.
	:
	(etc.)

	WWW: http://www.oneko.org/</programlisting>
	</sect2>

	<sect2>
	<title><filename>pkg-plist</filename></title>

	<para>This file lists all the files installed by the port. It
	is also called the <quote>packing list</quote> because the
	package is generated by packing the files listed here. The
	pathnames are relative to the installation prefix (usually
	<filename>/usr/local</filename>. If you are using the
	<makevar>MAN<replaceable>n</replaceable></makevar> variables
	(as you should be), do not list any manpages here. If the
	port creates directories during installation, make sure to
	add <literal>@dirrm</literal> lines to remove them when the
	package is deleted.</para>

	<para>Here is a small example:</para>

	<programlisting>bin/oneko
	lib/X11/app-defaults/Oneko
	lib/X11/oneko/cat1.xpm
	lib/X11/oneko/cat2.xpm
	lib/X11/oneko/mouse.xpm
	@dirrm lib/X11/oneko</programlisting>

	<para>Refer to the &man.pkg.create.1; manual page for details
	on the packing list.</para>

	<note>
	<para>It is recommended that you keep all the filenames in
	this file sorted alphabetically. It will make verifying
	the changes when you upgrade the port much easier.</para>
	</note>

	<note>
	<para>Creating a packing list manually can be a very tedious
	task. If the port installs a large numbers of files,
	<link linkend="plist-autoplist">creating the packing list
	automatically</link> might save time.</para>
	</note>

	<para>There is only one case when
	<filename>pkg-plist</filename> can be omitted from a port.
	If the port installs just a handful of files, and perhaps
	directories, the files and directories may be listed in the
	variables <makevar>PLIST_FILES</makevar> and
	<makevar>PLIST_DIRS</makevar>, respectively, within the
	port's <filename>Makefile</filename>. For instance, we
	could get along without <filename>pkg-plist</filename> in
	the above <filename>oneko</filename> port by adding the
	following lines to the <filename>Makefile</filename>:</para>

	<programlisting>PLIST_FILES= bin/oneko \
	lib/X11/app-defaults/Oneko \
	lib/X11/oneko/cat1.xpm \
	lib/X11/oneko/cat2.xpm \
	lib/X11/oneko/mouse.xpm
	PLIST_DIRS= lib/X11/oneko</programlisting>

	<para>Of course, <makevar>PLIST_DIRS</makevar> should be left
	unset if a port installs no directories of its own.</para>

	<para>The price for this way of listing port's files and
	directories is that you cannot use command sequences
	described in &man.pkg.create.1;. Therefore, it is suitable
	only for simple ports and makes them even simpler. At the
	same time, it has the advantage of reducing the number of
	files in the ports collection. Please consider using this
	technique before you resort to
	<filename>pkg-plist</filename>.</para>

	<para>Later we will see how <filename>pkg-plist</filename>
	and <makevar>PLIST_FILES</makevar> can be used to fulfill
	<link linkend="plist">more sophisticated
	tasks</link>.</para>
	</sect2>
	</sect1>

	<sect1 id="porting-checksum">
	<title>Creating the Checksum File</title>

	<para>Just type <command>make makesum</command>. The ports make
	rules will automatically generate the file
	<filename>distinfo</filename>.</para>

	<para>If a file fetched has its checksum changed regularly and
	you are certain the source is trusted (i.e., it comes from
	manufacturer CDs or documentation generated daily), you should
	specify these files in the <makevar>IGNOREFILES</makevar>
	variable. Then the checksum is not calculated for that file
	when you run <command>make makesum</command>, but set to
	<literal>IGNORE</literal>.</para>
	</sect1>

	<sect1 id="porting-testing">
	<title>Testing the Port</title>

	<para>You should make sure that the port rules do exactly what
	you want them to do, including packaging up the port. These
	are the important points you need to verify.</para>

	<itemizedlist>
	<listitem>
	<para><filename>pkg-plist</filename> does not contain
	anything not installed by your port</para>
	</listitem>

	<listitem>
	<para><filename>pkg-plist</filename> contains everything
	that is installed by your port</para>
	</listitem>

	<listitem>
	<para>Your port can be installed multiple times using the
	<maketarget>reinstall</maketarget> target</para>
	</listitem>

	<listitem>
	<para>Your port <link linkend="plist-cleaning">cleans
	up</link> after itself upon deinstall</para>
	</listitem>
	</itemizedlist>

	<procedure>
	<title>Recommended Test Ordering</title>

	<step>
	<para><command>make install</command></para>
	</step>

	<step>
	<para><command>make package</command></para>
	</step>

	<step>
	<para><command>make deinstall</command></para>
	</step>

	<step>
	<para><command>pkg_add
	<replaceable>package-name</replaceable></command></para>
	</step>

	<step>
	<para><command>make deinstall</command></para>
	</step>

	<step>
	<para><command>make reinstall</command></para>
	</step>

	<step>
	<para><command>make package</command></para>
	</step>

	<step>
	<para><command>make readme</command></para>
	</step>
	</procedure>

	<para>Make sure that there are not any warnings issued in any of
	the <maketarget>package</maketarget> and
	<maketarget>deinstall</maketarget> stages. After step 3,
	check to see if all the new directories are correctly deleted.
	Also, try using the software after step 4, to ensure that it
	works correctly when installed from a package.</para>

	<para>The most thorough way to automate these steps is via
	installing the <application>ports tinderbox</application>.
	This maintains <literal>jails</literal> in which you can
	test all of the above steps without changing the state of
	your running system. Please see
	<filename>ports/ports-mgmt/tinderbox</filename> for more
	information.</para>
	</sect1>

	<sect1 id="porting-portlint">
	<title>Checking Your Port with
	<command>portlint</command></title>

	<para>Please use <command>portlint</command> to see if your port
	conforms to our guidelines. The <filename
	role="package">ports-mgmt/portlint</filename> program is
	part of the ports collection. In particular, you may want to
	check if the <link linkend="porting-samplem">Makefile</link>
	is in the right shape and the <link
	linkend="porting-pkgname">package</link> is named
	appropriately.</para>
	</sect1>

	<sect1 id="porting-submitting">
	<title>Submitting the New Port</title>

	<para>Before you submit the new port, make sure you have read
	the <link
	linkend="porting-dads">DOs and DON'Ts</link> section.</para>

	<para>Now that you are happy with your port, the only thing
	remaining is to put it in the main &os; ports tree and make
	everybody else happy about it too. We do not need your
	<filename>work</filename> directory or the
	<filename>pkgname.tgz</filename> package, so delete them now.
	Next, assuming your port is called oneko,
	<command>cd</command> to the directory above where the
	<literal>oneko</literal> directory is located, and then type
	the following: <command>shar `find oneko` >
	oneko.shar</command></para>

	<para>Include your <literal>oneko.shar</literal> file in a bug
	report and send it with the &man.send-pr.1; program (see
	<ulink
	url="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug
	Reports and General Commentary</ulink> for more information
	about &man.send-pr.1;). Be sure to classify the bug report
	as category <literal>ports</literal> and class
	<literal>change-request</literal> (Do not mark the report
	<literal>confidential</literal>!). Also add a short
	description of the program you ported to the
	<quote>Description</quote> field of the PR (e.g., perhaps a
	short version of the <makevar>COMMENT</makevar>), and add
	the shar file to the <quote>Fix</quote> field.</para>

	<note>
	<para>You can make our work a lot easier, if you use a good
	description in the synopsis of the problem report. We
	prefer something like <quote>New port:
	<category>/<portname> <short description of
	the port></quote> for new ports. If you stick to this
	scheme, the chance that someone will take a look at your PR
	soon is much better.</para>
	</note>

	<para>One more time, <emphasis>do not include the original
	source distfile, the <filename>work</filename> directory, or
	the package you built with <command>make
	package</command></emphasis>; and, do use &man.shar.1; for
	new ports, not &man.diff.1;.</para>

	<para>After you have submitted your port, please be patient.
	Sometimes it can take a few months before a port is included
	in &os;, although it might only take a few days. You can
	view the list of <ulink
	url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">ports
	PRs waiting to be committed to &os;</ulink>.</para>

	<para>Once we have looked at your port, we will get back to you
	if necessary, and put it in the tree. Your name will also
	be added to the list of <ulink
	url="&url.articles.contributors;/contrib-additional.html">Additional
	FreeBSD Contributors</ulink> and other files.</para>
	</sect1>
	</chapter>

	<chapter id="slow">
	<title>Slow Porting</title>

	<para>Ok, so it was not that simple, and the port required some
	modifications to get it to work. In this section, we will
	explain, step by step, how to modify it to get it to work with
	the ports paradigm.</para>

	<sect1 id="slow-work">
	<title>How Things Work</title>

	<para>First, this is the sequence of events which occurs when
	the user first types <command>make</command> in your port's
	directory. You may find that having
	<filename>bsd.port.mk</filename> in another window while you
	read this really helps to understand it.</para>

	<para>But do not worry if you do not really understand what
	<filename>bsd.port.mk</filename> is doing, not many people
	do... <!-- smiley --><emphasis>:-)</emphasis></para>

	<procedure>
	<step>
	<para>The <maketarget>fetch</maketarget> target is run. The
	<maketarget>fetch</maketarget> target is responsible for
	making sure that the tarball exists locally in
	<makevar>DISTDIR</makevar>. If
	<maketarget>fetch</maketarget> cannot find the required
	files in <makevar>DISTDIR</makevar> it will look up the
	URL <makevar>MASTER_SITES</makevar>, which is set in the
	Makefile, as well as our main FTP site at <ulink
	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/"></ulink>,
	where we put sanctioned distfiles as backup. It will then
	attempt to fetch the named distribution file with
	<makevar>FETCH</makevar>, assuming that the requesting
	site has direct access to the Internet. If that succeeds,
	it will save the file in <makevar>DISTDIR</makevar> for
	future use and proceed.</para>
	</step>

	<step>
	<para>The <maketarget>extract</maketarget> target is run.
	It looks for your port's distribution file (typically a
	<command>gzip</command>ped tarball) in
	<makevar>DISTDIR</makevar> and unpacks it into a temporary
	subdirectory specified by <makevar>WRKDIR</makevar>
	(defaults to <filename>work</filename>).</para>
	</step>

	<step>
	<para>The <maketarget>patch</maketarget> target is run.
	First, any patches defined in
	<makevar>PATCHFILES</makevar> are applied. Second, if any
	patch files named
	<filename>patch-<replaceable>*</replaceable></filename>
	are found in <makevar>PATCHDIR</makevar> (defaults to the
	<filename>files</filename> subdirectory), they are applied
	at this time in alphabetical order.</para>
	</step>

	<step>
	<para>The <maketarget>configure</maketarget> target is run.
	This can do any one of many different things.</para>

	<orderedlist>
	<listitem>
	<para>If it exists,
	<filename>scripts/configure</filename> is run.</para>
	</listitem>

	<listitem>
	<para>If <makevar>HAS_CONFIGURE</makevar> or
	<makevar>GNU_CONFIGURE</makevar> is set,
	<filename><makevar>WRKSRC</makevar>/configure</filename>
	is run.</para>
	</listitem>

	<listitem>
	<para>If <makevar>USE_IMAKE</makevar> is set,
	<makevar>XMKMF</makevar> (default: <command>xmkmf
	-a</command>) is run.</para>
	</listitem>
	</orderedlist>
	</step>

	<step>
	<para>The <maketarget>build</maketarget> target is run.
	This is responsible for descending into the port's private
	working directory (<makevar>WRKSRC</makevar>) and building
	it. If <makevar>USE_GMAKE</makevar> is set, GNU
	<command>make</command> will be used, otherwise the system
	<command>make</command> will be used.</para>
	</step>
	</procedure>

	<para>The above are the default actions. In addition, you can
	define targets
	<maketarget>pre-<replaceable>something</replaceable></maketarget>
	or
	<maketarget>post-<replaceable>something</replaceable></maketarget>,
	or put scripts with those names, in the
	<filename>scripts</filename> subdirectory, and they will be
	run before or after the default actions are done.</para>

	<para>For example, if you have a
	<maketarget>post-extract</maketarget> target defined in your
	<filename>Makefile</filename>, and a file
	<filename>pre-build</filename> in the
	<filename>scripts</filename> subdirectory, the
	<maketarget>post-extract</maketarget> target will be called
	after the regular extraction actions, and the
	<filename>pre-build</filename> script will be executed before
	the default build rules are done. It is recommended that you
	use <filename>Makefile</filename> targets if the actions are
	simple enough, because it will be easier for someone to figure
	out what kind of non-default action the port requires.</para>

	<para>The default actions are done by the
	<filename>bsd.port.mk</filename> targets
	<maketarget>do-<replaceable>something</replaceable></maketarget>.
	For example, the commands to extract a port are in the target
	<maketarget>do-extract</maketarget>. If you are not happy
	with the default target, you can fix it by redefining the
	<maketarget>do-<replaceable>something</replaceable></maketarget>
	target in your <filename>Makefile</filename>.</para>

	<note>
	<para>The <quote>main</quote> targets (e.g.,
	<maketarget>extract</maketarget>,
	<maketarget>configure</maketarget>, etc.) do nothing more
	than make sure all the stages up to that one are completed
	and call the real targets or scripts, and they are not
	intended to be changed. If you want to fix the extraction,
	fix <maketarget>do-extract</maketarget>, but never ever
	change the way <maketarget>extract</maketarget>
	operates! Additionally, the target
	<maketarget>post-deinstall</maketarget> is invalid and
	is not run by the ports infrastructure.</para>
	</note>

	<para>Now that you understand what goes on when the user types
	<command>make</command>, let us go through the recommended
	steps to create the perfect port.</para>
	</sect1>

	<sect1 id="slow-sources">
	<title>Getting the Original Sources</title>

	<para>Get the original sources (normally) as a compressed
	tarball
	(<filename><replaceable>foo</replaceable>.tar.gz</filename> or
	<filename><replaceable>foo</replaceable>.tar.bz2</filename>)
	and copy it into <makevar>DISTDIR</makevar>. Always use
	<emphasis>mainstream</emphasis> sources when and where you
	can.</para>

	<para>You will need to set the variable
	<makevar>MASTER_SITES</makevar> to reflect where the original
	tarball resides. You will find convenient shorthand
	definitions for most mainstream sites in
	<filename>bsd.sites.mk</filename>. Please use these
	sites—and the associated definitions—if at all
	possible, to help avoid the problem of having the same
	information repeated over again many times in the source base.
	As these sites tend to change over time, this becomes a
	maintenance nightmare for everyone involved.</para>

	<para>If you cannot find a FTP/HTTP site that is well-connected
	to the net, or can only find sites that have irritatingly
	non-standard formats, you might want to put a copy on a
	reliable FTP or HTTP server that you control (e.g., your home
	page).</para>

	<para>If you cannot find somewhere convenient and reliable to
	put the distfile we can <quote>house</quote> it ourselves on
	<hostid>ftp.FreeBSD.org</hostid>; however, this is the
	least-preferred solution. The distfile must be placed into
	<filename>~/public_distfiles/</filename> of someone's
	<hostid>freefall</hostid> account. Ask the person who commits
	your port to do this. This person will also set
	<makevar>MASTER_SITES</makevar> to
	<makevar>MASTER_SITE_LOCAL</makevar> and
	<makevar>MASTER_SITE_SUBDIR</makevar> to their
	<hostid>freefall</hostid> username.</para>

	<para>If your port's distfile changes all the time without any
	kind of version update by the author, consider putting the
	distfile on your home page and listing it as the first
	<makevar>MASTER_SITES</makevar>. If you can, try to talk the
	port author out of doing this; it really does help to
	establish some kind of source code control. Hosting your own
	version will prevent users from getting <errorname>checksum
	mismatch</errorname> errors, and also reduce the workload of
	maintainers of our FTP site. Also, if there is only one
	master site for the port, it is recommended that you house a
	backup at your site and list it as the second
	<makevar>MASTER_SITES</makevar>.</para>

	<para>If your port requires some additional `patches' that are
	available on the Internet, fetch them too and put them in
	<makevar>DISTDIR</makevar>. Do not worry if they come from a
	site other than where you got the main source tarball, we have
	a way to handle these situations (see the description of <link
	linkend="porting-patchfiles">PATCHFILES</link>
	below).</para>
	</sect1>

	<sect1 id="slow-modifying">
	<title>Modifying the Port</title>

	<para>Unpack a copy of the tarball in a private directory and
	make whatever changes are necessary to get the port to compile
	properly under the current version of &os;. Keep
	<emphasis>careful track</emphasis> of everything you do, as
	you will be automating the process shortly. Everything,
	including the deletion, addition, or modification of files
	should be doable using an automated script or patch file when
	your port is finished.</para>

	<para>If your port requires significant user
	interaction/customization to compile or install, you should
	take a look at one of Larry Wall's classic
	<application>Configure</application> scripts and perhaps do
	something similar yourself. The goal of the new ports
	collection is to make each port as
	<quote>plug-and-play</quote> as possible for the end-user
	while using a minimum of disk space.</para>

	<note>
	<para>Unless explicitly stated, patch files, scripts, and
	other files you have created and contributed to the &os;
	ports collection are assumed to be covered by the standard
	BSD copyright conditions.</para>
	</note>
	</sect1>

	<sect1 id="slow-patch">
	<title>Patching</title>

	<para>In the preparation of the port, files that have been added
	or changed can be picked up with a &man.diff.1; for later
	feeding to &man.patch.1;. Each patch you wish to apply should
	be saved into a file named
	<filename>patch-<replaceable>*</replaceable></filename> where
	<replaceable>*</replaceable> indicates the pathname of the
	file that is patched, such as
	<filename>patch-Imakefile</filename> or
	<filename>patch-src-config.h</filename>. These files should
	be stored in <makevar>PATCHDIR</makevar> (usually
	<filename>files/</filename>, from where they will be
	automatically applied. All patches must be relative to
	<makevar>WRKSRC</makevar> (generally the directory your port's
	tarball unpacks itself into, that being where the build is
	done). To make fixes and upgrades easier, you should avoid
	having more than one patch fix the same file (e.g.,
	<filename>patch-file</filename> and
	<filename>patch-file2</filename> both changing
	<filename><makevar>WRKSRC</makevar>/foobar.c</filename>).
	Note that if the path of a patched file contains an underscore
	(<literal>_</literal>) character, the patch needs to have two
	underscores instead in its name. For example, to patch a file
	named <filename>src/freeglut_joystick.c</filename>, the
	corresponding patch should be named
	<filename>patch-src-freeglut__joystick.c</filename>.</para>

	<para>Please only use characters
	<literal>[-+._a-zA-Z0-9]</literal> for naming your patches.
	Do not use any other characters besides them. Do not name
	your patches like <filename>patch-aa</filename> or
	<filename>patch-ab</filename> etc, always mention the path and
	file name in patch names.</para>

	<para>Do not put RCS strings in patches. SVN will mangle them
	when we put the files into the ports tree, and when we check
	them out again, they will come out different and the patch
	will fail. RCS strings are surrounded by dollar
	(<literal>&dollar;</literal>) signs, and typically start with
	<literal>&dollar;Id</literal> or
	<literal>&dollar;RCS</literal>.</para>

	<para>Using the recurse (<option>-r</option>) option to
	&man.diff.1; to generate patches is fine, but please take a
	look at the resulting patches to make sure you do not have any
	unnecessary junk in there. In particular, diffs between two
	backup files, <filename>Makefile</filename>s when the port
	uses <command>Imake</command> or GNU
	<command>configure</command>, etc., are unnecessary and should
	be deleted. If you had to edit
	<filename>configure.in</filename> and run
	<command>autoconf</command> to regenerate
	<command>configure</command>, do not take the diffs of
	<command>configure</command> (it often grows to a few thousand
	lines!); define <literal>USE_AUTOTOOLS=autoconf:261</literal>
	and take the diffs of
	<filename>configure.in</filename>.</para>

	<para>Also, try to minimize the amount of non-functional
	whitespace changes in your patches. It is common in the Open
	Source world for projects to share large amounts of a code
	base, but obey different style and indenting rules. If you
	take a working piece of functionality from one project to fix
	similar areas in another, please be careful: the resulting
	line patch may be full of non-functional changes. It not only
	increases the size of the SVN repository but makes it hard to
	find out what exactly caused the problem and what you changed
	at all.</para>

	<para>If you had to delete a file, then you can do it in the
	<maketarget>post-extract</maketarget> target rather than as
	part of the patch.</para>

	<para>Simple replacements can be performed directly from the
	port <filename>Makefile</filename> using the in-place mode of
	&man.sed.1;. This is very useful when you need to patch in a
	variable value. Example:</para>

	<programlisting>post-patch:
	@${REINPLACE_CMD} -e 's\|for Linux\|for FreeBSD\|g' ${WRKSRC}/README</programlisting>

	<para>Quite often, there is a situation when the software being
	ported, especially if it is primarily developed on &windows;,
	uses the CR/LF convention for most of its source files. This
	may cause problems with further patching, compiler warnings,
	scripts execution (<command>/bin/sh^M</command> not found),
	etc. To quickly convert all files from CR/LF to just LF, add
	<literal>USE_DOS2UNIX=yes</literal> to the port
	<filename>Makefile</filename>. A list of files to convert can
	be specified:</para>

	<programlisting>USE_DOS2UNIX= util.c util.h</programlisting>

	<para>If you want to convert a group of files across
	subdirectories, <makevar>DOS2UNIX_REGEX</makevar> can be used.
	Its argument is a <command>find</command> compatible regular
	expression. More on the format is in &man.re.format.7;. This
	option is useful for converting all files of a given
	extension, for example all source code files leaving binary
	files intact:</para>

	<programlisting>USE_DOS2UNIX= yes
	DOS2UNIX_REGEX= .*\.(c\|cpp\|h)</programlisting>

	<para>If you want to create a patch file based off of an
	existing file, you can copy it with an
	<filename>.orig</filename> extension, and then modify the
	original one. The <maketarget>makepatch</maketarget> target
	will write out an appropriate patch file to the <filename
	class="directory">files</filename> directory of the
	port.</para>
	</sect1>

	<sect1 id="slow-configure">
	<title>Configuring</title>

	<para>Include any additional customization commands in your
	<filename>configure</filename> script and save it in the
	<filename>scripts</filename> subdirectory. As mentioned
	above, you can also do this with <filename>Makefile</filename>
	targets and/or scripts with the name
	<filename>pre-configure</filename> or
	<filename>post-configure</filename>.</para>
	</sect1>

	<sect1 id="slow-user-input">
	<title>Handling User Input</title>

	<para>If your port requires user input to build, configure, or
	install, you must set <makevar>IS_INTERACTIVE</makevar> in
	your <filename>Makefile</filename>. This will allow
	<quote>overnight builds</quote> to skip your port if the user
	sets the variable <envar>BATCH</envar> in his environment (and
	if the user sets the variable <envar>INTERACTIVE</envar>, then
	<emphasis>only</emphasis> those ports requiring interaction
	are built). This will save a lot of wasted time on the set of
	machines that continually build ports (see below).</para>

	<para>It is also recommended that if there are reasonable
	default answers to the questions, you check the
	<makevar>PACKAGE_BUILDING</makevar> variable and turn off the
	interactive script when it is set. This will allow us to
	build the packages for CDROMs and FTP.</para>
	</sect1>
	</chapter>

	<chapter id="makefile">
	<title>Configuring the Makefile</title>

	<para>Configuring the <filename>Makefile</filename> is pretty
	simple, and again we suggest that you look at existing examples
	before starting. Also, there is a <link
	linkend="porting-samplem">sample Makefile</link> in this
	handbook, so take a look and please follow the ordering of
	variables and sections in that template to make your port easier
	for others to read.</para>

	<para>Now, consider the following problems in sequence as you
	design your new <filename>Makefile</filename>:</para>

	<sect1 id="makefile-source">
	<title>The Original Source</title>

	<para>Does it live in <makevar>DISTDIR</makevar> as a standard
	<command>gzip</command>ped tarball named something like
	<filename>foozolix-1.2.tar.gz</filename>? If so, you can go on
	to the next step. If not, you should look at overriding any
	of the <makevar>DISTVERSION</makevar>,
	<makevar>DISTNAME</makevar>, <makevar>EXTRACT_CMD</makevar>,
	<makevar>EXTRACT_BEFORE_ARGS</makevar>,
	<makevar>EXTRACT_AFTER_ARGS</makevar>,
	<makevar>EXTRACT_SUFX</makevar>, or
	<makevar>DISTFILES</makevar> variables, depending on how alien
	a format your port's distribution file is.</para>

	<para>In the worst case, you can simply create your own
	<maketarget>do-extract</maketarget> target to override the
	default, though this should be rarely, if ever,
	necessary.</para>
	</sect1>

	<sect1 id="makefile-naming">
	<title>Naming</title>

	<para>The first part of the port's <filename>Makefile</filename>
	names the port, describes its version number, and lists it
	in the correct category.</para>

	<sect2>
	<title><makevar>PORTNAME</makevar> and
	<makevar>PORTVERSION</makevar></title>

	<para>You should set <makevar>PORTNAME</makevar> to the
	base name of your port, and <makevar>PORTVERSION</makevar>
	to the version number of the port.</para>
	</sect2>

	<sect2 id="makefile-naming-revepoch">
	<title><makevar>PORTREVISION</makevar> and
	<makevar>PORTEPOCH</makevar></title>

	<sect3>
	<title><makevar>PORTREVISION</makevar></title>

	<para>The <makevar>PORTREVISION</makevar> variable is a
	monotonically increasing value which is reset to 0 with
	every increase of <makevar>PORTVERSION</makevar> (i.e.,
	every time a new official vendor release is made), and
	appended to the package name if non-zero. Changes to
	<makevar>PORTREVISION</makevar> are used by automated
	tools (e.g., &man.pkg.version.1;) to highlight the fact
	that a new package is available.</para>

	<para><makevar>PORTREVISION</makevar> should be increased
	each time a change is made to the port which significantly
	affects the content or structure of the derived
	package.</para>

	<para>Examples of when <makevar>PORTREVISION</makevar>
	should be bumped:</para>

	<itemizedlist>
	<listitem>
	<para>Addition of patches to correct security
	vulnerabilities, bugs, or to add new functionality to
	the port.</para>
	</listitem>

	<listitem>
	<para>Changes to the port <filename>Makefile</filename>
	to enable or disable compile-time options in the
	package.</para>
	</listitem>

	<listitem>
	<para>Changes in the packing list or the install-time
	behavior of the package (e.g., change to a script
	which generates initial data for the package, like ssh
	host keys).</para>
	</listitem>

	<listitem>
	<para>Version bump of a port's shared library dependency
	(in this case, someone trying to install the old
	package after installing a newer version of the
	dependency will fail since it will look for the old
	libfoo.x instead of libfoo.(x+1)).</para>
	</listitem>

	<listitem>
	<para>Silent changes to the port distfile which have
	significant functional differences, i.e., changes to
	the distfile requiring a correction to
	<filename>distinfo</filename> with no corresponding
	change to <makevar>PORTVERSION</makevar>, where a
	<command>diff -ru</command> of the old and new
	versions shows non-trivial changes to the code.</para>
	</listitem>
	</itemizedlist>

	<para>Examples of changes which do not require a
	<makevar>PORTREVISION</makevar> bump:</para>

	<itemizedlist>
	<listitem>
	<para>Style changes to the port skeleton with no
	functional change to what appears in the resulting
	package.</para>
	</listitem>

	<listitem>
	<para>Changes to <makevar>MASTER_SITES</makevar> or
	other functional changes to the port which do not
	affect the resulting package.</para>
	</listitem>

	<listitem>
	<para>Trivial patches to the distfile such as correction
	of typos, which are not important enough that users of
	the package should go to the trouble of
	upgrading.</para>
	</listitem>

	<listitem>
	<para>Build fixes which cause a package to become
	compilable where it was previously failing (as long as
	the changes do not introduce any functional change on
	any other platforms on which the port did previously
	build). Since <makevar>PORTREVISION</makevar>
	reflects the content of the package, if the package
	was not previously buildable then there is no need to
	increase <makevar>PORTREVISION</makevar> to mark a
	change.</para>
	</listitem>
	</itemizedlist>

	<para>A rule of thumb is to ask yourself whether a change
	committed to a port is something which everyone would
	benefit from having (either because of an enhancement,
	fix, or by virtue that the new package will actually work
	at all), and weigh that against that fact that it will
	cause everyone who regularly updates their ports tree to
	be compelled to update. If yes, the
	<makevar>PORTREVISION</makevar> should be bumped.</para>
	</sect3>

	<sect3>
	<title><makevar>PORTEPOCH</makevar></title>

	<para>From time to time a software vendor or FreeBSD porter
	will do something silly and release a version of their
	software which is actually numerically less than the
	previous version. An example of this is a port which goes
	from foo-20000801 to foo-1.0 (the former will be
	incorrectly treated as a newer version since 20000801 is a
	numerically greater value than 1).</para>

	+ <tip>
	+ <para>The results of version number comparisons are not
	+ always obvious. &man.pkg.version.1; can be used to test
	+ the comparison of two version number strings. The
	+ <application>pkgng</application> equivalent is
	+ <command>pkg version -t</command>. For example:</para>
	+
	+ <screen>&prompt.user; <userinput>pkg_version -t 0.031 0.29</userinput>
	+></screen>
	+
	+ <para>Or, for <application>pkgng</application>
	+ users:</para>
	+
	+ <screen>&prompt.user; <userinput>pkg version -t 0.031 0.29</userinput>
	+></screen>
	+
	+ <para>The <literal>></literal> output indicates that
	+ version 0.031 is considered greater than version 0.29,
	+ which may not have been obvious to the porter.</para>
	+ </tip>
	+
	<para>In situations such as this, the
	<makevar>PORTEPOCH</makevar> version should be increased.
	If <makevar>PORTEPOCH</makevar> is nonzero it is appended
	to the package name as described in section 0 above.
	<makevar>PORTEPOCH</makevar> must never be decreased or
	reset to zero, because that would cause comparison to a
	package from an earlier epoch to fail (i.e., the package
	would not be detected as out of date): the new version
	number (e.g., <literal>1.0,1</literal> in the above
	example) is still numerically less than the previous
	version (20000801), but the <literal>,1</literal> suffix
	is treated specially by automated tools and found to be
	greater than the implied suffix <literal>,0</literal> on
	the earlier package.</para>

	<para>Dropping or resetting <makevar>PORTEPOCH</makevar>
	incorrectly leads to no end of grief; if you do not
	understand the above discussion, please keep after it
	until you do, or ask questions on the mailing
	lists.</para>

	<para>It is expected that <makevar>PORTEPOCH</makevar> will
	not be used for the majority of ports, and that sensible
	use of <makevar>PORTVERSION</makevar> can often preempt it
	becoming necessary if a future release of the software
	should change the version structure. However, care is
	needed by FreeBSD porters when a vendor release is made
	without an official version number — such as a code
	<quote>snapshot</quote> release. The temptation is to
	label the release with the release date, which will cause
	problems as in the example above when a new
	<quote>official</quote> release is made.</para>

	<para>For example, if a snapshot release is made on the date
	20000917, and the previous version of the software was
	version 1.2, the snapshot release should be given a
	<makevar>PORTVERSION</makevar> of 1.2.20000917 or similar,
	not 20000917, so that the succeeding release, say 1.3, is
	still a numerically greater value.</para>
	</sect3>

	<sect3>
	<title>Example of <makevar>PORTREVISION</makevar> and
	<makevar>PORTEPOCH</makevar> Usage</title>

	<para>The <literal>gtkmumble</literal> port, version
	<literal>0.10</literal>, is committed to the ports
	collection:</para>

	<programlisting>PORTNAME= gtkmumble
	PORTVERSION= 0.10</programlisting>

	<para><makevar>PKGNAME</makevar> becomes
	<literal>gtkmumble-0.10</literal>.</para>

	<para>A security hole is discovered which requires a local
	FreeBSD patch. <makevar>PORTREVISION</makevar> is bumped
	accordingly.</para>

	<programlisting>PORTNAME= gtkmumble
	PORTVERSION= 0.10
	PORTREVISION= 1</programlisting>

	<para><makevar>PKGNAME</makevar> becomes
	<literal>gtkmumble-0.10_1</literal></para>

	<para>A new version is released by the vendor, numbered
	<literal>0.2</literal> (it turns out the author actually
	intended <literal>0.10</literal> to actually mean
	<literal>0.1.0</literal>, not <quote>what comes after
	0.9</quote> - oops, too late now). Since the new minor
	version <literal>2</literal> is numerically less than the
	previous version <literal>10</literal>, the
	<makevar>PORTEPOCH</makevar> must be bumped to manually
	force the new package to be detected as
	<quote>newer</quote>. Since it is a new vendor release of
	the code, <makevar>PORTREVISION</makevar> is reset to 0
	(or removed from the
	<filename>Makefile</filename>).</para>

	<programlisting>PORTNAME= gtkmumble
	PORTVERSION= 0.2
	PORTEPOCH= 1</programlisting>

	<para><makevar>PKGNAME</makevar> becomes
	<literal>gtkmumble-0.2,1</literal></para>

	<para>The next release is 0.3. Since
	<makevar>PORTEPOCH</makevar> never decreases, the version
	variables are now:</para>

	<programlisting>PORTNAME= gtkmumble
	PORTVERSION= 0.3
	PORTEPOCH= 1</programlisting>

	<para><makevar>PKGNAME</makevar> becomes
	<literal>gtkmumble-0.3,1</literal></para>

	<note>
	<para>If <makevar>PORTEPOCH</makevar> were reset to
	<literal>0</literal> with this upgrade, someone who had
	installed the <literal>gtkmumble-0.10_1</literal>
	package would not detect the
	<literal>gtkmumble-0.3</literal> package as newer, since
	<literal>3</literal> is still numerically less than
	<literal>10</literal>. Remember, this is the whole
	point of <makevar>PORTEPOCH</makevar> in the first
	place.</para>
	</note>
	</sect3>
	</sect2>

	<sect2>
	<title><makevar>PKGNAMEPREFIX</makevar> and
	<makevar>PKGNAMESUFFIX</makevar></title>

	<para>Two optional variables, <makevar>PKGNAMEPREFIX</makevar>
	and <makevar>PKGNAMESUFFIX</makevar>, are combined with
	<makevar>PORTNAME</makevar> and
	<makevar>PORTVERSION</makevar> to form
	<makevar>PKGNAME</makevar> as
	<literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
	Make sure this conforms to our <link
	linkend="porting-pkgname">guidelines for a good package
	name</link>. In particular, you are
	<emphasis>not</emphasis> allowed to use a hyphen
	(<literal>-</literal>) in <makevar>PORTVERSION</makevar>.
	Also, if the package name has the
	<replaceable>language-</replaceable> or the
	<replaceable>-compiled.specifics</replaceable> part (see
	below), use <makevar>PKGNAMEPREFIX</makevar> and
	<makevar>PKGNAMESUFFIX</makevar>, respectively. Do not make
	them part of <makevar>PORTNAME</makevar>.</para>
	</sect2>

	<sect2>
	<title><makevar>LATEST_LINK</makevar></title>

	<para><makevar>LATEST_LINK</makevar> is used during package
	building to determine a shortened name to create links that
	can be used by <command>pkg_add -r</command>. This makes it
	possible to, for example, install the latest perl version by
	running <command>pkg_add -r perl</command> without knowing
	the exact version number. This name needs to be unique and
	obvious to users.</para>

	<para>In some cases, several versions of a program may be
	present in the ports collection at the same time. Both the
	index build and the package build system need to be able to
	see them as different, independent ports, although they may
	all have the same <makevar>PORTNAME</makevar>,
	<makevar>PKGNAMEPREFIX</makevar>, and even
	<makevar>PKGNAMESUFFIX</makevar>. In those cases, the
	optional <makevar>LATEST_LINK</makevar> variable should be
	set to a different value for all ports except the
	<quote>main</quote> one — see the
	<filename>lang/gcc46</filename> and
	<filename>lang/gcc</filename> ports, and the
	<filename>www/apache*</filename> family for examples of its
	use. By setting <makevar>NO_LATEST_LINK</makevar>, no link
	will be generated, which may be an option for all but the
	<quote>main</quote> version. Note that how to choose a
	<quote>main</quote> version — <quote>most
	popular</quote>, <quote>best supported</quote>,
	<quote>least patched</quote>, and so on — is outside
	the scope of this handbook's recommendations; we only tell
	you how to specify the other ports' versions after you have
	picked a <quote>main</quote> one.</para>
	</sect2>

	<sect2 id="porting-pkgname">
	<title>Package Naming Conventions</title>

	<para>The following are the conventions you should follow in
	naming your packages. This is to have our package directory
	easy to scan, as there are already thousands of packages and
	users are going to turn away if they hurt their eyes!</para>

	<para>The package name should look like
	<filename><replaceable><optional>language<optional>_region</optional></optional>-name<optional><optional>-</optional>compiled.specifics</optional>-version.numbers</replaceable></filename>.</para>

	<para>The package name is defined as
	<literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
	Make sure to set the variables to conform to that
	format.</para>

	<orderedlist>
	<listitem>
	<para>FreeBSD strives to support the native language of
	its users. The <replaceable>language-</replaceable>
	part should be a two letter abbreviation of the natural
	language defined by ISO-639 if the port is specific to a
	certain language. Examples are <literal>ja</literal>
	for Japanese, <literal>ru</literal> for Russian,
	<literal>vi</literal> for Vietnamese,
	<literal>zh</literal> for Chinese, <literal>ko</literal>
	for Korean and <literal>de</literal> for German.</para>

	<para>If the port is specific to a certain region within
	the language area, add the two letter country code as
	well. Examples are <literal>en_US</literal> for US
	English and <literal>fr_CH</literal> for Swiss
	French.</para>

	<para>The <replaceable>language-</replaceable> part should
	be set in the <makevar>PKGNAMEPREFIX</makevar>
	variable.</para>
	</listitem>

	<listitem>
	<para>The first letter of the <filename>name</filename>
	part should be lowercase. (The rest of the name may
	contain capital letters, so use your own discretion when
	you are converting a software name that has some capital
	letters in it.) There is a tradition of naming
	<literal>Perl 5</literal> modules by prepending
	<literal>p5-</literal> and converting the double-colon
	separator to a hyphen; for example, the
	<literal>Data::Dumper</literal> module becomes
	<literal>p5-Data-Dumper</literal>.</para>
	</listitem>

	<listitem>
	<para>Make sure that the port's name and version are
	clearly separated and placed into the
	<makevar>PORTNAME</makevar> and
	<makevar>PORTVERSION</makevar> variables. The only
	reason for <makevar>PORTNAME</makevar> to contain a
	version part is if the upstream distribution is really
	named that way, as in the
	<filename>textproc/libxml2</filename> or
	<filename>japanese/kinput2-freewnn</filename> ports.
	Otherwise, the <makevar>PORTNAME</makevar> should not
	contain any version-specific information. It is quite
	normal for several ports to have the same
	<makevar>PORTNAME</makevar>, as the
	<filename>www/apache*</filename> ports do; in that case,
	different versions (and different index entries) are
	distinguished by the <makevar>PKGNAMEPREFIX</makevar>,
	<makevar>PKGNAMESUFFIX</makevar>, and
	<makevar>LATEST_LINK</makevar> values.</para>
	</listitem>

	<listitem>
	<para>If the port can be built with different <link
	linkend="makefile-masterdir">hardcoded defaults</link>
	(usually part of the directory name in a family of
	ports), the
	<replaceable>-compiled.specifics</replaceable> part
	should state the compiled-in defaults (the hyphen is
	optional). Examples are paper size and font
	units.</para>

	<para>The <replaceable>-compiled.specifics</replaceable>
	part should be set in the
	<makevar>PKGNAMESUFFIX</makevar> variable.</para>
	</listitem>

	<listitem>
	<para>The version string should follow a dash
	(<literal>-</literal>) and be a period-separated list of
	integers and single lowercase alphabetics. In
	particular, it is not permissible to have another dash
	inside the version string. The only exception is the
	string <literal>pl</literal> (meaning
	<quote>patchlevel</quote>), which can be used
	<emphasis>only</emphasis> when there are no major and
	minor version numbers in the software. If the software
	version has strings like <quote>alpha</quote>,
	<quote>beta</quote>, <quote>rc</quote>, or
	<quote>pre</quote>, take the first letter and put it
	immediately after a period. If the version string
	continues after those names, the numbers should follow
	the single alphabet without an extra period between
	them.</para>

	<para>The idea is to make it easier to sort ports by
	looking at the version string. In particular, make sure
	version number components are always delimited by a
	period, and if the date is part of the string, use the
	<literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>
	format, not
	<literal><replaceable>dd</replaceable>.<replaceable>mm</replaceable>.<replaceable>yyyy</replaceable></literal>
	or the non-Y2K compliant
	<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>
	format. It is important to prefix the version with
	<literal>0.0.</literal> in case a release with an actual
	version number is made, which would of course be
	numerically less than
	<literal><replaceable>yyyy</replaceable></literal>.</para>
	</listitem>
	</orderedlist>

	<para>Here are some (real) examples on how to convert the name
	as called by the software authors to a suitable package
	name:</para>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="6">
	<thead>
	<row>
	<entry>Distribution Name</entry>
	<entry><makevar>PKGNAMEPREFIX</makevar></entry>
	<entry><makevar>PORTNAME</makevar></entry>
	<entry><makevar>PKGNAMESUFFIX</makevar></entry>
	<entry><makevar>PORTVERSION</makevar></entry>
	<entry>Reason</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>mule-2.2.2</entry>
	<entry>(empty)</entry>
	<entry>mule</entry>
	<entry>(empty)</entry>
	<entry>2.2.2</entry>
	<entry>No changes required</entry>
	</row>

	<row>
	<entry>EmiClock-1.0.2</entry>
	<entry>(empty)</entry>
	<entry>emiclock</entry>
	<entry>(empty)</entry>
	<entry>1.0.2</entry>
	<entry>No uppercase names for single programs</entry>
	</row>

	<row>
	<entry>rdist-1.3alpha</entry>
	<entry>(empty)</entry>
	<entry>rdist</entry>
	<entry>(empty)</entry>
	<entry>1.3.a</entry>
	<entry>No strings like <literal>alpha</literal>
	allowed</entry>
	</row>

	<row>
	<entry>es-0.9-beta1</entry>
	<entry>(empty)</entry>
	<entry>es</entry>
	<entry>(empty)</entry>
	<entry>0.9.b1</entry>
	<entry>No strings like <literal>beta</literal>
	allowed</entry>
	</row>

	<row>
	<entry>mailman-2.0rc3</entry>
	<entry>(empty)</entry>
	<entry>mailman</entry>
	<entry>(empty)</entry>
	<entry>2.0.r3</entry>
	<entry>No strings like <literal>rc</literal>
	allowed</entry>
	</row>

	<row>
	<entry>v3.3beta021.src</entry>
	<entry>(empty)</entry>
	<entry>tiff</entry>
	<entry>(empty)</entry>
	<entry>3.3</entry>
	<entry>What the heck was that anyway?</entry>
	</row>

	<row>
	<entry>tvtwm</entry>
	<entry>(empty)</entry>
	<entry>tvtwm</entry>
	<entry>(empty)</entry>
	<entry>pl11</entry>
	<entry>Version string always required</entry>
	</row>

	<row>
	<entry>piewm</entry>
	<entry>(empty)</entry>
	<entry>piewm</entry>
	<entry>(empty)</entry>
	<entry>1.0</entry>
	<entry>Version string always required</entry>
	</row>

	<row>
	<entry>xvgr-2.10pl1</entry>
	<entry>(empty)</entry>
	<entry>xvgr</entry>
	<entry>(empty)</entry>
	<entry>2.10.1</entry>
	<entry><literal>pl</literal> allowed only when no
	major/minor version numbers</entry>
	</row>

	<row>
	<entry>gawk-2.15.6</entry>
	<entry>ja-</entry>
	<entry>gawk</entry>
	<entry>(empty)</entry>
	<entry>2.15.6</entry>
	<entry>Japanese language version</entry>
	</row>

	<row>
	<entry>psutils-1.13</entry>
	<entry>(empty)</entry>
	<entry>psutils</entry>
	<entry>-letter</entry>
	<entry>1.13</entry>
	<entry>Paper size hardcoded at package build
	time</entry>
	</row>

	<row>
	<entry>pkfonts</entry>
	<entry>(empty)</entry>
	<entry>pkfonts</entry>
	<entry>300</entry>
	<entry>1.0</entry>
	<entry>Package for 300dpi fonts</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>If there is absolutely no trace of version information
	in the original source and it is unlikely that the original
	author will ever release another version, just set the
	version string to <literal>1.0</literal> (like the
	<literal>piewm</literal> example above). Otherwise, ask the
	original author or use the date string
	(<literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>)
	as the version.</para>
	</sect2>
	</sect1>

	<sect1 id="makefile-categories">
	<title>Categorization</title>

	<sect2>
	<title><makevar>CATEGORIES</makevar></title>

	<para>When a package is created, it is put under
	<filename>/usr/ports/packages/All</filename> and links are
	made from one or more subdirectories of
	<filename>/usr/ports/packages</filename>. The names of
	these subdirectories are specified by the variable
	<makevar>CATEGORIES</makevar>. It is intended to make life
	easier for the user when he is wading through the pile of
	packages on the FTP site or the CDROM. Please take a look
	at the <link linkend="porting-categories">current list of
	categories</link> and pick the ones that are suitable for
	your port.</para>

	<para>This list also determines where in the ports tree the
	port is imported. If you put more than one category here,
	it is assumed that the port files will be put in the
	subdirectory with the name in the first category. See <link
	linkend="choosing-categories">below</link> for more
	discussion about how to pick the right categories.</para>
	</sect2>

	<sect2 id="porting-categories">
	<title>Current List of Categories</title>

	<para>Here is the current list of port categories. Those
	marked with an asterisk (<literal>*</literal>) are
	<emphasis>virtual</emphasis> categories—those that do
	not have a corresponding subdirectory in the ports tree.
	They are only used as secondary categories, and only for
	search purposes.</para>

	<note>
	<para>For non-virtual categories, you will find a one-line
	description in the <makevar>COMMENT</makevar> in that
	subdirectory's <filename>Makefile</filename>.</para>
	</note>

	<informaltable frame="none" pgwide="1">
	<tgroup cols="3">
	<thead>
	<row>
	<entry>Category</entry>
	<entry>Description</entry>
	<entry>Notes</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><filename>accessibility</filename></entry>
	<entry>Ports to help disabled users.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>afterstep*</filename></entry>
	<entry>Ports to support the <ulink
	url="http://www.afterstep.org">AfterStep</ulink>
	window manager.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>arabic</filename></entry>
	<entry>Arabic language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>archivers</filename></entry>
	<entry>Archiving tools.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>astro</filename></entry>
	<entry>Astronomical ports.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>audio</filename></entry>
	<entry>Sound support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>benchmarks</filename></entry>
	<entry>Benchmarking utilities.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>biology</filename></entry>
	<entry>Biology-related software.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>cad</filename></entry>
	<entry>Computer aided design tools.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>chinese</filename></entry>
	<entry>Chinese language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>comms</filename></entry>
	<entry>Communication software.</entry>
	<entry>Mostly software to talk to your serial
	port.</entry>
	</row>

	<row>
	<entry><filename>converters</filename></entry>
	<entry>Character code converters.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>databases</filename></entry>
	<entry>Databases.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>deskutils</filename></entry>
	<entry>Things that used to be on the desktop before
	computers were invented.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>devel</filename></entry>
	<entry>Development utilities.</entry>
	<entry>Do not put libraries here just because they are
	libraries—unless they truly do not belong
	anywhere else, they should not be in this
	category.</entry>
	</row>

	<row>
	<entry><filename>dns</filename></entry>
	<entry>DNS-related software.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>docs*</filename></entry>
	<entry>Meta-ports for FreeBSD documentation.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>editors</filename></entry>
	<entry>General editors.</entry>
	<entry>Specialized editors go in the section for those
	tools (e.g., a mathematical-formula editor will go
	in <filename>math</filename>).</entry>
	</row>

	<row>
	<entry><filename>elisp*</filename></entry>
	<entry>Emacs-lisp ports.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>emulators</filename></entry>
	<entry>Emulators for other operating systems.</entry>
	<entry>Terminal emulators do <emphasis>not</emphasis>
	belong here—X-based ones should go to
	<filename>x11</filename> and text-based ones to
	either <filename>comms</filename> or
	<filename>misc</filename>, depending on the exact
	functionality.</entry>
	</row>

	<row>
	<entry><filename>finance</filename></entry>
	<entry>Monetary, financial and related
	applications.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>french</filename></entry>
	<entry>French language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>ftp</filename></entry>
	<entry>FTP client and server utilities.</entry>
	<entry>If your port speaks both FTP and HTTP, put it
	in <filename>ftp</filename> with a secondary
	category of <filename>www</filename>.</entry>
	</row>

	<row>
	<entry><filename>games</filename></entry>
	<entry>Games.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>geography*</filename></entry>
	<entry>Geography-related software.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>german</filename></entry>
	<entry>German language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>gnome*</filename></entry>
	<entry>Ports from the <ulink
	url="http://www.gnome.org">GNOME</ulink>
	Project.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>gnustep*</filename></entry>
	<entry>Software related to the GNUstep desktop
	environment.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>graphics</filename></entry>
	<entry>Graphics utilities.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>hamradio*</filename></entry>
	<entry>Software for amateur radio.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>haskell*</filename></entry>
	<entry>Software related to the Haskell
	language.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>hebrew</filename></entry>
	<entry>Hebrew language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>hungarian</filename></entry>
	<entry>Hungarian language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>ipv6*</filename></entry>
	<entry>IPv6 related software.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>irc</filename></entry>
	<entry>Internet Relay Chat utilities.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>japanese</filename></entry>
	<entry>Japanese language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>java</filename></entry>
	<entry>Software related to the Java™
	language.</entry>
	<entry>The <filename>java</filename> category must
	not be the only one for a port. Save for ports
	directly related to the Java language, porters are
	also encouraged not to use <filename>java</filename>
	as the main category of a port.</entry>
	</row>

	<row>
	<entry><filename>kde*</filename></entry>
	<entry>Ports from the <ulink
	url="http://www.kde.org">KDE</ulink>
	Project.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>kld*</filename></entry>
	<entry>Kernel loadable modules.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>korean</filename></entry>
	<entry>Korean language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>lang</filename></entry>
	<entry>Programming languages.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>linux*</filename></entry>
	<entry>Linux applications and support
	utilities.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>lisp*</filename></entry>
	<entry>Software related to the Lisp language.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>mail</filename></entry>
	<entry>Mail software.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>math</filename></entry>
	<entry>Numerical computation software and other
	utilities for mathematics.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>mbone*</filename></entry>
	<entry>MBone applications.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>misc</filename></entry>
	<entry>Miscellaneous utilities</entry>
	<entry>Basically things that do not belong anywhere
	else. If at all possible, try to find a better
	category for your port than <literal>misc</literal>,
	as ports tend to get overlooked in here.</entry>
	</row>

	<row>
	<entry><filename>multimedia</filename></entry>
	<entry>Multimedia software.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>net</filename></entry>
	<entry>Miscellaneous networking software.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>net-im</filename></entry>
	<entry>Instant messaging software.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>net-mgmt</filename></entry>
	<entry>Networking management software.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>net-p2p</filename></entry>
	<entry>Peer to peer network applications.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>news</filename></entry>
	<entry>USENET news software.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>palm</filename></entry>
	<entry>Software support for the <ulink
	url="http://www.palm.com/">Palm™</ulink>
	series.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>parallel*</filename></entry>
	<entry>Applications dealing with parallelism in
	computing.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>pear*</filename></entry>
	<entry>Ports related to the Pear PHP
	framework.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>perl5*</filename></entry>
	<entry>Ports that require
	<application>Perl</application> version 5 to
	run.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>plan9*</filename></entry>
	<entry>Various programs from <ulink
	url="http://www.cs.bell-labs.com/plan9dist/">Plan9</ulink>.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>polish</filename></entry>
	<entry>Polish language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>ports-mgmt</filename></entry>
	<entry>Ports for managing, installing and developing
	FreeBSD ports and packages.</entry>
	</row>

	<row>
	<entry><filename>portuguese</filename></entry>
	<entry>Portuguese language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>print</filename></entry>
	<entry>Printing software.</entry>
	<entry>Desktop publishing tools
	(previewers, etc.) belong here too.</entry>
	</row>

	<row>
	<entry><filename>python*</filename></entry>
	<entry>Software related to the <ulink
	url="http://www.python.org/">Python</ulink>
	language.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>ruby*</filename></entry>
	<entry>Software related to the <ulink
	url="http://www.ruby-lang.org/">Ruby</ulink>
	language.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>rubygems*</filename></entry>
	<entry>Ports of <ulink
	url="http://www.rubygems.org/">RubyGems</ulink>
	packages.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>russian</filename></entry>
	<entry>Russian language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>scheme*</filename></entry>
	<entry>Software related to the Scheme
	language.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>science</filename></entry>
	<entry>Scientific ports that do not fit into other
	categories such as <filename>astro</filename>,
	<filename>biology</filename> and
	<filename>math</filename>.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>security</filename></entry>
	<entry>Security utilities.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>shells</filename></entry>
	<entry>Command line shells.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>spanish*</filename></entry>
	<entry>Spanish language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>sysutils</filename></entry>
	<entry>System utilities.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>tcl*</filename></entry>
	<entry>Ports that use Tcl to run.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>textproc</filename></entry>
	<entry>Text processing utilities.</entry>
	<entry>It does not include desktop publishing tools,
	which go to <filename>print</filename>.</entry>
	</row>

	<row>
	<entry><filename>tk*</filename></entry>
	<entry>Ports that use Tk to run.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>ukrainian</filename></entry>
	<entry>Ukrainian language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>vietnamese</filename></entry>
	<entry>Vietnamese language support.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>windowmaker*</filename></entry>
	<entry>Ports to support the WindowMaker window
	manager.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>www</filename></entry>
	<entry>Software related to the World Wide Web.</entry>
	<entry>HTML language
	support belongs here too.</entry>
	</row>

	<row>
	<entry><filename>x11</filename></entry>
	<entry>The X Window System and friends.</entry>
	<entry>This category is only for software that
	directly supports the window system. Do not put
	regular X applications here; most of them should go
	into other <filename>x11-*</filename> categories
	(see below). If your port <emphasis>is</emphasis>
	an X application, define <makevar>USE_XLIB</makevar>
	(implied by <makevar>USE_IMAKE</makevar>) and put it
	in the appropriate category.</entry>
	</row>

	<row>
	<entry><filename>x11-clocks</filename></entry>
	<entry>X11 clocks.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>x11-drivers</filename></entry>
	<entry>X11 drivers.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>x11-fm</filename></entry>
	<entry>X11 file managers.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>x11-fonts</filename></entry>
	<entry>X11 fonts and font utilities.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>x11-servers</filename></entry>
	<entry>X11 servers.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>x11-themes</filename></entry>
	<entry>X11 themes.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>x11-toolkits</filename></entry>
	<entry>X11 toolkits.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>x11-wm</filename></entry>
	<entry>X11 window managers.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>xfce*</filename></entry>
	<entry>Ports related to the <ulink
	url="http://www.xfce.org/">Xfce</ulink> desktop
	environment.</entry>
	<entry></entry>
	</row>

	<row>
	<entry><filename>zope*</filename></entry>
	<entry><ulink url="http://www.zope.org/">Zope</ulink>
	support.</entry>
	<entry></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>
	</sect2>

	<sect2 id="choosing-categories">
	<title>Choosing the Right Category</title>

	<para>As many of the categories overlap, you often have to
	choose which of the categories should be the primary
	category of your port. There are several rules that govern
	this issue. Here is the list of priorities, in decreasing
	order of precedence:</para>

	<itemizedlist>
	<listitem>
	<para>The first category must be a physical category (see
	<link linkend="porting-categories">above</link>). This
	is necessary to make the packaging work. Virtual
	categories and physical categories may be intermixed
	after that.</para>
	</listitem>

	<listitem>
	<para>Language specific categories always come first. For
	example, if your port installs Japanese X11 fonts, then
	your <makevar>CATEGORIES</makevar> line would read
	<filename>japanese x11-fonts</filename>.</para>
	</listitem>

	<listitem>
	<para>Specific categories are listed before less-specific
	ones. For instance, an HTML editor should be listed as
	<filename>www editors</filename>, not the other way
	around. Also, you should not list
	<filename>net</filename> when the port belongs to any of
	<filename>irc</filename>, <filename>mail</filename>,
	<filename>news</filename>,
	<filename>security</filename>, or
	<filename>www</filename>, as <filename>net</filename> is
	included implicitly.</para>
	</listitem>

	<listitem>
	<para><filename>x11</filename> is used as a secondary
	category only when the primary category is a natural
	language. In particular, you should not put
	<filename>x11</filename> in the category line for X
	applications.</para>
	</listitem>

	<listitem>
	<para><application>Emacs</application> modes should be
	placed in the same ports category as the application
	supported by the mode, not in
	<filename>editors</filename>. For example, an
	<application>Emacs</application> mode to edit source
	files of some programming language should go into
	<filename>lang</filename>.</para>
	</listitem>

	<listitem>
	<para>Ports which install loadable kernel modules should
	have the virtual category <filename>kld</filename> in
	their <makevar>CATEGORIES</makevar> line.</para>
	</listitem>

	<listitem>
	<para><filename>misc</filename> should not appear with any
	other non-virtual category. If you have
	<literal>misc</literal> with something else in your
	<makevar>CATEGORIES</makevar> line, that means you can
	safely delete <literal>misc</literal> and just put the
	port in that other subdirectory!</para>
	</listitem>

	<listitem>
	<para>If your port truly does not belong anywhere else,
	put it in <filename>misc</filename>.</para>
	</listitem>
	</itemizedlist>

	<para>If you are not sure about the category, please put a
	comment to that effect in your &man.send-pr.1; submission so
	we can discuss it before we import it. If you are a
	committer, send a note to the &a.ports; so we can discuss it
	first. Too often, new ports are imported to the wrong
	category only to be moved right away. This causes
	unnecessary and undesirable bloat in the master source
	repository.</para>
	</sect2>

	<sect2 id="proposing-categories">
	<title>Proposing a New Category</title>

	<para>As the Ports Collection has grown over time, various new
	categories have been introduced. New categories can either
	be <emphasis>virtual</emphasis> categories—those that
	do not have a corresponding subdirectory in the ports
	tree— or <emphasis>physical</emphasis>
	categories—those that do. The following text
	discusses the issues involved in creating a new physical
	category so that you can understand them before you propose
	one.</para>

	<para>Our existing practice has been to avoid creating a new
	physical category unless either a large number of ports
	would logically belong to it, or the ports that would belong
	to it are a logically distinct group that is of limited
	general interest (for instance, categories related to spoken
	human languages), or preferably both.</para>

	<para>The rationale for this is that such a change creates a
	<ulink url="&url.articles.committers-guide;/#ports"> fair
	amount of work</ulink> for both the committers and also
	for all users who track changes to the Ports Collection. In
	addition, proposed category changes just naturally seem to
	attract controversy. (Perhaps this is because there is no
	clear consensus on when a category is <quote>too
	big</quote>, nor whether categories should lend themselves
	to browsing (and thus what number of categories would be an
	ideal number), and so forth.)</para>

	<para>Here is the procedure:</para>

	<procedure>
	<step>
	<para>Propose the new category on &a.ports;. You should
	include a detailed rationale for the new category,
	including why you feel the existing categories are not
	sufficient, and the list of existing ports proposed to
	move. (If there are new ports pending in
	<application>GNATS</application> that would fit this
	category, list them too.) If you are the maintainer
	and/or submitter, respectively, mention that as it may
	help you to make your case.</para>
	</step>

	<step>
	<para>Participate in the discussion.</para>
	</step>

	<step>
	<para>If it seems that there is support for your idea,
	file a PR which includes both the rationale and the list
	of existing ports that need to be moved. Ideally, this
	PR should also include patches for the following:</para>

	<itemizedlist>
	<listitem>
	<para><filename>Makefile</filename>s for the
	new ports once they are repocopied</para>
	</listitem>

	<listitem>
	<para><filename>Makefile</filename> for the
	new category</para>
	</listitem>

	<listitem>
	<para><filename>Makefile</filename> for the
	old ports' categories</para>
	</listitem>

	<listitem>
	<para><filename>Makefile</filename>s for ports
	that depend on the old ports</para>
	</listitem>

	<listitem>
	<para>(for extra credit, you can include the other
	files that have to change, as per the procedure
	in the Committer's Guide.)</para>
	</listitem>
	</itemizedlist>
	</step>

	<step>
	<para>Since it affects the ports infrastructure and
	involves not only performing repo-copies but also
	possibly running regression tests on the build cluster,
	the PR should be assigned to the &a.portmgr;.</para>
	</step>

	<step>
	<para>If that PR is approved, a committer will need to
	follow the rest of the procedure that is <ulink
	url="&url.articles.committers-guide;/article.html#PORTS">
	outlined in the Committer's Guide</ulink>.</para>
	</step>
	</procedure>

	<para>Proposing a new virtual category should be similar to
	the above but much less involved, since no ports will
	actually have to move. In this case, the only patches to
	include in the PR would be those to add the new category to
	the <makevar>CATEGORIES</makevar> of the affected
	ports.</para>
	</sect2>

	<sect2 id="proposing-reorg">
	<title>Proposing Reorganizing All the Categories</title>

	<para>Occasionally someone proposes reorganizing the
	categories with either a 2-level structure, or some other
	kind of keyword structure. To date, nothing has come of any
	of these proposals because, while they are very easy to
	make, the effort involved to retrofit the entire existing
	ports collection with any kind of reorganization is daunting
	to say the very least. Please read the history of these
	proposals in the mailing list archives before you post this
	idea; furthermore, you should be prepared to be challenged
	to offer a working prototype.</para>
	</sect2>
	</sect1>

	<sect1 id="makefile-distfiles">
	<title>The Distribution Files</title>

	<para>The second part of the <filename>Makefile</filename>
	describes the files that must be downloaded in order to build
	the port, and where they can be downloaded from.</para>

	<sect2>
	<title><makevar>DISTVERSION/DISTNAME</makevar></title>

	<para><makevar>DISTNAME</makevar> is the name of the port as
	called by the authors of the software.
	<makevar>DISTNAME</makevar> defaults to
	<literal>${PORTNAME}-${PORTVERSION}</literal>, so override
	it only if necessary. <makevar>DISTNAME</makevar> is only
	used in two places. First, the distribution file list
	(<makevar>DISTFILES</makevar>) defaults to
	<makevar>${DISTNAME}</makevar><makevar>${EXTRACT_SUFX}</makevar>.
	Second, the distribution file is expected to extract into a
	subdirectory named <makevar>WRKSRC</makevar>, which defaults
	to
	<filename>work/<makevar>${DISTNAME}</makevar></filename>.</para>

	<para>Some vendor's distribution names which do not fit into
	the <literal>${PORTNAME}-${PORTVERSION}</literal>-scheme can
	be handled automatically by setting
	<makevar>DISTVERSION</makevar>.
	<makevar>PORTVERSION</makevar> and
	<makevar>DISTNAME</makevar> will be derived automatically,
	but can of course be overridden. The following table lists
	some examples:</para>

	<informaltable frame="none" pgwide="0">
	<tgroup cols="2">
	<thead>
	<row>
	<entry><makevar>DISTVERSION</makevar></entry>
	<entry><makevar>PORTVERSION</makevar></entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>0.7.1d</entry>
	<entry>0.7.1.d</entry>
	</row>

	<row>
	<entry>10Alpha3</entry>
	<entry>10.a3</entry>
	</row>

	<row>
	<entry>3Beta7-pre2</entry>
	<entry>3.b7.p2</entry>
	</row>

	<row>
	<entry>8:f_17</entry>
	<entry>8f.17</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<note>
	<para><makevar>PKGNAMEPREFIX</makevar> and
	<makevar>PKGNAMESUFFIX</makevar> do not affect
	<makevar>DISTNAME</makevar>. Also note that if
	<makevar>WRKSRC</makevar> is equal to
	<filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename>
	while the original source archive is named something other
	than
	<makevar>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</makevar>,
	you should probably leave <makevar>DISTNAME</makevar>
	alone— you are better off defining
	<makevar>DISTFILES</makevar> than having to set both
	<makevar>DISTNAME</makevar> and <makevar>WRKSRC</makevar>
	(and possibly <makevar>EXTRACT_SUFX</makevar>).</para>
	</note>
	</sect2>

	<sect2>
	<title><makevar>MASTER_SITES</makevar></title>

	<para>Record the directory part of the FTP/HTTP-URL pointing
	at the original tarball in <makevar>MASTER_SITES</makevar>.
	Do not forget the trailing slash
	(<filename>/</filename>)!</para>

	<para>The <command>make</command> macros will try to use this
	specification for grabbing the distribution file with
	<makevar>FETCH</makevar> if they cannot find it already on
	the system.</para>

	<para>It is recommended that you put multiple sites on this
	list, preferably from different continents. This will
	safeguard against wide-area network problems. We are even
	planning to add support for automatically determining the
	closest master site and fetching from there; having multiple
	sites will go a long way towards helping this effort.</para>

	<para>If the original tarball is part of one of the popular
	archives such as SourceForge, GNU, or Perl CPAN, you may be
	able refer to those sites in an easy compact form using
	<makevar>MASTER_SITE_<replaceable>*</replaceable></makevar>
	(e.g., <makevar>MASTER_SITE_SOURCEFORGE</makevar>,
	<makevar>MASTER_SITE_GNU</makevar> and
	<makevar>MASTER_SITE_PERL_CPAN</makevar>). Simply set
	<makevar>MASTER_SITES</makevar> to one of these variables
	and <makevar>MASTER_SITE_SUBDIR</makevar> to the path within
	the archive. Here is an example:</para>

	<programlisting>MASTER_SITES= ${MASTER_SITE_GNU}
	MASTER_SITE_SUBDIR= make</programlisting>

	<para>Or you can use a condensed format:</para>

	<programlisting>MASTER_SITES= GNU/make</programlisting>

	<para>These variables are defined in
	<filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are
	new entries added all the time, so make sure to check the
	latest version of this file before submitting a port.</para>

	<para>Several <emphasis>magic</emphasis> macros exist for
	popular sites with a predictable directory structure. For
	these, just use the abbreviation and the system will try to
	guess the correct subdirectory for you.</para>

	<programlisting>MASTER_SITES= SF</programlisting>

	<para>If the guess is incorrect, it can be overridden as
	follows.</para>

	<programlisting>MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>

	<para>This can be also written as</para>
	<programlisting>MASTER_SITES= SF
	MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>

	<table frame="none">
	<title>Popular Magic <makevar>MASTER_SITES</makevar>
	Macros</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Macro</entry>
	<entry>Assumed subdirectory</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>APACHE_JAKARTA</makevar></entry>
	<entry><makevar>/dist/jakarta/${PORTNAME:S,-,,/,}/source</makevar></entry>
	</row>

	<row>
	<entry><makevar>BERLIOS</makevar></entry>
	<entry><makevar>/${PORTNAME:L}</makevar></entry>
	</row>

	<row>
	<entry><makevar>CHEESESHOP</makevar></entry>
	<entry><makevar>/packages/source/source/${DISTNAME:C/(.)./\1/}/${DISTNAME:C/(.)-[0-9].*/\1/}</makevar></entry>
	</row>

	<row>
	<entry><makevar>DEBIAN</makevar></entry>
	<entry><makevar>/debian/pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}</makevar></entry>
	</row>

	<row>
	<entry><makevar>GCC</makevar></entry>
	<entry><makevar>/pub/gcc/releases/${DISTNAME}</makevar></entry>
	</row>

	<row>
	<entry><makevar>GNOME</makevar></entry>
	<entry><makevar>/pub/GNOME/sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</makevar></entry>
	</row>

	<row>
	<entry><makevar>GNU</makevar></entry>
	<entry><makevar>/gnu/${PORTNAME}</makevar></entry>
	</row>

	<row>
	<entry><makevar>MOZDEV</makevar></entry>
	<entry><makevar>/pub/mozdev/${PORTNAME:L}</makevar></entry>
	</row>

	<row>
	<entry><makevar>PERL_CPAN</makevar></entry>
	<entry><makevar>/pub/CPAN/modules/by-module/${PORTNAME:C/-.*//}</makevar></entry>
	</row>

	<row>
	<entry><makevar>PYTHON</makevar></entry>
	<entry><makevar>/ftp/python/${PYTHON_PORTVERSION:C/rc[0-9]//}</makevar></entry>
	</row>

	<row>
	<entry><makevar>RUBYFORGE</makevar></entry>
	<entry><makevar>/${PORTNAME:L}</makevar></entry>
	</row>

	<row>
	<entry><makevar>SAVANNAH</makevar></entry>
	<entry><makevar>/${PORTNAME:L}</makevar></entry>
	</row>

	<row>
	<entry><makevar>SF</makevar></entry>
	<entry><makevar>/project/${PORTNAME:L}/${PORTNAME:L}/${PORTVERSION}</makevar></entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect2>

	<sect2>
	<title><makevar>EXTRACT_SUFX</makevar></title>

	<para>If you have one distribution file, and it uses an odd
	suffix to indicate the compression mechanism, set
	<makevar>EXTRACT_SUFX</makevar>.</para>

	<para>For example, if the distribution file was named
	<filename>foo.tgz</filename> instead of the more normal
	<filename>foo.tar.gz</filename>, you would write:</para>

	<programlisting>DISTNAME= foo
	EXTRACT_SUFX= .tgz</programlisting>

	<para>The <makevar>USE_BZIP2</makevar>,
	<makevar>USE_XZ</makevar> and
	<makevar>USE_ZIP</makevar> variables automatically set
	<makevar>EXTRACT_SUFX</makevar> to
	<literal>.tar.bz2</literal>, <literal>.tar.xz</literal>
	or <literal>.zip</literal> as necessary. If neither of
	these are set then <makevar>EXTRACT_SUFX</makevar>
	defaults to <literal>.tar.gz</literal>.</para>

	<note>
	<para>You never need to set both
	<makevar>EXTRACT_SUFX</makevar> and
	<makevar>DISTFILES</makevar>.</para>
	</note>
	</sect2>

	<sect2>
	<title><makevar>DISTFILES</makevar></title>

	<para>Sometimes the names of the files to be downloaded have
	no resemblance to the name of the port. For example, it
	might be called <filename>source.tar.gz</filename> or
	similar. In other cases the application's source code might
	be in several different archives, all of which must be
	downloaded.</para>

	<para>If this is the case, set <makevar>DISTFILES</makevar> to
	be a space separated list of all the files that must be
	downloaded.</para>

	<programlisting>DISTFILES= source1.tar.gz source2.tar.gz</programlisting>

	<para>If not explicitly set, <makevar>DISTFILES</makevar>
	defaults to
	<literal>${DISTNAME}${EXTRACT_SUFX}</literal>.</para>
	</sect2>

	<sect2>
	<title><makevar>EXTRACT_ONLY</makevar></title>

	<para>If only some of the <makevar>DISTFILES</makevar> must be
	extracted—for example, one of them is the source code,
	while another is an uncompressed document—list the
	filenames that must be extracted in
	<makevar>EXTRACT_ONLY</makevar>.</para>

	<programlisting>DISTFILES= source.tar.gz manual.html
	EXTRACT_ONLY= source.tar.gz</programlisting>

	<para>If <emphasis>none</emphasis> of the
	<makevar>DISTFILES</makevar> should be uncompressed then set
	<makevar>EXTRACT_ONLY</makevar> to the empty string.</para>

	<programlisting>EXTRACT_ONLY=</programlisting>
	</sect2>

	<sect2 id="porting-patchfiles">
	<title><makevar>PATCHFILES</makevar></title>

	<para>If your port requires some additional patches that are
	available by FTP or HTTP, set <makevar>PATCHFILES</makevar>
	to the names of the files and <makevar>PATCH_SITES</makevar>
	to the URL of the directory that contains them (the format
	is the same as <makevar>MASTER_SITES</makevar>).</para>

	<para>If the patch is not relative to the top of the source
	tree (i.e., <makevar>WRKSRC</makevar>) because it contains
	some extra pathnames, set
	<makevar>PATCH_DIST_STRIP</makevar> accordingly. For
	instance, if all the pathnames in the patch have an extra
	<literal>foozolix-1.0/</literal> in front of the filenames,
	then set <literal>PATCH_DIST_STRIP=-p1</literal>.</para>

	<para>Do not worry if the patches are compressed; they will be
	decompressed automatically if the filenames end with
	<filename>.gz</filename> or <filename>.Z</filename>.</para>

	<para>If the patch is distributed with some other files, such
	as documentation, in a <command>gzip</command>ped tarball,
	you cannot just use <makevar>PATCHFILES</makevar>. If that
	is the case, add the name and the location of the patch
	tarball to <makevar>DISTFILES</makevar> and
	<makevar>MASTER_SITES</makevar>. Then, use the
	<makevar>EXTRA_PATCHES</makevar> variable to point to those
	files and <filename>bsd.port.mk</filename> will
	automatically apply them for you. In particular, do
	<emphasis>not</emphasis> copy patch files into the
	<makevar>PATCHDIR</makevar> directory—that directory
	may not be writable.</para>

	<note>
	<para>The tarball will have been extracted alongside the
	regular source by then, so there is no need to explicitly
	extract it if it is a regular <command>gzip</command>ped
	or <command>compress</command>ed tarball. If you do the
	latter, take extra care not to overwrite something that
	already exists in that directory. Also, do not forget to
	add a command to remove the copied patch in the
	<maketarget>pre-clean</maketarget> target.</para>
	</note>
	</sect2>

	<sect2 id="porting-master-sites-n">
	<title>Multiple Distribution Files or Patches from Different
	Sites and Subdirectories
	(<literal>MASTER_SITES:n</literal>)</title>

	<para>(Consider this to be a somewhat <quote>advanced
	topic</quote>; those new to this document may wish to skip
	this section at first).</para>

	<para>This section has information on the fetching mechanism
	known as both <literal>MASTER_SITES:n</literal> and
	<literal>MASTER_SITES_NN</literal>. We will refer to this
	mechanism as <literal>MASTER_SITES:n</literal>.</para>

	<para>A little background first. OpenBSD has a neat feature
	inside the <makevar>DISTFILES</makevar> and
	<makevar>PATCHFILES</makevar> variables which allows files
	and patches to be postfixed with <literal>:n</literal>
	identifiers. Here, <literal>n</literal> can be both
	<literal>[0-9]</literal> and denote a group designation.
	For example:</para>

	<programlisting>DISTFILES= alpha:0 beta:1</programlisting>

	<para>In OpenBSD, distribution file <filename>alpha</filename>
	will be associated with variable
	<makevar>MASTER_SITES0</makevar> instead of our common
	<makevar>MASTER_SITES</makevar> and
	<filename>beta</filename> with
	<makevar>MASTER_SITES1</makevar>.</para>

	<para>This is a very interesting feature which can decrease
	that endless search for the correct download site.</para>

	<para>Just picture 2 files in <makevar>DISTFILES</makevar> and
	20 sites in <makevar>MASTER_SITES</makevar>, the sites slow
	as hell where <filename>beta</filename> is carried by all
	sites in <makevar>MASTER_SITES</makevar>, and
	<filename>alpha</filename> can only be found in the 20th
	site. It would be such a waste to check all of them if the
	maintainer knew this beforehand, would it not? Not a good
	start for that lovely weekend!</para>

	<para>Now that you have the idea, just imagine more
	<makevar>DISTFILES</makevar> and more
	<makevar>MASTER_SITES</makevar>. Surely our
	<quote>distfiles survey meister</quote> would appreciate the
	relief to network strain that this would bring.</para>

	<para>In the next sections, information will follow on the
	FreeBSD implementation of this idea. We improved a bit on
	OpenBSD's concept.</para>

	<sect3>
	<title>Simplified Information</title>

	<para>This section tells you how to quickly prepare fine
	grained fetching of multiple distribution files and
	patches from different sites and subdirectories. We
	describe here a case of simplified
	<literal>MASTER_SITES:n</literal> usage. This will be
	sufficient for most scenarios. However, if you need
	further information, you will have to refer to the next
	section.</para>

	<para>Some applications consist of multiple distribution
	files that must be downloaded from a number of different
	sites. For example,
	<application>Ghostscript</application> consists of the
	core of the program, and then a large number of driver
	files that are used depending on the user's printer. Some
	of these driver files are supplied with the core, but many
	others must be downloaded from a variety of different
	sites.</para>

	<para>To support this, each entry in
	<makevar>DISTFILES</makevar> may be followed by a colon
	and a <quote>tag name</quote>. Each site listed in
	<makevar>MASTER_SITES</makevar> is then followed by a
	colon, and the tag that indicates which distribution files
	should be downloaded from this site.</para>

	<para>For example, consider an application with the source
	split in two parts, <filename>source1.tar.gz</filename>
	and <filename>source2.tar.gz</filename>, which must be
	downloaded from two different sites. The port's
	<filename>Makefile</filename> would include lines like
	<xref
	linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/>.</para>

	<example
	id="ports-master-sites-n-example-simple-use-one-file-per-site">
	<title>Simplified Use of <literal>MASTER_SITES:n</literal>
	with One File Per Site</title>

	<programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \
	ftp://ftp.example2.com/:source2
	DISTFILES= source1.tar.gz:source1 \
	source2.tar.gz:source2</programlisting>
	</example>

	<para>Multiple distribution files can have the same tag.
	Continuing the previous example, suppose that there was a
	third distfile, <filename>source3.tar.gz</filename>, that
	should be downloaded from
	<hostid>ftp.example2.com</hostid>. The
	<filename>Makefile</filename> would then be written like
	<xref
	linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para>

	<example
	id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site">
	<title>Simplified Use of <literal>MASTER_SITES:n</literal>
	with More Than One File Per Site</title>

	<programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \
	ftp://ftp.example2.com/:source2
	DISTFILES= source1.tar.gz:source1 \
	source2.tar.gz:source2 \
	source3.tar.gz:source2</programlisting>
	</example>
	</sect3>

	<sect3>
	<title>Detailed Information</title>

	<para>Okay, so the previous section example did not reflect
	your needs? In this section we will explain in detail
	how the fine grained fetching mechanism
	<literal>MASTER_SITES:n</literal> works and how you can
	modify your ports to use it.</para>

	<orderedlist>
	<listitem>
	<para>Elements can be postfixed with
	<literal>:<replaceable>n</replaceable></literal> where
	<replaceable>n</replaceable> is
	<literal>[^:,]+</literal>, i.e.,
	<replaceable>n</replaceable> could conceptually be any
	alphanumeric string but we will limit it to
	<literal>[a-zA-Z_][0-9a-zA-Z_]+</literal> for
	now.</para>

	<para>Moreover, string matching is case sensitive;
	i.e., <literal>n</literal> is different from
	<literal>N</literal>.</para>

	<para>However, the following words cannot be used for
	postfixing purposes since they yield special meaning:
	<literal>default</literal>, <literal>all</literal> and
	<literal>ALL</literal> (they are used internally in
	item <xref
	linkend="porting-master-sites-n-what-changes-in-port-targets"/>).
	Furthermore, <literal>DEFAULT</literal> is a special
	purpose word (check item <xref
	linkend="porting-master-sites-n-DEFAULT-group"/>).</para>
	</listitem>

	<listitem>
	<para>Elements postfixed with <literal>:n</literal>
	belong to the group <literal>n</literal>,
	<literal>:m</literal> belong to group
	<literal>m</literal> and so forth.</para>
	</listitem>

	<listitem id="porting-master-sites-n-DEFAULT-group">
	<para>Elements without a postfix are groupless, i.e.,
	they all belong to the special group
	<literal>DEFAULT</literal>. If you postfix any
	elements with <literal>DEFAULT</literal>, you are just
	being redundant unless you want to have an element
	belonging to both <literal>DEFAULT</literal> and other
	groups at the same time (check item <xref
	linkend="porting-master-sites-n-comma-operator"/>).</para>

	<para>The following examples are equivalent but the
	first one is preferred:</para>

	<programlisting>MASTER_SITES= alpha</programlisting>

	<programlisting>MASTER_SITES= alpha:DEFAULT</programlisting>
	</listitem>

	<listitem>
	<para>Groups are not exclusive, an element may belong to
	several different groups at the same time and a group
	can either have either several different elements or
	none at all. Repeated elements within the same group
	will be simply that, repeated elements.</para>
	</listitem>

	<listitem id="porting-master-sites-n-comma-operator">
	<para>When you want an element to belong to several
	groups at the same time, you can use the comma
	operator (<literal>,</literal>).</para>

	<para>Instead of repeating it several times, each time
	with a different postfix, we can list several groups
	at once in a single postfix. For instance,
	<literal>:m,n,o</literal> marks an element that
	belongs to group <literal>m</literal>,
	<literal>n</literal> and <literal>o</literal>.</para>

	<para>All the following examples are equivalent but the
	last one is preferred:</para>

	<programlisting>MASTER_SITES= alpha alpha:SOME_SITE</programlisting>

	<programlisting>MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE</programlisting>

	<programlisting>MASTER_SITES= alpha:SOME_SITE,DEFAULT</programlisting>

	<programlisting>MASTER_SITES= alpha:DEFAULT,SOME_SITE</programlisting>
	</listitem>

	<listitem>
	<para>All sites within a given group are sorted
	according to <makevar>MASTER_SORT_AWK</makevar>. All
	groups within <makevar>MASTER_SITES</makevar> and
	<makevar>PATCH_SITES</makevar> are sorted as
	well.</para>
	</listitem>

	<listitem id="porting-master-sites-n-group-semantics">
	<para>Group semantics can be used in any of the
	following variables <makevar>MASTER_SITES</makevar>,
	<makevar>PATCH_SITES</makevar>,
	<makevar>MASTER_SITE_SUBDIR</makevar>,
	<makevar>PATCH_SITE_SUBDIR</makevar>,
	<makevar>DISTFILES</makevar>, and
	<makevar>PATCHFILES</makevar> according to the
	following syntax:</para>

	<orderedlist>
	<listitem>
	<para>All <makevar>MASTER_SITES</makevar>,
	<makevar>PATCH_SITES</makevar>,
	<makevar>MASTER_SITE_SUBDIR</makevar> and
	<makevar>PATCH_SITE_SUBDIR</makevar> elements must
	be terminated with the forward slash
	<literal>/</literal> character. If any elements
	belong to any groups, the group postfix
	<literal>:<replaceable>n</replaceable></literal>
	must come right after the terminator
	<literal>/</literal>. The
	<literal>MASTER_SITES:n</literal> mechanism relies
	on the existence of the terminator
	<literal>/</literal> to avoid confusing elements
	where a <literal>:n</literal> is a valid part of
	the element with occurrences where
	<literal>:n</literal> denotes group
	<literal>n</literal>. For compatibility purposes,
	since the <literal>/</literal> terminator was not
	required before in both
	<makevar>MASTER_SITE_SUBDIR</makevar> and
	<makevar>PATCH_SITE_SUBDIR</makevar> elements, if
	the postfix immediate preceding character is not
	a <literal>/</literal> then <literal>:n</literal>
	will be considered a valid part of the element
	instead of a group postfix even if an element is
	postfixed with <literal>:n</literal>. See both
	<xref
	linkend="ports-master-sites-n-example-detailed-use-master-site-subdir"/>
	and <xref
	linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para>

	<example
	id="ports-master-sites-n-example-detailed-use-master-site-subdir">

	<title>Detailed Use of
	<literal>MASTER_SITES:n</literal> in
	<makevar>MASTER_SITE_SUBDIR</makevar></title>

	<programlisting>MASTER_SITE_SUBDIR= old:n new/:NEW</programlisting>

	<itemizedlist>
	<listitem>
	<para>Directories within group
	<literal>DEFAULT</literal> ->
	old:n</para>
	</listitem>

	<listitem>
	<para>Directories within group
	<literal>NEW</literal> -> new</para>
	</listitem>
	</itemizedlist>
	</example>

	<example
	id="ports-master-sites-n-example-detailed-use-complete-example-master-sites">
	<title>Detailed Use of
	<literal>MASTER_SITES:n</literal> with Comma
	Operator, Multiple Files, Multiple Sites and
	Multiple Subdirectories</title>

	<programlisting>MASTER_SITES= http://site1/%SUBDIR%/ http://site2/:DEFAULT \
	http://site3/:group3 http://site4/:group4 \
	http://site5/:group5 http://site6/:group6 \
	http://site7/:DEFAULT,group6 \
	http://site8/%SUBDIR%/:group6,group7 \
	http://site9/:group8
	DISTFILES= file1 file2:DEFAULT file3:group3 \
	file4:group4,group5,group6 file5:grouping \
	file6:group7
	MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \
	directory-one/:group6,DEFAULT \
	directory</programlisting>

	<para>The previous example results in the
	following fine grained fetching. Sites are
	listed in the exact order they will be
	used.</para>

	<itemizedlist>
	<listitem>
	<para><filename>file1</filename> will be
	fetched from</para>

	<itemizedlist>
	<listitem>
	<para><makevar>MASTER_SITE_OVERRIDE</makevar></para>
	</listitem>

	<listitem>
	<para>http://site1/directory-trial:1/</para>
	</listitem>

	<listitem>
	<para>http://site1/directory-one/</para>
	</listitem>

	<listitem>
	<para>http://site1/directory/</para>
	</listitem>

	<listitem>
	<para>http://site2/</para>
	</listitem>

	<listitem>
	<para>http://site7/</para>
	</listitem>

	<listitem>
	<para><makevar>MASTER_SITE_BACKUP</makevar></para>
	</listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<para><filename>file2</filename> will be
	fetched exactly as
	<filename>file1</filename> since they
	both belong to the same group</para>

	<itemizedlist>
	<listitem>
	<para><makevar>MASTER_SITE_OVERRIDE</makevar></para>
	</listitem>

	<listitem>
	<para>http://site1/directory-trial:1/</para>
	</listitem>

	<listitem>
	<para>http://site1/directory-one/</para>
	</listitem>

	<listitem>
	<para>http://site1/directory/</para>
	</listitem>

	<listitem>
	<para>http://site2/</para>
	</listitem>

	<listitem>
	<para>http://site7/</para>
	</listitem>

	<listitem>
	<para><makevar>MASTER_SITE_BACKUP</makevar></para>
	</listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<para><filename>file3</filename> will be
	fetched from</para>

	<itemizedlist>
	<listitem>
	<para><makevar>MASTER_SITE_OVERRIDE</makevar></para>
	</listitem>

	<listitem>
	<para>http://site3/</para>
	</listitem>

	<listitem>
	<para><makevar>MASTER_SITE_BACKUP</makevar></para>
	</listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<para><filename>file4</filename> will be
	fetched from</para>

	<itemizedlist>
	<listitem>
	<para><makevar>MASTER_SITE_OVERRIDE</makevar></para>
	</listitem>

	<listitem>
	<para>http://site4/</para>
	</listitem>

	<listitem>
	<para>http://site5/</para>
	</listitem>

	<listitem>
	<para>http://site6/</para>
	</listitem>

	<listitem>
	<para>http://site7/</para>
	</listitem>

	<listitem>
	<para>http://site8/directory-one/</para>
	</listitem>

	<listitem>
	<para><makevar>MASTER_SITE_BACKUP</makevar></para>
	</listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<para><filename>file5</filename> will be
	fetched from</para>

	<itemizedlist>
	<listitem>
	<para><makevar>MASTER_SITE_OVERRIDE</makevar></para>
	</listitem>

	<listitem>
	<para><makevar>MASTER_SITE_BACKUP</makevar></para>
	</listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<para><filename>file6</filename> will be
	fetched from</para>

	<itemizedlist>
	<listitem>
	<para><makevar>MASTER_SITE_OVERRIDE</makevar></para>
	</listitem>

	<listitem>
	<para>http://site8/</para>
	</listitem>

	<listitem>
	<para><makevar>MASTER_SITE_BACKUP</makevar></para>
	</listitem>
	</itemizedlist>
	</listitem>
	</itemizedlist>
	</example>
	</listitem>
	</orderedlist>
	</listitem>

	<listitem>
	<para>How do I group one of the special variables from
	<filename>bsd.sites.mk</filename>, e.g.,
	<makevar>MASTER_SITE_SOURCEFORGE</makevar>?</para>

	<para>See <xref
	linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para>

	<example
	id="ports-master-sites-n-example-detailed-use-master-site-sourceforge">
	<title>Detailed Use of
	<literal>MASTER_SITES:n</literal> with
	<makevar>MASTER_SITE_SOURCEFORGE</makevar></title>

	<programlisting>MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/}
	DISTFILES= something.tar.gz:sourceforge</programlisting>
	</example>

	<para><filename>something.tar.gz</filename> will be
	fetched from all sites within
	<makevar>MASTER_SITE_SOURCEFORGE</makevar>.</para>
	</listitem>

	<listitem>
	<para>How do I use this with <makevar>PATCH*</makevar>
	variables?</para>

	<para>All examples were done with
	<makevar>MASTER*</makevar> variables but they work
	exactly the same for <makevar>PATCH*</makevar> ones as
	can be seen in <xref
	linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para>

	<example
	id="ports-master-sites-n-example-detailed-use-patch-sites">
	<title>Simplified Use of
	<literal>MASTER_SITES:n</literal> with
	<makevar>PATCH_SITES</makevar></title>

	<programlisting>PATCH_SITES= http://site1/ http://site2/:test
	PATCHFILES= patch1:test</programlisting>
	</example>
	</listitem>
	</orderedlist>
	</sect3>

	<sect3>
	<title>What Does Change for Ports? What Does Not?</title>

	<orderedlist numeration="lowerroman">
	<listitem>
	<para>All current ports remain the same. The
	<literal>MASTER_SITES:n</literal> feature code is only
	activated if there are elements postfixed with
	<literal>:<replaceable>n</replaceable></literal> like
	elements according to the aforementioned syntax rules,
	especially as shown in item <xref
	linkend="porting-master-sites-n-group-semantics"/>.</para>
	</listitem>

	<listitem
	id="porting-master-sites-n-what-changes-in-port-targets">
	<para>The port targets remain the same:
	<maketarget>checksum</maketarget>,
	<maketarget>makesum</maketarget>,
	<maketarget>patch</maketarget>,
	<maketarget>configure</maketarget>,
	<maketarget>build</maketarget>, etc. With the obvious
	exceptions of <maketarget>do-fetch</maketarget>,
	<maketarget>fetch-list</maketarget>,
	<maketarget>master-sites</maketarget> and
	<maketarget>patch-sites</maketarget>.</para>

	<itemizedlist>
	<listitem>
	<para><maketarget>do-fetch</maketarget>: deploys the
	new grouping postfixed
	<makevar>DISTFILES</makevar> and
	<makevar>PATCHFILES</makevar> with their matching
	group elements within both
	<makevar>MASTER_SITES</makevar> and
	<makevar>PATCH_SITES</makevar> which use matching
	group elements within both
	<makevar>MASTER_SITE_SUBDIR</makevar> and
	<makevar>PATCH_SITE_SUBDIR</makevar>. Check <xref
	linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para>
	</listitem>

	<listitem>
	<para><maketarget>fetch-list</maketarget>: works
	like old <maketarget>fetch-list</maketarget> with
	the exception that it groups just like
	<maketarget>do-fetch</maketarget>.</para>
	</listitem>

	<listitem>
	<para><maketarget>master-sites</maketarget> and
	<maketarget>patch-sites</maketarget>:
	(incompatible with older versions) only return the
	elements of group <literal>DEFAULT</literal>; in
	fact, they execute targets
	<maketarget>master-sites-default</maketarget> and
	<maketarget>patch-sites-default</maketarget>
	respectively.</para>

	<para>Furthermore, using target either
	<maketarget>master-sites-all</maketarget> or
	<maketarget>patch-sites-all</maketarget> is
	preferred to directly checking either
	<maketarget>MASTER_SITES</maketarget> or
	<maketarget>PATCH_SITES</maketarget>. Also,
	directly checking is not guaranteed to work in any
	future versions. Check item <xref
	linkend="porting-master-sites-n-new-port-targets-master-sites-all"/>
	for more information on these new port
	targets.</para>
	</listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<para>New port targets</para>

	<orderedlist>
	<listitem>
	<para>There are
	<maketarget>master-sites-<replaceable>n</replaceable></maketarget>
	and
	<maketarget>patch-sites-<replaceable>n</replaceable></maketarget>
	targets which will list the elements of the
	respective group <replaceable>n</replaceable>
	within <makevar>MASTER_SITES</makevar> and
	<makevar>PATCH_SITES</makevar> respectively. For
	instance, both
	<maketarget>master-sites-DEFAULT</maketarget> and
	<maketarget>patch-sites-DEFAULT</maketarget> will
	return the elements of group
	<literal>DEFAULT</literal>,
	<maketarget>master-sites-test</maketarget> and
	<maketarget>patch-sites-test</maketarget> of group
	<literal>test</literal>, and thereon.</para>
	</listitem>

	<listitem
	id="porting-master-sites-n-new-port-targets-master-sites-all">
	<para>There are new targets
	<maketarget>master-sites-all</maketarget> and
	<maketarget>patch-sites-all</maketarget> which do
	the work of the old
	<maketarget>master-sites</maketarget> and
	<maketarget>patch-sites</maketarget> ones. They
	return the elements of all groups as if they all
	belonged to the same group with the caveat that it
	lists as many
	<makevar>MASTER_SITE_BACKUP</makevar> and
	<makevar>MASTER_SITE_OVERRIDE</makevar> as there
	are groups defined within either
	<makevar>DISTFILES</makevar> or
	<makevar>PATCHFILES</makevar>; respectively for
	<maketarget>master-sites-all</maketarget> and
	<maketarget>patch-sites-all</maketarget>.</para>
	</listitem>
	</orderedlist>
	</listitem>
	</orderedlist>
	</sect3>
	</sect2>

	<sect2>
	<title><makevar>DIST_SUBDIR</makevar></title>

	<para>Do not let your port clutter
	<filename>/usr/ports/distfiles</filename>. If your port
	requires a lot of files to be fetched, or contains a file
	that has a name that might conflict with other ports (e.g.,
	<filename>Makefile</filename>), set
	<makevar>DIST_SUBDIR</makevar> to the name of the port
	(<literal>${PORTNAME}</literal> or
	<literal>${PKGNAMEPREFIX}${PORTNAME}</literal> should work
	fine). This will change <makevar>DISTDIR</makevar> from the
	default <filename>/usr/ports/distfiles</filename> to
	<filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>,
	and in effect puts everything that is required for your port
	into that subdirectory.</para>

	<para>It will also look at the subdirectory with the same name
	on the backup master site at
	<filename>ftp.FreeBSD.org</filename>. (Setting
	<makevar>DISTDIR</makevar> explicitly in your
	<makevar>Makefile</makevar> will not accomplish this, so
	please use <makevar>DIST_SUBDIR</makevar>.)</para>

	<note>
	<para>This does not affect the
	<makevar>MASTER_SITES</makevar> you define in your
	<filename>Makefile</filename>.</para>
	</note>
	</sect2>

	<sect2>
	<title><makevar>ALWAYS_KEEP_DISTFILES</makevar></title>

	<para>If your port uses binary distfiles and has a license
	that requires that the source code is provided with packages
	distributed in binary form, e.g., GPL,
	<makevar>ALWAYS_KEEP_DISTFILES</makevar> will instruct the
	&os; build cluster to keep a copy of the files specified in
	<makevar>DISTFILES</makevar>. Users of these ports will
	generally not need these files, so it is a good idea to only
	add the source distfiles to <makevar>DISTFILES</makevar>
	when <makevar>PACKAGE_BUILDING</makevar> is defined.</para>

	<example
	id="ports-master-sites-n-example-always-keep-distfiles">
	<title>Use of
	<makevar>ALWAYS_KEEP_DISTFILES</makevar></title>

	<programlisting>.if defined(PACKAGE_BUILDING)
	DISTFILES+= <replaceable>foo.tar.gz</replaceable>
	ALWAYS_KEEP_DISTFILES= yes
	.endif</programlisting>
	</example>

	<para>When adding extra files to <makevar>DISTFILES</makevar>,
	make sure you also add them to
	<filename>distinfo</filename>. Also, the additional files
	will normally be extracted into <makevar>WRKDIR</makevar> as
	well, which for some ports may lead to undesirable side
	effects and require special handling.</para>
	</sect2>
	</sect1>

	<sect1 id="makefile-maintainer">
	<title><makevar>MAINTAINER</makevar></title>

	<para>Set your mail-address here. Please. <!-- smiley
	--><emphasis>:-)</emphasis></para>

	<para>Note that only a single address without the comment part
	is allowed as a <makevar>MAINTAINER</makevar> value. The
	format used should be <literal>user@hostname.domain</literal>.
	Please do not include any descriptive text such as your real
	name in this entry—that merely confuses
	<filename>bsd.port.mk</filename>.</para>

	<para>The maintainer is responsible for keeping the port up to
	date, and ensuring the port works correctly.
	For a detailed description of the responsibilities of a port
	maintainer, refer to the <ulink
	url="&url.articles.contributing-ports;/maintain-port.html">The
	challenge for port maintainers</ulink> section.</para>

	<para>Changes to the port will be sent to the maintainer of a
	port for review and approval before being committed. If the
	maintainer does not respond to an update request after two
	weeks (excluding major public holidays), then that is
	considered a maintainer timeout, and the update may be made
	without explicit maintainer approval. If the maintainer does
	not respond within three months, then that maintainer is
	considered absent without leave, and can be replaced as the
	maintainer of the particular port in question. Exceptions to
	this are anything maintained by the &a.portmgr;, or the
	&a.security-officer;. No unauthorized commits may ever be
	made to ports maintained by those groups.</para>

	<para>We reserve the right to modify the maintainer's submission
	to better match existing policies and style of the Ports
	Collection without explicit blessing from the submitter.
	Also, large infrastructural changes can result in a port being
	modified without the maintainer's consent. These kinds of
	changes will never affect the port's functionality.</para>

	<para>The &a.portmgr; reserves the right to revoke or override
	anyone's maintainership for any reason, and the
	&a.security-officer; reserves the right to revoke or override
	maintainership for security reasons.</para>
	</sect1>

	<sect1 id="makefile-comment">
	<title><makevar>COMMENT</makevar></title>

	<para>This is a one-line description of the port.
	Please respect the following rules:</para>

	<orderedlist>
	<listitem>
	<para>Try to keep the COMMENT value at no longer than 70
	characters, as this line will be used by the
	&man.pkg.info.1; utility to display a one-line summary
	of the port;</para>
	</listitem>

	<listitem>
	<para>Do <emphasis>not</emphasis> include the package
	name (or version number of the software);</para>
	</listitem>

	<listitem>
	<para>The comment should begin with a capital and end
	without a period;</para>
	</listitem>

	<listitem>
	<para>Do not start with an indefinite article (i.e.,
	A or An);</para>
	</listitem>

	<listitem>
	<para>Names are capitalized (for example, Apache,
	JavaScript, Perl);</para>
	</listitem>

	<listitem>
	<para>For lists of words, use the Oxford comma (e.g.,
	green, red<emphasis>,</emphasis> and blue);</para>
	</listitem>

	<listitem>
	<para>Spell check the text.</para>
	</listitem>
	</orderedlist>

	<para>Here is an example:</para>

	<programlisting>COMMENT= Cat chasing a mouse all over the screen</programlisting>

	<para>The COMMENT variable should immediately follow the
	MAINTAINER variable in the
	<filename>Makefile</filename>.</para>
	</sect1>

	<sect1 id="makefile-portscout">
	<title><makevar>PORTSCOUT</makevar></title>

	<para><application>Portscout</application> is an automated
	distfile check utility for the &os; Ports Collection,
	described in detail in
	<xref linkend="distfile-survey"/>.</para>

	<para>The <makevar>PORTSCOUT</makevar> variable defines
	special conditions within which the
	<application>Portscout</application> distfile
	scanner should be restricted.</para>

	<para>Situations where the <makevar>PORTSCOUT</makevar>
	variable should be set include:</para>

	<itemizedlist>
	<listitem>
	<para>When distfiles should be ignored, whether for
	specific versions, or specific minor revisions. For
	example, to exclude version
	<replaceable>8.2</replaceable> from distfile version
	checks because it is known to be broken, add:</para>

	<programlisting>PORTSCOUT= ignore:8.2</programlisting>

	</listitem>
	<listitem>
	<para>When specific versions or specific major and minor
	revisions of a distfile should be checked. For
	example, if only version
	<replaceable>0.6.4</replaceable> should be monitored
	because newer versions have compatablity issues with
	&os;, add:</para>

	<programlisting>PORTSCOUT= limit:^0\.6\.4</programlisting>

	</listitem>
	<listitem>
	<para>When URLs listing the available versions differ
	from the download URLs. For example, to limit
	distfile version checks to the download page for the
	<filename role="package">databases/pgtune</filename>
	port, add:</para>

	<programlisting>PORTSCOUT= site:http://pgfoundry.org/frs/?group_id=1000416</programlisting>
	</listitem>
	</itemizedlist>
	</sect1>

	<sect1 id="makefile-depend">
	<title>Dependencies</title>

	<para>Many ports depend on other ports. This is a very
	convenient feature of most Unix-like operating systems,
	including &os;. Multiple ports can share a common dependency,
	rather than bundling that dependency with every port or
	package that needs it. There are seven variables that can be
	used to ensure that all the required bits will be on the
	user's machine. There are also some pre-supported dependency
	variables for common cases, plus a few more to control the
	behavior of dependencies.</para>

	<sect2>
	<title><makevar>LIB_DEPENDS</makevar></title>

	<para>This variable specifies the shared libraries this port
	depends on. It is a list of
	<replaceable>lib</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>
	tuples where <replaceable>lib</replaceable> is the name of
	the shared library, <replaceable>dir</replaceable> is the
	directory in which to find it in case it is not available,
	and <replaceable>target</replaceable> is the target to call
	in that directory. For example,</para>

	<programlisting>LIB_DEPENDS= jpeg:${PORTSDIR}/graphics/jpeg</programlisting>

	<para>will check for a shared jpeg library with any version,
	and descend into the
	<filename>graphics/jpeg</filename> subdirectory of your
	ports tree to build and install it if it is not found. The
	<replaceable>target</replaceable> part can be omitted if it
	is equal to <makevar>DEPENDS_TARGET</makevar> (which
	defaults to <literal>install</literal>).</para>

	<note>
	<para>The <replaceable>lib</replaceable> part is a regular
	expression which is being looked up in the
	<command>ldconfig -r</command> output. Values such as
	<literal>intl.9</literal> and
	<literal>intl.[5-7]</literal> are allowed. The first
	pattern, <literal>intl.9</literal>, will match only
	version 9 of intl, while <literal>intl.[5-7]</literal>,
	will match any of: <literal>intl.5</literal>,
	<literal>intl.6</literal> or
	<literal>intl.7</literal>.</para>
	</note>

	<para>The dependency is checked twice, once from within the
	<maketarget>extract</maketarget> target and then from within
	the <maketarget>install</maketarget> target. Also, the name
	of the dependency is put into the package so that
	&man.pkg.add.1; will automatically install it if it is not
	on the user's system.</para>
	</sect2>

	<sect2>
	<title><makevar>RUN_DEPENDS</makevar></title>

	<para>This variable specifies executables or files this port
	depends on during run-time. It is a list of
	<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>
	tuples where <replaceable>path</replaceable> is the name of
	the executable or file, <replaceable>dir</replaceable> is
	the directory in which to find it in case it is not
	available, and <replaceable>target</replaceable> is the
	target to call in that directory. If
	<replaceable>path</replaceable> starts with a slash
	(<literal>/</literal>), it is treated as a file and its
	existence is tested with <command>test -e</command>;
	otherwise, it is assumed to be an executable, and
	<command>which -s</command> is used to determine if the
	program exists in the search path.</para>

	<para>For example,</para>

	<programlisting>RUN_DEPENDS= ${LOCALBASE}/news/bin/innd:${PORTSDIR}/news/inn \
	xmlcatmgr:${PORTSDIR}/textproc/xmlcatmgr</programlisting>

	<para>will check if the file or directory
	<filename>/usr/local/news/bin/innd</filename> exists, and
	build and install it from the <filename>news/inn</filename>
	subdirectory of the ports tree if it is not found. It will
	also see if an executable called
	<command>xmlcatmgr</command> is in the search path, and
	descend into the <filename>textproc/xmlcatmgr</filename>
	subdirectory of your ports tree to build and install it if
	it is not found.</para>

	<note>
	<para>In this case, <command>innd</command> is actually an
	executable; if an executable is in a place that is not
	expected to be in the search path, you should use the full
	pathname.</para>
	</note>

	<note>
	<para>The official search <envar>PATH</envar> used on the
	ports build cluster is</para>

	<programlisting>/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin</programlisting>
	</note>

	<para>The dependency is checked from within the
	<maketarget>install</maketarget> target. Also, the name of
	the dependency is put into the package so that
	&man.pkg.add.1; will automatically install it if it is not
	on the user's system. The <replaceable>target</replaceable>
	part can be omitted if it is the same as
	<makevar>DEPENDS_TARGET</makevar>.</para>

	<para>A quite common situation is when
	<makevar>RUN_DEPENDS</makevar> is literally the same as
	<makevar>BUILD_DEPENDS</makevar>, especially if ported
	software is written in a scripted language or if it requires
	the same build and run-time environment. In this
	case, it is both tempting and intuitive to directly
	assign one to the other:</para>

	<programlisting>RUN_DEPENDS= ${BUILD_DEPENDS}</programlisting>

	<para>However, such assignment can pollute run-time
	dependencies with entries not defined in the port's original
	<makevar>BUILD_DEPENDS</makevar>. This happens because of
	&man.make.1;'s lazy evaluation of variable assignment.
	Consider a <filename>Makefile</filename> with
	<makevar>USE_<replaceable>*</replaceable></makevar>
	variables, which are processed by
	<filename>ports/Mk/bsd.*.mk</filename> to augment initial
	build dependencies. For example,
	<literal>USE_GMAKE=yes</literal> adds <filename
	role="package">devel/gmake</filename> to
	<makevar>BUILD_DEPENDS</makevar>. To prevent such
	additional dependencies from polluting
	<makevar>RUN_DEPENDS</makevar>, take care to assign with
	expansion, i.e., expand the value before assigning it to the
	variable:</para>

	<programlisting>RUN_DEPENDS:= ${BUILD_DEPENDS}</programlisting>
	</sect2>

	<sect2>
	<title><makevar>BUILD_DEPENDS</makevar></title>

	<para>This variable specifies executables or files this port
	requires to build. Like <makevar>RUN_DEPENDS</makevar>, it
	is a list of
	<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>
	tuples. For example,</para>

	<programlisting>BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>

	<para>will check for an executable called
	<command>unzip</command>, and descend into the
	<filename>archivers/unzip</filename> subdirectory of your
	ports tree to build and install it if it is not
	found.</para>

	<note>
	<para><quote>build</quote> here means everything from
	extraction to compilation. The dependency is checked from
	within the <maketarget>extract</maketarget> target. The
	<replaceable>target</replaceable> part can be omitted if
	it is the same as <makevar>DEPENDS_TARGET</makevar></para>
	</note>
	</sect2>

	<sect2>
	<title><makevar>FETCH_DEPENDS</makevar></title>

	<para>This variable specifies executables or files this port
	requires to fetch. Like the previous two, it is a list of
	<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>
	tuples. For example,</para>

	<programlisting>FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>

	<para>will check for an executable called
	<command>ncftp2</command>, and descend into the
	<filename>net/ncftp2</filename> subdirectory of your ports
	tree to build and install it if it is not found.</para>

	<para>The dependency is checked from within the
	<maketarget>fetch</maketarget> target. The
	<replaceable>target</replaceable> part can be omitted if it
	is the same as <makevar>DEPENDS_TARGET</makevar>.</para>
	</sect2>

	<sect2>
	<title><makevar>EXTRACT_DEPENDS</makevar></title>

	<para>This variable specifies executables or files this port
	requires for extraction. Like the previous, it is a list of
	<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>
	tuples. For example,</para>

	<programlisting>EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>

	<para>will check for an executable called
	<command>unzip</command>, and descend into the
	<filename>archivers/unzip</filename> subdirectory of your
	ports tree to build and install it if it is not
	found.</para>

	<para>The dependency is checked from within the
	<maketarget>extract</maketarget> target. The
	<replaceable>target</replaceable> part can be omitted if it
	is the same as <makevar>DEPENDS_TARGET</makevar>.</para>

	<note>
	<para>Use this variable only if the extraction does not
	already work (the default assumes <command>gzip</command>)
	and cannot be made to work using
	<makevar>USE_ZIP</makevar> or <makevar>USE_BZIP2</makevar>
	described in <xref linkend="use-vars"/>.</para>
	</note>
	</sect2>

	<sect2>
	<title><makevar>PATCH_DEPENDS</makevar></title>

	<para>This variable specifies executables or files this port
	requires to patch. Like the previous, it is a list of
	<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>
	tuples. For example,</para>

	<programlisting>PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract</programlisting>

	<para>will descend into the <filename>java/jfc</filename>
	subdirectory of your ports tree to extract it.</para>

	<para>The dependency is checked from within the
	<maketarget>patch</maketarget> target. The
	<replaceable>target</replaceable> part can be omitted if it
	is the same as <makevar>DEPENDS_TARGET</makevar>.</para>
	</sect2>

	+ <sect2 id="uses">
	+ <title><makevar>USES</makevar></title>
	+
	+ <para>There several parameters exist for defining different
	+ kind of features and dependencies that the port in question
	+ uses. They can be specified by adding the following line to
	+ the <filename>Makefile</filename> of the port:</para>
	+
	+ <programlisting>USES= feature[:arguments]</programlisting>
	+
	+ <para>For the complete list of such values, please see <xref
	+ linkend="uses-values"/>.</para>
	+
	+ <warning>
	+ <para><makevar>USES</makevar> cannot be assigned after
	+ inclusion of <filename>bsd.port.pre.mk</filename>.</para>
	+ </warning>
	+ </sect2>
	+
	<sect2 id="use-vars">
	<title><makevar>USE_<replaceable>*</replaceable></makevar></title>

	<para>Several variables exist to define
	common dependencies shared by many ports. Their
	use is optional, but helps to reduce the verbosity of
	the port <filename>Makefile</filename>s. Each of them is
	styled as
	<makevar>USE_<replaceable>*</replaceable></makevar>.
	These variables may be used only in the port
	<filename>Makefile</filename>s and
	<filename>ports/Mk/bsd.*.mk</filename>. They are not meant
	for user-settable options — use
	<makevar>PORT_OPTIONS</makevar> for that purpose.</para>

	<note>
	<para>It is <emphasis>always</emphasis> incorrect to set any
	<makevar>USE_<replaceable>*</replaceable></makevar> in
	<filename>/etc/make.conf</filename>. For instance,
	setting</para>

	<programlisting>USE_GCC=3.4</programlisting>

	<para>would add a dependency on gcc34 for every port,
	including gcc34 itself!</para>
	</note>

	<table frame="none">
	<title>The
	<makevar>USE_<replaceable>*</replaceable></makevar>
	Variables</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Means</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>USE_BZIP2</makevar></entry>
	<entry>The port's tarballs are compressed with
	<command>bzip2</command>.</entry>
	</row>

	<row>
	<entry><makevar>USE_ZIP</makevar></entry>
	<entry>The port's tarballs are compressed with
	<command>zip</command>.</entry>
	</row>

	<row>
	- <entry><makevar>USE_BISON</makevar></entry>
	- <entry>The port uses <command>bison</command> for
	- building.</entry>
	- </row>
	-
	- <row>
	<entry><makevar>USE_CDRTOOLS</makevar></entry>
	<entry>The port requires
	<application>cdrecord</application> either from
	<filename
	role="package">sysutils/cdrtools</filename> or
	<filename
	role="package">sysutils/cdrtools-cjk</filename>,
	according to the user's preference.</entry>
	</row>

	<row>
	<entry><makevar>USE_GCC</makevar></entry>
	<entry>The port requires a specific version of
	<command>gcc</command> to build. The exact version
	can be specified with value such as
	<literal>3.4</literal>. The minimal required
	version can be specified as <literal>3.4+</literal>.
	The <command>gcc</command> from the base system is
	used when it satisfies the requested version,
	otherwise an appropriate <command>gcc</command> is
	compiled from ports and the <makevar>CC</makevar>
	and <makevar>CXX</makevar> variables are
	adjusted.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>Variables related to <application>gmake</application>
	and the <filename>configure</filename> script are described
	in <xref linkend="building"/>, while
	<application>autoconf</application>,
	<application>automake</application> and
	<application>libtool</application> are described in
	<xref linkend="using-autotools"/>.
	<application>Perl</application> related variables are
	described in <xref linkend="using-perl"/>. X11 variables
	are listed in <xref linkend="using-x11"/>.
	<xref linkend="using-gnome"/> deals with GNOME and
	<xref linkend="using-kde"/> with KDE related variables.
	<xref linkend="using-java"/> documents Java variables, while
	<xref linkend="using-php"/> contains information on
	<application>Apache</application>,
	<application>PHP</application> and PEAR modules.
	<application>Python</application> is discussed in
	<xref linkend="using-python"/>, while
	<application>Ruby</application> in
	<xref linkend="using-ruby"/>. <xref linkend="using-sdl"/>
	provides variables used for <application>SDL</application>
	applications and finally, <xref linkend="using-xfce"/>
	contains information on
	<application>Xfce</application>.</para>
	</sect2>

	<sect2>
	<title>Minimal Version of a Dependency</title>

	<para>A minimal version of a dependency can be specified in
	any <makevar>*_DEPENDS</makevar> variable except
	<makevar>LIB_DEPENDS</makevar> using the following
	syntax:</para>

	<programlisting>p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy</programlisting>

	<para>The first field contains a dependent package name, which
	must match the entry in the package database, a comparison
	sign, and a package version. The dependency is satisfied if
	p5-Spiffy-0.26 or newer is installed on the machine.</para>
	</sect2>

	<sect2>
	<title>Notes on Dependencies</title>

	<para>As mentioned above, the default target to call when a
	dependency is required is
	<maketarget>DEPENDS_TARGET</maketarget>. It defaults to
	<literal>install</literal>. This is a user variable; it is
	never defined in a port's <filename>Makefile</filename>. If
	your port needs a special way to handle a dependency, use
	the <literal>:target</literal> part of the
	<makevar>*_DEPENDS</makevar> variables instead of redefining
	<makevar>DEPENDS_TARGET</makevar>.</para>

	<para>When you type <command>make clean</command>, its
	dependencies are automatically cleaned too. If you do not
	wish this to happen, define the variable
	<makevar>NOCLEANDEPENDS</makevar> in your environment. This
	may be particularly desirable if the port has something that
	takes a long time to rebuild in its dependency list, such as
	KDE, GNOME or Mozilla.</para>

	<para>To depend on another port unconditionally, use the
	variable <makevar>${NONEXISTENT}</makevar> as the first
	field of <makevar>BUILD_DEPENDS</makevar> or
	<makevar>RUN_DEPENDS</makevar>. Use this only when you need
	to get the source of the other port. You can often save
	compilation time by specifying the target too. For
	instance</para>

	<programlisting>BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting>

	<para>will always descend to the <literal>jpeg</literal> port
	and extract it.</para>
	</sect2>

	<sect2>
	<title>Circular Dependencies Are Fatal</title>

	<important>
	<para>Do not introduce any circular dependencies into the
	ports tree!</para>
	</important>

	<para>The ports building technology does not tolerate circular
	dependencies. If you introduce one, you will have someone,
	somewhere in the world, whose FreeBSD installation will
	break almost immediately, with many others quickly to
	follow. These can really be hard to detect; if in doubt,
	before you make that change, make sure you have done the
	following: <command>cd /usr/ports; make index</command>.
	That process can be quite slow on older machines, but you
	may be able to save a large number of people—including
	yourself— a lot of grief in the process.</para>
	</sect2>

	<sect2>
	<title>Problems Caused by Automatic Dependencies</title>

	<para>Dependencies must be declared either explicitly or by
	using the <link
	linkend="makefile-options">OPTIONS framework</link>.
	Using other methods like automatic detection complicates
	indexing, which causes problems for port and package
	management.</para>

	<example>
	<title>Wrong Declaration of an Optional Dependency</title>

	<programlisting>.include <bsd.port.pre.mk>

	.if exists(${LOCALBASE}/bin/foo)
	LIB_DEPENDS= bar:${PORTSDIR}/foo/bar
	.endif</programlisting>
	</example>

	<para>The problem with trying to automatically add
	dependencies is that files and settings outside an
	individual port can change at any time. For example: an
	index is built, then a batch of ports are installed. But
	one of the ports installs the tested file. The index is now
	incorrect, because an installed port unexpectedly has a new
	dependency. The index may still be wrong even after
	rebuilding if other ports also determine their need for
	dependencies based on the existence of other files.</para>

	<example>
	<title>Correct Declaration of an Optional Dependency</title>

	<programlisting>OPTIONS_DEFINE= BAR
	BAR_DESC= Bar support

	.include <bsd.port.options.mk>

	.if ${PORT_OPTIONS:MBAR}
	LIB_DEPENDS= bar:${PORTSDIR}/foo/bar
	.endif</programlisting>
	</example>

	<para>Testing option variables is the correct method. It will
	not cause inconsistencies in the index of a batch of ports,
	provided the options were defined prior to the index build.
	Simple scripts can then be used to automate the building,
	installation, and updating of these ports and their
	packages.</para>
	</sect2>

	<sect2 id="use-want">
	<title><makevar>USE_</makevar> and
	<makevar>WANT_</makevar></title>

	<para><makevar>USE_</makevar> variables are set by the port
	maintainer to define software on which this port depends. A
	port that needs Firefox would set</para>

	<programlisting>USE_FIREFOX= yes</programlisting>

	<para>Some <makevar>USE_</makevar> variables can accept
	version numbers or other parameters. For example, a port
	that requires Apache 2.2 would set</para>

	<programlisting>USE_APACHE= 22</programlisting>

	<para>For more control over dependencies in some cases,
	<makevar>WANT_</makevar> variables are available to more
	precisely specify what is needed. For example, consider the
	<filename role="package">mail/squirrelmail</filename> port.
	This port needs some PHP modules, which are listed in the
	<makevar>USE_PHP</makevar> variable:</para>

	<programlisting>USE_PHP= session mhash gettext mbstring pcre openssl xml</programlisting>

	<para>Those modules may be available in CLI or web versions,
	so the web version is selected with a
	<makevar>WANT_</makevar> variable:</para>

	<programlisting>WANT_PHP_WEB= yes</programlisting>

	<para>Available <makevar>USE_</makevar> and
	<makevar>WANT_</makevar> variables are defined in the files
	in <filename>/usr/ports/Mk</filename>.</para>
	</sect2>
	</sect1>

	<sect1 id="makefile-masterdir">
	<title><makevar>MASTERDIR</makevar></title>

	<para>If your port needs to build slightly different versions of
	packages by having a variable (for instance, resolution, or
	paper size) take different values, create one subdirectory per
	package to make it easier for users to see what to do, but try
	to share as many files as possible between ports. Typically
	you only need a very short <filename>Makefile</filename> in
	all but one of the directories if you use variables cleverly.
	In the sole <filename>Makefile</filename>, you can use
	<makevar>MASTERDIR</makevar> to specify the directory where
	the rest of the files are. Also, use a variable as part of
	<link
	linkend="porting-pkgname"><makevar>PKGNAMESUFFIX</makevar></link>
	so the packages will have different names.</para>

	<para>This will be best demonstrated by an example. This is
	part of <filename>japanese/xdvi300/Makefile</filename>;</para>

	<programlisting>PORTNAME= xdvi
	PORTVERSION= 17
	PKGNAMEPREFIX= ja-
	PKGNAMESUFFIX= ${RESOLUTION}
	:
	# default
	RESOLUTION?= 300
	-.if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \
	- ${RESOLUTION} != 300 && ${RESOLUTION} != 400
	+.if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \
	+ ${RESOLUTION} != 300 && ${RESOLUTION} != 400
	@${ECHO_MSG} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\""
	@${ECHO_MSG} "Possible values are: 118, 240, 300 (default) and 400."
	@${FALSE}
	.endif</programlisting>

	<para><filename role="package">japanese/xdvi300</filename> also
	has all the regular patches, package files, etc. If you type
	<command>make</command> there, it will take the default value
	for the resolution (300) and build the port normally.</para>

	<para>As for other resolutions, this is the
	<emphasis>entire</emphasis>
	<filename>xdvi118/Makefile</filename>:</para>

	<programlisting>RESOLUTION= 118
	MASTERDIR= ${.CURDIR}/../xdvi300

	.include "${MASTERDIR}/Makefile"</programlisting>

	<para>(<filename>xdvi240/Makefile</filename> and
	<filename>xdvi400/Makefile</filename> are similar). The
	<makevar>MASTERDIR</makevar> definition tells
	<filename>bsd.port.mk</filename> that the regular set of
	subdirectories like <makevar>FILESDIR</makevar> and
	<makevar>SCRIPTDIR</makevar> are to be found under
	<filename>xdvi300</filename>. The
	<literal>RESOLUTION=118</literal> line will override the
	<literal>RESOLUTION=300</literal> line in
	<filename>xdvi300/Makefile</filename> and the port will be
	built with resolution set to 118.</para>
	</sect1>

	<sect1 id="makefile-manpages">
	<title>Man Pages</title>

	<para>The <makevar>MAN[1-9LN]</makevar> variables will
	automatically add any manpages to
	<filename>pkg-plist</filename> (this means you must
	<emphasis>not</emphasis> list manpages in the
	<filename>pkg-plist</filename>—see <link
	linkend="plist-sub">generating PLIST</link> for more). It
	also makes the install stage automatically compress or
	uncompress manpages depending on the setting of
	<makevar>NO_MANCOMPRESS</makevar> in
	<filename>/etc/make.conf</filename>.</para>

	<para>If your port tries to install multiple names for manpages
	using symlinks or hardlinks, you must use the
	<makevar>MLINKS</makevar> variable to identify these. The
	link installed by your port will be destroyed and recreated by
	<filename>bsd.port.mk</filename> to make sure it points to the
	correct file. Any manpages listed in MLINKS must not be
	listed in the <filename>pkg-plist</filename>.</para>

	<para>To specify whether the manpages are compressed upon
	installation, use the <makevar>MANCOMPRESSED</makevar>
	variable. This variable can take three values,
	<literal>yes</literal>, <literal>no</literal> and
	<literal>maybe</literal>. <literal>yes</literal> means
	manpages are already installed compressed,
	<literal>no</literal> means they are not, and
	<literal>maybe</literal> means the software already respects
	the value of <makevar>NO_MANCOMPRESS</makevar> so
	<filename>bsd.port.mk</filename> does not have to do anything
	special.</para>

	<para><makevar>MANCOMPRESSED</makevar> is automatically set to
	<literal>yes</literal> if <makevar>USE_IMAKE</makevar> is set
	and <makevar>NO_INSTALL_MANPAGES</makevar> is not set, and to
	<literal>no</literal> otherwise. You do not have to
	explicitly define it unless the default is not suitable for
	your port.</para>

	<para>If your port anchors its man tree somewhere other than
	<makevar>PREFIX</makevar>, you can use the
	<makevar>MANPREFIX</makevar> to set it. Also, if only
	manpages in certain sections go in a non-standard place, such
	as some <literal>perl</literal> modules ports, you can set
	individual man paths using
	<makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar>
	(where <replaceable>sect</replaceable> is one of
	<literal>1-9</literal>, <literal>L</literal> or
	<literal>N</literal>).</para>

	<para>If your manpages go to language-specific subdirectories,
	set the name of the languages to <makevar>MANLANG</makevar>.
	The value of this variable defaults to <literal>""</literal>
	(i.e., English only).</para>

	<para>Here is an example that puts it all together.</para>

	<programlisting>MAN1= foo.1
	MAN3= bar.3
	MAN4= baz.4
	MLINKS= foo.1 alt-name.8
	MANLANG= "" ja
	MAN3PREFIX= ${PREFIX}/share/foobar
	MANCOMPRESSED= yes</programlisting>

	<para>This states that six files are installed by this
	port;</para>

	<programlisting>${MANPREFIX}/man/man1/foo.1.gz
	${MANPREFIX}/man/ja/man1/foo.1.gz
	${PREFIX}/share/foobar/man/man3/bar.3.gz
	${PREFIX}/share/foobar/man/ja/man3/bar.3.gz
	${MANPREFIX}/man/man4/baz.4.gz
	${MANPREFIX}/man/ja/man4/baz.4.gz</programlisting>

	<para>Additionally
	<filename>${MANPREFIX}/man/man8/alt-name.8.gz</filename> may
	or may not be installed by your port. Regardless, a symlink
	will be made to join the foo(1) manpage and alt-name(8)
	manpage.</para>

	<para>If only some manpages are translated, you can use several
	variables dynamically created from <makevar>MANLANG</makevar>
	content:</para>

	<programlisting>MANLANG= "" de ja
	MAN1= foo.1
	MAN1_EN= bar.1
	MAN3_DE= baz.3</programlisting>

	<para>This translates into this list of files:</para>

	<programlisting>${MANPREFIX}/man/man1/foo.1.gz
	${MANPREFIX}/man/de/man1/foo.1.gz
	${MANPREFIX}/man/ja/man1/foo.1.gz
	${MANPREFIX}/man/man1/bar.1.gz
	${MANPREFIX}/man/de/man3/baz.3.gz</programlisting>
	</sect1>

	<sect1 id="makefile-info">
	<title>Info Files</title>

	<para>If your package needs to install GNU info files, they
	should be listed in the <makevar>INFO</makevar> variable
	(without the trailing <literal>.info</literal>), one entry per
	document. These files are assumed to be installed to
	<filename><makevar>PREFIX</makevar>/<makevar>INFO_PATH</makevar></filename>.
	You can change <makevar>INFO_PATH</makevar> if your package
	uses a different location. However, this is not recommended.
	These entries contain just the path relative to
	<filename><makevar>PREFIX</makevar>/<makevar>INFO_PATH</makevar></filename>.
	For example, <filename role="package">lang/gcc34</filename>
	installs info files to
	<filename><makevar>PREFIX</makevar>/<makevar>INFO_PATH</makevar>/gcc34</filename>,
	and <makevar>INFO</makevar> will be something like
	this:</para>

	<programlisting>INFO= gcc34/cpp gcc34/cppinternals gcc34/g77 ...</programlisting>

	<para>Appropriate installation/de-installation code will be
	automatically added to the temporary
	<filename>pkg-plist</filename> before package
	registration.</para>
	</sect1>

	<sect1 id="makefile-options">
	<title>Makefile Options</title>

	<para>Many applications can be built with optional or differing
	configurations. Examples include choice of natural (human)
	language, GUI versus command-line, or type of database to
	support. Users may need a different configuration than the
	default, so the ports system provides hooks the port author
	can use to control which variant will be built. Supporting
	these options properly will make users happy, and effectively
	provide two or more ports for the price of one.</para>

	<sect2>
	<title>Knobs</title>

	<sect3>
	<title><makevar>WITH_<replaceable>*</replaceable></makevar>
	and
	<makevar>WITHOUT_<replaceable>*</replaceable></makevar></title>

	<para>These variables are designed to be set by the system
	administrator. There are many that are standardized in
	the <ulink
	url="http://svn.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>ports/KNOBS</filename></ulink>
	file.</para>

	<para>When creating a port, do not make knob names specific
	to a given application. For example in Avahi port, use
	<makevar>WITHOUT_MDNS</makevar> instead of
	<makevar>WITHOUT_AVAHI_MDNS</makevar>.</para>

	<note>
	<para>You should not assume that a
	<makevar>WITH_<replaceable>*</replaceable></makevar>
	necessarily has a corresponding
	<makevar>WITHOUT_<replaceable>*</replaceable></makevar>
	variable and vice versa. In general, the default is
	simply assumed.</para>
	</note>

	<note>
	<para>Unless otherwise specified, these variables are only
	tested for being set or not set, rather than being set
	to a specific value such as <literal>YES</literal>
	or <literal>NO</literal>.</para>
	</note>

	<table frame="none">
	<title>Common
	<makevar>WITH_<replaceable>*</replaceable></makevar> and
	<makevar>WITHOUT_<replaceable>*</replaceable></makevar>
	Variables</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Means</entry>
	</row>
	</thead>

	<tbody>
	<row id="knobs-without-nls">
	<entry><makevar>WITHOUT_NLS</makevar></entry>
	<entry>If set, says that internationalization is not
	needed, which can save compile time. By default,
	internationalization is used.</entry>
	</row>

	<row>
	<entry><makevar>WITH_OPENSSL_BASE</makevar></entry>
	<entry>Use the version of OpenSSL in the base
	system.</entry>
	</row>

	<row>
	<entry><makevar>WITH_OPENSSL_PORT</makevar></entry>
	<entry>Installs the version of OpenSSL from
	<filename
	role="package">security/openssl</filename>, even
	if the base is up to date.</entry>
	</row>

	<row>
	<entry><makevar>WITHOUT_X11</makevar></entry>
	<entry>Ports that can be built both with and
	without X support are normally
	built with X support. If this variable is
	defined, then the version that does not have X
	support will be built instead.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect3>

	<sect3>
	<title>Knob Naming</title>

	<para>Porters should use like-named knobs, both
	for the benefit of end-users and to help keep the number
	of knob names down. A list of popular knob names can be
	found in the <ulink
	url="http://svn.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>KNOBS</filename></ulink>
	file.</para>

	<para>Knob names should reflect what the knob is and does.
	When a port has a lib-prefix in the
	<makevar>PORTNAME</makevar> the lib-prefix should be
	dropped in knob naming.</para>
	</sect3>
	</sect2>

	<sect2>
	<title><makevar>OPTIONS</makevar></title>

	<sect3>
	<title>Background</title>

	<para>The <makevar>OPTIONS_*</makevar> variables give the
	user installing the port a dialog showing the available
	options, and then saves those options to
	<filename>/var/db/ports/<makevar>${UNIQUENAME}</makevar>/options</filename>.
	The next time the port is built, the options are
	reused.</para>

	<para>When the user runs <command>make config</command> (or
	runs <command>make build</command> for the first time),
	the framework checks for
	<filename>/var/db/ports/<makevar>${UNIQUENAME}</makevar>/options</filename>.
	If that file does not exist, the values of
	<makevar>OPTIONS_*</makevar> are used, and a dialog box is
	displayed where the options can be enabled or disabled.
	Then the <filename>options</filename> file is saved and
	the configured variables are used when building the
	port.</para>

	<para>If a new version of the port adds new
	<makevar>OPTIONS</makevar>, the dialog will be presented
	to the user with the saved values of old
	<makevar>OPTIONS</makevar> prefilled.</para>

	<para><command>make showconfig</command> shows the
	saved configuration. Use <command>make rmconfig</command>
	to remove the saved configuration.</para>
	</sect3>

	<sect3>
	<title>Syntax</title>

	<para><makevar>OPTIONS_DEFINE</makevar> contains a list of
	<makevar>OPTIONS</makevar> to be used. These are
	independent of each other and are not grouped:</para>

	<programlisting>OPTIONS_DEFINE= OPT1 OPT2</programlisting>

	<para>Once defined, <makevar>OPTIONS</makevar> are
	described (optional, but strongly recommended):</para>

	<programlisting>OPT1_DESC= Describe OPT1
	OPT2_DESC= Describe OPT2
	OPT3_DESC= Describe OPT3
	OPT4_DESC= Describe OPT4
	OPT5_DESC= Describe OPT5
	OPT6_DESC= Describe OPT6</programlisting>

	<tip>
	<para><filename>ports/Mk/bsd.options.desc.mk</filename>
	has descriptions for many common
	<makevar>OPTIONS</makevar>; there is usually no need
	to override these.</para>
	</tip>

	<tip>
	<para>When describing options, view it from the
	perspective of the user: <quote>What does it do?</quote>
	and <quote>Why would I want to enable this?</quote> Do
	not just repeat the name. For example, describing the
	<literal>NLS</literal> option as
	<quote>include NLS support</quote> does not help the
	user, who can already see the option name but may not
	know what it means. Describing it as <quote>Native
	Language Support via gettext utilities</quote> is
	much more helpful.</para>
	</tip>

	<para><makevar>OPTIONS</makevar> can be grouped as radio
	choices, where only one choice from each group is
	allowed:</para>

	<programlisting>OPTIONS_SINGLE= SG1
	OPTIONS_SINGLE_SG1= OPT3 OPT4</programlisting>

	<para><makevar>OPTIONS</makevar> can be grouped as radio
	choices, where none or only one choice from each group
	is allowed:</para>

	- <programlisting>OPTIONS_RADIO= RG1
	+ <programlisting>OPTIONS_RADIO= RG1
	OPTIONS_RADIO_RG1= OPT7 OPT8</programlisting>

	<para><makevar>OPTIONS</makevar> can also be grouped as
	<quote>multiple-choice</quote> lists, where
	<emphasis>at least one</emphasis> option must be
	enabled:</para>

	<programlisting>OPTIONS_MULTI= MG1
	OPTIONS_MULTI_MG1= OPT5 OPT6</programlisting>

	<para><makevar>OPTIONS</makevar> can also be grouped as
	<quote>multiple-choice</quote> lists, where none or any
	option can be enabled:</para>

	<programlisting>OPTIONS_GROUP= GG1
	OPTIONS_GROUP_GG1= OPT9 OPT10</programlisting>

	<para><makevar>OPTIONS</makevar> are unset by default,
	unless they are listed in
	<makevar>OPTIONS_DEFAULT</makevar>:</para>

	<programlisting>OPTIONS_DEFAULT= OPT1 OPT3 OPT6</programlisting>

	<para><makevar>OPTIONS</makevar> definitions must appear
	before the inclusion of
	<filename>bsd.port.options.mk</filename>. The
	<makevar>PORT_OPTIONS</makevar> variable can only be
	tested after the inclusion of
	<filename>bsd.port.options.mk</filename>. Inclusion of
	<filename>bsd.port.pre.mk</filename> can be used instead,
	too, and is still widely used in ports written before the
	introduction of <filename>bsd.port.options.mk</filename>.
	But be aware that some variables will not work as expected
	after the inclusion of
	<filename>bsd.port.pre.mk</filename>, typically some
	<makevar>USE_*</makevar> flags.</para>

	<example id="ports-options-simple-use">
	<title>Simple Use of <makevar>OPTIONS</makevar></title>

	<programlisting>OPTIONS_DEFINE= FOO BAR
	FOO_DESC= Enable option foo
	BAR_DESC= Support feature bar

	OPTIONS_DEFAULT=FOO

	.include <bsd.port.options.mk>

	.if ${PORT_OPTIONS:MFOO}
	CONFIGURE_ARGS+=--with-foo
	.else
	CONFIGURE_ARGS+=--without-foo
	.endif

	.if ${PORT_OPTIONS:MBAR}
	RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar
	.endif

	.include <bsd.port.mk></programlisting>
	</example>

	<example id ="ports-options-check-unset">
	- <title>Check for Unset Port <makevar>OPTIONS</makevar></title>
	+ <title>Check for Unset Port
	+ <makevar>OPTIONS</makevar></title>
	+
	<programlisting>.if ! ${PORT_OPTIONS:MEXAMPLES}
	CONFIGURE_ARGS+=--without-examples
	.endif</programlisting>
	</example>

	<example id="ports-options-practical-use">
	<title>Practical Use of <makevar>OPTIONS</makevar></title>

	<programlisting>OPTIONS_DEFINE= EXAMPLES

	OPTIONS_SINGLE= BACKEND
	OPTIONS_SINGLE_BACKEND= MYSQL PGSQL BDB

	OPTIONS_MULTI= AUTH
	OPTIONS_MULTI_AUTH= LDAP PAM SSL

	EXAMPLES_DESC= Install extra examples
	MYSQL_DESC= Use MySQL as backend
	PGSQL_DESC= Use PostgreSQL as backend
	BDB_DESC= Use Berkeley DB as backend
	LDAP_DESC= Build with LDAP authentication support
	PAM_DESC= Build with PAM support
	SSL_DESC= Build with OpenSSL support

	OPTIONS_DEFAULT= PGSQL LDAP SSL

	.include <bsd.port.options.mk>

	.if ${PORT_OPTIONS:MPGSQL}
	USE_PGSQL= yes
	CONFIGURE_ARGS+= --with-postgres
	.else
	CONFIGURE_ARGS+= --without-postgres
	.endif

	.if ${PORT_OPTIONS:MICU}
	LIB_DEPENDS+= icuuc:${PORTSDIR}/devel/icu
	.endif

	.if ! ${PORT_OPTIONS:MEXAMPLES}
	CONFIGURE_ARGS+= --without-examples
	.endif

	# Check other OPTIONS

	.include <bsd.port.mk></programlisting>
	</example>

	- <example id="ports-options-old-style-use">
	- <title>Old-Style Use of <makevar>OPTIONS</makevar></title>
	-
	- <programlisting>OPTIONS= FOO "Enable option foo" On
	-
	-.include <bsd.port.pre.mk>
	-
	-.if defined(WITHOUT_FOO)
	-CONFIGURE_ARGS+= --without-foo
	-.else
	-CONFIGURE_ARGS+= --with-foo
	-.endif
	-
	-.include <bsd.port.post.mk></programlisting>
	- </example>
	-
	- <important>
	- <para>This method of using <makevar>OPTIONS</makevar>
	- is deprecated, and will be removed at some point.
	- Do not use this method for new ports.</para>
	- </important>
	</sect3>

	<sect3>
	<title>Default Options</title>
	- <para>The following options are always on by default.</para>
	- <itemizedlist>
	+
	+ <para>The following options are always on by default.</para>
	+
	+ <itemizedlist>
	<listitem>
	<para><literal>DOCS</literal> — build and install
	documentation.</para>
	</listitem>
	+
	<listitem>
	<para><literal>NLS</literal> — Native Language
	Support.</para>
	- </listitem>
	+ </listitem>
	+
	<listitem>
	- <para><literal>EXAMPLES</literal> — build and install
	- examples.</para>
	+ <para><literal>EXAMPLES</literal> — build and
	+ install examples.</para>
	</listitem>
	+
	<listitem>
	- <para><literal>IPV6</literal> — IPv6 protocol support.</para>
	+ <para><literal>IPV6</literal> — IPv6 protocol
	+ support.</para>
	</listitem>
	</itemizedlist>
	+
	<note>
	<para>There is no need to add these to
	- <makevar>OPTIONS_DEFAULT</makevar>. To have them show up
	- in the options selection dialog, however, they must be added
	- to <makevar>OPTIONS_DEFINE</makevar>.</para>
	- </note>
	+ <makevar>OPTIONS_DEFAULT</makevar>. To have them show
	+ up in the options selection dialog, however, they must
	+ be added to <makevar>OPTIONS_DEFINE</makevar>.</para>
	+ </note>
	</sect3>
	</sect2>

	<sect2>
	<title>Feature Auto-Activation</title>

	<para>When using a GNU configure script, keep an eye on which
	optional features are activated by auto-detection.
	Explicitly disable optional features you do not wish to be
	used by passing respective <literal>--without-xxx</literal>
	or <literal>--disable-xxx</literal> in
	<makevar>CONFIGURE_ARGS</makevar>.</para>

	<example>
	<title>Wrong Handling of an Option</title>

	<programlisting>.if ${PORT_OPTIONS:MFOO}
	LIB_DEPENDS+= foo:${PORTSDIR}/devel/foo
	CONFIGURE_ARGS+= --enable-foo
	.endif</programlisting>
	</example>

	<para>In the example above, imagine a library libfoo is
	installed on the system. The user does not want this
	application to use libfoo, so he toggled the option off in
	the <literal>make config</literal> dialog. But the
	application's configure script detects the library present
	in the system and includes its support in the resulting
	executable. Now when the user decides to remove libfoo from
	the system, the ports system does not protest (no dependency
	on libfoo was recorded) but the application breaks.</para>

	<example>
	<title>Correct Handling of an Option</title>

	<programlisting>.if ${PORT_OPTIONS:MFOO}
	LIB_DEPENDS+= foo:${PORTSDIR}/devel/foo
	CONFIGURE_ARGS+= --enable-foo
	.else
	CONFIGURE_ARGS+= --disable-foo
	.endif</programlisting>
	</example>

	<para>In the second example, the library libfoo is explicitly
	disabled. The configure script does not enable related
	features in the application, despite library's presence in
	the system.</para>

	<note>
	<para>Under some circumstances, the shorthand conditional
	syntax can cause problems with complex constructs.
	If you receive errors such as <literal>Malformed
	conditional</literal>, an alternative syntax can be
	used.</para>
	<programlisting>.if !empty(VARIABLE:MVALUE)
	# as an alternative to
	.if ${VARIABLE:MVALUE}</programlisting>
	</note>
	</sect2>
	</sect1>

	<sect1 id="makefile-wrkdir">
	<title>Specifying the Working Directory</title>

	<para>Each port is extracted in to a working directory, which
	must be writable. The ports system defaults to having the
	<makevar>DISTFILES</makevar> unpack in to a directory called
	<literal>${DISTNAME}</literal>. In other words, if you have
	set:</para>

	<programlisting>PORTNAME= foo
	PORTVERSION= 1.0</programlisting>

	<para>then the port's distribution files contain a top-level
	directory, <filename>foo-1.0</filename>, and the rest of the
	files are located under that directory.</para>

	<para>There are a number of variables you can override if that
	is not the case.</para>

	<sect2>
	<title><makevar>WRKSRC</makevar></title>

	<para>The variable lists the name of the directory that is
	created when the application's distfiles are extracted. If
	our previous example extracted into a directory called
	<filename>foo</filename> (and not
	<filename>foo-1.0</filename>) you would write:</para>

	<programlisting>WRKSRC= ${WRKDIR}/foo</programlisting>

	<para>or possibly</para>

	<programlisting>WRKSRC= ${WRKDIR}/${PORTNAME}</programlisting>
	</sect2>

	<sect2>
	<title><makevar>NO_WRKSUBDIR</makevar></title>

	<para>If the port does not extract in to a subdirectory at all
	then you should set <makevar>NO_WRKSUBDIR</makevar> to
	indicate that.</para>

	<programlisting>NO_WRKSUBDIR= yes</programlisting>
	</sect2>
	</sect1>

	<sect1 id="conflicts">
	<title>Conflict Handling</title>

	<para>There are three different variables to register a conflict
	between packages and ports: <makevar>CONFLICTS</makevar>,
	<makevar>CONFLICTS_INSTALL</makevar> and
	<makevar>CONFLICTS_BUILD</makevar>.</para>

	<note>
	<para>The conflict variables automatically set the variable
	<makevar>IGNORE</makevar>, which is more fully documented
	in <xref linkend="dads-noinstall"/>.</para>
	</note>

	<para>When removing one of several conflicting ports, it is
	advisable to retain the <makevar>CONFLICTS</makevar> entries
	in those other ports for a few months to cater for users who
	only update once in a while.</para>

	<sect2>
	<title><makevar>CONFLICTS_INSTALL</makevar></title>

	<para>If your package cannot coexist with other packages
	(because of file conflicts, runtime incompatibilities,
	etc.), list the other package names in the
	<makevar>CONFLICTS_INSTALL</makevar> variable. You can use
	shell globs like <literal>*</literal> and
	<literal>?</literal> here. Package names should be
	enumerated the same way they appear in
	<filename>/var/db/pkg</filename>. Please make sure that
	<makevar>CONFLICTS_INSTALL</makevar> does not match this
	port's package itself. Otherwise enforcing its installation
	with <makevar>FORCE_PKG_REGISTER</makevar> will no longer
	work. The CONFLICTS_INSTALL check is done after the build
	stage and prior to the install stage.</para>
	</sect2>

	<sect2>
	<title><makevar>CONFLICTS_BUILD</makevar></title>

	<para>If your port cannot be built if a certain port is
	already installed, list the other port names in the
	<makevar>CONFLICTS_BUILD</makevar> variable. You can use
	shell globs like <literal>*</literal> and
	<literal>?</literal> here. Package names should be
	enumerated the same way they appear in
	<filename>/var/db/pkg</filename>. The CONFLICTS_BUILD check
	is done prior to the build stage. Build conflicts are not
	recorded in the resulting package.</para>
	</sect2>

	<sect2>
	<title><makevar>CONFLICTS</makevar></title>

	<para>If your port cannot be built if a certain port is
	already installed and the resulting package cannot coexist
	with the other package, list the other package name in the
	<makevar>CONFLICTS</makevar> variable. You can use shell
	globs like <literal>*</literal> and <literal>?</literal>
	here. Packages names should be enumerated the same way they
	appear in <filename>/var/db/pkg</filename>. Please make
	sure that <makevar>CONFLICTS_INSTALL</makevar> does not
	match this port's package itself. Otherwise enforcing its
	installation with <makevar>FORCE_PKG_REGISTER</makevar> will
	no longer work. The CONFLICTS check is done prior to the
	build stage and prior to the install stage.</para>
	</sect2>
	</sect1>

	<sect1 id="install">
	<title>Installing Files</title>

	<sect2 id="install-macros">
	<title><makevar>INSTALL_*</makevar> Macros</title>

	<para>Do use the macros provided in
	<filename>bsd.port.mk</filename> to ensure correct modes and
	ownership of files in your own
	<maketarget>*-install</maketarget> targets.</para>

	<itemizedlist>
	<listitem>

	<para><makevar>INSTALL_PROGRAM</makevar> is a command to
	install binary executables.</para>
	</listitem>

	<listitem>
	<para><makevar>INSTALL_SCRIPT</makevar> is a command to
	install executable scripts.</para>
	</listitem>

	<listitem>
	<para><makevar>INSTALL_LIB</makevar> is a command to
	install shared libraries.</para>
	</listitem>

	<listitem>
	<para><makevar>INSTALL_KLD</makevar> is a command to
	install kernel loadable modules. Some architectures
	do not like having the modules stripped, so
	use this command instead of
	<makevar>INSTALL_PROGRAM</makevar>.</para>
	</listitem>

	<listitem>
	<para><makevar>INSTALL_DATA</makevar> is a command to
	install sharable data.</para>
	</listitem>

	<listitem>
	<para><makevar>INSTALL_MAN</makevar> is a command to
	install manpages and other documentation (it does not
	compress anything).</para>
	</listitem>
	</itemizedlist>

	<para>These are basically the <command>install</command>
	command with all the appropriate flags.</para>
	</sect2>

	<sect2 id="install-strip">
	<title>Stripping Binaries and Shared Libraries</title>

	<para>Do not strip binaries manually unless you have to. All
	binaries should be stripped, but the
	<makevar>INSTALL_PROGRAM</makevar> macro will install and
	strip a binary at the same time (see the next section). The
	<makevar>INSTALL_LIB</makevar> macro does the same thing to
	shared libraries.</para>

	<para>If you need to strip a file, but wish to use neither
	<makevar>INSTALL_PROGRAM</makevar> nor
	<makevar>INSTALL_LIB</makevar> macros,
	<makevar>${STRIP_CMD}</makevar> will strip your program or
	shared library. This is typically done within the
	<maketarget>post-install</maketarget> target. For
	example:</para>

	<programlisting>post-install:
	${STRIP_CMD} ${PREFIX}/bin/xdl</programlisting>

	<para>Use the &man.file.1; command on the installed executable
	to check whether the binary is stripped or not. If it does
	not say <literal>not stripped</literal>, it is stripped.
	Additionally, &man.strip.1; will not strip a previously
	stripped program; it will instead exit cleanly.</para>
	</sect2>

	<sect2 id="install-copytree">
	<title>Installing a Whole Tree of Files</title>

	<para>Sometimes, there is a need to install a big number of
	files, preserving their hierarchical organization, i.e.,
	copying over a whole directory tree from
	<makevar>WRKSRC</makevar> to a target directory under
	<makevar>PREFIX</makevar>.</para>

	<para>Two macros exist for this situation. The advantage of
	using these macros instead of <command>cp</command> is that
	they guarantee proper file ownership and permissions on
	target files. The first macro,
	<makevar>COPYTREE_BIN</makevar>, will set all the installed
	files to be executable, thus being suitable for installing
	into <filename><makevar>PREFIX</makevar>/bin</filename>.
	The second macro, <makevar>COPYTREE_SHARE</makevar>, does
	not set executable permissions on files, and is therefore
	suitable for installing files under
	<filename><makevar>PREFIX</makevar>/share</filename>
	target.</para>

	<programlisting>post-install:
	${MKDIR} ${EXAMPLESDIR}
	- (cd ${WRKSRC}/examples/ && ${COPYTREE_SHARE} \* ${EXAMPLESDIR})</programlisting>
	+ (cd ${WRKSRC}/examples && ${COPYTREE_SHARE} . ${EXAMPLESDIR})</programlisting>

	<para>This example will install the contents of
	<filename>examples</filename> directory in the vendor
	distfile to the proper examples location of your
	port.</para>

	<programlisting>post-install:
	${MKDIR} ${DATADIR}/summer
	- (cd ${WRKSRC}/temperatures/ && ${COPYTREE_SHARE} "June July August" ${DATADIR}/summer/)</programlisting>
	+ (cd ${WRKSRC}/temperatures && ${COPYTREE_SHARE} "June July August" ${DATADIR}/summer)</programlisting>

	<para>And this example will install the data of summer months
	to the <filename>summer</filename> subdirectory of a
	<filename><makevar>DATADIR</makevar></filename>.</para>

	<para>Additional <command>find</command> arguments can be
	passed via the third argument to the
	<makevar>COPYTREE_*</makevar> macros. For example, to
	install all files from the first example except Makefiles,
	one can use the following command.</para>

	<programlisting>post-install:
	${MKDIR} ${EXAMPLESDIR}
	- (cd ${WRKSRC}/examples/ && \
	- ${COPYTREE_SHARE} \* ${EXAMPLESDIR} "! -name Makefile")</programlisting>
	+ (cd ${WRKSRC}/examples && \
	+ ${COPYTREE_SHARE} . ${EXAMPLESDIR} "! -name Makefile")</programlisting>

	<para>Note that these macros does not add the installed files
	to <filename>pkg-plist</filename>. You still need to list
	them.</para>
	</sect2>

	<sect2 id="install-documentation">
	<title>Install Additional Documentation</title>

	<para>If your software has some documentation other than the
	standard man and info pages that you think is useful for the
	user, install it under
	<filename><makevar>PREFIX</makevar>/share/doc</filename>.
	This can be done, like the previous item, in the
	<maketarget>post-install</maketarget> target.</para>

	<para>Create a new directory for your port. The directory
	name should reflect what the port is. This usually means
	<makevar>PORTNAME</makevar>. However, if you think the user
	might want different versions of the port to be installed at
	the same time, you can use the whole
	<makevar>PKGNAME</makevar>.</para>

	<para>Make the installation dependent on the variable
	<literal>DOCS</literal> option so that users can disable it
	in <filename>/etc/make.conf</filename>, like this:</para>

	<programlisting>post-install:
	.if ${PORT_OPTIONS:MDOCS}
	${MKDIR} ${DOCSDIR}
	${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${DOCSDIR}
	.endif</programlisting>

	<para>Here are some handy variables and how they are expanded
	by default when used in the
	<filename>Makefile</filename>:</para>

	<itemizedlist>
	<listitem>
	<para><makevar>DATADIR</makevar> gets expanded to
	<filename><makevar>PREFIX</makevar>/share/<makevar>PORTNAME</makevar></filename>.</para>
	</listitem>

	<listitem>
	<para><makevar>DATADIR_REL</makevar> gets expanded to
	<filename>share/<makevar>PORTNAME</makevar></filename>.</para>
	</listitem>

	<listitem>
	<para><makevar>DOCSDIR</makevar> gets expanded to
	<filename><makevar>PREFIX</makevar>/share/doc/<makevar>PORTNAME</makevar></filename>.</para>
	</listitem>

	<listitem>
	<para><makevar>DOCSDIR_REL</makevar> gets expanded to
	<filename>share/doc/<makevar>PORTNAME</makevar></filename>.</para>
	</listitem>

	<listitem>
	<para><makevar>EXAMPLESDIR</makevar> gets expanded to
	<filename><makevar>PREFIX</makevar>/share/examples/<makevar>PORTNAME</makevar></filename>.</para>
	</listitem>

	<listitem>
	<para><makevar>EXAMPLESDIR_REL</makevar> gets expanded to
	<filename>share/examples/<makevar>PORTNAME</makevar></filename>.</para>
	</listitem>
	</itemizedlist>

	<note>
	- <para>The <literal>DOCS</literal> option only controls additional
	- documentation installed in <makevar>DOCSDIR</makevar>. It
	- does not apply to standard man pages and info pages.
	- Things installed in <makevar>DATADIR</makevar> and
	+ <para>The <literal>DOCS</literal> option only controls
	+ additional documentation installed in
	+ <makevar>DOCSDIR</makevar>. It does not apply to standard
	+ man pages and info pages. Things installed in
	+ <makevar>DATADIR</makevar> and
	<makevar>EXAMPLESDIR</makevar> are controlled by
	- <literal>DATA</literal> and
	- <literal>EXAMPLES</literal> options, respectively.</para>
	+ <literal>DATA</literal> and <literal>EXAMPLES</literal>
	+ options, respectively.</para>
	</note>

	<para>These variables are exported to
	<makevar>PLIST_SUB</makevar>. Their values will appear
	there as pathnames relative to
	<filename><makevar>PREFIX</makevar></filename> if possible.
	That is,
	<filename>share/doc/<makevar>PORTNAME</makevar></filename>
	will be substituted for <literal>%%DOCSDIR%%</literal> in
	the packing list by default, and so on. (See more on
	<filename>pkg-plist</filename> substitution <link
	linkend="plist-sub">here</link>.)</para>

	<para>All conditionally installed documentation files and
	directories should be included in
	<filename>pkg-plist</filename> with the
	<literal>%%PORTDOCS%%</literal> prefix, for example:</para>

	<programlisting>%%PORTDOCS%%%%DOCSDIR%%/AUTHORS
	%%PORTDOCS%%%%DOCSDIR%%/CONTACT
	%%PORTDOCS%%@dirrm %%DOCSDIR%%</programlisting>

	<para>As an alternative to enumerating the documentation files
	in <filename>pkg-plist</filename>, a port can set the
	variable <makevar>PORTDOCS</makevar> to a list of file names
	and shell glob patterns to add to the final packing list.
	The names will be relative to <makevar>DOCSDIR</makevar>.
	Therefore, a port that utilizes <makevar>PORTDOCS</makevar>
	and uses a non-default location for its documentation should
	set <makevar>DOCSDIR</makevar> accordingly. If a directory
	is listed in <makevar>PORTDOCS</makevar> or matched by a
	glob pattern from this variable, the entire subtree of
	contained files and directories will be registered in the
	- final packing list. If the <literal>DOCS</literal> option has
	- been unset then files and directories listed in
	- <makevar>PORTDOCS</makevar> would not be installed
	- or added to port packing list. Installing the
	- documentation at <makevar>PORTDOCS</makevar> as shown above
	- remains up to the port itself. A typical example of
	- utilizing <makevar>PORTDOCS</makevar> looks as
	- follows:</para>
	+ final packing list. If the <literal>DOCS</literal> option
	+ has been unset then files and directories listed in
	+ <makevar>PORTDOCS</makevar> would not be installed or added
	+ to port packing list. Installing the documentation at
	+ <makevar>PORTDOCS</makevar> as shown above remains up to the
	+ port itself. A typical example of utilizing
	+ <makevar>PORTDOCS</makevar> looks as follows:</para>

	<programlisting>PORTDOCS= README.* ChangeLog docs/*</programlisting>

	<note>
	<para>The equivalents of <makevar>PORTDOCS</makevar> for
	files installed under <makevar>DATADIR</makevar> and
	<makevar>EXAMPLESDIR</makevar> are
	<makevar>PORTDATA</makevar> and
	<makevar>PORTEXAMPLES</makevar>, respectively.</para>

	<para>You can also use the <filename>pkg-message</filename>
	file to display messages upon installation. See <link
	linkend="porting-message">the section on using
	<filename>pkg-message</filename></link> for details. The
	<filename>pkg-message</filename> file does not need to be
	added to <filename>pkg-plist</filename>.</para>
	</note>
	</sect2>

	<sect2 id="install-subdirs">
	<title>Subdirectories Under <makevar>PREFIX</makevar></title>

	<para>Try to let the port put things in the right
	subdirectories of <makevar>PREFIX</makevar>. Some ports
	lump everything and put it in the subdirectory with the
	port's name, which is incorrect. Also, many ports put
	everything except binaries, header files and manual pages in
	a subdirectory of <filename>lib</filename>, which does not
	work well with the BSD paradigm. Many of the files should
	be moved to one of the following: <filename>etc</filename>
	(setup/configuration files), <filename>libexec</filename>
	(executables started internally), <filename>sbin</filename>
	(executables for superusers/managers),
	<filename>info</filename> (documentation for info browser)
	or <filename>share</filename> (architecture independent
	files). See &man.hier.7; for details; the rules governing
	<filename>/usr</filename> pretty much apply to
	<filename>/usr/local</filename> too. The exception are
	ports dealing with USENET <quote>news</quote>. They may use
	<filename><makevar>PREFIX</makevar>/news</filename> as a
	destination for their files.</para>
	</sect2>
	</sect1>
	</chapter>

	<chapter id="special">
	<title>Special Considerations</title>

	<para>There are some more things you have to take into account
	when you create a port. This section explains the most common
	of those.</para>

	<sect1 id="porting-shlibs">
	<title>Shared Libraries</title>

	<para>If your port installs one or more shared libraries, define
	a <makevar>USE_LDCONFIG</makevar> make variable, which will
	instruct a <filename>bsd.port.mk</filename> to run
	<literal>&dollar;{LDCONFIG} -m</literal> on the directory
	where the new library is installed (usually
	<filename><makevar>PREFIX</makevar>/lib</filename>) during
	<maketarget>post-install</maketarget> target to register it
	into the shared library cache. This variable, when defined,
	will also facilitate addition of an appropriate
	<literal>@exec /sbin/ldconfig -m</literal> and
	<literal>@unexec /sbin/ldconfig -R</literal> pair into your
	<filename>pkg-plist</filename> file, so that a user who
	installed the package can start using the shared library
	immediately and de-installation will not cause the system to
	still believe the library is there.</para>

	<programlisting>USE_LDCONFIG= yes</programlisting>

	<para>If you need, you can override the default directory by
	setting the <makevar>USE_LDCONFIG</makevar> value to a list of
	directories into which shared libraries are to be installed.
	For example if your port installs shared libraries into
	<filename><makevar>PREFIX</makevar>/lib/foo</filename> and
	<filename><makevar>PREFIX</makevar>/lib/bar</filename>
	directories you could use the following in your
	<filename>Makefile</filename>:</para>

	<programlisting>USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar</programlisting>

	<para>Please double-check, often this is not necessary at all or
	can be avoided through <literal>-rpath</literal> or setting
	<envar>LD_RUN_PATH</envar> during linking (see <filename
	role="package">lang/moscow_ml</filename> for an example), or
	through a shell-wrapper which sets
	<makevar>LD_LIBRARY_PATH</makevar> before invoking the binary,
	like <filename role="package">www/seamonkey</filename>
	does.</para>

	<para>When installing 32-bit libraries on 64-bit system, use
	<makevar>USE_LDCONFIG32</makevar> instead.</para>

	<para>Try to keep shared library version numbers in the
	<filename>libfoo.so.0</filename> format. Our runtime linker
	only cares for the major (first) number.</para>

	<para>When the major library version number increments in the
	update to the new port version, all other ports that link to
	the affected library should have their
	<makevar>PORTREVISION</makevar> incremented, to force
	recompilation with the new library version.</para>
	</sect1>

	<sect1 id="porting-restrictions">
	<title>Ports with Distribution Restrictions</title>

	<para>Licenses vary, and some of them place restrictions on how
	the application can be packaged, whether it can be sold for
	profit, and so on.</para>

	<important>
	<para>It is your responsibility as a porter to read the
	licensing terms of the software and make sure that the
	FreeBSD project will not be held accountable for violating
	them by redistributing the source or compiled binaries
	either via FTP/HTTP or CD-ROM. If in doubt, please contact
	the &a.ports;.</para>
	</important>

	<para>In situations like this, the variables described in the
	following sections can be set.</para>

	<sect2>
	<title><makevar>NO_PACKAGE</makevar></title>

	<para>This variable indicates that we may not generate a
	binary package of the application. For instance, the
	license may disallow binary redistribution, or it may
	prohibit distribution of packages created from patched
	sources.</para>

	<para>However, the port's <makevar>DISTFILES</makevar> may be
	freely mirrored on FTP/HTTP. They may also be distributed
	on a CD-ROM (or similar media) unless
	<makevar>NO_CDROM</makevar> is set as well.</para>

	<para><makevar>NO_PACKAGE</makevar> should also be used if the
	binary package is not generally useful, and the application
	should always be compiled from the source code. For
	example, if the application has configuration information
	that is site specific hard coded in to it at compile time,
	set <makevar>NO_PACKAGE</makevar>.</para>

	<para><makevar>NO_PACKAGE</makevar> should be set to a string
	describing the reason why the package should not be
	generated.</para>
	</sect2>

	<sect2>
	<title><makevar>NO_CDROM</makevar></title>

	<para>This variable alone indicates that, although we are
	allowed to generate binary packages, we may put neither
	those packages nor the port's <makevar>DISTFILES</makevar>
	onto a CD-ROM (or similar media) for resale. However, the
	binary packages and the port's <makevar>DISTFILES</makevar>
	will still be available via FTP/HTTP.</para>

	<para> If this variable is set along with
	<makevar>NO_PACKAGE</makevar>, then only the port's
	<makevar>DISTFILES</makevar> will be available, and only via
	FTP/HTTP.</para>

	<para><makevar>NO_CDROM</makevar> should be set to a string
	describing the reason why the port cannot be redistributed
	on CD-ROM. For instance, this should be used if the port's
	license is for <quote>non-commercial</quote> use
	only.</para>
	</sect2>

	<sect2>
	<title><makevar>NOFETCHFILES</makevar></title>

	<para>Files defined in the <makevar>NOFETCHFILES</makevar>
	variable are not fetchable from any of the
	<makevar>MASTER_SITES</makevar>. An example of such a file
	is when the file is supplied on CD-ROM by the vendor.</para>

	<para>Tools which check for the availability of these files
	on the <makevar>MASTER_SITES</makevar> should ignore these
	files and not report about them.</para>
	</sect2>

	<sect2>
	<title><makevar>RESTRICTED</makevar></title>

	<para>Set this variable alone if the application's license
	permits neither mirroring the application's
	<makevar>DISTFILES</makevar> nor distributing the binary
	package in any way.</para>

	<para><makevar>NO_CDROM</makevar> or
	<makevar>NO_PACKAGE</makevar> should not be set along with
	<makevar>RESTRICTED</makevar> since the latter variable
	implies the former ones.</para>

	<para><makevar>RESTRICTED</makevar> should be set to a string
	describing the reason why the port cannot be redistributed.
	Typically, this indicates that the port contains proprietary
	software and that the user will need to manually download
	the <makevar>DISTFILES</makevar>, possibly after registering
	for the software or agreeing to accept the terms of an
	<acronym>EULA</acronym>.</para>
	</sect2>

	<sect2>
	<title><makevar>RESTRICTED_FILES</makevar></title>

	<para>When <makevar>RESTRICTED</makevar> or
	<makevar>NO_CDROM</makevar> is set, this variable defaults
	to <literal>${DISTFILES} ${PATCHFILES}</literal>, otherwise
	it is empty. If only some of the distribution files are
	restricted, then set this variable to list them.</para>

	<para>Note that the port committer should add an entry to
	<filename>/usr/ports/LEGAL</filename> for every listed
	distribution file, describing exactly what the restriction
	entails.</para>
	</sect2>

	<sect2>
	<title>Examples</title>

	<para>The preferred way to state "the distfiles for this port
	must be fetched manually" is as follows:</para>

	<programlisting>.if !exists(${DISTDIR}/${DISTNAME}${EXTRACT_SUFX})
	IGNORE= may not be redistributed because of licensing reasons. Please visit <replaceable>some-website</replaceable> to accept their license and download ${DISTFILES} into ${DISTDIR}
	.endif</programlisting>

	<para>This both informs the user, and sets the proper metadata
	on the user's machine for use by automated programs.</para>

	<para>Note that this stanza must be preceded by an inclusion
	of <filename>bsd.port.pre.mk</filename>.</para>
	</sect2>
	</sect1>

	<sect1 id="building">
	<title>Building Mechanisms</title>

	<sect2 id="parallel-builds">
	<title>Building Ports in Parallel</title>

	<para>The &os; ports framework supports parallel building
	using multiple <command>make</command> sub-processes, which
	allows <acronym>SMP</acronym> systems to utilize all of
	their available <acronym>CPU</acronym> power, allowing port
	builds to be faster and more effective.</para>

	<para>This is achieved by passing <makevar>-jX</makevar> flag
	to &man.make.1; running on vendor code. Unfortunately, not
	all ports handle parallel building well. Therefore it is
	required to explicitly enable this feature by adding
	<literal>MAKE_JOBS_SAFE=yes</literal> somewhere below the
	dependency declaration section of the
	<filename>Makefile</filename>.</para>

	<para>Another option for controlling this feature from the
	maintainer's point of view is the
	<makevar>MAKE_JOBS_UNSAFE=yes</makevar> variable. It is
	used when a port is known to be broken with
	<makevar>-jX</makevar> and a user forces the use of multi
	processor compilations for all ports in
	<filename>/etc/make.conf</filename> with the
	<literal>FORCE_MAKE_JOBS=yes</literal> variable.</para>
	</sect2>

	<sect2 id="using-make">
	<title><command>make</command>, <command>gmake</command>, and
	<command>imake</command></title>

	<para>If your port uses <application>GNU make</application>,
	set <literal>USE_GMAKE=yes</literal>.</para>

	<table frame="none">
	<title>Variables for Ports Related to
	<application>gmake</application></title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Means</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>USE_GMAKE</makevar></entry>
	<entry>The port requires <command>gmake</command> to
	build.</entry>
	</row>

	<row>
	<entry><makevar>GMAKE</makevar></entry>
	<entry>The full path for <command>gmake</command> if
	it is not in the <envar>PATH</envar>.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>If your port is an X application that creates
	<filename>Makefile</filename> files from
	<filename>Imakefile</filename> files using
	<application>imake</application>, then set
	<literal>USE_IMAKE=yes</literal>. This will cause the
	configure stage to automatically do an <command>xmkmf
	-a</command>. If the <option>-a</option> flag is a
	problem for your port, set <literal>XMKMF=xmkmf</literal>.
	If the port uses <application>imake</application> but does
	not understand the <maketarget>install.man</maketarget>
	target, <literal>NO_INSTALL_MANPAGES=yes</literal> should be
	set.</para>

	<para>If your port's source <filename>Makefile</filename> has
	something else than <maketarget>all</maketarget> as the main
	build target, set <makevar>ALL_TARGET</makevar> accordingly.
	Same goes for <maketarget>install</maketarget> and
	<makevar>INSTALL_TARGET</makevar>.</para>
	</sect2>

	<sect2 id="using-configure">
	<title><command>configure</command> Script</title>

	<para>If your port uses the <command>configure</command>
	script to generate <filename>Makefile</filename> files from
	<filename>Makefile.in</filename> files, set
	<literal>GNU_CONFIGURE=yes</literal>. If you want to give
	extra arguments to the <command>configure</command> script
	(the default argument is <literal>--prefix=&dollar;{PREFIX}
	--infodir=&dollar;{PREFIX}/&dollar;{INFO_PATH}
	--mandir=&dollar;{MANPREFIX}/man
	--build=&dollar;{CONFIGURE_TARGET}</literal>), set those
	extra arguments in <makevar>CONFIGURE_ARGS</makevar>. Extra
	environment variables can be passed using
	<makevar>CONFIGURE_ENV</makevar> variable.</para>

	<table frame="none">
	<title>Variables for Ports That Use
	<command>configure</command></title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Means</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>GNU_CONFIGURE</makevar></entry>
	<entry>The port uses <command>configure</command>
	script to prepare build.</entry>
	</row>

	<row>
	<entry><makevar>HAS_CONFIGURE</makevar></entry>
	<entry>Same as <makevar>GNU_CONFIGURE</makevar>,
	except default configure target is not added to
	<makevar>CONFIGURE_ARGS</makevar>.</entry>
	</row>

	<row>
	<entry><makevar>CONFIGURE_ARGS</makevar></entry>
	<entry>Additional arguments passed to
	<command>configure</command> script.</entry>
	</row>

	<row>
	<entry><makevar>CONFIGURE_ENV</makevar></entry>
	<entry>Additional environment variables to be set
	for <command>configure</command> script run.</entry>
	</row>

	<row>
	<entry><makevar>CONFIGURE_TARGET</makevar></entry>
	<entry>Override default configure target. Default
	value is
	<literal>&dollar;{MACHINE_ARCH}-portbld-freebsd&dollar;{OSREL}</literal>.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect2>

	+ <sect2 id="using-cmake">
	+ <title>Using <command>cmake</command></title>
	+
	+ <para>For ports that use <application>CMake</application>,
	+ define <literal>USES= cmake</literal>, or
	+ <literal>USES= cmake:outsource</literal> to build in a
	+ separate directory (see below).</para>
	+
	+ <table frame="none">
	+ <title>Variables for Ports That Use
	+ <command>cmake</command></title>
	+
	+ <tgroup cols="2">
	+ <thead>
	+ <row>
	+ <entry>Variable</entry>
	+ <entry>Means</entry>
	+ </row>
	+ </thead>
	+
	+ <tbody>
	+ <row>
	+ <entry><makevar>CMAKE_ARGS</makevar></entry>
	+ <entry>Port specific <application>CMake</application>
	+ flags to be passed to the <command>cmake</command>
	+ binary.</entry>
	+ </row>
	+
	+ <row>
	+ <entry><makevar>CMAKE_BUILD_TYPE</makevar></entry>
	+ <entry>Type of build (<application>CMake</application>
	+ predefined build profiles). Default is
	+ <literal>Release</literal>, or
	+ <literal>Debug</literal> if
	+ <makevar>WITH_DEBUG</makevar> is set.</entry>
	+ </row>
	+
	+ <row>
	+ <entry><makevar>CMAKE_ENV</makevar></entry>
	+ <entry>Environment variables to be set for
	+ <command>cmake</command> binary. Default is
	+ <literal>&dollar;{CONFIGURE_ENV}</literal>.</entry>
	+ </row>
	+
	+ <row>
	+ <entry><makevar>CMAKE_SOURCE_PATH</makevar></entry>
	+ <entry>Path to the source directory. Default is
	+ <literal>&dollar;{WRKSRC}</literal>.</entry>
	+ </row>
	+ </tbody>
	+ </tgroup>
	+ </table>
	+
	+ <para><application>CMake</application> supports the following
	+ build profiles: <literal>Debug</literal>,
	+ <literal>Release</literal>,
	+ <literal>RelWithDebInfo</literal> and
	+ <literal>MinSizeRel</literal>. <literal>Debug</literal> and
	+ <literal>Release</literal> profiles respect system
	+ <literal>*FLAGS</literal>, <literal>RelWithDebInfo</literal>
	+ and <literal>MinSizeRel</literal> will set
	+ <makevar>CFLAGS</makevar> to <literal>-O2 -g</literal> and
	+ <literal>-Os -DNDEBUG</literal> correspondingly. The
	+ lower-cased value of <makevar>CMAKE_BUILD_TYPE</makevar> is
	+ exported to the <makevar>PLIST_SUB</makevar> and should be
	+ used if port installs <literal>*.cmake</literal> files
	+ depending on the build type (see <filename
	+ role="package">deskutils/strigi</filename> for an
	+ example). Please note that some projects may define their
	+ own build profiles and/or force particular build type by
	+ setting <literal>CMAKE_BUILD_TYPE</literal> in
	+ <filename>CMakeLists.txt </filename> files. In order to
	+ make a port for such a project respect
	+ <makevar>CFLAGS</makevar> and <makevar>WITH_DEBUG</makevar>,
	+ the <literal>CMAKE_BUILD_TYPE</literal> definitions must be
	+ removed from those files.</para>
	+
	+ <para>Most <application>CMake</application>-based projects
	+ support an out-of-source method of building. The
	+ out-of-source build for a port can be requested by using the
	+ <literal>:outsource</literal> suffix. When enabled,
	+ <makevar>CONFIGURE_WRKSRC</makevar>,
	+ <makevar>BUILD_WRKSRC</makevar> and
	+ <makevar>INSTALL_WRKSRC</makevar> will be set to
	+ <literal>&dollar;{WRKDIR}/.build</literal> and this
	+ directory will be used to keep all files generated during
	+ configuration and build stages, leaving the source directory
	+ intact.</para>
	+
	+ <example id="using-cmake-example">
	+ <title><literal>USES= cmake</literal> Example</title>
	+
	+ <para>The following snippet demonstrates the use of
	+ <application>CMake</application> for a port.
	+ <makevar>CMAKE_SOURCE_PATH</makevar> is not usually
	+ required, but can be set when the sources are not located
	+ in the top directory, or if only a subset of the project
	+ is intended to be built by the port.</para>
	+
	+ <programlisting>USES= cmake:outsource
	+CMAKE_SOURCE_PATH= &dollar;{WRKSRC}/subproject</programlisting>
	+ </example>
	+ </sect2>
	+
	<sect2 id="using-scons">
	<title>Using <command>scons</command></title>

	<para>If your port uses <application>SCons</application>,
	define <literal>USE_SCONS=yes</literal>.</para>

	<table frame="none">
	<title>Variables for Ports That Use
	<command>scons</command></title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Means</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>SCONS_ARGS</makevar></entry>
	<entry>Port specific SCons flags passed to the SCons
	environment.</entry>
	</row>

	<row>
	<entry><makevar>SCONS_BUILDENV</makevar></entry>
	<entry>Variables to be set in system
	environment.</entry>
	</row>

	<row>
	<entry><makevar>SCONS_ENV</makevar></entry>
	<entry>Variables to be set in SCons
	environment.</entry>
	</row>

	<row>
	<entry><makevar>SCONS_TARGET</makevar></entry>
	<entry>Last argument passed to SCons, similar to
	<makevar>MAKE_TARGET</makevar>.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>To make third party <filename>SConstruct</filename>
	respect everything that is passed to SCons in
	<makevar>SCONS_ENV</makevar> (that is, most importantly,
	<makevar>CC/CXX/CFLAGS/CXXFLAGS</makevar>), patch the
	<filename>SConstruct</filename> so build
	<literal>Environment</literal> is constructed like
	this:</para>

	<programlisting>env = Environment(**ARGUMENTS)</programlisting>

	<para>It may be then modified with
	<literal>env.Append</literal> and
	<literal>env.Replace</literal>.</para>
	</sect2>
	</sect1>

	<sect1 id="using-autotools">
	<title>Using GNU Autotools</title>

	<sect2 id="using-autotools-introduction">
	<title>Introduction</title>

	<para>The various GNU autotools provide an abstraction
	mechanism for building a piece of software over a wide
	variety of operating systems and machine architectures.
	Within the Ports Collection, an individual port can make use
	of these tools via a simple construct:</para>

	<programlisting>USE_AUTOTOOLS= <replaceable>tool</replaceable>:<replaceable>version</replaceable>[:<replaceable>operation</replaceable>] ...</programlisting>

	<para>At the time of writing, <replaceable>tool</replaceable>
	can be one of <literal>libtool</literal>,
	<literal>libltdl</literal>, <literal>autoconf</literal>,
	<literal>autoheader</literal>, <literal>automake</literal>
	or <literal>aclocal</literal>.</para>

	<para><replaceable>version</replaceable> specifies the
	particular tool revision to be used (see
	<literal>devel/{automake,autoconf,libtool}[0-9]+</literal>
	for valid versions).</para>

	<para><replaceable>operation</replaceable> is an optional
	extension to modify how the tool is used.</para>

	<para>Multiple tools can be specified at once, either by
	including them all on a single line, or using the
	<literal>+=</literal> Makefile construct.</para>

	<para>Finally, there is the special tool, called
	<literal>autotools</literal>, which is a convenience
	function to bring in all available versions of the autotools
	to allow for cross-development work. This can also be
	accomplished by installing the
	<literal>devel/autotools</literal> port.</para>
	</sect2>

	<sect2 id="using-libtool">
	<title><command>libtool</command></title>

	<para>Shared libraries using the GNU building framework
	usually use <command>libtool</command> to adjust the
	compilation and installation of shared libraries to match
	the specifics of the underlying operating system. The usual
	practice is to use copy of <command>libtool</command>
	bundled with the application. In case you need to use
	external <command>libtool</command>, you can use the version
	provided by The Ports Collection:</para>

	<programlisting>USE_AUTOTOOLS= libtool:<replaceable>version</replaceable>[:env]</programlisting>

	<para>With no additional operations,
	<literal>libtool:<replaceable>version</replaceable></literal>
	tells the building framework to patch the configure script
	with the system-installed copy of
	<command>libtool</command>. The
	<makevar>GNU_CONFIGURE</makevar> is implied. Further, a
	number of make and shell variables will be assigned for
	onward use by the port. See
	<filename>bsd.autotools.mk</filename> for details.</para>

	<para>With the <literal>:env</literal> operation, only the
	environment will be set up.</para>

	<para>Finally, <makevar>LIBTOOLFLAGS</makevar> and
	<makevar>LIBTOOLFILES</makevar> can be optionally set to
	override the most likely arguments to, and files patched by,
	<command>libtool</command>. Most ports are unlikely to need
	this. See <filename>bsd.autotools.mk</filename> for further
	details.</para>
	</sect2>

	<sect2 id="using-libltdl">
	<title><command>libltdl</command></title>

	<para>Some ports make use of the <command>libltdl</command>
	library package, which is part of the
	<command>libtool</command> suite. Use of this library does
	not automatically necessitate the use of
	<command>libtool</command> itself, so a separate construct
	is provided.</para>

	<programlisting>USE_AUTOTOOLS= libltdl:<replaceable>version</replaceable></programlisting>

	<para>Currently, all this does is to bring in a
	<makevar>LIB_DEPENDS</makevar> on the appropriate
	<command>libltdl</command> port, and is provided as a
	convenience function to help eliminate any dependencies on
	the autotools ports outside of the
	<makevar>USE_AUTOTOOLS</makevar> framework. There are no
	optional operations for this tool.</para>
	</sect2>

	<sect2 id="using-autoconf">
	<title><command>autoconf</command> and
	<command>autoheader</command></title>

	<para>Some ports do not contain a configure script, but do
	contain an autoconf template in the
	<filename>configure.ac</filename> file. You can use the
	following assignments to let <command>autoconf</command>
	create the configure script, and also have
	<command>autoheader</command> create template headers for
	use by the configure script.</para>

	<programlisting>USE_AUTOTOOLS= autoconf:<replaceable>version</replaceable>[:env]</programlisting>

	<para>and</para>

	<programlisting>USE_AUTOTOOLS= autoheader:<replaceable>version</replaceable></programlisting>

	<para>which also implies the use of
	<literal>autoconf:<replaceable>version</replaceable></literal>.</para>

	<para>Similarly to <command>libtool</command>, the inclusion
	of the optional <literal>:env</literal> operation simply
	sets up the environment for further use. Without it,
	patching and reconfiguration of the port is carried
	out.</para>

	<para>The additional optional variables
	<makevar>AUTOCONF_ARGS</makevar> and
	<makevar>AUTOHEADER_ARGS</makevar> can be overridden by the
	port <filename>Makefile</filename> if specifically
	requested. As with the <command>libtool</command>
	equivalents, most ports are unlikely to need this.</para>
	</sect2>

	<sect2 id="using-automake">
	<title><command>automake</command> and
	<command>aclocal</command></title>

	<para>Some packages only contain
	<filename>Makefile.am</filename> files. These have to be
	converted into <filename>Makefile.in</filename> files using
	<command>automake</command>, and the further processed by
	<command>configure</command> to generate an actual
	<filename>Makefile</filename>.</para>

	<para>Similarly, packages occasionally do not ship with
	included <filename>aclocal.m4</filename> files, again
	required to build the software. This can be achieved with
	<command>aclocal</command>, which scans
	<filename>configure.ac</filename> or
	<filename>configure.in</filename>.</para>

	<para><command>aclocal</command> has a similar relationship to
	<command>automake</command> as <command>autoheader</command>
	does to <command>autoconf</command>, described in the
	previous section. <command>aclocal</command> implies the
	use of <command>automake</command>, thus we have:</para>

	<programlisting>USE_AUTOTOOLS= automake:<replaceable>version</replaceable>[:<replaceable>env</replaceable>]</programlisting>

	<para>and</para>

	<programlisting>USE_AUTOTOOLS= aclocal:<replaceable>version</replaceable></programlisting>

	<para>which also implies the use of
	<literal>automake:<replaceable>version</replaceable></literal>.</para>

	<para>Similarly to <command>libtool</command> and
	<command>autoconf</command>, the inclusion of the optional
	<literal>:env</literal> operation simply sets up the
	environment for further use. Without it, reconfiguration of
	the port is carried out.</para>

	<para>As with <command>autoconf</command> and
	<command>autoheader</command>, both
	<command>automake</command> and <command>aclocal</command>
	have optional argument variables,
	<makevar>AUTOMAKE_ARGS</makevar> and
	<makevar>ACLOCAL_ARGS</makevar> respectively, which may be
	overridden by the port <filename>Makefile</filename> if
	required.</para>
	</sect2>
	</sect1>

	<sect1 id="using-pkg-config">
	<title>Using <literal>pkg-config</literal></title>

	<para>If your ports requires <literal>pkg-config</literal>,
	just set <makevar>USE_PKGCONFIG</makevar> to the following
	possible values:</para>
	<table frame="none">
	<title>Values for <makevar>USE_PKGCONFIG</makevar></title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Definition</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>USE_PKGCONFIG= yes</makevar></entry>
	<entry>The ports uses pkg-config only at build
	time</entry>
	</row>

	<row>
	<entry><makevar>USE_PKGCONFIG= build</makevar></entry>
	<entry>The ports uses pkg-config only at build
	time</entry>
	</row>

	<row>
	<entry><makevar>USE_PKGCONFIG= run</makevar></entry>
	<entry>The ports uses pkg-config only at run
	time</entry>
	</row>

	<row>
	<entry><makevar>USE_PKGCONFIG= both</makevar></entry>
	<entry>The ports uses pkg-config both at build and run
	time</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect1>

	<sect1 id="using-gettext">
	<title>Using GNU <literal>gettext</literal></title>

	<sect2>
	<title>Basic Usage</title>

	<para>If your port requires <literal>gettext</literal>,
	just set <makevar>USE_GETTEXT</makevar> to
	<literal>yes</literal>, and your port will grow the
	dependency on <filename
	role="package">devel/gettext</filename>. The value of
	<makevar>USE_GETTEXT</makevar> can also specify the required
	version of the <literal>libintl</literal> library, the basic
	part of <literal>gettext</literal>, but using this feature
	is <emphasis>strongly discouraged</emphasis>: Your port
	should work with just the current version of <filename
	role="package">devel/gettext</filename>.</para>

	<para>A rather common case is a port using
	<literal>gettext</literal> and <command>configure</command>.
	Generally, GNU <command>configure</command> should be able
	to locate <literal>gettext</literal> automatically. If it
	ever fails to, hints at the location of
	<literal>gettext</literal> can be passed in
	<envar>CPPFLAGS</envar> and <envar>LDFLAGS</envar> as
	follows:</para>

	<programlisting>USE_GETTEXT= yes
	CPPFLAGS+= -I${LOCALBASE}/include
	LDFLAGS+= -L${LOCALBASE}/lib

	-GNU_CONFIGURE= yes
	-CONFIGURE_ENV= CPPFLAGS="${CPPFLAGS}" \
	- LDFLAGS="${LDFLAGS}"</programlisting>
	+GNU_CONFIGURE= yes</programlisting>

	<para>Of course, the code can be more compact if there are no
	more flags to pass to <command>configure</command>:</para>

	<programlisting>USE_GETTEXT= yes
	-GNU_CONFIGURE= yes
	-CONFIGURE_ENV= CPPFLAGS="-I${LOCALBASE}/include" \
	- LDFLAGS="-L${LOCALBASE}/lib"</programlisting>
	+GNU_CONFIGURE= yes</programlisting>
	</sect2>

	<sect2>
	<title>Optional Usage</title>

	<para>Some software products allow for disabling NLS, e.g.,
	through passing <option>--disable-nls</option> to
	<command>configure</command>. In that case, your port
	should use <literal>gettext</literal> conditionally,
	depending on the status of <link
	linkend="knobs-without-nls"><makevar>WITHOUT_NLS</makevar></link>.
	For ports of low to medium complexity, you can rely on the
	following idiom:</para>

	<programlisting>GNU_CONFIGURE= yes

	-.if !defined(WITHOUT_NLS)
	+.include <bsd.port.options.mk>
	+
	+.if ${PORT_OPTIONS:MNLS}
	USE_GETTEXT= yes
	PLIST_SUB+= NLS=""
	.else
	CONFIGURE_ARGS+= --disable-nls
	PLIST_SUB+= NLS="@comment "
	-.endif</programlisting>
	+.endif

	+.include <bsd.port.mk></programlisting>
	+
	<para>The next item on your to-do list is to arrange so that
	the message catalog files are included in the packing list
	conditionally. The <filename>Makefile</filename> part of
	this task is already provided by the idiom. It is explained
	in the section on <link linkend="plist-sub">advanced
	<filename>pkg-plist</filename> practices</link>. In a
	nutshell, each occurrence of <literal>%%NLS%%</literal> in
	<filename>pkg-plist</filename> will be replaced by
	<quote><literal>@comment </literal></quote> if NLS is
	disabled, or by a null string if NLS is enabled.
	Consequently, the lines prefixed by
	<literal>%%NLS%%</literal> will become mere comments in the
	final packing list if NLS is off; otherwise the prefix will
	be just left out. All you need to do now is insert
	<literal>%%NLS%%</literal> before each path to a message
	catalog file in <filename>pkg-plist</filename>. For
	example:</para>

	<programlisting>%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo
	%%NLS%%share/locale/no/LC_MESSAGES/foobar.mo</programlisting>

	<para>In high complexity cases, you may need to use more
	advanced techniques than the recipe given here, such as
	<link linkend="plist-dynamic">dynamic packing list
	generation</link>.</para>
	</sect2>

	<sect2>
	<title>Handling Message Catalog Directories</title>

	<para>There is a point to note about installing message
	catalog files. The target directories for them, which
	reside under
	<filename><makevar>LOCALBASE</makevar>/share/locale</filename>,
	should rarely be created and removed by a port. The most
	+
	popular languages have their respective directories listed
	- in <filename><makevar>PORTSDIR</makevar>/Templates/BSD.local.dist</filename>.
	+ in
	+ <filename><makevar>PORTSDIR</makevar>/Templates/BSD.local.dist</filename>.
	The directories for many other languages are governed by the
	<filename role="package">devel/gettext</filename> port.
	- Consult its <filename>pkg-plist</filename> and see
	- whether the port is going to install a message catalog file
	- for a unique language.</para>
	+ Consult its <filename>pkg-plist</filename> and see whether
	+ the port is going to install a message catalog file for a
	+ unique language.</para>
	</sect2>
	</sect1>

	<sect1 id="using-perl">
	<title>Using <application>Perl</application></title>

	<para>If <makevar>MASTER_SITES</makevar> is set to
	<makevar>MASTER_SITE_PERL_CPAN</makevar>, then the preferred
	value of <makevar>MASTER_SITE_SUBDIR</makevar> is the
	top-level hierarchy name. For example, the recommended value
	for <literal>p5-Module-Name</literal> is
	<literal>Module</literal>. The top-level hierarchy can be
	examined at <ulink
	url="http://cpan.org/modules/by-module/">cpan.org</ulink>.
	This keeps the port working when the author of the module
	changes.</para>

	<para>The exception to this rule is when the relevant directory
	does not exist or the distfile does not exist in that
	directory. In such case, using author's id as
	<makevar>MASTER_SITE_SUBDIR</makevar> is allowed.</para>

	<para>All of the tunable knobs below accept either
	<literal>YES</literal> or a version string like
	<literal>5.8.0+</literal>. <literal>YES</literal> means
	that the port can be used with any of the supported
	Perl versions. If a port only
	works with specific versions of
	Perl, it can be indicated with a
	version string, specifying a minimum version (e.g.,
	<literal>5.7.3+</literal>), a maximum version (e.g.,
	<literal>5.8.0-</literal>) or an exact version (e.g.,
	<literal>5.8.3</literal>).</para>

	<table frame="none">
	<title>Variables for Ports That Use
	<application>Perl</application></title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Meaning</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>USE_PERL5</makevar></entry>
	<entry>The port uses Perl 5
	to build and run.</entry>
	</row>

	<row>
	<entry><makevar>USE_PERL5_BUILD</makevar></entry>
	<entry>The port uses Perl 5
	to build.</entry>
	</row>

	<row>
	<entry><makevar>USE_PERL5_RUN</makevar></entry>
	<entry>The port uses Perl 5
	to run.</entry>
	</row>

	<row>
	<entry><makevar>PERL</makevar></entry>
	<entry>The full path of the Perl 5 interpreter,
	either in the system or installed from a port, but
	without the version number. Use this if you need to
	replace <quote><literal>#!</literal></quote>lines in
	scripts.</entry>
	</row>

	<row>
	<entry><makevar>PERL_CONFIGURE</makevar></entry>
	<entry>Configure using Perl's MakeMaker. It implies
	<makevar>USE_PERL5</makevar>.</entry>
	</row>

	<row>
	<entry><makevar>PERL_MODBUILD</makevar></entry>
	<entry>Configure, build and install using Module::Build.
	It implies <makevar>PERL_CONFIGURE</makevar>.</entry>
	</row>
	</tbody>
	</tgroup>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Read only variables</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>PERL_VERSION</makevar></entry>
	<entry>The full version of Perl
	installed (e.g., <literal>5.8.9</literal>).</entry>
	</row>

	<row>
	<entry><makevar>PERL_LEVEL</makevar></entry>
	<entry>The installed Perl version as
	an integer of the form <literal>MNNNPP</literal>
	(e.g., <literal>500809</literal>).</entry>
	</row>

	<row>
	<entry><makevar>PERL_ARCH</makevar></entry>
	<entry>Where Perl stores architecture
	dependent libraries. Defaults to
	<literal>${ARCH}-freebsd</literal>.</entry>
	</row>

	<row>
	<entry><makevar>PERL_PORT</makevar></entry>
	<entry>Name of the Perl port that is
	installed (e.g., <literal>perl5</literal>).</entry>
	</row>

	<row>
	<entry><makevar>SITE_PERL</makevar></entry>
	<entry>Directory name where site specific
	Perl packages go. This value is
	added to <makevar>PLIST_SUB</makevar>.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<note>
	<para>Ports of Perl modules which do not have an official
	website should link to <hostid>cpan.org</hostid> in the WWW
	line of <filename>pkg-descr</filename>. The
	preferred URL form is
	<literal>http://search.cpan.org/dist/Module-Name/</literal>
	(including the trailing slash).</para>
	</note>

	<note>
	<para>Do not use <literal>${SITE_PERL}</literal> in dependency
	declarations. Doing so assumes that
	<filename>bsd.perl.mk</filename> has been included, which is
	not always true. Ports depending on this port will have
	incorrect dependencies if this port's files move later in an
	upgrade. The right way to declare Perl module dependencies
	is shown in the example below.</para>
	</note>

	<example id="use-perl-dependency-example">
	<title>Perl Dependency Example</title>

	<programlisting>p5-IO-Tee>=0.64:${PORTSDIR}/devel/p5-IO-Tee</programlisting>
	</example>
	</sect1>

	<sect1 id="using-x11">
	<title>Using X11</title>

	<sect2 id="x11-variables">
	<title>X.Org Components</title>

	<para>The X11 implementation available in The Ports Collection
	is X.Org. If your application depends on X components, set
	<makevar>USE_XORG</makevar> to the list of required
	components. Available components, at the time of writing,
	are:</para>

	<para><literal>bigreqsproto compositeproto damageproto dmx
	dmxproto dri2proto evieproto fixesproto fontcacheproto
	fontenc fontsproto fontutil glproto ice inputproto kbproto
	libfs oldx pciaccess pixman printproto randrproto
	recordproto renderproto resourceproto scrnsaverproto sm
	trapproto videoproto x11 xau xaw xaw6 xaw7 xbitmaps
	xcmiscproto xcomposite xcursor xdamage xdmcp xevie xext
	xextproto xf86bigfontproto xf86dgaproto xf86driproto
	xf86miscproto xf86rushproto xf86vidmodeproto xfixes xfont
	xfontcache xft xi xinerama xineramaproto xkbfile xkbui
	xmu xmuu xorg-server xp xpm xprintapputil xprintutil
	xproto xproxymngproto xrandr xrender xres xscrnsaver xt
	xtrans xtrap xtst xv xvmc xxf86dga xxf86misc
	xxf86vm</literal>.</para>

	<para>Always up-to-date list can be found in
	<filename>/usr/ports/Mk/bsd.xorg.mk</filename>.</para>

	<para>The Mesa Project is an effort to provide free OpenGL
	implementation. You can specify a dependency on various
	components of this project with <makevar>USE_GL</makevar>
	variable. Valid options are: <literal>glut, glu, glw, glew,
	gl</literal> and <literal>linux</literal>. For backwards
	compatibility, the value of <literal>yes</literal> maps to
	<literal>glu</literal>.</para>

	<example id="use-xorg-example">
	<title>USE_XORG Example</title>

	<programlisting>USE_XORG= xrender xft xkbfile xt xaw
	USE_GL= glu</programlisting>
	</example>

	<para>Some ports define <makevar>USE_XLIB</makevar>, which
	makes the port depend on all the 50 or so libraries. This
	variable exists for backwards compatibility, as it predates
	modular X.Org, and should not be used on new ports.</para>

	<table frame="none">
	<title>Variables for Ports That Use X</title>

	<tgroup cols="2">
	<tbody>
	<row>
	<entry><makevar>USE_XLIB</makevar></entry>
	<entry>The port uses the X libraries. Deprecated -
	use a list of X.Org components in
	<makevar>USE_XORG</makevar> variable
	instead.</entry>
	</row>

	<row>
	<entry><makevar>USE_IMAKE</makevar></entry>
	<entry>The port uses <command>imake</command>.</entry>
	</row>

	<row>
	<entry><makevar>XMKMF</makevar></entry>
	<entry>Set to the path of <command>xmkmf</command> if
	not in the <envar>PATH</envar>. Defaults to
	<literal>xmkmf -a</literal>.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<table frame="none">
	<title>Variables for Depending on Individual Parts of
	X11</title>

	<tgroup cols="2">
	<tbody>
	<row>
	<entry><makevar>X_IMAKE_PORT</makevar></entry>
	<entry>Port providing <command>imake</command> and
	several other utilities used to build X11.</entry>
	</row>

	<row>
	<entry><makevar>X_LIBRARIES_PORT</makevar></entry>
	<entry>Port providing X11 libraries.</entry>
	</row>

	<row>
	<entry><makevar>X_CLIENTS_PORT</makevar></entry>
	<entry>Port providing X clients.</entry>
	</row>

	<row>
	<entry><makevar>X_SERVER_PORT</makevar></entry>
	<entry>Port providing X server.</entry>
	</row>

	<row>
	<entry><makevar>X_FONTSERVER_PORT</makevar></entry>
	<entry>Port providing font server.</entry>
	</row>

	<row>
	<entry><makevar>X_PRINTSERVER_PORT</makevar></entry>
	<entry>Port providing print server.</entry>
	</row>

	<row>
	<entry><makevar>X_VFBSERVER_PORT</makevar></entry>
	<entry>Port providing virtual framebuffer
	server.</entry>
	</row>

	<row>
	<entry><makevar>X_NESTSERVER_PORT</makevar></entry>
	<entry>Port providing a nested X server.</entry>
	</row>

	<row>
	<entry><makevar>X_FONTS_ENCODINGS_PORT</makevar></entry>
	<entry>Port providing encodings for fonts.</entry>
	</row>

	<row>
	<entry><makevar>X_FONTS_MISC_PORT</makevar></entry>
	<entry>Port providing miscellaneous bitmap
	fonts.</entry>
	</row>

	<row>
	<entry><makevar>X_FONTS_100DPI_PORT</makevar></entry>
	<entry>Port providing 100dpi bitmap fonts.</entry>
	</row>

	<row>
	<entry><makevar>X_FONTS_75DPI_PORT</makevar></entry>
	<entry>Port providing 75dpi bitmap fonts.</entry>
	</row>

	<row>
	<entry><makevar>X_FONTS_CYRILLIC_PORT</makevar></entry>
	<entry>Port providing cyrillic bitmap fonts.</entry>
	</row>

	<row>
	<entry><makevar>X_FONTS_TTF_PORT</makevar></entry>
	<entry>Port providing &truetype; fonts.</entry>
	</row>

	<row>
	<entry><makevar>X_FONTS_TYPE1_PORT</makevar></entry>
	<entry>Port providing Type1 fonts.</entry>
	</row>

	<row>
	<entry><makevar>X_MANUALS_PORT</makevar></entry>
	<entry>Port providing developer oriented manual
	pages</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<example id="using-x11-vars">
	<title>Using X11-Related Variables</title>

	<programlisting># Use some X11 libraries and depend on
	# font server as well as cyrillic fonts.
	RUN_DEPENDS= ${LOCALBASE}/bin/xfs:${X_FONTSERVER_PORT} \
	${LOCALBASE}/lib/X11/fonts/cyrillic/crox1c.pcf.gz:${X_FONTS_CYRILLIC_PORT}

	USE_XORG= x11 xpm</programlisting>
	</example>
	</sect2>

	<sect2 id="x11-motif">
	<title>Ports That Require Motif</title>

	<para>If your port requires a Motif library, define
	<makevar>USE_MOTIF</makevar> in the
	<filename>Makefile</filename>. Default Motif implementation
	is <filename
	role="package">x11-toolkits/open-motif</filename>. Users
	can choose <filename
	role="package">x11-toolkits/lesstif</filename> instead by
	setting <makevar>WANT_LESSTIF</makevar> variable.</para>

	<para>The <makevar>MOTIFLIB</makevar> variable will be set by
	<filename>bsd.port.mk</filename> to reference the
	appropriate Motif library. Please patch the source of your
	port to use <literal>&dollar;{MOTIFLIB}</literal> wherever
	the Motif library is referenced in the original
	<filename>Makefile</filename> or
	<filename>Imakefile</filename>.</para>

	<para>There are two common cases:</para>

	<itemizedlist>
	<listitem>
	<para>If the port refers to the Motif library as
	<literal>-lXm</literal> in its
	<filename>Makefile</filename> or
	<filename>Imakefile</filename>, simply substitute
	<literal>&dollar;{MOTIFLIB}</literal> for it.</para>
	</listitem>

	<listitem>
	<para>If the port uses <literal>XmClientLibs</literal> in
	its <filename>Imakefile</filename>, change it to
	<literal>&dollar;{MOTIFLIB} &dollar;{XTOOLLIB}
	&dollar;{XLIB}</literal>.</para>
	</listitem>
	</itemizedlist>

	<para>Note that <makevar>MOTIFLIB</makevar> (usually) expands
	to <literal>-L/usr/local/lib -lXm</literal> or
	<literal>/usr/local/lib/libXm.a</literal>, so there is no
	need to add <literal>-L</literal> or <literal>-l</literal>
	in front.</para>
	</sect2>

	<sect2>
	<title>X11 Fonts</title>

	<para>If your port installs fonts for the X Window System, put
	them in
	<filename><makevar>LOCALBASE</makevar>/lib/X11/fonts/local</filename>.</para>
	</sect2>

	<sect2>
	<title>Getting a Fake <envar>DISPLAY</envar> with Xvfb</title>

	<para>Some applications require a working X11 display for
	compilation to succeed. This pose a problem for machines
	that operate headless. When the following variable is used,
	the build infrastructure will start the virtual framebuffer
	X server. The working <envar>DISPLAY</envar> is then passed
	to the build.</para>

	<programlisting>USE_DISPLAY= yes</programlisting>
	</sect2>

	<sect2 id="desktop-entries">
	<title>Desktop Entries</title>

	<para>Desktop entries (<ulink
	url="http://standards.freedesktop.org/desktop-entry-spec/latest/">a
	Freedesktop standard</ulink>) provide a way to
	automatically adjust desktop features when a new program is
	installed, without requiring user intervention. For
	example, newly-installed programs automatically appear in
	the application menus of compatible desktop environments.
	Desktop entries originated in the
	<application>GNOME</application> desktop environment, but
	are now a standard and also work with
	<application>KDE</application> and
	<application>Xfce</application>. This bit of automation
	provides a real benefit to the user, and desktop entries are
	encouraged for applications which can be used in a desktop
	environment.</para>

	<sect3>
	<title>Using Predefined <filename>.desktop</filename>
	Files</title>

	<para>Ports that include predefined
	<filename>*.desktop</filename> files should
	include those files in <filename>pkg-plist</filename>
	and install them in the
	<filename><makevar>&dollar;LOCALBASE</makevar>/share/applications</filename>
	directory. The <link
	linkend="install-macros"><makevar>INSTALL_DATA</makevar>
	macro</link> is useful for installing these
	files.</para>
	</sect3>

	<sect3 id="desktop-entries-macro">
	<title>Creating Desktop Entries with the
	<makevar>DESKTOP_ENTRIES</makevar> Macro</title>

	<para>Desktop entries can be easily created for applications
	by using the <makevar>DESKTOP_ENTRIES</makevar> variable.
	A file named
	<filename><replaceable>name</replaceable>.desktop</filename>
	will be created, installed, and added to the
	<filename>pkg-plist</filename> automatically. Syntax
	is:</para>

	<programlisting>DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify</programlisting>

	<para>The list of possible categories is available on the
	<ulink
	url="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop
	website</ulink>. <makevar>StartupNotify</makevar>
	indicates whether the application is compatible with
	<emphasis>startup notifications</emphasis>. These are
	typically a graphic indicator like a clock that appear at
	the mouse pointer, menu, or panel to give the user an
	indication when a program is starting. A program that is
	compatible with startup notifications clears the indicator
	after it has started. Programs that are not compatible
	with startup notifications would never clear the indicator
	(potentially confusing and infuriating the user), and
	should have <makevar>StartupNotify</makevar> set to
	<literal>false</literal> so the indicator is not shown at
	all.</para>

	<para>Example:</para>

	<programlisting>DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \
	"${DATADIR}/xtra/graf/tome-128.png" \
	"tome -v -g" "Application;Game;RolePlaying;" \
	false</programlisting>

	</sect3>
	</sect2>
	</sect1>

	<sect1 id="using-gnome">
	<title>Using GNOME</title>

	<para>The FreeBSD/GNOME project uses its own set of variables to
	define which GNOME components a particular port uses. A
	<ulink
	url="http://www.FreeBSD.org/gnome/docs/porting.html">comprehensive
	list of these variables</ulink> exists within the
	FreeBSD/GNOME project's homepage.</para>
	</sect1>

	<sect1 id="using-qt">
	<title>Using Qt</title>

	<sect2 id="qt-common">
	<title>Ports That Require Qt</title>

	<table frame="none">
	<title>Variables for Ports That Use Qt</title>

	<tgroup cols="2">
	<tbody>
	<row>
	<entry><makevar>USE_QT_VER</makevar></entry>
	<entry>The port uses the Qt toolkit. The only
	possible value is <literal>3</literal>.
	Appropriate parameters are passed to
	<command>configure</command> script and
	<command>make</command>.</entry>
	</row>

	<row>
	<entry><makevar>USE_QT4</makevar></entry>
	<entry>Specify tool and library dependencies for ports
	that use Qt 4. See <link
	linkend="qt4-components">Qt 4 component
	selection</link> for more details.</entry>
	</row>

	<row>
	<entry><makevar>QT_PREFIX</makevar></entry>
	<entry>Set to the path where Qt installed to
	(read-only variable).</entry>
	</row>

	<row>
	<entry><makevar>MOC</makevar></entry>
	<entry>Set to the path of <command>moc</command>
	(read-only variable). Default set according to
	<makevar>USE_QT_VER</makevar> value.</entry>
	</row>

	<row>
	<entry><makevar>QTCPPFLAGS</makevar></entry>
	<entry>Additional compiler flags passed via
	<makevar>CONFIGURE_ENV</makevar> for Qt toolkit.
	Default set according to
	<makevar>USE_QT_VER</makevar>.</entry>
	</row>

	<row>
	<entry><makevar>QTCFGLIBS</makevar></entry>
	<entry>Additional libraries for linking passed via
	<makevar>CONFIGURE_ENV</makevar> for Qt toolkit.
	Default set according to
	<makevar>USE_QT_VER</makevar>.</entry>
	</row>

	<row>
	<entry><makevar>QTNONSTANDARD</makevar></entry>
	<entry>Suppress modification of
	<makevar>CONFIGURE_ENV</makevar>,
	<makevar>CONFIGURE_ARGS</makevar>,
	<makevar>CPPFLAGS</makevar> and
	<makevar>MAKE_ENV</makevar>.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<table frame="none">
	<title>Additional Variables for Ports That Use Qt
	4.x</title>

	<tgroup cols="2">
	<tbody>
	<row>
	<entry><makevar>UIC</makevar></entry>
	<entry>Set to the path of <command>uic</command>
	(read-only variable).</entry>
	</row>

	<row>
	<entry><makevar>QMAKE</makevar></entry>
	<entry>Set to the path of <command>qmake</command>
	(read-only variable).</entry>
	</row>

	<row>
	<entry><makevar>QMAKESPEC</makevar></entry>
	<entry>Set to the path of configuration file for
	<command>qmake</command> (read-only
	variable).</entry>
	</row>

	<row>
	<entry><makevar>QMAKEFLAGS</makevar></entry>
	<entry>Additional flags for
	<command>qmake</command>.</entry>
	</row>

	<row>
	<entry><makevar>QT_INCDIR</makevar></entry>
	<entry>Set to Qt 4 include directories (read-only
	variable).</entry>
	</row>

	<row>
	<entry><makevar>QT_LIBDIR</makevar></entry>
	<entry>Set to Qt 4 libraries path (read-only
	variable).</entry>
	</row>

	<row>
	<entry><makevar>QT_PLUGINDIR</makevar></entry>
	<entry>Set to Qt 4 plugins path (read-only
	variable).</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>When <makevar>USE_QT_VER</makevar> is set to
	<literal>3</literal>, some useful settings are passed to the
	<command>configure</command> script:</para>

	<programlisting>CONFIGURE_ARGS+= --with-qt-includes=${QT_PREFIX}/include \
	--with-qt-libraries=${QT_PREFIX}/lib \
	--with-extra-libs=${LOCALBASE}/lib \
	--with-extra-includes=${LOCALBASE}/include
	CONFIGURE_ENV+= MOC="${MOC}" LIBS="${QTCFGLIBS}" \
	QTDIR="${QT_PREFIX}" KDEDIR="${KDE_PREFIX}"
	CPPFLAGS+= ${QTCPPFLAGS}</programlisting>

	<para>If <makevar>USE_QT4</makevar> is set, the following
	settings are deployed:</para>

	<programlisting>CONFIGURE_ARGS+= --with-qt-includes=${QT_INCDIR} \
	--with-qt-libraries=${QT_LIBDIR} \
	--with-extra-libs=${LOCALBASE}/lib \
	--with-extra-includes=${LOCALBASE}/include
	CONFIGURE_ENV+= MOC="${MOC}" UIC="${UIC}" LIBS="${QTCFGLIBS}" \
	QMAKE="${QMAKE}" QMAKESPEC="${QMAKESPEC}" QTDIR="${QT_PREFIX}"
	MAKE_ENV+= QMAKESPEC="${QMAKESPEC}"

	PLIST_SUB+= QT_INCDIR_REL=${QT_INCDIR_REL} \
	QT_LIBDIR_REL=${QT_LIBDIR_REL} \
	QT_PLUGINDIR_REL=${QT_PLUGINDIR_REL}</programlisting>
	</sect2>

	<sect2 id="qt4-components">
	<title>Component Selection (Qt 4.x Only)</title>

	<para>Individual Qt 4 tool and library dependencies
	must be specified in the <makevar>USE_QT4</makevar>
	variable. Every component
	can be suffixed by either <literal>_build</literal> or
	<literal>_run</literal>, the suffix indicating whether the
	component should be depended on at buildtime or runtime,
	respectively. If unsuffixed, the component will be depended
	on at both build- and runtime. Usually, library components
	should be specified unsuffixed, tool components should be
	specified with the <literal>_build</literal> suffix and
	plugin components should be specified with the
	<literal>_run</literal> suffix. The most commonly used
	components are listed below (all available components are
	listed in <makevar>_USE_QT4_ALL</makevar> in
	<filename>/usr/ports/Mk/bsd.qt.mk</filename>):</para>

	<table frame="none">
	<title>Available Qt 4 Library Components</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Name</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>corelib</literal></entry>
	<entry>core library (can be omitted unless the port
	uses nothing but <literal>corelib</literal>)</entry>
	</row>

	<row>
	<entry><literal>gui</literal></entry>
	<entry>graphical user interface library</entry>
	</row>

	<row>
	<entry><literal>network</literal></entry>
	<entry>network library</entry>
	</row>

	<row>
	<entry><literal>opengl</literal></entry>
	<entry>OpenGL library</entry>
	</row>

	<row>
	<entry><literal>qt3support</literal></entry>
	<entry>Qt 3 compatibility library</entry>
	</row>

	<row>
	<entry><literal>qtestlib</literal></entry>
	<entry>unit testing library</entry>
	</row>

	<row>
	<entry><literal>script</literal></entry>
	<entry>script library</entry>
	</row>

	<row>
	<entry><literal>sql</literal></entry>
	<entry>SQL library</entry>
	</row>

	<row>
	<entry><literal>xml</literal></entry>
	<entry>XML library</entry>
	</row>

	</tbody>
	</tgroup>
	</table>

	<para>You can determine which libraries the application
	depends on, by running <command>ldd</command> on the main
	executable after a successful compilation.</para>

	<table frame="none">
	<title>Available Qt 4 Tool Components</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Name</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>moc</literal></entry>
	<entry>meta object compiler (needed for almost
	every Qt application at buildtime)</entry>
	</row>

	<row>
	<entry><literal>qmake</literal></entry>
	<entry>Makefile generator / build utility</entry>
	</row>

	<row>
	<entry><literal>rcc</literal></entry>
	<entry>resource compiler (needed if the application
	comes with <filename>*.rc</filename> or
	<filename>*.qrc</filename> files)</entry>
	</row>

	<row>
	<entry><literal>uic</literal></entry>
	<entry>user interface compiler (needed if the
	application comes with <filename>*.ui</filename>
	files created by Qt Designer - in practice, every Qt
	application with a GUI)</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<table frame="none">
	<title>Available Qt 4 Plugin Components</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Name</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>iconengines</literal></entry>
	<entry>SVG icon engine plugin (if the application
	ships SVG icons)</entry>
	</row>

	<row>
	<entry><literal>imageformats</literal></entry>
	<entry>imageformat plugins for GIF, JPEG, MNG and
	SVG (if the application ships image files)</entry>
	</row>

	</tbody>
	</tgroup>
	</table>

	<example id="qt4-components-example">
	<title>Selecting Qt 4 Components</title>

	<para>In this example, the ported application uses the Qt 4
	graphical user interface library, the Qt 4 core library,
	all of the Qt 4 code generation tools and Qt 4's Makefile
	generator. Since the <literal>gui</literal> library
	implies a dependency on the core library,
	<literal>corelib</literal> does not need to be specified.
	The Qt 4 code generation tools <literal>moc</literal>,
	<literal>uic</literal> and <literal>rcc</literal>, as well
	as the Makefile generator <literal>qmake</literal> are
	only needed at buildtime, thus they are specified with the
	<literal>_build</literal> suffix:</para>

	<programlisting>USE_QT4= gui moc_build qmake_build rcc_build uic_build</programlisting>
	</example>
	</sect2>

	<sect2 id="qt-additional">
	<title>Additional Considerations</title>

	<para>If the application does not provide a
	<filename>configure</filename> file but a
	<filename>.pro</filename> file, you can use the
	following:</para>

	<programlisting>HAS_CONFIGURE= yes

	do-configure:
	- @cd ${WRKSRC} && ${SETENV} ${CONFIGURE_ENV} \
	+ @cd ${WRKSRC} && ${SETENV} ${CONFIGURE_ENV} \
	${QMAKE} ${QMAKEFLAGS} PREFIX=${PREFIX} texmaker.pro</programlisting>

	<para>Note the similarity to the <command>qmake</command> line
	from the provided <filename>BUILD.sh</filename> script.
	Passing <makevar>CONFIGURE_ENV</makevar> ensures
	<command>qmake</command> will see the
	<makevar>QMAKESPEC</makevar> variable, without which it
	cannot work. <command>qmake</command> generates standard
	Makefiles, so it is not necessary to write our own
	<maketarget>build</maketarget> target.</para>

	<para>Qt applications often are written to be cross-platform
	and often X11/Unix is not the platform they are developed
	on, which in turn often leads to certain loose ends,
	like:</para>

	<itemizedlist>
	<listitem>
	<para><emphasis>Missing additional include
	paths.</emphasis> Many applications come with
	system tray icon support, but neglect to look for
	includes and/or libraries in the X11 directories. You
	can tell <command>qmake</command> to add directories to
	the include and library search paths via the command
	line, for example:</para>

	<programlisting>${QMAKE} ${QMAKEFLAGS} PREFIX=${PREFIX} INCLUDEPATH+=${LOCALBASE}/include \
	LIBS+=-L${LOCALBASE}/lib sillyapp.pro</programlisting>
	</listitem>

	<listitem>
	<para><emphasis>Bogus installation paths.</emphasis>
	Sometimes data such as icons or .desktop files are by
	default installed into directories which are not scanned
	by XDG-compatible applications. <filename
	role="package">editors/texmaker</filename> is an
	example for this - look at
	<filename>patch-texmaker.pro</filename> in the
	<filename>files</filename> directory of that port for a
	template on how to remedy this directly in the
	<command>qmake</command> project file.</para>
	</listitem>
	</itemizedlist>
	</sect2>
	</sect1>

	<sect1 id="using-kde">
	<title>Using KDE</title>

	<sect2 id="kde-variables">
	<title>Variable Definitions (KDE 3.x Only)</title>

	<table frame="none">
	<title>Variables for Ports That Use KDE 3.x</title>

	<tgroup cols="2">
	<tbody>
	<row>
	<entry><makevar>USE_KDELIBS_VER</makevar></entry>
	<entry>The port uses KDE libraries. It specifies the
	major version of KDE to use and implies
	<makevar>USE_QT_VER</makevar> of the appropriate
	version. The only possible value is
	<literal>3</literal>.</entry>
	</row>

	<row>
	<entry><makevar>USE_KDEBASE_VER</makevar></entry>
	<entry>The port uses KDE base. It specifies the major
	version of KDE to use and implies
	<makevar>USE_QT_VER</makevar> of the appropriate
	version. The only possible value is
	<literal>3</literal>.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect2>

	<sect2 id="kde4-variables">
	<title>KDE 4 Variable Definitions</title>

	<para>If your application depends on KDE 4.x, set
	<makevar>USE_KDE4</makevar> to the list of required
	components. <literal>_build</literal> and
	<literal>_run</literal> suffixes can be used to force
	components dependency type (e.g.,
	<literal>baseapps_run</literal>). If no suffix is set, a
	- default dependency type will be used. If you want to force
	+ default dependency type will be used. If you want to force
	both types, add the component twice with both suffixes
	(e.g., <literal>automoc4_build automoc4_run</literal>). The
	most commonly used components are listed below (up-to-date
	components are documented at the top of
	<filename>/usr/ports/Mk/bsd.kde4.mk</filename>):</para>

	<table frame="none">
	<title>Available KDE 4 Components</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Name</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>kdehier</literal></entry>
	<entry>Hierarchy of common KDE directories</entry>
	</row>

	<row>
	<entry><literal>kdelibs</literal></entry>
	<entry>KDE Developer Platform</entry>
	</row>

	<row>
	<entry><literal>kdeprefix</literal></entry>
	<entry>If set, port will be installed into
	<literal>&dollar;{KDE4_PREFIX}</literal> instead of
	<literal>&dollar;{LOCALBASE}</literal></entry>
	</row>

	<row>
	<entry><literal>sharedmime</literal></entry>
	<entry>MIME types database for KDE ports</entry>
	</row>

	<row>
	<entry><literal>automoc4</literal></entry>
	<entry>Automatic moc for Qt 4 packages</entry>
	</row>

	<row>
	<entry><literal>akonadi</literal></entry>
	<entry>Storage server for KDE-Pim</entry>
	</row>

	<row>
	<entry><literal>soprano</literal></entry>
	<entry>Qt 4 RDF framework</entry>
	</row>

	<row>
	<entry><literal>strigi</literal></entry>
	<entry>Desktop search daemon</entry>
	</row>

	<row>
	<entry><literal>libkcddb</literal></entry>
	<entry>KDE CDDB library</entry>
	</row>

	<row>
	<entry><literal>libkcompactdisc</literal></entry>
	<entry>KDE library for interfacing with audio
	CDs</entry>
	</row>

	<row>
	<entry><literal>libkdeedu</literal></entry>
	<entry>Libraries used by educational
	applications</entry>
	</row>

	<row>
	<entry><literal>libkdcraw</literal></entry>
	<entry>KDE LibRaw library</entry>
	</row>

	<row>
	<entry><literal>libkexiv2</literal></entry>
	<entry>KDE Exiv2 library</entry>
	</row>

	<row>
	<entry><literal>libkipi</literal></entry>
	<entry> KDE Image Plugin Interface</entry>
	</row>

	<row>
	<entry><literal>libkonq</literal></entry>
	<entry>Konqueror core library</entry>
	</row>

	<row>
	<entry><literal>libksane</literal></entry>
	<entry>KDE SANE ("Scanner Access Now Easy")
	library</entry>
	</row>

	<row>
	<entry><literal>pimlibs</literal></entry>
	<entry>KDE-Pim libraries</entry>
	</row>

	<row>
	<entry><literal>kate</literal></entry>
	<entry>Text editor framework</entry>
	</row>

	<row>
	<entry><literal>marble</literal></entry>
	<entry>Virtual globe</entry>
	</row>

	<row>
	<entry><literal>okular</literal></entry>
	<entry>Universal document viewer</entry>
	</row>

	<row>
	<entry><literal>korundum</literal></entry>
	<entry>KDE Ruby bindings</entry>
	</row>

	<row>
	<entry><literal>perlkde</literal></entry>
	<entry>KDE Perl bindings</entry>
	</row>

	<row>
	<entry><literal>pykde4</literal></entry>
	<entry>KDE Python bindings</entry>
	</row>

	<row>
	<entry><literal>pykdeuic4</literal></entry>
	<entry>PyKDE user interface compiler</entry>
	</row>

	<row>
	<entry>smokekde<literal></literal></entry>
	<entry>KDE SMOKE libraries</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>KDE 4.x ports are installed into
	<makevar>KDE4_PREFIX</makevar>, which is
	<filename>/usr/local/kde4</filename> currently, to avoid
	conflicts with KDE 3.x ports. This is achieved by
	specifying the <literal>kdeprefix</literal> component, which
	overrides the default <makevar>PREFIX</makevar>. The ports
	however respect any <makevar>PREFIX</makevar> set via
	<envar>MAKEFLAGS</envar> environment variable and/or
	<command>make</command> arguments.</para>

	<example id="kde4-components-example">
	<title><makevar>USE_KDE4</makevar> Example</title>

	<para>This is a simple example for a KDE 4 port.
	- <makevar>USE_CMAKE</makevar> instructs the port to utilize
	- <application>CMake</application> — configuration
	- tool widely spread among KDE 4 projects.
	+ <literal>USES= cmake:outsource</literal> instructs the
	+ port to utilize <application>CMake</application>, a
	+ configuration tool widely used by KDE 4 projects (see
	+ <xref linkend="using-cmake"/> for detailed usage).
	<makevar>USE_KDE4</makevar> brings dependency on KDE
	libraries and makes port using
	<command>automoc4</command> at build stage.
	Required KDE components and other dependencies can be
	determined through configure log.
	<makevar>USE_KDE4</makevar> does not imply
	<makevar>USE_QT4</makevar>. If a port requires some
	Qt 4 components, they should be specified in
	<makevar>USE_QT4</makevar>.</para>

	- <programlisting>USE_CMAKE= yes
	+ <programlisting>USES= cmake:outsource
	USE_KDE4= kdelibs kdeprefix automoc4
	USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting>
	</example>
	</sect2>
	</sect1>

	<sect1 id="using-java">
	<title>Using Java</title>

	<sect2 id="java-variables">
	<title>Variable Definitions</title>

	<para>If your port needs a Java™ Development Kit
	(JDK™) to either build, run or even extract the
	distfile, then it should define
	<makevar>USE_JAVA</makevar>.</para>

	<para>There are several JDKs in the ports collection, from
	various vendors, and in several versions. If your port must
	use one of these versions, you can define which one. The
	most current version is <filename
	role="package">java/jdk16</filename>.</para>

	<table frame="none">
	<title>Variables Which May be Set by Ports That Use
	Java</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Means</entry>
	</row>
	</thead>
	<tbody>
	<row>
	<entry><makevar>USE_JAVA</makevar></entry>
	<entry>Should be defined for the remaining variables
	to have any effect.</entry>
	</row>

	<row>
	<entry><makevar>JAVA_VERSION</makevar></entry>
	<entry>List of space-separated suitable Java versions
	for the port. An optional <literal>"+"</literal>
	allows you to specify a range of versions (allowed
	values:
	<literal>1.5[+] 1.6[+] 1.7[+]</literal>).</entry>
	</row>

	<row>
	<entry><makevar>JAVA_OS</makevar></entry>
	<entry>List of space-separated suitable JDK port
	operating systems for the port (allowed values:
	<literal>native linux</literal>).</entry>
	</row>

	<row>
	<entry><makevar>JAVA_VENDOR</makevar></entry>
	<entry>List of space-separated suitable JDK port
	vendors for the port (allowed values:
	<literal>freebsd bsdjava sun
	openjdk</literal>).</entry>
	</row>

	<row>
	<entry><makevar>JAVA_BUILD</makevar></entry>
	<entry>When set, it means that the selected JDK port
	should be added to the build dependencies of the
	port.</entry>
	</row>

	<row>
	<entry><makevar>JAVA_RUN</makevar></entry>
	<entry>When set, it means that the selected JDK port
	should be added to the run dependencies of the
	port.</entry>
	</row>

	<row>
	<entry><makevar>JAVA_EXTRACT</makevar></entry>
	<entry>When set, it means that the selected JDK port
	should be added to the extract dependencies of the
	port.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>Below is the list of all settings a port will receive
	after setting <makevar>USE_JAVA</makevar>:</para>

	<table frame="none">
	<title>Variables Provided to Ports That Use Java</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Value</entry>
	</row>
	</thead>
	<tbody>
	<row>
	<entry><makevar>JAVA_PORT</makevar></entry>
	<entry>The name of the JDK port (e.g.,
	<literal>'java/openjdk6'</literal>).</entry>
	</row>

	<row>
	<entry><makevar>JAVA_PORT_VERSION</makevar></entry>
	<entry>The full version of the JDK port (e.g.,
	<literal>'1.6.0'</literal>). If you only need the
	first two digits of this version number, use
	<makevar>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</makevar>.</entry>
	</row>

	<row>
	<entry><makevar>JAVA_PORT_OS</makevar></entry>

	<entry>The operating system used by the JDK port
	(e.g., <literal>'native'</literal>).</entry>
	</row>

	<row>
	<entry><makevar>JAVA_PORT_VENDOR</makevar></entry>
	<entry>The vendor of the JDK port (e.g.,
	<literal>'openjdk'</literal>).</entry>
	</row>

	<row>
	<entry><makevar>JAVA_PORT_OS_DESCRIPTION</makevar></entry>
	<entry>Description of the operating system used by the
	JDK port (e.g.,
	<literal>'Native'</literal>).</entry>
	</row>

	<row>
	<entry><makevar>JAVA_PORT_VENDOR_DESCRIPTION</makevar></entry>
	<entry>Description of the vendor of the JDK port
	(e.g., <literal>'OpenJDK BSD Porting
	Team'</literal>).</entry>
	</row>

	<row>
	<entry><makevar>JAVA_HOME</makevar></entry>
	<entry>Path to the installation directory of the JDK
	(e.g.,
	<filename>'/usr/local/openjdk6'</filename>).</entry>
	</row>

	<row>
	<entry><makevar>JAVAC</makevar></entry>
	<entry>Path to the Java compiler to use (e.g.,
	<filename>'/usr/local/openjdk6/bin/javac'</filename>).</entry>
	</row>

	<row>
	<entry><makevar>JAR</makevar></entry>
	<entry>Path to the <command>jar</command> tool to use
	(e.g.,
	<filename>'/usr/local/openjdk6/bin/jar'</filename>
	or
	<filename>'/usr/local/bin/fastjar'</filename>).</entry>
	</row>

	<row>
	<entry><makevar>APPLETVIEWER</makevar></entry>
	<entry>Path to the <command>appletviewer</command>
	utility (e.g.,
	<filename>'/usr/local/openjdk6/bin/appletviewer'</filename>).</entry>
	</row>

	<row>
	<entry><makevar>JAVA</makevar></entry>
	<entry>Path to the <command>java</command> executable.
	Use this for executing Java programs (e.g.,
	<filename>'/usr/local/openjdk6/bin/java'</filename>).</entry>
	</row>

	<row>
	<entry><makevar>JAVADOC</makevar></entry>
	<entry>Path to the <command>javadoc</command> utility
	program.</entry>
	</row>

	<row>
	<entry><makevar>JAVAH</makevar></entry>
	<entry>Path to the <command>javah</command>
	program.</entry>
	</row>

	<row>
	<entry><makevar>JAVAP</makevar></entry>
	<entry>Path to the <command>javap</command>
	program.</entry>
	</row>

	<row>
	<entry><makevar>JAVA_KEYTOOL</makevar></entry>
	<entry>Path to the <command>keytool</command> utility
	program.</entry>
	</row>

	<row>
	<entry><makevar>JAVA_N2A</makevar></entry>
	<entry>Path to the <command>native2ascii</command>
	tool.</entry>
	</row>

	<row>
	<entry><makevar>JAVA_POLICYTOOL</makevar></entry>
	<entry>Path to the <command>policytool</command>
	program.</entry>
	</row>

	<row>
	<entry><makevar>JAVA_SERIALVER</makevar></entry>
	<entry>Path to the <command>serialver</command>
	utility program.</entry>
	</row>

	<row>
	<entry><makevar>RMIC</makevar></entry>
	<entry>Path to the RMI stub/skeleton generator,
	<command>rmic</command>.</entry>
	</row>

	<row>
	<entry><makevar>RMIREGISTRY</makevar></entry>
	<entry>Path to the RMI registry program,
	<command>rmiregistry</command>.</entry>
	</row>

	<row>
	<entry><makevar>RMID</makevar></entry>
	<entry>Path to the RMI daemon program
	<command>rmid</command>.</entry>
	</row>

	<row>
	<entry><makevar>JAVA_CLASSES</makevar></entry>
	<entry>Path to the archive that contains the JDK class
	files,
	<filename>${JAVA_HOME}/jre/lib/rt.jar</filename>.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>You may use the <literal>java-debug</literal> make
	target to get information for debugging your port. It will
	display the value of many of the forecited variables.</para>

	<para>Additionally, the following constants are defined so all
	Java ports may be installed in a consistent way:</para>

	<table frame="none">
	<title>Constants Defined for Ports That Use Java</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Constant</entry>
	<entry>Value</entry>
	</row>
	</thead>
	<tbody>
	<row>
	<entry><makevar>JAVASHAREDIR</makevar></entry>
	<entry>The base directory for everything related to
	Java. Default:
	<filename>${PREFIX}/share/java</filename>.</entry>
	</row>

	<row>
	<entry><makevar>JAVAJARDIR</makevar></entry>
	<entry>The directory where JAR files should be
	installed. Default:
	<filename>${JAVASHAREDIR}/classes</filename>.</entry>
	</row>

	<row>
	<entry><makevar>JAVALIBDIR</makevar></entry>
	<entry>The directory where JAR files installed by
	other ports are located. Default:
	<filename>${LOCALBASE}/share/java/classes</filename>.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>The related entries are defined in both
	<makevar>PLIST_SUB</makevar> (documented in
	<xref linkend="plist-sub"/>) and
	<makevar>SUB_LIST</makevar>.</para>
	</sect2>

	<sect2 id="java-building-with-ant">
	<title>Building with Ant</title>

	<para>When the port is to be built using Apache Ant, it has to
	define <makevar>USE_ANT</makevar>. Ant is thus considered
	to be the sub-make command. When no
	<literal>do-build</literal> target is defined by the port, a
	default one will be set that simply runs Ant according to
	<makevar>MAKE_ENV</makevar>, <makevar>MAKE_ARGS</makevar>
	and <makevar>ALL_TARGET</makevar>. This is similar to the
	<makevar>USE_GMAKE</makevar> mechanism, which is documented
	in <xref linkend="building"/>.</para>
	</sect2>

	<sect2 id="java-best-practices">
	<title>Best Practices</title>

	<para>When porting a Java library, your port should install
	the JAR file(s) in <filename>${JAVAJARDIR}</filename>, and
	everything else under
	<filename>${JAVASHAREDIR}/${PORTNAME}</filename> (except for
	the documentation, see below). In order to reduce the
	packing file size, you may reference the JAR file(s)
	directly in the <filename>Makefile</filename>. Just use the
	following statement (where <filename>myport.jar</filename>
	is the name of the JAR file installed as part of the
	port):</para>

	<programlisting>PLIST_FILES+= %%JAVAJARDIR%%/myport.jar</programlisting>

	<para>When porting a Java application, the port usually
	installs everything under a single directory (including its
	JAR dependencies). The use of
	<filename>${JAVASHAREDIR}/${PORTNAME}</filename> is strongly
	encouraged in this regard. It is up the porter to decide
	whether the port should install the additional JAR
	dependencies under this directory or directly use the
	already installed ones (from
	<filename>${JAVAJARDIR}</filename>).</para>

	<para>Regardless of the type of your port (library or
	application), the additional documentation should be
	installed in the <link linkend="install-documentation">same
	location</link> as for any other port. The JavaDoc tool is
	known to produce a different set of files depending on the
	version of the JDK that is used. For ports that do not
	enforce the use of a particular JDK, it is therefore a
	complex task to specify the packing list
	(<filename>pkg-plist</filename>). This is one reason why
	porters are strongly encouraged to use the
	<makevar>PORTDOCS</makevar> macro. Moreover, even if you
	can predict the set of files that will be generated by
	<command>javadoc</command>, the size of the resulting
	<filename>pkg-plist</filename> advocates for the use of
	<makevar>PORTDOCS</makevar>.</para>

	<para>The default value for <makevar>DATADIR</makevar> is
	<filename>${PREFIX}/share/${PORTNAME}</filename>. It is a
	good idea to override <makevar>DATADIR</makevar> to
	<filename>${JAVASHAREDIR}/${PORTNAME}</filename> for Java
	ports. Indeed, <makevar>DATADIR</makevar> is automatically
	added to <makevar>PLIST_SUB</makevar> (documented in <xref
	linkend="plist-sub"/>) so you may use
	<literal>%%DATADIR%%</literal> directly in
	<filename>pkg-plist</filename>.</para>

	<para>As for the choice of building Java ports from source or
	directly installing them from a binary distribution, there
	is no defined policy at the time of writing. However,
	people from the <ulink
	url="http://www.freebsd.org/java/">&os; Java
	Project</ulink> encourage porters to have their ports built
	from source whenever it is a trivial task.</para>

	<para>All the features that have been presented in this
	section are implemented in <filename>bsd.java.mk</filename>.
	If you ever think that your port needs more sophisticated
	Java support, please first have a look at the <ulink
	url="http://svn.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=markup">bsd.java.mk
	SVN log</ulink> as it usually takes some time
	to document the latest features. Then, if you think the
	support you are lacking would be beneficial to many other
	Java ports, feel free to discuss it on the &a.java;.</para>

	<para>Although there is a <literal>java</literal> category for
	PRs, it refers to the JDK porting effort from the &os; Java
	project. Therefore, you should submit your Java port in the
	<literal>ports</literal> category as for any other port,
	unless the issue you are trying to resolve is related to
	either a JDK implementation or
	<filename>bsd.java.mk</filename>.</para>

	<para>Similarly, there is a defined policy regarding the
	<makevar>CATEGORIES</makevar> of a Java port, which is
	detailed in <xref linkend="makefile-categories"/>.</para>
	</sect2>
	</sect1>

	<sect1 id="using-php">
	<title>Web Applications, Apache and PHP</title>

	<sect2 id="using-apache">
	<title>Apache</title>

	<table frame="none">
	<title>Variables for Ports That Use Apache</title>

	<tgroup cols="2">
	<tbody>

	<row>
	<entry><makevar>USE_APACHE</makevar></entry>
	<entry>The port requires Apache. Possible values:
	<literal>yes</literal> (gets any version),
	<literal>20</literal>, <literal>22</literal>,
	<literal>20-22</literal>, <literal>20+</literal>,
	etc. The default APACHE version is
	<literal>22</literal>. More details are available
	in <filename>ports/Mk/bsd.apache.mk</filename> and
	at <ulink
	url="http://wiki.freebsd.org/Apache/">wiki.freebsd.org/Apache/</ulink>.</entry>
	</row>

	<row>
	<entry><makevar>WITH_APACHE2</makevar></entry>
	<entry>This variable is deprecated and should
	not be used any more.</entry>
	</row>

	<row>
	<entry><makevar>APXS</makevar></entry>
	<entry>Full path to the <command>apxs</command>
	binary. Can be overridden in your port.</entry>
	</row>

	<row>
	<entry><makevar>HTTPD</makevar></entry>
	<entry>Full path to the <command>httpd</command>
	binary. Can be overridden in your port.</entry>
	</row>

	<row>
	<entry><makevar>APACHE_VERSION</makevar></entry>
	<entry>The version of present Apache installation
	(read-only variable). This variable is only
	available after inclusion of
	<filename>bsd.port.pre.mk</filename>. Possible
	values: <literal>20</literal>,
	<literal>22</literal>.</entry>
	</row>

	<row>
	<entry><makevar>APACHEMODDIR</makevar></entry>
	<entry>Directory for Apache modules. This variable is
	automatically expanded in
	<filename>pkg-plist</filename>.</entry>
	</row>

	<row>
	<entry><makevar>APACHEINCLUDEDIR</makevar></entry>
	<entry>Directory for Apache headers. This variable is
	automatically expanded in
	<filename>pkg-plist</filename>.</entry>
	</row>

	<row>
	<entry><makevar>APACHEETCDIR</makevar></entry>
	<entry>Directory for Apache configuration files. This
	variable is automatically expanded in
	<filename>pkg-plist</filename>.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<table frame="none">
	<title>Useful Variables for Porting Apache Modules</title>

	<tgroup cols="2">
	<tbody>

	<row>
	<entry><makevar>MODULENAME</makevar></entry>
	<entry>Name of the module. Default value is
	<makevar>PORTNAME</makevar>. Example:
	<literal>mod_hello</literal></entry>
	</row>

	<row>
	<entry><makevar>SHORTMODNAME</makevar></entry>
	<entry>Short name of the module. Automatically
	derived from <makevar>MODULENAME</makevar>, but can
	be overridden. Example:
	<literal>hello</literal></entry>
	</row>

	<row>
	<entry><makevar>AP_FAST_BUILD</makevar></entry>
	<entry>Use <command>apxs</command> to compile and
	install the module.</entry>
	</row>

	<row>
	<entry><makevar>AP_GENPLIST</makevar></entry>
	<entry>Also automatically creates a
	<filename>pkg-plist</filename>.</entry>
	</row>

	<row>
	<entry><makevar>AP_INC</makevar></entry>
	<entry>Adds a directory to a header search path during
	compilation.</entry>
	</row>

	<row>
	<entry><makevar>AP_LIB</makevar></entry>
	<entry>Adds a directory to a library search path
	during compilation.</entry>
	</row>

	<row>
	<entry><makevar>AP_EXTRAS</makevar></entry>
	<entry>Additional flags to pass to
	<command>apxs</command>.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect2>

	<sect2 id="web-apps">
	<title>Web Applications</title>

	<para>Web applications should be installed into
	<filename><makevar>PREFIX</makevar>/www/<replaceable>appname</replaceable></filename>.
	For your convenience, this path is available both in
	<filename>Makefile</filename> and in
	<filename>pkg-plist</filename> as <makevar>WWWDIR</makevar>,
	and the path relative to <makevar>PREFIX</makevar> is
	available in <filename>Makefile</filename> as
	<makevar>WWWDIR_REL</makevar>.</para>

	<para>The user and group of web server process are available
	as <makevar>WWWOWN</makevar> and <makevar>WWWGRP</makevar>,
	in case you need to change the ownership of some files. The
	default values of both are <literal>www</literal>. If you
	want different values for your port, use <literal>WWWOWN?=
	myuser</literal> notation, to allow user to override it
	easily.</para>

	<para>Do not depend on Apache unless the web app explicitly
	needs Apache. Respect that users may wish to run your web
	app on different web server than Apache.</para>
	</sect2>

	<sect2 id="php-variables">
	<title>PHP</title>

	<table frame="none">
	<title>Variables for Ports That Use PHP</title>

	<tgroup cols="2">
	<tbody>
	<row>
	<entry><makevar>USE_PHP</makevar></entry>
	<entry>The port requires PHP. The value
	<literal>yes</literal> adds a dependency on PHP.
	The list of required PHP extensions can be specified
	instead. Example: <literal>pcre xml
	gettext</literal></entry>
	</row>

	<row>
	<entry><makevar>DEFAULT_PHP_VER</makevar></entry>
	<entry>Selects which major version of PHP will be
	installed as a dependency when no PHP is installed
	yet. Default is <literal>5</literal>. Possible
	values: <literal>4</literal>,
	<literal>5</literal></entry>
	</row>

	<row>
	<entry><makevar>IGNORE_WITH_PHP</makevar></entry>
	<entry>The port does not work with PHP of the given
	version. Possible values: <literal>4</literal>,
	<literal>5</literal></entry>
	</row>

	<row>
	<entry><makevar>USE_PHPIZE</makevar></entry>
	<entry>The port will be built as a PHP
	extension.</entry>
	</row>

	<row>
	<entry><makevar>USE_PHPEXT</makevar></entry>
	<entry>The port will be treated as a PHP extension,
	including installation and registration in the
	extension registry.</entry>
	</row>

	<row>
	<entry><makevar>USE_PHP_BUILD</makevar></entry>
	<entry>Set PHP as a build dependency.</entry>
	</row>

	<row>
	<entry><makevar>WANT_PHP_CLI</makevar></entry>
	<entry>Want the CLI (command line) version of
	PHP.</entry>
	</row>

	<row>
	<entry><makevar>WANT_PHP_CGI</makevar></entry>
	<entry>Want the CGI version of PHP.</entry>
	</row>

	<row>
	<entry><makevar>WANT_PHP_MOD</makevar></entry>
	<entry>Want the Apache module version of PHP.</entry>
	</row>

	<row>
	<entry><makevar>WANT_PHP_SCR</makevar></entry>
	<entry>Want the CLI or the CGI version of PHP.</entry>
	</row>

	<row>
	<entry><makevar>WANT_PHP_WEB</makevar></entry>
	<entry>Want the Apache module or the CGI version of
	PHP.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect2>

	<sect2>
	<title>PEAR Modules</title>

	<para>Porting PEAR modules is a very simple process.</para>

	<para>Use the variables <makevar>FILES</makevar>,
	<makevar>TESTS</makevar>, <makevar>DATA</makevar>,
	<makevar>SQLS</makevar>, <makevar>SCRIPTFILES</makevar>,
	<makevar>DOCS</makevar> and <makevar>EXAMPLES</makevar> to
	list the files you want to install. All listed files will
	be automatically installed into the appropriate locations
	and added to <filename>pkg-plist</filename>.</para>

	<para>Include
	<filename>&dollar;{PORTSDIR}/devel/pear/bsd.pear.mk</filename>
	on the last line of the
	<filename>Makefile</filename>.</para>

	<example id="pear-makefile">
	<title>Example Makefile for PEAR Class</title>

	<programlisting>PORTNAME= Date
	PORTVERSION= 1.4.3
	CATEGORIES= devel www pear

	MAINTAINER= example@domain.com
	COMMENT= PEAR Date and Time Zone Classes

	BUILD_DEPENDS= ${PEARDIR}/PEAR.php:${PORTSDIR}/devel/pear-PEAR
	RUN_DEPENDS:= ${BUILD_DEPENDS}

	FILES= Date.php Date/Calc.php Date/Human.php Date/Span.php \
	Date/TimeZone.php
	TESTS= test_calc.php test_date_methods_span.php testunit.php \
	testunit_date.php testunit_date_span.php wknotest.txt \
	bug674.php bug727_1.php bug727_2.php bug727_3.php \
	bug727_4.php bug967.php weeksinmonth_4_monday.txt \
	weeksinmonth_4_sunday.txt weeksinmonth_rdm_monday.txt \
	weeksinmonth_rdm_sunday.txt
	DOCS= TODO
	_DOCSDIR= .

	.include <bsd.port.pre.mk>
	.include "&dollar;{PORTSDIR}/devel/pear/bsd.pear.mk"
	.include <bsd.port.post.mk></programlisting>
	</example>
	</sect2>
	</sect1>

	<sect1 id="using-python">
	<title>Using Python</title>

	<para>The Ports Collection supports parallel installation of
	multiple Python versions. Ports should make sure to use a
	correct <command>python</command> interpreter, according to
	the user-settable <makevar>PYTHON_VERSION</makevar> variable.
	Most prominently, this means replacing the path to
	<command>python</command> executable in scripts with the value
	of <makevar>PYTHON_CMD</makevar> variable.</para>

	<para>Ports that install files under
	<makevar>PYTHON_SITELIBDIR</makevar> should use the
	<literal>pyXY-</literal> package name prefix, so their package
	name embeds the version of Python they are installed
	into.</para>

	<programlisting>PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX}</programlisting>

	<table frame="none">
	<title>Most Useful Variables for Ports That Use Python</title>

	<tgroup cols="2">
	<tbody>
	<row>
	<entry><makevar>USE_PYTHON</makevar></entry>
	<entry>The port needs Python. Minimal required version
	can be specified with values such as
	<literal>2.6+</literal>. Version ranges can also be
	specified, by separating two version numbers with a
	dash, e.g.: <literal>2.6-2.7</literal></entry>
	</row>

	<row>
	<entry><makevar>USE_PYDISTUTILS</makevar></entry>
	<entry>Use Python distutils for configuring, compiling
	and installing. This is required when the port comes
	with <filename>setup.py</filename>. This overrides
	the <maketarget>do-build</maketarget> and
	<maketarget>do-install</maketarget> targets and may
	also override <maketarget>do-configure</maketarget> if
	<makevar>GNU_CONFIGURE</makevar> is not
	defined.</entry>
	</row>

	<row>
	<entry><makevar>PYTHON_PKGNAMEPREFIX</makevar></entry>
	<entry>Used as a <makevar>PKGNAMEPREFIX</makevar> to
	distinguish packages for different Python versions.
	Example: <literal>py24-</literal></entry>
	</row>

	<row>
	<entry><makevar>PYTHON_SITELIBDIR</makevar></entry>
	<entry>Location of the site-packages tree, that contains
	installation path of Python (usually
	<makevar>LOCALBASE</makevar>). The
	<makevar>PYTHON_SITELIBDIR</makevar> variable can be
	very useful when installing Python modules.</entry>
	</row>

	<row>
	<entry><makevar>PYTHONPREFIX_SITELIBDIR</makevar></entry>
	<entry>The PREFIX-clean variant of PYTHON_SITELIBDIR.
	Always use <literal>%%PYTHON_SITELIBDIR%%</literal> in
	<filename>pkg-plist</filename> when possible. The
	default value of
	<literal>%%PYTHON_SITELIBDIR%%</literal> is
	<literal>lib/python%%PYTHON_VERSION%%/site-packages</literal></entry>
	</row>

	<row>
	<entry><makevar>PYTHON_CMD</makevar></entry>
	<entry>Python interpreter command line, including
	version number.</entry>
	</row>

	<row>
	<entry><makevar>PYNUMERIC</makevar></entry>
	<entry>Dependency line for numeric extension.</entry>
	</row>

	<row>
	<entry><makevar>PYNUMPY</makevar></entry>
	<entry>Dependency line for the new numeric extension,
	numpy. (PYNUMERIC is deprecated by upstream
	vendor).</entry>
	</row>

	<row>
	<entry><makevar>PYXML</makevar></entry>
	<entry>Dependency line for XML extension (not needed for
	Python 2.0 and higher as it is also in base
	distribution).</entry>
	</row>

	<row>
	<entry><makevar>USE_TWISTED</makevar></entry>
	<entry>Add dependency on twistedCore. The list of
	required components can be specified as a value of
	this variable. Example: <literal>web lore pair
	flow</literal></entry>
	</row>

	<row>
	<entry><makevar>USE_ZOPE</makevar></entry>
	<entry>Add dependency on Zope, a web application
	platform. Change Python dependency to Python 2.7.
	Set <makevar>ZOPEBASEDIR</makevar> containing a
	directory with Zope installation.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>A complete list of available variables can be found in
	<filename>/usr/ports/Mk/bsd.python.mk</filename>.</para>
	</sect1>

	<sect1 id="using-tcl">
	<title>Using <application>Tcl/Tk</application></title>

	<para>The Ports Collection supports parallel installation of
	multiple <application>Tcl/Tk</application> versions. Ports
	should try to support at least the default
	<application>Tcl/Tk</application> version and higher with the
	<makevar>USE_TCL</makevar> and <makevar>USE_TK</makevar>
	variables. It is possible to specify the desired version of
	<command>tcl</command> with the
	<makevar>WITH_TCL_VER</makevar> variable.</para>

	<table frame="none">
	<title>The Most Useful Variables for Ports That Use
	<application>Tcl/Tk</application></title>

	<tgroup cols="2">
	<tbody>
	<row>
	<entry><makevar>USE_TCL</makevar></entry>
	<entry>The port depends on the
	<application>Tcl</application> library (not the
	shell). Minimal required version can be specified
	with values such as 84+. Individual unsupported
	versions can be specified with the
	<makevar>INVALID_TCL_VER</makevar> variable.</entry>
	</row>

	<row>
	<entry><makevar>USE_TCL_BUILD</makevar></entry>
	<entry>The port needs <application>Tcl</application>
	only during the build time.</entry>
	</row>

	<row>
	<entry><makevar>USE_TCL_WRAPPER</makevar></entry>
	<entry>Ports that require the
	<application>Tcl</application> shell and do not
	require a specific <literal>tclsh</literal> version
	should use this new variable. The
	<literal>tclsh</literal> wrapper is installed on the
	system. The user can specify the desired
	<command>tcl</command> shell to use.</entry>
	</row>

	<row>
	<entry><makevar>WITH_TCL_VER</makevar></entry>
	<entry>User-defined variable that sets the desired
	<application>Tcl</application> version.</entry>
	</row>

	<row>
	<entry><makevar><replaceable>UNIQUENAME</replaceable>_WITH_TCL_VER</makevar></entry>
	<entry>Like <makevar>WITH_TCL_VER</makevar>, but
	per-port.</entry>
	</row>

	<row>
	<entry><makevar>USE_TCL_THREADS</makevar></entry>
	<entry>Require a threaded build of
	<application>Tcl/Tk</application>.</entry>
	</row>

	<row>
	<entry><makevar>USE_TK</makevar></entry>
	<entry>The port depends on the
	<application>Tk</application> library (not the wish
	shell). Implies <makevar>USE_TCL</makevar> with the
	same value. For more information see the description
	of <makevar>USE_TCL</makevar> variable.</entry>
	</row>

	<row>
	<entry><makevar>USE_TK_BUILD</makevar></entry>
	<entry>Analog to the <makevar>USE_TCL_BUILD</makevar>
	variable.</entry>
	</row>

	<row>
	<entry><makevar>USE_TK_WRAPPER</makevar></entry>
	<entry>Analog to the <makevar>USE_TCL_WRAPPER</makevar>
	variable.</entry>
	</row>

	<row>
	<entry><makevar>WITH_TK_VER</makevar></entry>
	<entry>Analog to the <makevar>WITH_TCL_VER</makevar>
	variable and implies <makevar>WITH_TCL_VER</makevar>
	of the same value.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>A complete list of available variables can be found in
	<filename>/usr/ports/Mk/bsd.tcl.mk</filename>.</para>
	</sect1>

	<sect1 id="using-emacs">
	<title>Using Emacs</title>

	<para>This section is yet to be written.</para>
	</sect1>

	<sect1 id="using-ruby">
	<title>Using Ruby</title>

	<table frame="none">
	<title>Useful Variables for Ports That Use Ruby</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Description</entry>
	</row>
	</thead>
	<tbody>
	<row>
	<entry><makevar>USE_RUBY</makevar></entry>
	<entry>The port requires Ruby.</entry>
	</row>

	<row>
	<entry><makevar>USE_RUBY_EXTCONF</makevar></entry>
	<entry>The port uses <filename>extconf.rb</filename> to
	configure.</entry>
	</row>

	<row>
	<entry><makevar>USE_RUBY_SETUP</makevar></entry>
	<entry>The port uses <filename>setup.rb</filename> to
	configure.</entry>
	</row>

	<row>
	<entry><makevar>RUBY_SETUP</makevar></entry>
	<entry>Set to the alternative name of
	<filename>setup.rb</filename>. Common value is
	<filename>install.rb</filename>.</entry>
	</row>

	</tbody>
	</tgroup>
	</table>

	<para>The following table shows the selected variables available
	to port authors via the ports infrastructure. These variables
	should be used to install files into their proper locations.
	Use them in <filename>pkg-plist</filename> as much as
	possible. These variables should not be redefined in the
	port.</para>

	<table frame="none">
	<title>Selected Read-Only Variables for Ports That Use
	Ruby</title>

	<tgroup cols="3">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Description</entry>
	<entry>Example value</entry>
	</row>
	</thead>
	<tbody>

	<row>
	<entry><makevar>RUBY_PKGNAMEPREFIX</makevar></entry>
	<entry>Used as a <makevar>PKGNAMEPREFIX</makevar> to
	distinguish packages for different Ruby
	versions.</entry>
	<entry><literal>ruby18-</literal></entry>
	</row>

	<row>
	<entry><makevar>RUBY_VERSION</makevar></entry>
	<entry>Full version of Ruby in the form of
	<literal>x.y.z</literal>.</entry>
	<entry><literal>1.8.2</literal></entry>
	</row>

	<row>
	<entry><makevar>RUBY_SITELIBDIR</makevar></entry>
	<entry>Architecture independent libraries installation
	path.</entry>
	<entry><literal>/usr/local/lib/ruby/site_ruby/1.8</literal></entry>
	</row>

	<row>
	<entry><makevar>RUBY_SITEARCHLIBDIR</makevar></entry>
	<entry>Architecture dependent libraries installation
	path.</entry>
	<entry><literal>/usr/local/lib/ruby/site_ruby/1.8/amd64-freebsd6</literal></entry>
	</row>

	<row>
	<entry><makevar>RUBY_MODDOCDIR</makevar></entry>
	<entry>Module documentation installation path.</entry>
	<entry><literal>/usr/local/share/doc/ruby18/patsy</literal></entry>
	</row>

	<row>
	<entry><makevar>RUBY_MODEXAMPLESDIR</makevar></entry>
	<entry>Module examples installation path.</entry>
	<entry><literal>/usr/local/share/examples/ruby18/patsy</literal></entry>
	</row>

	</tbody>
	</tgroup>
	</table>

	<para>A complete list of available variables can be found in
	<filename>/usr/ports/Mk/bsd.ruby.mk</filename>.</para>

	</sect1>

	<sect1 id="using-sdl">
	<title>Using SDL</title>

	<para>The <makevar>USE_SDL</makevar> variable is used to
	autoconfigure the dependencies for ports which use an SDL
	based library like <filename
	role="package">devel/sdl12</filename> and <filename
	role="package">x11-toolkits/sdl_gui</filename>.</para>

	<para>The following SDL libraries are recognized at the
	moment:</para>

	<itemizedlist>
	<listitem>
	<para>sdl: <filename
	role="package">devel/sdl12</filename></para>
	</listitem>

	<listitem>
	<para>gfx: <filename
	role="package">graphics/sdl_gfx</filename></para>
	</listitem>

	<listitem>
	<para>gui: <filename
	role="package">x11-toolkits/sdl_gui</filename></para>
	</listitem>

	<listitem>
	<para>image: <filename
	role="package">graphics/sdl_image</filename></para>
	</listitem>

	<listitem>
	<para>ldbad: <filename
	role="package">devel/sdl_ldbad</filename></para>
	</listitem>

	<listitem>
	<para>mixer: <filename
	role="package">audio/sdl_mixer</filename></para>
	</listitem>

	<listitem>
	<para>mm: <filename
	role="package">devel/sdlmm</filename></para>
	</listitem>

	<listitem>
	<para>net: <filename
	role="package">net/sdl_net</filename></para>
	</listitem>

	<listitem>
	<para>sound: <filename
	role="package">audio/sdl_sound</filename></para>
	</listitem>

	<listitem>
	<para>ttf: <filename
	role="package">graphics/sdl_ttf</filename></para>
	</listitem>
	</itemizedlist>

	<para>Therefore, if a port has a dependency on
	<filename role="package">net/sdl_net</filename> and
	<filename role="package">audio/sdl_mixer</filename>,
	the syntax will be:</para>

	<programlisting>USE_SDL= net mixer</programlisting>

	<para>The dependency <filename
	role="package">devel/sdl12</filename>, which is required by
	<filename role="package">net/sdl_net</filename> and <filename
	role="package">audio/sdl_mixer</filename>, is automatically
	added as well.</para>

	<para>If you use <makevar>USE_SDL</makevar>, it will
	automatically:</para>

	<itemizedlist>
	<listitem>
	<para>Add a dependency on
	<application>sdl12-config</application> to
	<makevar>BUILD_DEPENDS</makevar></para>
	</listitem>

	<listitem>
	<para>Add the variable <makevar>SDL_CONFIG</makevar> to
	<makevar>CONFIGURE_ENV</makevar></para>
	</listitem>

	<listitem>
	<para>Add the dependencies of the selected libraries to the
	<makevar>LIB_DEPENDS</makevar></para>
	</listitem>
	</itemizedlist>

	<para>To check whether an SDL library is available, you can do
	it with the <makevar>WANT_SDL</makevar> variable:</para>

	<programlisting>WANT_SDL= yes

	.include <bsd.port.pre.mk>

	.if ${HAVE_SDL:Mmixer}!=""
	USE_SDL+= mixer
	.endif

	.include <bsd.port.post.mk></programlisting>
	</sect1>

	<sect1 id="using-wx">
	<title>Using <application>wxWidgets</application></title>

	<para>This section describes the status of the
	<application>wxWidgets</application> libraries in the ports
	tree and its integration with the ports system.</para>

	<sect2 id="wx-introduction">
	<title>Introduction</title>

	<para>There are many versions of the
	<application>wxWidgets</application> libraries which
	conflict between them (install files under the same name).
	In the ports tree this problem has been solved by installing
	each version under a different name using version number
	suffixes.</para>

	<para>The obvious disadvantage of this is that each
	application has to be modified to find the expected version.
	Fortunately, most of the applications call the
	<command>wx-config</command> script to determine the
	necessary compiler and linker flags. The script is named
	differently for every available version. Majority of
	applications respect an environment variable, or accept a
	configure argument, to specify which
	<command>wx-config</command> script to call. Otherwise they
	have to be patched.</para>
	</sect2>

	<sect2 id="wx-version">
	<title>Version Selection</title>

	<para>To make your port use a specific version of
	<application>wxWidgets</application> there are two variables
	available for defining (if only one is defined the other
	will be set to a default value):</para>

	<table id="wx-ver-sel-table" frame="none">
	<title>Variables to Select
	<application>wxWidgets</application> Versions</title>

	<tgroup cols="3">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Description</entry>
	<entry>Default value</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>USE_WX</makevar></entry>
	<entry>List of versions the port can use</entry>
	<entry>All available versions</entry>
	</row>

	<row>
	<entry><makevar>USE_WX_NOT</makevar></entry>
	<entry>List of versions the port can not use</entry>
	<entry>None</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>The following is a list of available
	<application>wxWidgets</application> versions and the
	corresponding ports in the tree:</para>

	<table frame="none">
	<title>Available <application>wxWidgets</application>
	Versions</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Version</entry>
	<entry>Port</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>2.4</literal></entry>
	<entry><filename
	role="package">x11-toolkits/wxgtk24</filename></entry>
	</row>

	<row>
	<entry><literal>2.6</literal></entry>
	<entry><filename
	role="package">x11-toolkits/wxgtk26</filename></entry>
	</row>

	<row>
	<entry><literal>2.8</literal></entry>
	<entry><filename
	role="package">x11-toolkits/wxgtk28</filename></entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<note>
	<para>The versions starting from <literal>2.5</literal> also
	come in Unicode version and are installed by a slave port
	named like the normal one plus a
	<literal>-unicode</literal> suffix, but this can be
	handled with variables (see <xref
	linkend="wx-unicode"/>).</para>
	</note>

	<para>The variables in <xref linkend="wx-ver-sel-table"/> can
	be set to one or more of the following combinations
	separated by spaces:</para>

	<table frame="none">
	<title><application>wxWidgets</application> Version
	Specifications</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Description</entry>
	<entry>Example</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>Single version</entry>
	<entry><literal>2.4</literal></entry>
	</row>

	<row>
	<entry>Ascending range</entry>
	<entry><literal>2.4+</literal></entry>
	</row>

	<row>
	<entry>Descending range</entry>
	<entry><literal>2.6-</literal></entry>
	</row>

	<row>
	<entry>Full range (must be ascending)</entry>
	<entry><literal>2.4-2.6</literal></entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>There are also some variables to select the preferred
	versions from the available ones. They can be set to a list
	of versions, the first ones will have higher
	priority.</para>

	<table frame="none">
	<title>Variables to Select Preferred
	<application>wxWidgets</application> Versions</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Name</entry>
	<entry>Designed for</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>WANT_WX_VER</makevar></entry>
	<entry>the port</entry>
	</row>

	<row>
	<entry><makevar>WITH_WX_VER</makevar></entry>
	<entry>the user</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect2>

	<sect2 id="wx-components">
	<title>Component Selection</title>

	<para>There are other applications that, while not being
	<application>wxWidgets</application> libraries, are related
	to them. These applications can be specified in the
	<makevar>WX_COMPS</makevar> variable. The following
	components are available:</para>

	<table frame="none">
	<title>Available <application>wxWidgets</application>
	Components</title>

	<tgroup cols="3">
	<thead>
	<row>
	<entry>Name</entry>
	<entry>Description</entry>
	<entry>Version restriction</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>wx</literal></entry>
	<entry>main library</entry>
	<entry>none</entry>
	</row>

	<row>
	<entry><literal>contrib</literal></entry>
	<entry>contributed libraries</entry>
	<entry><literal>none</literal></entry>
	</row>

	<row>
	<entry><literal>python</literal></entry>
	<entry><application>wxPython</application>
	(<application>Python</application> bindings)</entry>
	<entry><literal>2.4-2.6</literal></entry>
	</row>

	<row>
	<entry><literal>mozilla</literal></entry>
	<entry><application>wxMozilla</application></entry>
	<entry><literal>2.4</literal></entry>
	</row>

	<row>
	<entry><literal>svg</literal></entry>
	<entry><application>wxSVG</application></entry>
	<entry><literal>2.6</literal></entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>The dependency type can be selected for each component
	by adding a suffix separated by a semicolon. If not present
	then a default type will be used (see <xref
	linkend="wx-def-dep-types"/>). The following types are
	available:</para>

	<table frame="none">
	<title>Available <application>wxWidgets</application>
	Dependency Types</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Name</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>build</literal></entry>
	<entry>Component is required for building, equivalent
	to <makevar>BUILD_DEPENDS</makevar></entry>
	</row>

	<row>
	<entry><literal>run</literal></entry>
	<entry>Component is required for running, equivalent
	to <makevar>RUN_DEPENDS</makevar></entry>
	</row>

	<row>
	<entry><literal>lib</literal></entry>
	<entry>Component is required for building and running,
	equivalent to <makevar>LIB_DEPENDS</makevar></entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>The default values for the components are detailed in
	the following table:</para>

	<table id="wx-def-dep-types" frame="none">
	<title>Default <application>wxWidgets</application>
	Dependency Types</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Component</entry>
	<entry>Dependency type</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>wx</literal></entry>
	<entry><literal>lib</literal></entry>
	</row>

	<row>
	<entry><literal>contrib</literal></entry>
	<entry><literal>lib</literal></entry>
	</row>

	<row>
	<entry><literal>python</literal></entry>
	<entry><literal>run</literal></entry>
	</row>

	<row>
	<entry><literal>mozilla</literal></entry>
	<entry><literal>lib</literal></entry>
	</row>

	<row>
	<entry><literal>svg</literal></entry>
	<entry><literal>lib</literal></entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<example id="wx-components-example">
	<title>Selecting <application>wxWidgets</application>
	Components</title>

	<para>The following fragment corresponds to a port which
	uses <application>wxWidgets</application> version
	<literal>2.4</literal> and its contributed
	libraries.</para>

	<programlisting>USE_WX= 2.4
	WX_COMPS= wx contrib</programlisting>
	</example>
	</sect2>

	<sect2 id="wx-unicode">
	<title>Unicode</title>

	<para>The <application>wxWidgets</application> library
	supports Unicode since version <literal>2.5</literal>. In
	the ports tree both versions are available and can be
	selected with the following variables:</para>

	<table id="wx-unicode-var-table" frame="none">
	<title>Variables to Select Unicode in
	<application>wxWidgets</application>
	Versions</title>

	<tgroup cols="3">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Description</entry>
	<entry>Designed for</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>WX_UNICODE</makevar></entry>
	<entry>The port works <emphasis>only</emphasis> with
	the Unicode version</entry>
	<entry>the port</entry>
	</row>

	<row>
	<entry><makevar>WANT_UNICODE</makevar></entry>
	<entry>The port works with both versions but prefers
	the Unicode one</entry>
	<entry>the port</entry>
	</row>

	<row>
	<entry><makevar>WITH_UNICODE</makevar></entry>
	<entry>The port will use the Unicode version</entry>
	<entry>the user</entry>
	</row>

	<row>
	<entry><makevar>WITHOUT_UNICODE</makevar></entry>
	<entry>The port will use the normal version if
	supported (when <makevar>WX_UNICODE</makevar> is not
	defined)</entry>
	<entry>the user</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<warning>
	<para>Do not use <makevar>WX_UNICODE</makevar> for ports
	that can use both Unicode and normal versions. If you
	want the port to use Unicode by default define
	<makevar>WANT_UNICODE</makevar> instead.</para>
	</warning>
	</sect2>

	<sect2 id="wx-version-detection">
	<title>Detecting Installed Versions</title>

	<para>To detect an installed version you have to define
	<makevar>WANT_WX</makevar>. If you do not set it to a
	specific version then the components will have a version
	suffix. The <makevar>HAVE_WX</makevar> variable will be
	filled after detection.</para>

	<example id="wx-ver-det-example">
	<title>Detecting Installed
	<application>wxWidgets</application> Versions and
	Components</title>

	<para>The following fragment can be used in a port that uses
	<application>wxWidgets</application> if it is installed,
	or an option is selected.</para>

	<programlisting>WANT_WX= yes

	.include <bsd.port.pre.mk>

	.if defined(WITH_WX) \|\| !empty(PORT_OPTIONS:MWX) \|\| !empty(HAVE_WX:Mwx-2.4)
	USE_WX= 2.4
	CONFIGURE_ARGS+= --enable-wx
	.endif</programlisting>

	<para>The following fragment can be used in a port that
	enables <application>wxPython</application> support if it
	is installed or if an option is selected, in addition to
	<application>wxWidgets</application>, both version
	<literal>2.6</literal>.</para>

	<programlisting>USE_WX= 2.6
	WX_COMPS= wx
	WANT_WX= 2.6

	.include <bsd.port.pre.mk>

	.if defined(WITH_WXPYTHON) \|\| !empty(PORT_OPTIONS:MWXPYTHON) \|\| !empty(HAVE_WX:Mpython)
	WX_COMPS+= python
	CONFIGURE_ARGS+= --enable-wxpython
	.endif</programlisting>
	</example>
	</sect2>

	<sect2 id="wx-defined-variables">
	<title>Defined Variables</title>

	<para>The following variables are available in the port (after
	defining one from
	<xref linkend="wx-ver-sel-table"/>).</para>

	<table frame="none">
	<title>Variables Defined for Ports That Use
	<application>wxWidgets</application></title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Name</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>WX_CONFIG</makevar></entry>
	<entry>The path to the
	<application>wxWidgets</application>
	<command>wx-config</command> script (with different
	name)</entry>
	</row>

	<row>
	<entry><makevar>WXRC_CMD</makevar></entry>
	<entry>The path to the
	<application>wxWidgets</application>
	<command>wxrc</command> program (with different
	name)</entry>
	</row>

	<row>
	<entry><makevar>WX_VERSION</makevar></entry>
	<entry>The <application>wxWidgets</application>
	version that is going to be used (e.g.,
	<literal>2.6</literal>)</entry>
	</row>

	<row>
	<entry><makevar>WX_UNICODE</makevar></entry>
	<entry>If not defined but Unicode is going to be used
	then it will be defined</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect2>

	<sect2 id="wx-premk">
	<title>Processing in
	<filename>bsd.port.pre.mk</filename></title>

	<para>If you need to use the variables for running commands
	right after including <filename>bsd.port.pre.mk</filename>
	you need to define <makevar>WX_PREMK</makevar>.</para>

	<important>
	<para>If you define <makevar>WX_PREMK</makevar>, then the
	version, dependencies, components and defined variables
	will not change if you modify the
	<application>wxWidgets</application> port variables
	<emphasis>after</emphasis> including
	<filename>bsd.port.pre.mk</filename>.</para>
	</important>

	<example id="wx-premk-example">
	<title>Using <application>wxWidgets</application> Variables
	in Commands</title>

	<para>The following fragment illustrates the use of
	<makevar>WX_PREMK</makevar> by running the
	<command>wx-config</command> script to obtain the full
	version string, assign it to a variable and pass it to the
	program.</para>

	<programlisting>USE_WX= 2.4
	WX_PREMK= yes

	.include <bsd.port.pre.mk>

	.if exists(${WX_CONFIG})
	VER_STR!= ${WX_CONFIG} --release

	PLIST_SUB+= VERSION="${VER_STR}"
	.endif</programlisting>
	</example>

	<note>
	<para>The <application>wxWidgets</application> variables can
	be safely used in commands when they are inside targets
	without the need of <makevar>WX_PREMK</makevar>.</para>
	</note>
	</sect2>

	<sect2 id="wx-additional-config-args">
	<title>Additional <command>configure</command>
	Arguments</title>

	<para>Some GNU <command>configure</command> scripts can not
	find <application>wxWidgets</application> with just the
	<literal>WX_CONFIG</literal> environment variable set,
	requiring additional arguments. The
	<makevar>WX_CONF_ARGS</makevar> variable can be used for
	provide them.</para>

	<table frame="none">
	<title>Legal Values for
	<makevar>WX_CONF_ARGS</makevar></title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Possible value</entry>
	<entry>Resulting argument</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>absolute</literal></entry>
	<entry><literal>--with-wx-config=${WX_CONFIG}</literal></entry>
	</row>

	<row>
	<entry><literal>relative</literal></entry>
	<entry><literal>--with-wx=${LOCALBASE}
	--with-wx-config=${WX_CONFIG:T}</literal></entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</sect2>
	</sect1>

	<sect1 id="using-lua">
	<title>Using <application>Lua</application></title>

	<para>This section describes the status of the
	<application>Lua</application> libraries in the ports tree and
	its integration with the ports system.</para>

	<sect2 id="lua-introduction">
	<title>Introduction</title>

	<para>There are many versions of the
	<application>Lua</application> libraries and corresponding
	interpreters, which conflict between them (install files
	under the same name). In the ports tree this problem has
	been solved by installing each version under a different
	name using version number suffixes.</para>

	<para>The obvious disadvantage of this is that each
	application has to be modified to find the expected version.
	But it can be solved by adding some additional flags to the
	compiler and linker.</para>
	</sect2>

	<sect2 id="lua-version">
	<title>Version Selection</title>

	<para>To make your port use a specific version of
	<application>Lua</application> there are two variables
	available for defining (if only one is defined the other
	will be set to a default value):</para>

	<table id="lua-ver-sel-table" frame="none">
	<title>Variables to Select <application>Lua</application>
	Versions</title>

	<tgroup cols="3">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Description</entry>
	<entry>Default value</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>USE_LUA</makevar></entry>
	<entry>List of versions the port can use</entry>
	<entry>All available versions</entry>
	</row>

	<row>
	<entry><makevar>USE_LUA_NOT</makevar></entry>
	<entry>List of versions the port can not use</entry>
	<entry>None</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>The following is a list of available
	<application>Lua</application> versions and the
	corresponding ports in the tree:</para>

	<table frame="none">
	<title>Available <application>Lua</application>
	Versions</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Version</entry>
	<entry>Port</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>4.0</literal></entry>
	<entry><filename
	role="package">lang/lua4</filename></entry>
	</row>

	<row>
	<entry><literal>5.0</literal></entry>
	<entry><filename
	role="package">lang/lua50</filename></entry>
	</row>

	<row>
	<entry><literal>5.1</literal></entry>
	<entry><filename
	role="package">lang/lua</filename></entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>The variables in <xref linkend="lua-ver-sel-table"/> can
	be set to one or more of the following combinations
	separated by spaces:</para>

	<table frame="none">
	<title><application>Lua</application> Version
	Specifications</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Description</entry>
	<entry>Example</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>Single version</entry>
	<entry><literal>4.0</literal></entry>
	</row>

	<row>
	<entry>Ascending range</entry>
	<entry><literal>5.0+</literal></entry>
	</row>

	<row>
	<entry>Descending range</entry>
	<entry><literal>5.0-</literal></entry>
	</row>

	<row>
	<entry>Full range (must be ascending)</entry>
	<entry><literal>5.0-5.1</literal></entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>There are also some variables to select the preferred
	versions from the available ones. They can be set to a list
	of versions, the first ones will have higher
	priority.</para>

	<table frame="none">
	<title>Variables to Select Preferred
	<application>Lua</application> Versions</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Name</entry>
	<entry>Designed for</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>WANT_LUA_VER</makevar></entry>
	<entry>the port</entry>
	</row>

	<row>
	<entry><makevar>WITH_LUA_VER</makevar></entry>
	<entry>the user</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<example id="lua-version-example">
	<title>Selecting the <application>Lua</application>
	Version</title>

	<para>The following fragment is from a port which can use
	<application>Lua</application> version
	<literal>5.0</literal> or <literal>5.1</literal>, and uses
	<literal>5.0</literal> by default. It can be overridden
	by the user with <makevar>WITH_LUA_VER</makevar>.</para>

	<programlisting>USE_LUA= 5.0-5.1
	WANT_LUA_VER= 5.0</programlisting>
	</example>
	</sect2>

	<sect2 id="lua-components">
	<title>Component Selection</title>

	<para>There are other applications that, while not being
	<application>Lua</application> libraries, are related to
	them. These applications can be specified in the
	<makevar>LUA_COMPS</makevar> variable. The following
	components are available:</para>

	<table frame="none">
	<title>Available <application>Lua</application>
	Components</title>

	<tgroup cols="3">
	<thead>
	<row>
	<entry>Name</entry>
	<entry>Description</entry>
	<entry>Version restriction</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>lua</literal></entry>
	<entry>main library</entry>
	<entry>none</entry>
	</row>

	<row>
	<entry><literal>tolua</literal></entry>
	<entry>Library for accessing C/C++ code</entry>
	<entry><literal>4.0-5.0</literal></entry>
	</row>

	<row>
	<entry><literal>ruby</literal></entry>
	<entry>Ruby bindings</entry>
	<entry><literal>4.0-5.0</literal></entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<note>
	<para>There are more components but they are modules for the
	interpreter, not used by applications (only by other
	modules).</para>
	</note>

	<para>The dependency type can be selected for each component
	by adding a suffix separated by a semicolon. If not present
	then a default type will be used (see <xref
	linkend="lua-def-dep-types"/>). The following types are
	available:</para>

	<table frame="none">
	<title>Available <application>Lua</application> Dependency
	Types</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Name</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>build</literal></entry>
	<entry>Component is required for building, equivalent
	to <makevar>BUILD_DEPENDS</makevar></entry>
	</row>

	<row>
	<entry><literal>run</literal></entry>
	<entry>Component is required for running, equivalent
	to <makevar>RUN_DEPENDS</makevar></entry>
	</row>

	<row>
	<entry><literal>lib</literal></entry>
	<entry>Component is required for building and running,
	equivalent to <makevar>LIB_DEPENDS</makevar></entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>The default values for the components are detailed in
	the following table:</para>

	<table id="lua-def-dep-types" frame="none">
	<title>Default <application>Lua</application> Dependency
	Types</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Component</entry>
	<entry>Dependency type</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><literal>lua</literal></entry>
	<entry><literal>lib</literal> for
	<literal>4.0-5.0</literal> (shared) and
	<literal>build</literal> for <literal>5.1</literal>
	(static)</entry>
	</row>

	<row>
	<entry><literal>tolua</literal></entry>
	<entry><literal>build</literal> (static)</entry>
	</row>

	<row>
	<entry><literal>ruby</literal></entry>
	<entry><literal>lib</literal> (shared)</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<example id="lua-components-example">
	<title>Selecting <application>Lua</application>
	Components</title>

	<para>The following fragment corresponds to a port which
	uses <application>Lua</application> version
	<literal>4.0</literal> and its
	<application>Ruby</application> bindings.</para>

	<programlisting>USE_LUA= 4.0
	LUA_COMPS= lua ruby</programlisting>
	</example>
	</sect2>

	<sect2 id="lua-version-detection">
	<title>Detecting Installed Versions</title>

	<para>To detect an installed version you have to define
	<makevar>WANT_LUA</makevar>. If you do not set it to a
	specific version then the components will have a version
	suffix. The <makevar>HAVE_LUA</makevar> variable will be
	filled after detection.</para>

	<example id="lua-ver-det-example">
	<title>Detecting Installed <application>Lua</application>
	Versions and Components</title>

	<para>The following fragment can be used in a port that uses
	<application>Lua</application> if it is installed, or an
	option is selected.</para>

	<programlisting>WANT_LUA= yes

	.include <bsd.port.pre.mk>

	.if defined(WITH_LUA5) \|\| !empty(PORT_OPTIONS:MLUA5) \|\| !empty(HAVE_LUA:Mlua-5.[01])
	USE_LUA= 5.0-5.1
	CONFIGURE_ARGS+= --enable-lua5
	.endif</programlisting>

	<para>The following fragment can be used in a port that
	enables <application>tolua</application> support if it is
	installed or if an option is selected, in addition to
	<application>Lua</application>, both version
	<literal>4.0</literal>.</para>

	<programlisting>USE_LUA= 4.0
	LUA_COMPS= lua
	WANT_LUA= 4.0

	.include <bsd.port.pre.mk>

	.if defined(WITH_TOLUA) \|\| !empty(PORT_OPTIONS:MTOLUA) \|\| !empty(HAVE_LUA:Mtolua)
	LUA_COMPS+= tolua
	CONFIGURE_ARGS+= --enable-tolua
	.endif</programlisting>
	</example>
	</sect2>

	<sect2 id="lua-defined-variables">
	<title>Defined Variables</title>

	<para>The following variables are available in the port (after
	defining one from <xref
	linkend="lua-ver-sel-table"/>).</para>

	<table frame="none">
	<title>Variables Defined for Ports That Use
	<application>Lua</application></title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Name</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>LUA_VER</makevar></entry>
	<entry>The <application>Lua</application> version that
	is going to be used (e.g.,
	<literal>5.1</literal>)</entry>
	</row>

	<row>
	<entry><makevar>LUA_VER_SH</makevar></entry>
	<entry>The <application>Lua</application> shared
	library major version (e.g.,
	<literal>1</literal>)</entry>
	</row>

	<row>
	<entry><makevar>LUA_VER_STR</makevar></entry>
	<entry>The <application>Lua</application> version
	without the dots (e.g.,
	<literal>51</literal>)</entry>
	</row>

	<row>
	<entry><makevar>LUA_PREFIX</makevar></entry>
	<entry>The prefix where <application>Lua</application>
	(and components) is installed</entry>
	</row>

	<row>
	<entry><makevar>LUA_SUBDIR</makevar></entry>
	<entry>The directory under
	<filename>${PREFIX}/bin</filename>,
	<filename>${PREFIX}/share</filename> and
	<filename>${PREFIX}/lib</filename> where
	<application>Lua</application> is installed</entry>
	</row>

	<row>
	<entry><makevar>LUA_INCDIR</makevar></entry>
	<entry>The directory where
	<application>Lua</application> and
	<application>tolua</application> header files are
	installed</entry>
	</row>

	<row>
	<entry><makevar>LUA_LIBDIR</makevar></entry>
	<entry>The directory where
	<application>Lua</application> and
	<application>tolua</application> libraries are
	installed</entry>
	</row>

	<row>
	<entry><makevar>LUA_MODLIBDIR</makevar></entry>
	<entry>The directory where
	<application>Lua</application> module libraries
	(<filename>.so</filename>) are installed</entry>
	</row>

	<row>
	<entry><makevar>LUA_MODSHAREDIR</makevar></entry>
	<entry>The directory where
	<application>Lua</application> modules
	(<filename>.lua</filename>) are installed</entry>
	</row>

	<row>
	<entry><makevar>LUA_PKGNAMEPREFIX</makevar></entry>
	<entry>The package name prefix used by
	<application>Lua</application> modules</entry>
	</row>

	<row>
	<entry><makevar>LUA_CMD</makevar></entry>
	<entry>The path to the <application>Lua</application>
	interpreter</entry>
	</row>

	<row>
	<entry><makevar>LUAC_CMD</makevar></entry>
	<entry>The path to the <application>Lua</application>
	compiler</entry>
	</row>

	<row>
	<entry><makevar>TOLUA_CMD</makevar></entry>
	<entry>The path to the
	<application>tolua</application> program</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<example id="lua-variables-example">
	<title>Telling the Port Where to Find
	<application>Lua</application></title>

	<para>The following fragment shows how to tell a port that
	uses a configure script where the
	<application>Lua</application> header files and libraries
	are.</para>

	<programlisting>USE_LUA= 4.0
	GNU_CONFIGURE= yes
	CONFIGURE_ENV= CPPFLAGS="-I${LUA_INCDIR}" LDFLAGS="-L${LUA_LIBDIR}"</programlisting>
	</example>
	</sect2>

	<sect2 id="lua-premk">
	<title>Processing in
	<filename>bsd.port.pre.mk</filename></title>

	<para>If you need to use the variables for running commands
	right after including <filename>bsd.port.pre.mk</filename>
	you need to define <makevar>LUA_PREMK</makevar>.</para>

	<important>
	<para>If you define <makevar>LUA_PREMK</makevar>, then the
	version, dependencies, components and defined variables
	will not change if you modify the
	<application>Lua</application> port variables
	<emphasis>after</emphasis> including
	<filename>bsd.port.pre.mk</filename>.</para>
	</important>

	<example id="lua-premk-example">
	<title>Using <application>Lua</application> Variables in
	Commands</title>

	<para>The following fragment illustrates the use of
	<makevar>LUA_PREMK</makevar> by running the
	<application>Lua</application> interpreter to obtain the
	full version string, assign it to a variable and pass it
	to the program.</para>

	<programlisting>USE_LUA= 5.0
	LUA_PREMK= yes

	.include <bsd.port.pre.mk>

	.if exists(${LUA_CMD})
	VER_STR!= ${LUA_CMD} -v

	CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}"
	.endif</programlisting>
	</example>

	<note>
	<para>The <application>Lua</application> variables can be
	safely used in commands when they are inside targets
	without the need of <makevar>LUA_PREMK</makevar>.</para>
	</note>
	</sect2>
	</sect1>

	<sect1 id="using-xfce">
	<title>Using Xfce</title>

	<para>The <makevar>USE_XFCE</makevar> variable is used to
	autoconfigure the dependencies for ports which use an Xfce
	based library or application like <filename
	role="package">x11-toolkits/libxfce4gui</filename> and
	<filename role="package">x11-wm/xfce4-panel</filename>.</para>

	<para>The following Xfce libraries and applications are
	recognized at the moment:</para>

	<itemizedlist>
	<listitem>
	<para>libexo: <filename
	role="package">x11/libexo</filename></para>
	</listitem>

	<listitem>
	<para>libgui: <filename
	role="package">x11-toolkits/libxfce4gui</filename></para>
	</listitem>

	<listitem>
	<para>libutil: <filename
	role="package">x11/libxfce4util</filename></para>
	</listitem>

	<listitem>
	<para>libmcs: <filename
	role="package">x11/libxfce4mcs</filename></para>
	</listitem>

	<listitem>
	<para>mcsmanager: <filename
	role="package">sysutils/xfce4-mcs-manager</filename></para>
	</listitem>

	<listitem>
	<para>panel: <filename
	role="package">x11-wm/xfce4-panel</filename></para>
	</listitem>

	<listitem>
	<para>thunar: <filename
	role="package">x11-fm/thunar</filename></para>
	</listitem>

	<listitem>
	<para>wm: <filename
	role="package">x11-wm/xfce4-wm</filename></para>
	</listitem>

	<listitem>
	<para>xfdev: <filename
	role="package">dev/xfce4-dev-tools</filename></para>
	</listitem>
	</itemizedlist>

	<para>The following additional parameters are recognized:</para>

	<itemizedlist>
	<listitem>
	<para>configenv: Use this if your port requires a special
	modified <makevar>CONFIGURE_ENV</makevar> to find its
	required libraries.</para>

	<programlisting>-I&dollar;{LOCALBASE}/include -L&dollar;{LOCALBASE}/lib</programlisting>

	<para>gets added to CPPFLAGS to
	<makevar>CONFIGURE_ENV</makevar>.</para>
	</listitem>
	</itemizedlist>

	<para>Therefore, if a port has a dependency on <filename
	role="package">sysutils/xfce4-mcs-manager</filename> and
	requires the special CPPFLAGS in its configure environment,
	the syntax will be:</para>

	<programlisting>USE_XFCE= mcsmanager configenv</programlisting>
	</sect1>

	<sect1 id="using-mozilla">
	<title>Using Mozilla</title>

	<table frame="none">
	<title>Variables for Ports That Use Mozilla</title>

	<tgroup cols="2">
	<tbody>

	<row>
	<entry><makevar>USE_GECKO</makevar></entry>
	<entry>Gecko backend the port can handle. Possible
	values: <literal>libxul</literal>
	(<filename>libxul.so</filename>),
	<literal>seamonkey</literal>
	(<filename>libgtkembedmoz.so</filename>, deprecated,
	should not be used any more).</entry>
	</row>

	<row>
	<entry><makevar>USE_FIREFOX</makevar></entry>
	<entry>The port requires Firefox as a runtime
	dependency. Possible values: <literal>yes</literal>
	(get default version), <literal>40</literal>,
	<literal>36</literal>, <literal>35</literal>. Default
	dependency is on version
	<literal>40</literal>.</entry>
	</row>

	<row>
	<entry><makevar>USE_FIREFOX_BUILD</makevar></entry>
	<entry>The port requires Firefox as a buildtime
	dependency. Possible values: see USE_FIREFOX. This
	automatically sets USE_FIREFOX and assigns the same
	value.</entry>
	</row>

	<row>
	<entry><makevar>USE_SEAMONKEY</makevar></entry>
	<entry>The port requires SeaMonkey as a runtime
	dependency. Possible values: <literal>yes</literal>
	(get default version), <literal>20</literal>,
	<literal>11</literal> (deprecated, should not be used
	any more). Default dependency is on version
	<literal>20</literal>.</entry>
	</row>

	<row>
	<entry><makevar>USE_SEAMONKEY_BUILD</makevar></entry>
	<entry>The port requires SeaMonkey as a buildtime
	dependency. Possible values: see USE_SEAMONKEY. This
	automatically sets USE_SEAMONKEY and assigns the same
	value.</entry>
	</row>

	<row>
	<entry><makevar>USE_THUNDERBIRD</makevar></entry>
	<entry>The port requires Thunderbird as a runtime
	dependency. Possible values: <literal>yes</literal>
	(get default version), <literal>31</literal>,
	<literal>30</literal> (deprecated, should not be used
	any more). Default dependency is on version
	<literal>31</literal>.</entry>
	</row>

	<row>
	<entry><makevar>USE_THUNDERBIRD_BUILD</makevar></entry>
	<entry>The port requires Thunderbird as a buildtime
	dependency. Possible values: see USE_THUNDERBIRD.
	This automatically sets USE_THUNDERBIRD and assigns
	the same value.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>A complete list of available variables can be found in
	<filename>/usr/ports/Mk/bsd.gecko.mk</filename>.</para>
	</sect1>

	<sect1 id="using-databases">
	<title>Using Databases</title>

	<table frame="none">
	<title>Variables for Ports Using Databases</title>

	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Means</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>USE_BDB</makevar></entry>
	<entry>If variable is set to <literal>yes</literal>,
	add dependency on <filename
	role="package">databases/db41</filename> port. The
	variable may also be set to values: 40, 41, 42, 43,
	44, 46, 47, 48, or 51. You can declare a range of
	acceptable values, <makevar>USE_BDB</makevar>=42+ will
	find the highest installed version, and fall back to
	42 if nothing else is installed.</entry>
	</row>

	<row>
	<entry><makevar>USE_MYSQL</makevar></entry>
	<entry>If variable is set to <literal>yes</literal>, add
	dependency on <filename
	role="package">databases/mysql55-client</filename>
	port. An associated variable,
	<makevar>WANT_MYSQL_VER</makevar>, may be set to
	values such as 323, 40, 41, 50, 51, 52, 55, or
	60.</entry>
	</row>

	<row>
	<entry><makevar>USE_PGSQL</makevar></entry>
	<entry>If set to <literal>yes</literal>, add dependency
	on <filename
	role="package">databases/postgresql90-client</filename>
	port. An associated variable,
	<makevar>WANT_PGSQL_VER</makevar>, may be set to
	values such as 83, 84, 90, 91 or 92. You can declare
	a minimum or maximum value;
	<makevar>WANT_PGSQL_VER</makevar>=
	<literal> 90+</literal> will cause the
	port to depend on a minimum version of 9.0.</entry>
	</row>

	<row>
	<entry><makevar>USE_SQLITE</makevar></entry>
	<entry>If variable is set to <literal>yes</literal>, add
	dependency on
	<filename role="package">databases/sqlite3</filename>
	port. The variable may also be set to values: 3,
	2.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>More details are available in <ulink
	url="http://svn.FreeBSD.org/ports/head/Mk/bsd.database.mk?view=markup">bsd.database.mk</ulink>.</para>
	</sect1>

	<sect1 id="rc-scripts">
	<title>Starting and Stopping Services (<literal>rc</literal>
	Scripts)</title>

	<para><filename>rc.d</filename> scripts are used to start
	services on system startup, and to give administrators a
	standard way of stopping, starting and restarting the service.
	Ports integrate into the system <filename>rc.d</filename>
	framework. Details on its usage can be found in <ulink
	url="&url.books.handbook;/configtuning-rcd.html">the rc.d
	Handbook chapter</ulink>. Detailed explanation of available
	commands is provided in &man.rc.8; and &man.rc.subr.8;.
	Finally, there is <ulink url="&url.articles.rc-scripting;">an
	article</ulink> on practical aspects of
	<filename>rc.d</filename> scripting.</para>

	<para>One or more <filename>rc.d</filename> scripts can be
	installed:</para>

	<programlisting>USE_RC_SUBR= doormand</programlisting>

	<para>Scripts must be placed in the <filename>files</filename>
	subdirectory and a <literal>.in</literal> suffix must be added
	to their filename. Standard <makevar>SUB_LIST</makevar>
	expansions will be used for this file. Use of the
	<literal>%%PREFIX%%</literal> and
	<literal>%%LOCALBASE%%</literal> expansions is strongly
	encouraged as well. More on <makevar>SUB_LIST</makevar> in
	<link
	linkend="using-sub-files">the relevant
	section</link>.</para>

	<para>Prior to &os; 6.1-RELEASE, integration with
	&man.rcorder.8; is available by using
	<makevar>USE_RCORDER</makevar> instead of
	<makevar>USE_RC_SUBR</makevar>. However, use of this method
	is not necessary unless the port has an option to install
	itself in the base, or the service needs to run prior to the
	<filename>FILESYSTEMS</filename> <filename>rc.d</filename>
	script in the base.</para>

	<para>As of &os; 6.1-RELEASE, local
	<filename>rc.d</filename> scripts (including those installed
	by ports) are included in the overall &man.rcorder.8; of the
	base system.</para>

	<para>Example simple <filename>rc.d</filename> script:</para>

	<programlisting>#!/bin/sh

	# &dollar;FreeBSD&dollar;
	#
	# PROVIDE: doormand
	# REQUIRE: LOGIN
	# KEYWORD: shutdown
	#
	# Add the following lines to /etc/rc.conf.local or /etc/rc.conf
	# to enable this service:
	#
	# doormand_enable (bool): Set to NO by default.
	# Set it to YES to enable doormand.
	# doormand_config (path): Set to %%PREFIX%%/etc/doormand/doormand.cf
	# by default.

	. /etc/rc.subr

	name=doormand
	rcvar=doormand_enable

	load_rc_config $name

	: ${doormand_enable:="NO"}
	: ${doormand_config="%%PREFIX%%/etc/doormand/doormand.cf"}

	command=%%PREFIX%%/sbin/${name}
	pidfile=/var/run/${name}.pid

	command_args="-p $pidfile -f $doormand_config"

	run_rc_command "$1"</programlisting>

	<para> Unless there is a good reason to start the service
	earlier all ports scripts should use</para>

	<programlisting>REQUIRE: LOGIN</programlisting>

	<para>If the service runs as a particular user (other than root)
	this is mandatory.</para>

	<programlisting>KEYWORD: shutdown</programlisting>

	<para>is included in the script above because the mythical port
	we are using as an example starts a service, and should be
	shut down cleanly when the system shuts down. If the script
	is not starting a persistent service this is not
	necessary.</para>

	<para>For optional configuration elements the "="
	style of default variable assignment is preferable to the
	":=" style here, since the former sets a default
	value only if the variable is unset, and the latter sets one
	if the variable is unset <emphasis>or</emphasis> null. A user
	might very well include something like</para>

	<programlisting>doormand_flags=""</programlisting>

	<para>in their <filename>rc.conf.local</filename> file, and a
	variable substitution using ":=" would
	inappropriately override the user's intention. The
	<literal>_enable</literal> variable is not optional,
	and should use the ":" for the default.</para>

	<note>
	<para>No new scripts should be added with the
	<filename>.sh</filename> suffix.</para>
	</note>

	<sect2>
	<title>Stopping Services at Deinstall</title>

	<para>It is possible to have a service stopped automatically
	as part of the deinstall routine. We advise using this
	feature only when it is absolutely necessary to stop a
	service before its files go away. Usually, it is up to the
	administrator's discretion to decide, whether to stop the
	service on deinstall or not. Also note this affects
	upgrades, too.</para>

	<para>A line like this goes in the
	<filename>pkg-plist</filename>:</para>

	<programlisting>@stopdaemon doormand</programlisting>

	<para>The argument must match the content of
	<makevar>USE_RC_SUBR</makevar> variable.</para>
	</sect2>

	<sect2>
	<title>Pre-Commit Checklist</title>

	<para>Before contributing a port with an
	<filename>rc.d</filename> script, and more importantly,
	before committing one, please consult the following
	checklist to be sure that it is ready.</para>

	<procedure>
	<step>
	<para>If this is a new file, does it have
	<filename>.sh</filename> in the file name? If so that
	should be changed to just <filename>file.in</filename>
	since new <filename>rc.d</filename> files may not end
	with that extension.</para>
	</step>

	<step>
	<para>Does the file have a
	<literal>&dollar;FreeBSD&dollar;</literal> tag?</para>
	</step>

	<step>
	<para>Do the name of the file (minus
	<filename>.in</filename>), the
	<literal>PROVIDE</literal> line, and
	<literal>&dollar;</literal><replaceable>name</replaceable>
	all match? The file name matching
	<literal>PROVIDE</literal> makes debugging easier,
	especially for &man.rcorder.8; issues. Matching the
	file name and
	<literal>&dollar;</literal><replaceable>name</replaceable>
	makes it easier to figure out which variables are
	relevant in <filename>rc.conf[.local]</filename>. The
	latter is also what you might call “policy”
	for all new scripts, including those in the base
	system.</para>
	</step>

	<step>
	<para>Is the <literal>REQUIRE</literal> line set to
	<literal>LOGIN</literal>? This is mandatory for scripts
	that run as a non-root user. If it runs as root, is
	there a good reason for it to run prior to
	<literal>LOGIN</literal>? If not, it should run there
	so that we can loosely group local scripts to a point in
	&man.rcorder.8; after most everything in the base is
	already running.</para>
	</step>

	<step>
	<para>Does the script start a persistent service? If so,
	it should have <literal>KEYWORD:
	shutdown</literal>.</para>
	</step>

	<step>

	<para>Make sure there is no <literal>KEYWORD:
	FreeBSD</literal> present. This has not been
	necessary or desirable for years. It is also an
	indication that the new script was copy/pasted from an
	old script, so extra caution should be given to the
	review.</para>
	</step>

	<step>
	<para>If the script uses an interpreted language like
	<command>perl</command>, <command>python</command>, or
	<command>ruby</command>, make certain that
	<varname>command_interpreter</varname> is set
	appropriately. Otherwise,</para>

	<screen>&prompt.root; <userinput>service <replaceable>name</replaceable> stop</userinput></screen>

	<para>will probably not work properly. See
	&man.service.8; for more information.</para>
	</step>

	<step>
	<para>Have all occurrences of
	<filename>/usr/local</filename> been replaced with
	<literal>%%PREFIX%%</literal>?</para>
	</step>

	<step>
	<para>Do the default variable assignments come after
	<function>load_rc_config</function>?</para>
	</step>

	<step>
	<para>Are there default assignments to empty strings?
	They should be removed, but double-check that the option
	is documented in the comments at the top of the
	file.</para>
	</step>

	<step>
	<para>Are things that are set in variables actually used
	in the script?</para>
	</step>

	<step>
	<para>Are options listed in the default
	<replaceable>name</replaceable><varname>_flags</varname>
	things that are actually mandatory? If so, they should
	be in <varname>command_args</varname>. The
	<option>-d</option> option is a red flag (pardon the
	pun) here, since it is usually the option to
	“daemonize” the process, and therefore is
	actually mandatory.</para>
	</step>

	<step>
	<para>The
	<replaceable>name</replaceable><varname>_flags</varname>
	variable should never be included in
	<varname>command_args</varname> (and vice versa,
	although that error is less common).</para>
	</step>

	<step>
	<para>Does the script execute any code unconditionally?
	This is frowned on. Usually these things can/should be
	dealt with through a
	<function>start_precmd</function>.</para>
	</step>

	<step>
	<para>All boolean tests should utilize the
	<function>checkyesno</function> function. No
	hand-rolled tests for <literal>[Yy][Ee][Ss]</literal>,
	etc.</para>
	</step>

	<step>
	<para>If there is a loop (for example, waiting for
	something to start) does it have a counter to terminate
	the loop? We do not want the boot to be stuck forever
	if there is an error.</para>
	</step>

	<step>
	<para>Does the script create files or directories that
	need specific permissions, for example, a
	<filename>pid</filename> file that needs to be owned by
	the user that runs the process? Rather than the
	traditional &man.touch.1;/&man.chown.8;/&man.chmod.1;
	routine, consider using &man.install.1; with the proper
	command line arguments to do the whole procedure with
	one step.</para>
	</step>
	</procedure>
	</sect2>
	</sect1>

	<sect1 id="users-and-groups">
	<title>Adding Users and Groups</title>

	<para>Some ports require a certain user to be on the installed
	system. Choose a free UID from 50 to 999 and register it
	either in <filename>ports/UIDs</filename> (for users) or in
	<filename>ports/GIDs</filename> (for groups). Make sure you
	do not use a UID already used by the system or other
	ports.</para>

	<para>Please include a patch against these two files when you
	require a new user or group to be created for your
	port.</para>

	<para>Then you can use <makevar>USERS</makevar> and
	<makevar>GROUPS</makevar> variables in your
	<filename>Makefile</filename>, and the user will be
	automatically created when installing the port.</para>

	<programlisting>USERS= pulse
	GROUPS= pulse pulse-access pulse-rt</programlisting>

	<para>The current list of reserved UIDs and GIDs can be found
	in <filename>ports/UIDs</filename> and
	<filename>ports/GIDs</filename>.</para>
	</sect1>

	<sect1 id="requiring-kernel-sources">
	<title>Ports That Rely on Kernel Sources</title>

	<para>Some ports (such as kernel loadable modules) need the
	kernel source files so that the port can compile. Here is the
	correct way to determine if the user has them
	installed:</para>

	<programlisting>.if !exists(${SRC_BASE}/sys/Makefile)
	IGNORE= requires kernel sources to be installed
	.endif</programlisting>
	</sect1>
	</chapter>

	<chapter id="plist">
	<title>Advanced <filename>pkg-plist</filename> Practices</title>

	<sect1 id="plist-sub">
	<title>Changing <filename>pkg-plist</filename> Based on Make
	Variables</title>

	<para>Some ports, particularly the <literal>p5-</literal> ports,
	need to change their <filename>pkg-plist</filename> depending
	on what options they are configured with (or version of
	<literal>perl</literal>, in the case of <literal>p5-</literal>
	ports). To make this easy, any instances in the
	<filename>pkg-plist</filename> of
	<literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>,
	and <literal>%%PERL_VERSION%%</literal> will be substituted
	for appropriately. The value of <literal>%%OSREL%%</literal>
	is the numeric revision of the operating system (e.g.,
	<literal>4.9</literal>). <literal>%%PERL_VERSION%%</literal>
	and <literal>%%PERL_VER%%</literal> is the full version number
	of <command>perl</command> (e.g., <literal>5.8.9</literal>).
	Several other
	<literal>%%<replaceable>VARS</replaceable>%%</literal> related
	to port's documentation files are described in <link
	linkend="install-documentation">the relevant
	section</link>.</para>

	<para>If you need to make other substitutions, you can set the
	<makevar>PLIST_SUB</makevar> variable with a list of
	<literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal>
	pairs and instances of
	<literal>%%<replaceable>VAR</replaceable>%%</literal> will be
	substituted with <replaceable>VALUE</replaceable> in the
	<filename>pkg-plist</filename>.</para>

	<para>For instance, if you have a port that installs many files
	in a version-specific subdirectory, you can put something
	like</para>

	<programlisting>OCTAVE_VERSION= 2.0.13
	PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>

	<para>in the <filename>Makefile</filename> and use
	<literal>%%OCTAVE_VERSION%%</literal> wherever the version
	shows up in <filename>pkg-plist</filename>. That way, when
	you upgrade the port, you will not have to change dozens (or
	in some cases, hundreds) of lines in the
	<filename>pkg-plist</filename>.</para>

	<para>If your port installs files conditionally on the options
	set in the port, the usual way of handling it is prefixing the
	<filename>pkg-plist</filename> lines with a
	<literal>%%TAG%%</literal> and adding that
	<literal>TAG</literal> to the <makevar>PLIST_SUB</makevar>
	variable inside the <filename>Makefile</filename> with a
	special value of <literal>@comment</literal>, which makes
	package tools to ignore the line:</para>

	<programlisting>.if defined(WITH_X11)
	PLIST_SUB+= X11=""
	.else
	PLIST_SUB+= X11="@comment "
	.endif</programlisting>

	<para>and in the <filename>pkg-plist</filename>:</para>

	<programlisting>%%X11%%bin/foo-gui</programlisting>

	<para>This substitution (as well as addition of any <link
	linkend="makefile-manpages">manual pages</link>) will be
	done between the <maketarget>pre-install</maketarget> and
	<maketarget>do-install</maketarget> targets, by reading from
	<filename><makevar>PLIST</makevar></filename> and writing to
	<filename><makevar>TMPPLIST</makevar></filename> (default:
	<filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>).
	So if your port builds
	<filename><makevar>PLIST</makevar></filename> on the fly, do
	so in or before <maketarget>pre-install</maketarget>. Also,
	if your port needs to edit the resulting file, do so in
	<maketarget>post-install</maketarget> to a file named
	<filename><makevar>TMPPLIST</makevar></filename>.</para>

	<para>Another possibility to modify port's packing list is based
	on setting the variables <makevar>PLIST_FILES</makevar> and
	<makevar>PLIST_DIRS</makevar>. The value of each variable is
	regarded as a list of pathnames to write to
	<filename><makevar>TMPPLIST</makevar></filename> along with
	<filename><makevar>PLIST</makevar></filename> contents. Names
	listed in <makevar>PLIST_FILES</makevar> and
	<makevar>PLIST_DIRS</makevar> are subject to
	<literal>%%<replaceable>VAR</replaceable>%%</literal>
	substitution, as described above. Except for that, names from
	<makevar>PLIST_FILES</makevar> will appear in the final
	packing list unchanged, while <literal>@dirrm</literal> will
	be prepended to names from <makevar>PLIST_DIRS</makevar>. To
	take effect, <makevar>PLIST_FILES</makevar> and
	<makevar>PLIST_DIRS</makevar> must be set before
	<filename><makevar>TMPPLIST</makevar></filename> is written,
	i.e., in <maketarget>pre-install</maketarget> or
	earlier.</para>
	</sect1>

	<sect1 id="plist-cleaning">
	<title>Empty Directories</title>

	<sect2 id="plist-dir-cleaning">
	<title>Cleaning Up Empty Directories</title>

	<para>Do make your ports remove empty directories when they
	are de-installed. This is usually accomplished by adding
	<literal>@dirrm</literal> lines for all directories that are
	specifically created by the port. You need to delete
	subdirectories before you can delete parent
	directories.</para>

	<programlisting> :
	lib/X11/oneko/pixmaps/cat.xpm
	lib/X11/oneko/sounds/cat.au
	:
	@dirrm lib/X11/oneko/pixmaps
	@dirrm lib/X11/oneko/sounds
	@dirrm lib/X11/oneko</programlisting>

	<para>However, sometimes <literal>@dirrm</literal> will give
	you errors because other ports share the same directory.
	You can use <literal>@dirrmtry</literal> to remove only
	empty directories without warning.</para>

	<programlisting>@dirrmtry share/doc/gimp</programlisting>

	<para>This will neither print any error messages nor cause
	&man.pkg.delete.1; to exit abnormally even if
	<filename><makevar>${PREFIX}</makevar>/share/doc/gimp</filename>
	is not empty due to other ports installing some files in
	there.</para>
	</sect2>

	<sect2 id="plist-dir-empty">
	<title>Creating Empty Directories</title>

	<para>Empty directories created during port installation need
	special attention. They will not get created when
	installing the package, because packages only store the
	files, and &man.pkg.add.1; creates directories for them as
	needed. To make sure the empty directory is created when
	installing the package, add this line to
	<filename>pkg-plist</filename> above the corresponding
	<literal>@dirrm</literal> line:</para>

	<programlisting>@exec mkdir -p %D/share/foo/templates</programlisting>
	</sect2>
	</sect1>

	<sect1 id="plist-config">
	<title>Configuration Files</title>

	<para>If your port installs configuration files to
	<filename><makevar>PREFIX</makevar>/etc</filename> (or
	elsewhere) do <emphasis>not</emphasis> simply list them in the
	<filename>pkg-plist</filename>. That will cause
	&man.pkg.delete.1; to remove the files carefully edited by
	the user, and a re-installation will wipe them out.</para>

	<para>Instead, install sample file(s) with a
	<filename><replaceable>filename</replaceable>.sample</filename>
	suffix. Then copy the sample file to the real configuration
	file name, if it does not already exist. On deinstall
	delete the configuration file, but only if it is identical
	to the <filename>.sample</filename> file.
	You need to handle this both in the port
	<filename>Makefile</filename>, and in the
	<filename>pkg-plist</filename> (for installation from the
	package).</para>

	<para>Example of the <filename>Makefile</filename> part:</para>

	<programlisting>post-install:
	@if [ ! -f ${PREFIX}/etc/orbit.conf ]; then \
	${CP} -p ${PREFIX}/etc/orbit.conf.sample ${PREFIX}/etc/orbit.conf ; \
	fi</programlisting>

	<para>For each configuration file, create the following three
	lines in <filename>pkg-plist</filename>:</para>

	<programlisting>@unexec if cmp -s %D/etc/orbit.conf.sample %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi
	etc/orbit.conf.sample
	@exec if [ ! -f %D/etc/orbit.conf ] ; then cp -p %D/%F %B/orbit.conf; fi</programlisting>

	<para>The order of these lines is important. On deinstallation,
	the sample file is compared to the actual configuration file.
	If these files are identical, no changes have been made by the
	user and the actual file can be safely deleted. Because the
	sample file must still exist for the comparison, the
	<literal>@unexec</literal> line comes before the sample
	configuration file name. On installation, if an actual
	configuration file is not already present, the sample file is
	copied to the actual file. The sample file must be present
	before it can be copied, so the <literal>@exec</literal> line
	comes after the sample configuration file name.</para>

	<para>To debug any issues, temporarily remove the
	<literal>-s</literal> flag to &man.cmp.1; for more
	output.</para>

	<para>See &man.pkg.create.1; for more information on
	<literal>%D</literal> and related substitution markers.</para>

	<para>If there is a very good reason not to install a working
	configuration file by default, leave the
	<literal>@exec</literal> line out of
	<filename>pkg-plist</filename> and add a <link
	linkend="porting-message">message</link> pointing out that
	the user must copy and edit the file before the software will
	work.</para>
	</sect1>

	<sect1 id="plist-dynamic">
	<title>Dynamic Versus Static Package List</title>

	<para>A <emphasis>static package list</emphasis> is a package
	list which is available in the Ports Collection either as a
	<filename>pkg-plist</filename> file (with or without variable
	substitution), or embedded into the
	<filename>Makefile</filename> via
	<makevar>PLIST_FILES</makevar> and
	<makevar>PLIST_DIRS</makevar>. Even if the contents are
	auto-generated by a tool or a target in the Makefile
	<emphasis>before</emphasis> the inclusion into the Ports
	Collection by a committer, this is still considered a static
	list, since it is possible to examine it without having to
	download or compile the distfile.</para>

	<para>A <emphasis>dynamic package list</emphasis> is a package
	list which is generated at the time the port is compiled based
	upon the files and directories which are installed. It is not
	possible to examine it before the source code of the ported
	application is downloaded and compiled, or after running a
	<literal>make clean</literal>.</para>

	<para>While the use of dynamic package lists is not forbidden,
	maintainers should use static package lists wherever possible,
	as it enables users to &man.grep.1; through available ports to
	discover, for example, which port installs a certain file.
	Dynamic lists should be primarily used for complex ports where
	the package list changes drastically based upon optional
	features of the port (and thus maintaining a static package
	list is infeasible), or ports which change the package list
	based upon the version of dependent software used (e.g., ports
	which generate docs with
	<application>Javadoc</application>).</para>

	<para>Maintainers who prefer dynamic package lists are
	encouraged to add a new target to their port which generates
	the <filename>pkg-plist</filename> file so that users may
	examine the contents.</para>
	</sect1>

	<sect1 id="plist-autoplist">
	<title>Automated Package List Creation</title>

	<para>First, make sure your port is almost complete, with only
	<filename>pkg-plist</filename> missing.</para>

	<para>Next, create a temporary directory tree into which your
	port can be installed, and install any dependencies.</para>

	<screen>&prompt.root; <userinput>mkdir /var/tmp/`make -V PORTNAME`</userinput>
	&prompt.root; <userinput>mtree -U -f `make -V MTREE_FILE` -d -e -p /var/tmp/`make -V PORTNAME`</userinput>
	&prompt.root; <userinput>make depends PREFIX=/var/tmp/`make -V PORTNAME`</userinput></screen>

	<para>Store the directory structure in a new file.</para>

	- <screen>&prompt.root; <userinput>(cd /var/tmp/`make -V PORTNAME` && find -d * -type d) \| sort > OLD-DIRS</userinput></screen>
	+ <screen>&prompt.root; <userinput>(cd /var/tmp/`make -V PORTNAME` && find -d * -type d) \| sort > OLD-DIRS</userinput></screen>

	<para>Create an empty <filename>pkg-plist</filename>
	file:</para>

	<screen>&prompt.root; <userinput>:>pkg-plist</userinput></screen>

	<para>If your port honors <makevar>PREFIX</makevar> (which it
	should) you can then install the port and create the package
	list.</para>

	<screen>&prompt.root; <userinput>make install PREFIX=/var/tmp/`make -V PORTNAME`</userinput>
	-&prompt.root; <userinput>(cd /var/tmp/`make -V PORTNAME` && find -d * \! -type d) \| sort > pkg-plist</userinput></screen>
	+&prompt.root; <userinput>(cd /var/tmp/`make -V PORTNAME` && find -d * \! -type d) \| sort > pkg-plist</userinput></screen>

	<para>You must also add any newly created directories to the
	packing list.</para>

	- <screen>&prompt.root; <userinput>(cd /var/tmp/`make -V PORTNAME` && find -d * -type d) \| sort \| comm -13 OLD-DIRS - \| sort -r \| sed -e 's#^#@dirrm #' >> pkg-plist</userinput></screen>
	+ <screen>&prompt.root; <userinput>(cd /var/tmp/`make -V PORTNAME` && find -d * -type d) \| sort \| comm -13 OLD-DIRS - \| sort -r \| sed -e 's#^#@dirrm #' >> pkg-plist</userinput></screen>

	<para>Finally, you need to tidy up the packing list by hand; it
	is not <emphasis>all</emphasis> automated. Manual pages
	should be listed in the port's <filename>Makefile</filename>
	under <makevar>MAN<replaceable>n</replaceable></makevar>, and
	not in the package list. User configuration files should be
	removed, or installed as
	<filename><replaceable>filename</replaceable>.sample</filename>.
	The <filename>info/dir</filename> file should not be listed
	and appropriate <filename>install-info</filename> lines should
	be added as noted in the <link linkend="makefile-info">info
	files</link> section. Any libraries installed by the port
	should be listed as specified in the <link
	linkend="porting-shlibs">shared libraries</link>
	section.</para>

	<para>Alternatively, use the <command>plist</command> script in
	<filename>/usr/ports/Tools/scripts/</filename> to build the
	package list automatically. The <filename>plist</filename>
	script is a <application>Ruby</application> script that
	automates most of the manual steps outlined in the previous
	paragraphs.</para>

	<para>The first step is the same as above: take the first three
	lines, that is, <command>mkdir</command>,
	<command>mtree</command> and <command>make depends</command>.
	Then build and install the port:</para>

	<screen>&prompt.root; <userinput>make install PREFIX=/var/tmp/`make -V PORTNAME`</userinput></screen>

	<para>And let <command>plist</command> create the
	<filename>pkg-plist</filename> file:</para>

	<screen>&prompt.root; <userinput>/usr/ports/Tools/scripts/plist -Md -m `make -V MTREE_FILE` /var/tmp/`make -V PORTNAME` > pkg-plist</userinput></screen>

	<para>The packing list still has to be tidied up by hand as
	stated above.</para>

	<para>Another tool that might be used to create an initial
	<filename>pkg-plist</filename> is <filename
	role="package">ports-mgmt/genplist</filename>. As with any
	automated tool, the resulting <filename>pkg-plist</filename>
	should be checked and manually edited as needed.</para>
	</sect1>
	</chapter>

	<chapter id="pkg-files">
	<title>The <filename>pkg-<replaceable>*</replaceable></filename>
	Files</title>

	<para>There are some tricks we have not mentioned yet about the
	<filename>pkg-<replaceable>*</replaceable></filename> files
	that come in handy sometimes.</para>

	<sect1 id="porting-message">
	<title><filename>pkg-message</filename></title>

	<para>If you need to display a message to the installer, you may
	place the message in <filename>pkg-message</filename>. This
	capability is often useful to display additional installation
	steps to be taken after a &man.pkg.add.1; or to display
	licensing information.</para>

	<para>When some lines about the build-time knobs or warnings
	have to be displayed, use <makevar>ECHO_MSG</makevar>. The
	<filename>pkg-message</filename> file is only for
	post-installation steps. Likewise, the distinction between
	<makevar>ECHO_MSG</makevar> and <makevar>ECHO_CMD</makevar>
	should be kept in mind. The former is for printing
	informational text to the screen, while the latter is for
	command pipelining:</para>

	<programlisting>update-etc-shells:
	@${ECHO_MSG} "updating /etc/shells"
	@${CP} /etc/shells /etc/shells.bak
	@( ${GREP} -v ${PREFIX}/bin/bash /etc/shells.bak; \
	${ECHO_CMD} ${PREFIX}/bin/bash) >/etc/shells
	@${RM} /etc/shells.bak</programlisting>

	<note>
	<para>The <filename>pkg-message</filename> file does not need
	to be added to <filename>pkg-plist</filename>. Also, it
	will not get automatically printed if the user is using the
	port, not the package, so you should probably display it
	from the <maketarget>post-install</maketarget> target
	yourself.</para>
	</note>
	</sect1>

	<sect1 id="pkg-install">
	<title><filename>pkg-install</filename></title>

	<para>If your port needs to execute commands when the binary
	package is installed with &man.pkg.add.1; you can do this via
	the <filename>pkg-install</filename> script. This script will
	automatically be added to the package, and will be run twice
	by &man.pkg.add.1;: the first time as <literal>&dollar;{SH}
	pkg-install &dollar;{PKGNAME} PRE-INSTALL</literal> and the
	second time as <literal>&dollar;{SH} pkg-install
	&dollar;{PKGNAME} POST-INSTALL</literal>.
	<literal>&dollar;2</literal> can be tested to determine which
	mode the script is being run in. The
	<envar>PKG_PREFIX</envar> environmental variable will be set
	to the package installation directory. See &man.pkg.add.1;
	for additional information.</para>

	<note>
	<para>This script is not run automatically if you install the
	port with <command>make install</command>. If you are
	depending on it being run, you will have to explicitly call
	it from your port's <filename>Makefile</filename>, with a
	line like <literal>PKG_PREFIX=&dollar;{PREFIX} &dollar;{SH}
	&dollar;{PKGINSTALL} &dollar;{PKGNAME}
	PRE-INSTALL</literal>.</para>
	</note>
	</sect1>

	<sect1 id="pkg-deinstall">
	<title><filename>pkg-deinstall</filename></title>

	<para>This script executes when a package is removed.</para>

	<para>This script will be run twice by &man.pkg.delete.1;.
	The first time as <literal>&dollar;{SH} pkg-deinstall
	&dollar;{PKGNAME} DEINSTALL</literal> and the second time as
	<literal>&dollar;{SH} pkg-deinstall &dollar;{PKGNAME}
	POST-DEINSTALL</literal>.</para>
	</sect1>

	<sect1 id="pkg-req">
	<title><filename>pkg-req</filename></title>

	<para>If your port needs to determine if it should install or
	not, you can create a <filename>pkg-req</filename>
	<quote>requirements</quote> script. It will be invoked
	automatically at installation/de-installation time to
	determine whether or not installation/de-installation should
	proceed.</para>

	<para>The script will be run at installation time by
	&man.pkg.add.1; as
	<literal>pkg-req &dollar;{PKGNAME} INSTALL</literal>.
	At de-installation time it will be run by
	&man.pkg.delete.1; as
	<literal>pkg-req &dollar;{PKGNAME} DEINSTALL</literal>.</para>
	</sect1>

	<sect1 id="pkg-names">
	<title id="porting-pkgfiles">Changing the Names of
	<filename>pkg-<replaceable>*</replaceable></filename>
	Files</title>

	<para>All the names of
	<filename>pkg-<replaceable>*</replaceable></filename> files
	are defined using variables so you can change them in your
	<filename>Makefile</filename> if need be. This is especially
	useful when you are sharing the same
	<filename>pkg-<replaceable>*</replaceable></filename> files
	among several ports or have to write to one of the above files
	(see <link linkend="porting-wrkdir">writing to places other
	than <makevar>WRKDIR</makevar></link> for why it is a bad
	idea to write directly into the
	<filename>pkg-<replaceable>*</replaceable></filename>
	subdirectory).</para>

	<para>Here is a list of variable names and their default values.
	(<makevar>PKGDIR</makevar> defaults to
	<makevar>${MASTERDIR}</makevar>.)</para>

	<informaltable frame="none" pgwide="0">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Default value</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>DESCR</makevar></entry>
	<entry><literal>${PKGDIR}/pkg-descr</literal></entry>
	</row>

	<row>
	<entry><makevar>PLIST</makevar></entry>
	<entry><literal>${PKGDIR}/pkg-plist</literal></entry>
	</row>

	<row>
	<entry><makevar>PKGINSTALL</makevar></entry>
	<entry><literal>${PKGDIR}/pkg-install</literal></entry>
	</row>

	<row>
	<entry><makevar>PKGDEINSTALL</makevar></entry>
	<entry><literal>${PKGDIR}/pkg-deinstall</literal></entry>
	</row>

	<row>
	<entry><makevar>PKGREQ</makevar></entry>
	<entry><literal>${PKGDIR}/pkg-req</literal></entry>
	</row>

	<row>
	<entry><makevar>PKGMESSAGE</makevar></entry>
	<entry><literal>${PKGDIR}/pkg-message</literal></entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<para>Please change these variables rather than overriding
	<makevar>PKG_ARGS</makevar>. If you change
	<makevar>PKG_ARGS</makevar>, those files will not correctly be
	installed in <filename>/var/db/pkg</filename> upon install
	from a port.</para>
	</sect1>

	<sect1 id="using-sub-files">
	<title>Making Use of <makevar>SUB_FILES</makevar> and
	<makevar>SUB_LIST</makevar></title>

	<para>The <makevar>SUB_FILES</makevar> and
	<makevar>SUB_LIST</makevar> variables are useful for dynamic
	values in port files, such as the installation
	<makevar>PREFIX</makevar> in
	<filename>pkg-message</filename>.</para>

	<para>The <makevar>SUB_FILES</makevar> variable specifies a list
	of files to be automatically modified. Each
	<replaceable>file</replaceable> in the
	<makevar>SUB_FILES</makevar> list must have a corresponding
	<filename><replaceable>file</replaceable>.in</filename>
	present in <makevar>FILESDIR</makevar>. A modified version
	will be created in <makevar>WRKDIR</makevar>. Files defined
	as a value of <makevar>USE_RC_SUBR</makevar> (or the
	deprecated <makevar>USE_RCORDER</makevar>) are automatically
	added to the <makevar>SUB_FILES</makevar>. For the files
	<filename>pkg-message</filename>,
	<filename>pkg-install</filename>,
	<filename>pkg-deinstall</filename> and
	<filename>pkg-req</filename>, the corresponding Makefile
	variable is automatically set to point to the processed
	version.</para>

	<para>The <makevar>SUB_LIST</makevar> variable is a list of
	<literal>VAR=VALUE</literal> pairs. For each pair
	<literal>%%VAR%%</literal> will get replaced with
	<literal>VALUE</literal> in each file listed in
	<makevar>SUB_FILES</makevar>. Several common pairs are
	automatically defined: <makevar>PREFIX</makevar>,
	<makevar>LOCALBASE</makevar>, <makevar>DATADIR</makevar>,
	- <makevar>DOCSDIR</makevar>, <makevar>EXAMPLESDIR</makevar>.
	+ <makevar>DOCSDIR</makevar>, <makevar>EXAMPLESDIR</makevar>,
	+ <makevar>WWWDIR</makevar>, and <makevar>ETCDIR</makevar>.
	Any line beginning with <literal>@comment</literal> will be
	deleted from resulting files after a variable
	substitution.</para>

	<para>The following example will replace
	<literal>%%ARCH%%</literal> with the system architecture in a
	<filename>pkg-message</filename>:</para>

	<programlisting>SUB_FILES= pkg-message
	SUB_LIST= ARCH=${ARCH}</programlisting>

	<para>Note that for this example, the
	<filename>pkg-message.in</filename> file must exist in
	<makevar>FILESDIR</makevar>.</para>

	<para>Example of a good
	<filename>pkg-message.in</filename>:</para>

	<programlisting>Now it is time to configure this package.
	Copy %%PREFIX%%/share/examples/putsy/%%ARCH%%.conf into your home directory
	as .putsy.conf and edit it.</programlisting>
	</sect1>
	</chapter>

	<chapter id="testing">
	<title>Testing Your Port</title>

	<sect1 id="make-describe">
	<title>Running <command>make describe</command></title>

	<para>Several of the &os; port maintenance tools, such as
	&man.portupgrade.1;, rely on a database called
	<filename>/usr/ports/INDEX</filename> which keeps track of
	such items as port dependencies. <filename>INDEX</filename>
	is created by the top-level
	<filename>ports/Makefile</filename> via <command>make
	index</command>, which descends into each port subdirectory
	and executes <command>make describe</command> there. Thus, if
	<command>make describe</command> fails in any port, no one can
	generate <filename>INDEX</filename>, and many people will
	quickly become unhappy.</para>

	<note>
	<para>It is important to be able to generate this file no
	matter what options are present in
	<filename>make.conf</filename>, so please avoid doing things
	such as using <literal>.error</literal> statements when (for
	instance) a dependency is not satisfied. (See <xref
	linkend="dads-dot-error"/>.)</para>
	</note>

	<para>If <command>make describe</command> produces a string
	rather than an error message, you are probably safe. See
	<filename>bsd.port.mk</filename> for the meaning of the
	string produced.</para>

	<para>Also note that running a recent version of
	<command>portlint</command> (as specified in the next section)
	will cause <command>make describe</command> to be run
	automatically.</para>
	</sect1>

	<sect1 id="testing-portlint">
	<title>Portlint</title>

	<para>Do check your work with <link
	linkend="porting-portlint"><command>portlint</command></link>
	before you submit or commit it. <command>portlint</command>
	warns you about many common errors, both functional and
	stylistic. For a new (or repocopied) port, <command>portlint
	-A</command> is the most thorough; for an existing port,
	<command>portlint -C</command> is sufficient.</para>

	<para>Since <command>portlint</command> uses heuristics to
	try to figure out errors, it can produce false positive
	warnings. In addition, occasionally something that is
	flagged as a problem really cannot be done in any other
	way due to limitations in the ports framework. When in
	doubt, the best thing to do is ask on &a.ports;.</para>
	</sect1>

	<sect1 id="testing-porttools">
	<title>Port Tools</title>

	<para>The <filename
	role="package">ports-mgmt/porttools</filename> program is
	part of the Ports Collection.</para>

	<para><command>port</command> is the front-end script, which can
	help you simplify the testing job. Whenever you want to test
	a new port or update an existing one, you can use
	<command>port test</command> to test your port, including the
	<link
	linkend="testing-portlint"><command>portlint</command></link>
	checking. This command also detects and lists any files that
	are not listed in <filename>pkg-plist</filename>. See the
	following example:</para>

	<screen>&prompt.root; <userinput>port test /usr/ports/net/csup</userinput></screen>
	</sect1>

	<sect1 id="porting-prefix">
	<title><makevar>PREFIX</makevar> and
	<makevar>DESTDIR</makevar></title>

	<para><makevar>PREFIX</makevar> determines where the port will
	be installed. It defaults to <filename>/usr/local</filename>,
	but can be set by the user to a custom path like
	<filename>/opt</filename>. Your port must respect the value
	of this variable.</para>

	<para><makevar>DESTDIR</makevar>, if set by the user, determines
	the complete alternative environment, usually a jail or an
	installed system mounted somewhere other than
	<filename>/</filename>. A port will actually install into
	<filename><makevar>DESTDIR</makevar>/<makevar>PREFIX</makevar></filename>,
	and register with the package database in
	<filename><makevar>DESTDIR</makevar>/var/db/pkg</filename>.
	As <makevar>DESTDIR</makevar> is handled automatically by the
	ports infrastructure with &man.chroot.8;, you do not need any
	modifications or any extra care to write
	<makevar>DESTDIR</makevar>-compliant ports.</para>

	<para>The value of <makevar>PREFIX</makevar> will be set to
	<makevar>LOCALBASE</makevar> (defaulting to
	<filename>/usr/local</filename>). If
	<makevar>USE_LINUX_PREFIX</makevar> is set,
	<makevar>PREFIX</makevar> will be <makevar>LINUXBASE</makevar>
	(defaulting to <filename>/compat/linux</filename>).</para>

	<para>Avoiding hard-coded <filename>/usr/local</filename> paths
	in the source makes the port much more flexible and able to
	cater to the needs of other sites. Often, this can be
	accomplished by simply replacing occurrences of
	<filename>/usr/local</filename> in the port's various
	<filename>Makefile</filename>s with
	<literal>&dollar;{PREFIX}</literal>. This variable is
	automatically passed down to every stage of the build and
	install processes.</para>

	<para>Make sure your application is not installing things in
	<filename>/usr/local</filename> instead of
	<makevar>PREFIX</makevar>. A quick test for such hard-coded
	paths is:</para>

	<screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/`make -V PORTNAME`</userinput></screen>

	<para>If anything is installed outside of
	<makevar>PREFIX</makevar>, the package creation process will
	complain that it cannot find the files.</para>

	<para>This test will not find hard-coded paths inside the
	port's files, nor will it verify that
	<makevar>LOCALBASE</makevar> is being used to correctly refer
	to files from other ports. The temporarily-installed port in
	<filename>/var/tmp/`make -V PORTNAME`</filename> should be
	tested for proper operation to make sure there
	are no problems with paths.</para>

	<para><makevar>PREFIX</makevar> should not be set explicitly
	in a port's <filename>Makefile</filename>. Users installing
	the port may have set <makevar>PREFIX</makevar> to a custom
	location, and the port should respect that setting.</para>

	<para>Refer to programs and files from other ports with the
	variables mentioned above, not explicit pathnames. For
	instance, if your port requires a macro
	<literal>PAGER</literal> to have the full pathname of
	<command>less</command>, do not use a literal path of
	<filename>/usr/local/bin/less</filename>. Instead, use
	<literal>&dollar;{LOCALBASE}</literal>:</para>

	<programlisting>-DPAGER=\"&dollar;{LOCALBASE}/bin/less\"</programlisting>

	<para>The path with <makevar>LOCALBASE</makevar> is more likely
	to still work if the system administrator has moved the whole
	<filename>/usr/local</filename> tree somewhere else.</para>
	</sect1>

	<sect1 id="testing-tinderbox">
	<title>Tinderbox</title>

	<para>If you are an avid ports contributor, you might want to
	take a look at <application>Tinderbox</application>. It is a
	powerful system for building and testing ports based on the
	scripts used on <link
	linkend="build-cluster">Pointyhat</link>. You can install
	<application>Tinderbox</application> using <filename
	role="package">ports-mgmt/tinderbox</filename> port. Be
	sure to read supplied documentation since the configuration is
	not trivial.</para>

	<para>Visit the <ulink
	url="http://tinderbox.marcuscom.com/">Tinderbox
	website</ulink> for more details.</para>
	</sect1>
	</chapter>

	<chapter id="port-upgrading">
	<title>Upgrading an Individual Port</title>

	<para>When you notice that a port is out of date compared to the
	latest version from the original authors, you should first
	ensure that you have the latest port. You can find them in the
	<filename>ports/ports-current</filename> directory of the &os;
	FTP mirror sites. However, if you are working with more than a
	few ports, you will probably find it easier to use
	<application>Subversion</application> or &man.portsnap.8;
	to keep your whole ports
	collection up-to-date, as described in the <ulink
	- url="&url.books.handbook;/synching.html#CVSUP-CONFIG">Handbook</ulink>.
	+ url="&url.books.handbook;/ports-using.html">Handbook</ulink>.
	This will have the added benefit of tracking all the ports'
	dependencies.</para>

	<para>The next step is to see if there is an update already
	pending. To do this, you have two options. There is a
	searchable interface to the <ulink
	url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
	FreeBSD Problem Report (PR) database</ulink> (also known as
	<literal>GNATS</literal>). Select <literal>ports</literal> in
	the dropdown, and enter the name of the port.</para>

	<para>However, sometimes people forget to put the name of the port
	into the Synopsis field in an unambiguous fashion. In that
	case, you can try the <link linkend="portsmon"> FreeBSD Ports
	Monitoring System</link> (also known as
	<literal>portsmon</literal>). This system attempts to classify
	port PRs by portname. To search for PRs about a particular
	port, use the <ulink
	- url="http://portsmon.FreeBSD.org/portoverview.py">
	- Overview of One Port</ulink>.</para>
	+ url="http://portsmon.FreeBSD.org/portoverview.py">Overview of
	+ One Port</ulink>.</para>

	<para>If there is no pending PR, the next step is to send an email
	to the port's maintainer, as shown by <command>make
	maintainer</command>. That person may already be working on
	an upgrade, or have a reason to not upgrade the port right now
	(because of, for example, stability problems of the new
	version); you would not want to duplicate their work. Note that
	unmaintained ports are listed with a maintainer of
	<literal>ports@FreeBSD.org</literal>, which is just the general
	ports mailing list, so sending mail there probably will not help
	in this case.</para>

	<para>If the maintainer asks you to do the upgrade or there is
	no maintainer, then you have a chance to help out &os; by
	preparing the update yourself! Please do this by using the
	&man.diff.1; command in the base system.</para>

	<para>To create a suitable <command>diff</command> for a single
	patch, copy the file that needs patching to
	<replaceable>something.orig</replaceable>, save your changes to
	<replaceable>something</replaceable> and then create your
	patch:</para>

	<informalexample>
	<screen>&prompt.user; <userinput>diff -u something.orig something > something.diff</userinput></screen>
	</informalexample>

	<para>Otherwise, you should either use the <command>svn
	diff</command> method (<xref linkend="svn-diff"/>) or copy the
	contents of the port to an entire different directory and use
	the result of the recursive &man.diff.1; output of the new and
	old ports directories (e.g., if your modified port directory is
	called <filename>superedit</filename> and the original is in our
	tree as <filename>superedit.bak</filename>, then save the result
	of <command>diff -ruN superedit.bak superedit</command>).
	Either unified or context diff is fine, but port committers
	generally prefer unified diffs. Note the use of the
	<literal>-N</literal> option—this is the accepted way to
	force diff to properly deal with the case of new files being
	added or old files being deleted. Before sending us the diff,
	please examine the output to make sure all the changes make
	sense. (In particular, make sure you first clean out the work
	directories with <command>make clean</command>).</para>

	<para>To simplify common operations with patch files, you can use
	<filename>/usr/ports/Tools/scripts/patchtool.py</filename>.
	Before using it, please read
	<filename>/usr/ports/Tools/scripts/README.patchtool</filename>.</para>

	<para>If the port is unmaintained, and you are actively using
	it yourself, please consider volunteering to become its
	maintainer. &os; has over 4000 ports without maintainers, and
	this is an area where more volunteers are always needed. (For a
	detailed description of the responsibilities of maintainers,
	refer to the section in the <ulink
	url="&url.books.developers-handbook;/policies.html#POLICIES-MAINTAINER">
	Developer's Handbook</ulink>.)</para>

	<para> The best way to send us the diff is by including it via
	&man.send-pr.1; (category <literal>ports</literal>). If you are
	maintaining the port, be sure to put <literal>[maintainer
	update]</literal> at the beginning of your synopsis line and set
	the <quote>Class</quote> of your PR to
	<literal>maintainer-update</literal>. Otherwise, the
	<quote>Class</quote> of your PR should be
	<literal>change-request</literal>. Please mention any added or
	deleted files in the message, as they have to be explicitly
	specified to &man.svn.1; when doing a commit. If the diff is
	more than about 20KB, please compress and uuencode it;
	otherwise, just include it in the PR as is.</para>

	<para>Before you &man.send-pr.1;, you should review the
	<ulink url="&url.articles.problem-reports;/pr-writing.html">
	Writing the problem report</ulink> section in the Problem
	Reports article; it contains far more information about how to
	write useful problem reports.</para>

	<important>
	<para>If your upgrade is motivated by security concerns or a
	serious fault in the currently committed port, please notify
	the &a.portmgr; to request immediate rebuilding and
	redistribution of your port's package. Unsuspecting users
	of &man.pkg.add.1; will otherwise continue to install the
	old version via <command>pkg_add -r</command> for several
	weeks.</para>
	</important>

	<note>
	<para>Once again, please use &man.diff.1; and not &man.shar.1;
	to send updates to existing ports! This helps ports
	committers understand exactly what is being changed.</para>
	</note>

	<para>Now that you have done all that, you will want to read about
	how to keep up-to-date in <xref linkend="keeping-up"/>.</para>

	<sect1 id="svn-diff">
	<title>Using <literal>SVN</literal> to Make Patches</title>

	- <para>If you can, please submit a &man.svn.1 diff; they are
	- easier to handle than diffs between <quote>new and old</quote>
	- directories. Plus it is easier for you to see what you have
	- changed and to update your diff if something is modified in
	- the Ports Collection from when you started to work on it until
	- you submit your changes, or if the committer asks you to fix
	- something.</para>
	+ <para>If you can, please submit a &man.svn.1; diff — they
	+ are easier to handle than diffs between <quote>new and
	+ old</quote> directories. Plus it is easier for you to see
	+ what you have changed and to update your diff if something is
	+ modified in the Ports Collection from when you started to work
	+ on it until you submit your changes, or if the committer asks
	+ you to fix something.</para>

	<screen>&prompt.user; <userinput>cd ~/my_wrkdir</userinput> <co id="my-wrkdir"/>
	-&prompt.user; <userinput>svn co svn://svn.FreeBSD.org/ports/head/dns/pdnsd</userinput> <co id="svn-FreeBSD-org"/>
	+&prompt.user; <userinput>svn co <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/ports/head/dns/pdnsd</userinput> <co id="svn-FreeBSD-org"/>
	&prompt.user; <userinput>cd ~/my_wrkdir/pdnsd</userinput></screen>

	<calloutlist>
	<callout arearefs="my-wrkdir">

	<para>This can be anywhere you want, of course; building
	ports is not limited to within <filename
	class="directory">/usr/ports/</filename>.</para>
	</callout>

	<callout arearefs="svn-FreeBSD-org">
	<para><ulink
	- url="http://svn.FreeBSD.org/">svn.FreeBSD.org</ulink>
	- is a public <literal>SVN</literal> server.</para>
	+ url="https://svn0.us-west.FreeBSD.org/">svn0.us-west.FreeBSD.org</ulink>
	+ is a public <literal>SVN</literal> server.
	+ Select the closest mirror and verify the mirror server
	+ certificate from the list of <ulink
	+ url="&url.books.handbook;/svn-mirrors.html">Subversion
	+ mirror sites</ulink>.</para>
	</callout>
	</calloutlist>

	<para>While in the working directory, make any changes that you
	would usually make to the port. If you add or remove a file,
	use <command>svn</command> to track these changes:</para>

	<screen>&prompt.user; <userinput>svn add new_file</userinput>
	&prompt.user; <userinput>svn remove deleted_file</userinput></screen>

	<para>Make sure that you check the port using the checklist in
	<xref linkend="porting-testing"/> and
	<xref linkend="porting-portlint"/>.</para>

	<screen>&prompt.user; <userinput>svn status</userinput>
	&prompt.user; <userinput>svn update</userinput> <co id="svn-update"/></screen>

	<calloutlist>
	<callout arearefs="svn-update">
	<para>This will try to merge the differences between your
	patch and current SVN; watch the output carefully. The
	letter in front of each file name indicates what was done
	with it. See <xref linkend="table-svn-up"/> for a
	complete list.</para>
	</callout>
	</calloutlist>

	<table pgwide="1" frame="none" id="table-svn-up">
	<title><literal>SVN</literal> Update File Prefixes</title>

	<tgroup cols="2">
	<tbody>
	<row>
	<entry>U</entry>
	<entry>The file was updated without problems.</entry>
	</row>

	<row>
	<entry>G</entry>
	<entry>The file was updated without problems (you will
	only see this when working against a remote
	repository).</entry>
	</row>

	<row>
	<entry>M</entry>
	<entry>The file had been modified, and was merged
	without conflicts.</entry>
	</row>

	<row>
	<entry>C</entry>
	<entry>The file had been modified, and was merged with
	conflicts.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>If you get <literal>C</literal> as a result of
	<command>svn update</command> it means something changed in
	the SVN repository and &man.svn.1; was not able to merge your
	local changes and those from the repository. It is always a
	good idea to inspect the changes anyway, since &man.svn.1;
	does not know anything about how a port should be, so it might
	(and probably will) merge things that do not make
	sense.</para>

	<para>The last step is to make a unified &man.diff.1;
	of the files against SVN:</para>

	<screen>&prompt.user; <userinput>svn diff > ../`basename ${PWD}`.diff</userinput></screen>

	<note>
	<para>Any files that have been removed should be explicitly
	mentioned in the PR, because file removal may not be obvious
	to the committer.</para>
	</note>

	<para>Send your patch following the guidelines in
	<xref linkend="port-upgrading"/>.</para>
	</sect1>

	<sect1 id="moved-and-updating-files">
	<title>The Files <filename>UPDATING</filename> and
	<filename>MOVED</filename></title>

	<para>If upgrading the port requires special steps like
	changing configuration files or running a specific program,
	you should document this in the file
	<filename>/usr/ports/UPDATING</filename>. The format of
	an entry in this file is as follows:</para>

	<programlisting>YYYYMMDD:
	AFFECTS: users of portcategory/portname
	AUTHOR: Your name <Your email address>

	Special instructions</programlisting>

	<para>If you are including exact portmaster or portupgrading
	instructions, please make sure to get the shell escaping
	right.</para>

	<para>The <filename>/usr/ports/MOVED</filename> file is used to
	list moved or removed ports. Each line in the file is made
	up of the name of the port, where the port was moved to, when,
	and why. If the port was removed, the section detailing where
	it was moved to can be left blank. Each section must be
	separated by the <literal>\|</literal> (pipe) character, like
	so:</para>

	<programlisting>old name\|new name (blank for deleted)\|date of move\|reason</programlisting>

	<para>The date should be entered in the form <literal>YYYY-
	MM-DD</literal>. New entries should be added to the end
	of the file to keep it in chronological order.</para>

	<para>If a port was removed but has since been restored,
	delete the line in this file that states that it was
	removed.</para>

	<para>The changes can be validated with
	<command>Tools/scripts/MOVEDlint.awk</command>.</para>
	</sect1>
	</chapter>

	<chapter id="security">
	<title>Ports Security</title>

	<sect1 id="security-intro">
	<title>Why Security is So Important</title>

	<para>Bugs are occasionally introduced to the software.
	Arguably, the most dangerous of them are those opening
	security vulnerabilities. From the technical viewpoint,
	such vulnerabilities are to be closed by exterminating
	the bugs that caused them. However, the policies for
	handling mere bugs and security vulnerabilities are
	very different.</para>

	<para>A typical small bug affects only those users who have
	enabled some combination of options triggering the bug.
	The developer will eventually release a patch followed
	by a new version of the software, free of the bug, but
	the majority of users will not take the trouble of upgrading
	immediately because the bug has never vexed them. A
	critical bug that may cause data loss represents a graver
	issue. Nevertheless, prudent users know that a lot of
	possible accidents, besides software bugs, are likely to
	lead to data loss, and so they make backups of important
	data; in addition, a critical bug will be discovered
	really soon.</para>

	<para>A security vulnerability is all different. First,
	it may remain unnoticed for years because often it does
	not cause software malfunction. Second, a malicious party
	can use it to gain unauthorized access to a vulnerable
	system, to destroy or alter sensitive data; and in the
	worst case the user will not even notice the harm caused.
	Third, exposing a vulnerable system often assists attackers
	to break into other systems that could not be compromised
	otherwise. Therefore closing a vulnerability alone is
	not enough: the audience should be notified of it in most
	clear and comprehensive manner, which will allow to
	evaluate the danger and take appropriate actions.</para>
	</sect1>

	<sect1 id="security-fix">
	<title>Fixing Security Vulnerabilities</title>

	<para>While on the subject of ports and packages, a security
	vulnerability may initially appear in the original
	distribution or in the port files. In the former case, the
	original software developer is likely to release a patch or a
	new version instantly, and you will only need to update the
	port promptly with respect to the author's fix. If the fix is
	delayed for some reason, you should either <link
	linkend="dads-noinstall">mark the port as
	<makevar>FORBIDDEN</makevar></link> or introduce a patch file
	of your own to the port. In the case of a vulnerable port,
	just fix the port as soon as possible. In either case, <link
	linkend="port-upgrading">the standard procedure for
	submitting your change</link> should be followed unless you
	have rights to commit it directly to the ports tree.</para>

	<important>
	<para>Being a ports committer is not enough to commit to
	an arbitrary port. Remember that ports usually have
	maintainers, whom you should respect.</para>
	</important>

	<para>Please make sure that the port's revision is bumped
	as soon as the vulnerability has been closed.
	That is how the users who upgrade installed packages
	on a regular basis will see they need to run an update.
	Besides, a new package will be built and distributed
	over FTP and WWW mirrors, replacing the vulnerable one.
	<makevar>PORTREVISION</makevar> should be bumped unless
	<makevar>PORTVERSION</makevar> has changed in the course
	of correcting the vulnerability. That is you should
	bump <makevar>PORTREVISION</makevar> if you have added a
	patch file to the port, but you should not if you have updated
	the port to the latest software version and thus already
	touched <makevar>PORTVERSION</makevar>. Please refer to the
	<link linkend="makefile-naming-revepoch">corresponding
	section</link> for more information.</para>
	</sect1>

	<sect1 id="security-notify">
	<title>Keeping the Community Informed</title>

	<sect2 id="security-notify-vuxml-db">
	<title>The VuXML Database</title>

	<para>A very important and urgent step to take as early after
	a security vulnerability is discovered as possible is to
	notify the community of port users about the jeopardy. Such
	notification serves two purposes. First, should the danger
	be really severe it will be wise to apply an instant
	workaround. E.g., stop the affected network service or even
	deinstall the port completely until the vulnerability is
	closed. Second, a lot of users tend to upgrade installed
	packages only occasionally. They will know from the
	notification that they <emphasis>must</emphasis> update the
	package without delay as soon as a corrected version is
	available.</para>

	<para>Given the huge number of ports in the tree
	a security advisory cannot be issued on each incident
	without creating a flood and losing the attention of
	the audience when it comes to really serious
	matters. Therefore security vulnerabilities found in
	ports are recorded in <ulink
	url="http://vuxml.freebsd.org/">the FreeBSD VuXML
	database</ulink>. The Security Officer Team members
	also monitor it for issues requiring their
	intervention.</para>

	<para>If you have committer rights you can update the VuXML
	database by yourself. So you will both help the Security
	Officer Team and deliver the crucial information to the
	community earlier. However, if you are not a committer,
	or you believe you have found an exceptionally severe
	vulnerability please do not hesitate to
	contact the Security Officer Team directly as described
	on the <ulink
	url="http://www.freebsd.org/security/#how">FreeBSD
	Security Information</ulink> page.</para>

	<para>The VuXML database is an
	XML document. Its source file <filename>vuln.xml</filename>
	is kept right inside the port <filename
	role="package">security/vuxml</filename>. Therefore
	the file's full pathname will be
	<filename><envar>PORTSDIR</envar>/security/vuxml/vuln.xml</filename>.
	Each time you discover a security vulnerability in a
	port please add an entry for it to that file.
	Until you are familiar with VuXML, the best thing you can
	do is to find an existing entry fitting your case, then copy
	it and use it as a template.</para>
	</sect2>

	<sect2 id="security-notify-vuxml-intro">
	<title>A Short Introduction to VuXML</title>

	<para>The full-blown XML format is complex, and far beyond the
	scope of this book. However, to gain basic insight on the
	structure of a VuXML entry you need only the notion of tags.
	XML tag names are enclosed in angle brackets. Each opening
	<tag> must have a matching closing </tag>. Tags
	may be nested. If nesting, the inner tags must be closed
	before the outer ones. There is a hierarchy of tags, i.e.,
	more complex rules of nesting them. This is similar to
	HTML. The major difference is that XML is
	e<emphasis>X</emphasis>tensible, i.e., based on defining
	custom tags. Due to its intrinsic structure XML puts
	otherwise amorphous data into shape. VuXML is particularly
	tailored to mark up descriptions of security
	vulnerabilities.</para>

	<para>Now consider a realistic VuXML entry:</para>

	<programlisting><vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> <co id="co-vx-vid"/>
	<topic>Several vulnerabilities found in Foo</topic> <co id="co-vx-top"/>
	<affects>
	<package>
	<name>foo</name> <co id="co-vx-nam"/>
	<name>foo-devel</name>
	<name>ja-foo</name>
	<range><ge>1.6</ge><lt>1.9</lt></range> <co id="co-vx-rng"/>
	<range><ge>2.*</ge><lt>2.4_1</lt></range>
	<range><eq>3.0b1</eq></range>
	</package>
	<package>
	<name>openfoo</name> <co id="co-vx-nm2"/>
	<range><lt>1.10_7</lt></range> <co id="co-vx-epo"/>
	<range><ge>1.2,1</ge><lt>1.3_1,1</lt></range>
	</package>
	</affects>
	<description>
	<body xmlns="http://www.w3.org/1999/xhtml">
	<p>J. Random Hacker reports:</p> <co id="co-vx-bdy"/>
	<blockquote
	cite="http://j.r.hacker.com/advisories/1">
	<p>Several issues in the Foo software may be exploited
	via carefully crafted QUUX requests. These requests will
	permit the injection of Bar code, mumble theft, and the
	readability of the Foo administrator account.</p>
	</blockquote>
	</body>
	</description>
	<references> <co id="co-vx-ref"/>
	<freebsdsa>SA-10:75.foo</freebsdsa> <co id="co-vx-fsa"/>
	<freebsdpr>ports/987654</freebsdpr> <co id="co-vx-fpr"/>
	<cvename>CAN-2010-0201</cvename> <co id="co-vx-cve"/>
	<cvename>CAN-2010-0466</cvename>
	<bid>96298</bid> <co id="co-vx-bid"/>
	<certsa>CA-2010-99</certsa> <co id="co-vx-cts"/>
	<certvu>740169</certvu> <co id="co-vx-ctv"/>
	<uscertsa>SA10-99A</uscertsa> <co id="co-vx-ucs"/>
	<uscertta>SA10-99A</uscertta> <co id="co-vx-uct"/>
	<mlist msgid="201075606@hacker.com">http://marc.theaimsgroup.com/?l=bugtraq&amp;m=203886607825605</mlist> <co id="co-vx-mls"/>
	<url>http://j.r.hacker.com/advisories/1</url> <co id="co-vx-url"/>
	</references>
	<dates>
	<discovery>2010-05-25</discovery> <co id="co-vx-dsc"/>
	<entry>2010-07-13</entry> <co id="co-vx-ent"/>
	<modified>2010-09-17</modified> <co id="co-vx-mod"/>
	</dates>
	</vuln></programlisting>

	<para>The tag names are supposed to be self-explanatory
	so we shall take a closer look only at fields you will need
	to fill in by yourself:</para>

	<calloutlist>
	<callout arearefs="co-vx-vid">
	<para>This is the top-level tag of a VuXML entry. It has
	a mandatory attribute, <literal>vid</literal>,
	specifying a universally unique identifier (UUID) for
	this entry (in quotes). You should generate a UUID for
	each new VuXML entry (and do not forget to substitute it
	for the template UUID unless you are writing the entry
	from scratch). You can use &man.uuidgen.1; to generate
	a VuXML UUID.</para>
	</callout>

	<callout arearefs="co-vx-top">
	<para>This is a one-line description of the issue
	found.</para>
	</callout>

	<callout arearefs="co-vx-nam">
	<para>The names of packages affected are listed there.
	Multiple names can be given since several packages may
	be based on a single master port or software product.
	This may include stable and development branches,
	localized versions, and slave ports featuring different
	choices of important build-time configuration
	options.</para>

	<important>
	<para>It is your responsibility to find all such related
	packages when writing a VuXML entry. Keep in mind
	that <literal>make search name=foo</literal> is your
	friend. The primary points to look for are as
	follows:</para>

	<itemizedlist>
	<listitem>
	<para>the <filename>foo-devel</filename> variant
	for a <filename>foo</filename> port;</para>
	</listitem>

	<listitem>
	<para>other variants with a suffix like
	<literal>-a4</literal> (for print-related
	packages), <literal>-without-gui</literal> (for
	packages with X support disabled), or
	similar;</para>
	</listitem>

	<listitem>
	<para><literal>jp-</literal>,
	<literal>ru-</literal>, <literal>zh-</literal>,
	and other possible localized variants in the
	corresponding national categories of the ports
	collection.</para>
	</listitem>
	</itemizedlist>
	</important>
	</callout>

	<callout arearefs="co-vx-rng">
	<para>Affected versions of the package(s) are specified
	there as one or more ranges using a combination of
	<literal><lt></literal>,
	<literal><le></literal>,
	<literal><eq></literal>,
	<literal><ge></literal>, and
	<literal><gt></literal> elements. The version
	ranges given should not overlap.</para>

	<para>In a range specification, <literal>*</literal>
	(asterisk) denotes the smallest version number. In
	particular, <literal>2.*</literal> is less than
	<literal>2.a</literal>. Therefore an asterisk may be
	used for a range to match all possible
	<literal>alpha</literal>, <literal>beta</literal>, and
	<literal>RC</literal> versions. For instance,
	<literal><ge>2.</ge><lt>3.</lt></literal>
	will selectively match every <literal>2.x</literal>
	version while
	<literal><ge>2.0</ge><lt>3.0</lt></literal>
	will not since the latter misses
	<literal>2.r3</literal> and matches
	<literal>3.b</literal>.</para>

	<para>The above example specifies that affected are
	versions from <literal>1.6</literal> to
	<literal>1.9</literal> inclusive, versions
	<literal>2.x</literal> before <literal>2.4_1</literal>,
	and version <literal>3.0b1</literal>.</para>
	</callout>

	<callout arearefs="co-vx-nm2">
	<para>Several related package groups (essentially, ports)
	can be listed in the <literal><affected></literal>
	section. This can be used if several software products
	(say FooBar, FreeBar and OpenBar) grow from the same
	code base and still share its bugs and vulnerabilities.
	Note the difference from listing multiple names within a
	single <package> section.</para>
	</callout>

	<callout arearefs="co-vx-epo">
	<para>The version ranges should allow for
	<makevar>PORTEPOCH</makevar> and
	<makevar>PORTREVISION</makevar> if applicable. Please
	remember that according to the collation rules, a
	version with a non-zero <makevar>PORTEPOCH</makevar> is
	greater than any version without
	<makevar>PORTEPOCH</makevar>, e.g.,
	<literal>3.0,1</literal> is greater than
	<literal>3.1</literal> or even than
	<literal>8.9</literal>.</para>
	</callout>

	<callout arearefs="co-vx-bdy">
	<para>This is a summary of the issue. XHTML is used in
	this field. At least enclosing
	<literal><p></literal> and
	<literal></p></literal> should appear. More
	complex mark-up may be used, but only for the sake of
	accuracy and clarity: No eye candy please.</para>
	</callout>

	<callout arearefs="co-vx-ref">
	<para>This section contains references to relevant
	documents. As many references as apply are
	encouraged.</para>
	</callout>

	<callout arearefs="co-vx-fsa">
	<para>This is a <ulink
	url="http://www.freebsd.org/security/#adv">FreeBSD
	security advisory</ulink>.</para>
	</callout>

	<callout arearefs="co-vx-fpr">
	<para>This is a <ulink
	url="http://www.freebsd.org/support.html#gnats">FreeBSD
	problem report</ulink>.</para>
	</callout>

	<callout arearefs="co-vx-cve">
	<para>This is a <ulink
	url="http://www.cve.mitre.org/">MITRE
	CVE</ulink> identifier.</para>
	</callout>

	<callout arearefs="co-vx-bid">
	<para>This is a <ulink
	url="http://www.securityfocus.com/bid">SecurityFocus
	Bug ID</ulink>.</para>
	</callout>

	<callout arearefs="co-vx-cts">
	<para>This is a
	<ulink url="http://www.cert.org/">US-CERT</ulink>
	security advisory.</para>
	</callout>

	<callout arearefs="co-vx-ctv">
	<para>This is a <ulink
	url="http://www.cert.org/">US-CERT</ulink>
	vulnerability note.</para>
	</callout>

	<callout arearefs="co-vx-ucs">
	<para>This is a <ulink
	url="http://www.cert.org/">US-CERT</ulink>
	Cyber Security Alert.</para>
	</callout>

	<callout arearefs="co-vx-uct">
	<para>This is a <ulink
	url="http://www.cert.org/">US-CERT</ulink>
	Technical Cyber Security Alert.</para>
	</callout>

	<callout arearefs="co-vx-mls">
	<para>This is a URL to an archived posting in a mailing
	list. The attribute <literal>msgid</literal> is
	optional and may specify the message ID of the
	posting.</para>
	</callout>

	<callout arearefs="co-vx-url">
	<para>This is a generic URL. It should be used only if
	none of the other reference categories apply.</para>
	</callout>

	<callout arearefs="co-vx-dsc">
	<para>This is the date when the issue was disclosed
	(<replaceable>YYYY-MM-DD</replaceable>).</para>
	</callout>

	<callout arearefs="co-vx-ent">
	<para>This is the date when the entry was added
	(<replaceable>YYYY-MM-DD</replaceable>).</para>
	</callout>

	<callout arearefs="co-vx-mod">
	<para>This is the date when any information in the entry
	was last modified
	(<replaceable>YYYY-MM-DD</replaceable>). New entries
	must not include this field. It should be added upon
	editing an existing entry.</para>
	</callout>
	</calloutlist>
	</sect2>

	<sect2 id="security-notify-vuxml-testing">
	<title>Testing Your Changes to the VuXML Database</title>

	<para>Assume you just wrote or filled in an entry for a
	vulnerability in the package <literal>clamav</literal> that
	has been fixed in version <literal>0.65_7</literal>.</para>

	<para>As a prerequisite, you need to
	<emphasis>install</emphasis> fresh versions of the ports
	<filename role="package">ports-mgmt/portaudit</filename>,
	<filename role="package">ports-mgmt/portaudit-db</filename>,
	and <filename
	role="package">security/vuxml</filename>.</para>

	<note>
	<para>To run <command>packaudit</command> you must have
	permission to write to its
	<filename><makevar>DATABASEDIR</makevar></filename>,
	typically <filename>/var/db/portaudit</filename>.</para>

	<para>To use a different directory set the
	<filename><makevar>DATABASEDIR</makevar></filename>
	environment variable to a different location.</para>

	<para>If you are working in a directory other than
	<filename>${PORTSDIR}/security/vuxml</filename> set the
	<filename><makevar>VUXMLDIR</makevar></filename>
	environment variable to the directory where
	<filename>vuln.xml</filename> is located.</para>
	</note>

	<para>First, check whether there already is an entry for this
	vulnerability. If there were such an entry, it would match
	the previous version of the package,
	<literal>0.65_6</literal>:</para>

	<screen>&prompt.user; <userinput>packaudit</userinput>
	&prompt.user; <userinput>portaudit clamav-0.65_6</userinput></screen>

	<para>If there is none found, you have the green light to add
	a new entry for this vulnerability.</para>

	<screen>&prompt.user; <userinput>cd ${PORTSDIR}/security/vuxml</userinput>
	&prompt.user; <userinput>make newentry</userinput></screen>

	<para>When you are done verify its syntax and
	formatting.</para>

	<screen>&prompt.user; <userinput>make validate</userinput></screen>

	<note>
	<para>You will need at least one of the following packages
	installed: <filename
	role="package">textproc/libxml2</filename>, <filename
	role="package">textproc/jade</filename>.</para>
	</note>

	<para>Now rebuild the <command>portaudit</command> database
	from the VuXML file:</para>

	<screen>&prompt.user; <userinput>packaudit</userinput></screen>

	<para>To verify that the <literal><affected></literal>
	section of your entry will match correct package(s), issue
	the following command:</para>

	<screen>&prompt.user; <userinput>portaudit -f /usr/ports/INDEX -r <replaceable>uuid</replaceable></userinput></screen>

	<note>
	<para>Please refer to &man.portaudit.1; for better
	understanding of the command syntax.</para>
	</note>

	<para>Make sure that your entry produces no spurious matches
	in the output.</para>

	<para>Now check whether the right package versions are matched
	by your entry:</para>

	<screen>&prompt.user; <userinput>portaudit clamav-0.65_6 clamav-0.65_7</userinput>
	Affected package: clamav-0.65_6 (matched by clamav<0.65_7)
	Type of problem: clamav remote denial-of-service.
	Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html>

	1 problem(s) found.</screen>

	<para>The former version should match while the
	latter one should not.</para>

	<para>Finally, verify whether the web page generated from the
	VuXML database looks like expected:</para>

	<screen>&prompt.user; <userinput>mkdir -p ~/public_html/portaudit</userinput>
	&prompt.user; <userinput>packaudit</userinput>
	&prompt.user; <userinput>lynx ~/public_html/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html</userinput></screen>
	</sect2>
	</sect1>
	</chapter>

	<chapter id="porting-dads">
	<title>Dos and Don'ts</title>

	<sect1 id="dads-intro">
	<title>Introduction</title>

	<para>Here is a list of common dos and don'ts that you encounter
	during the porting process. You should check your own port
	against this list, but you can also check ports in the <ulink
	url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">PR
	database</ulink> that others have submitted. Submit any
	comments on ports you check as described in <ulink
	url="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug
	Reports and General Commentary</ulink>. Checking ports in the
	PR database will both make it faster for us to commit them,
	and prove that you know what you are doing.</para>
	</sect1>

	<sect1 id="porting-wrkdir">
	<title><makevar>WRKDIR</makevar></title>

	<para>Do not write anything to files outside
	<makevar>WRKDIR</makevar>. <makevar>WRKDIR</makevar> is the
	only place that is guaranteed to be writable during the port
	build (see <ulink
	url="&url.books.handbook;/ports-using.html#PORTS-CD">
	installing ports from a CDROM</ulink> for an example of
	building ports from a read-only tree). If you need to modify
	one of the
	<filename>pkg-<replaceable>*</replaceable></filename> files,
	do so by <link
	linkend="porting-pkgfiles">redefining a variable</link>, not
	by writing over it.</para>
	</sect1>

	<sect1 id="porting-wrkdirprefix">
	<title><makevar>WRKDIRPREFIX</makevar></title>

	<para>Make sure your port honors
	<makevar>WRKDIRPREFIX</makevar>. Most ports do not have to
	worry about this. In particular, if you are referring to a
	<makevar>WRKDIR</makevar> of another port, note that the
	correct location is
	<filename><makevar>WRKDIRPREFIX</makevar><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename>
	not
	<filename><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename>
	or
	<filename><makevar>.CURDIR</makevar>/../../<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename>
	or some such.</para>

	<para>Also, if you are defining <makevar>WRKDIR</makevar>
	yourself, make sure you prepend
	<literal>&dollar;{WRKDIRPREFIX}&dollar;{.CURDIR}</literal> in
	the front.</para>
	</sect1>

	<sect1 id="porting-versions">
	<title>Differentiating Operating Systems and OS Versions</title>

	<para>You may come across code that needs modifications or
	conditional compilation based upon what version of Unix it is
	running under. If you need to make such changes to the code
	for conditional compilation, make sure you make the changes as
	general as possible so that we can back-port code to older
	FreeBSD systems and cross-port to other BSD systems such as
	4.4BSD from CSRG, BSD/386, 386BSD, NetBSD, and OpenBSD.</para>

	<para>The preferred way to tell 4.3BSD/Reno (1990) and newer
	versions of the BSD code apart is by using the
	<literal>BSD</literal> macro defined in <ulink
	url="http://svnweb.freebsd.org/base/head/sys/sys/param.h?view=markup">sys/param.h</ulink>.
	Hopefully that file is already included; if not, add the
	code:</para>

	<programlisting>#if (defined(__unix__) \|\| defined(unix)) && !defined(USG)
	#include <sys/param.h>
	#endif</programlisting>

	<para>to the proper place in the <filename>.c</filename> file.
	We believe that every system that defines these two symbols
	has <filename>sys/param.h</filename>. If you find a system
	that does not, we would like to know. Please send mail to the
	&a.ports;.</para>

	<para>Another way is to use the GNU Autoconf style of doing
	this:</para>

	<programlisting>#ifdef HAVE_SYS_PARAM_H
	#include <sys/param.h>
	#endif</programlisting>

	<para>Do not forget to add <literal>-DHAVE_SYS_PARAM_H</literal>
	to the <makevar>CFLAGS</makevar> in the
	<filename>Makefile</filename> for this method.</para>

	<para>Once you have <filename>sys/param.h</filename> included,
	you may use:</para>

	<programlisting>#if (defined(BSD) && (BSD >= 199103))</programlisting>

	<para>to detect if the code is being compiled on a 4.3 Net2 code
	base or newer (e.g., FreeBSD 1.x, 4.3/Reno, NetBSD 0.9,
	386BSD, BSD/386 1.1 and below).</para>

	<para>Use:</para>

	<programlisting>#if (defined(BSD) && (BSD >= 199306))</programlisting>

	<para>to detect if the code is being compiled on a 4.4 code base
	or newer (e.g., FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or
	above).</para>

	<para>The value of the <literal>BSD</literal> macro is
	<literal>199506</literal> for the 4.4BSD-Lite2 code base.
	This is stated for informational purposes only. It should not
	be used to distinguish between versions of FreeBSD based only
	on 4.4-Lite versus versions that have merged in changes from
	4.4-Lite2. The <literal>__FreeBSD__</literal> macro should be
	used instead.</para>

	<para>Use sparingly:</para>

	<itemizedlist>
	<listitem>
	<para><literal>__FreeBSD__</literal> is defined in all
	versions of FreeBSD. Use it if the change you are making
	<emphasis>only</emphasis> affects FreeBSD. Porting
	gotchas like the use of <literal>sys_errlist[]</literal>
	versus <function>strerror()</function> are Berkeley-isms,
	not FreeBSD changes.</para>
	</listitem>

	<listitem>
	<para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is
	defined to be <literal>2</literal>. In earlier versions,
	it is <literal>1</literal>. Later versions always bump it
	to match their major version number.</para>
	</listitem>

	<listitem>
	<para>If you need to tell the difference between a FreeBSD
	1.x system and a FreeBSD 2.x or above system, usually the
	right answer is to use the <literal>BSD</literal> macros
	described above. If there actually is a FreeBSD specific
	change (such as special shared library options when using
	<command>ld</command>) then it is OK to use
	<literal>__FreeBSD__</literal> and <literal>#if
	__FreeBSD__ > 1</literal> to detect a FreeBSD 2.x and
	later system. If you need more granularity in detecting
	FreeBSD systems since 2.0-RELEASE you can use the
	following:</para>

	<programlisting>#if __FreeBSD__ >= 2
	#include <osreldate.h>
	# if __FreeBSD_version >= 199504
	/* 2.0.5+ release specific code here */
	# endif
	#endif</programlisting>
	</listitem>
	</itemizedlist>

	<para>In the hundreds of ports that have been done, there have
	only been one or two cases where
	<literal>__FreeBSD__</literal> should have been used. Just
	because an earlier port screwed up and used it in the wrong
	place does not mean you should do so too.</para>
	</sect1>

	<sect1 id="freebsd-versions">
	<title><literal>__FreeBSD_version</literal> Values</title>

	<para>Here is a convenient list of
	<literal>__FreeBSD_version</literal> values as defined in
	<ulink
	url="http://svnweb.FreeBSD.org/base/head/sys/sys/param.h?view=markup">sys/param.h</ulink>:</para>

	<table frame="none">
	<title><literal>__FreeBSD_version</literal> Values</title>

	<tgroup cols="3">
	<thead>
	<row>
	<entry>Value</entry>
	<entry>Date</entry>
	<entry>Release</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry>119411</entry>
	<entry></entry>
	<entry>2.0-RELEASE</entry>
	</row>

	<row>
	<entry>199501, 199503</entry>
	<entry>March 19, 1995</entry>
	<entry>2.1-CURRENT</entry>
	</row>

	<row>
	<entry>199504</entry>
	<entry>April 9, 1995</entry>
	<entry>2.0.5-RELEASE</entry>
	</row>

	<row>
	<entry>199508</entry>
	<entry>August 26, 1995</entry>
	<entry>2.2-CURRENT before 2.1</entry>
	</row>

	<row>
	<entry>199511</entry>
	<entry>November 10, 1995</entry>
	<entry>2.1.0-RELEASE</entry>
	</row>

	<row>
	<entry>199512</entry>
	<entry>November 10, 1995</entry>
	<entry>2.2-CURRENT before 2.1.5</entry>
	</row>

	<row>
	<entry>199607</entry>
	<entry>July 10, 1996</entry>
	<entry>2.1.5-RELEASE</entry>
	</row>

	<row>
	<entry>199608</entry>
	<entry>July 12, 1996</entry>
	<entry>2.2-CURRENT before 2.1.6</entry>
	</row>

	<row>
	<entry>199612</entry>
	<entry>November 15, 1996</entry>
	<entry>2.1.6-RELEASE</entry>
	</row>

	<row>
	<entry>199612</entry>
	<entry></entry>
	<entry>2.1.7-RELEASE</entry>
	</row>

	<row>
	<entry>220000</entry>
	<entry>February 19, 1997</entry>
	<entry>2.2-RELEASE</entry>
	</row>

	<row>
	<entry>(not changed)</entry>
	<entry></entry>
	<entry>2.2.1-RELEASE</entry>
	</row>

	<row>
	<entry>(not changed)</entry>
	<entry></entry>
	<entry>2.2-STABLE after 2.2.1-RELEASE</entry>
	</row>

	<row>
	<entry>221001</entry>
	<entry>April 15, 1997</entry>
	<entry>2.2-STABLE after texinfo-3.9</entry>
	</row>

	<row>
	<entry>221002</entry>
	<entry>April 30, 1997</entry>
	<entry>2.2-STABLE after top</entry>
	</row>

	<row>
	<entry>222000</entry>
	<entry>May 16, 1997</entry>
	<entry>2.2.2-RELEASE</entry>
	</row>

	<row>
	<entry>222001</entry>
	<entry>May 19, 1997</entry>
	<entry>2.2-STABLE after 2.2.2-RELEASE</entry>
	</row>

	<row>
	<entry>225000</entry>
	<entry>October 2, 1997</entry>
	<entry>2.2.5-RELEASE</entry>
	</row>

	<row>
	<entry>225001</entry>
	<entry>November 20, 1997</entry>
	<entry>2.2-STABLE after 2.2.5-RELEASE</entry>
	</row>

	<row>
	<entry>225002</entry>
	<entry>December 27, 1997</entry>
	<entry>2.2-STABLE after ldconfig -R merge</entry>
	</row>

	<row>
	<entry>226000</entry>
	<entry>March 24, 1998</entry>
	<entry>2.2.6-RELEASE</entry>
	</row>

	<row>
	<entry>227000</entry>
	<entry>July 21, 1998</entry>
	<entry>2.2.7-RELEASE</entry>
	</row>

	<row>
	<entry>227001</entry>
	<entry>July 21, 1998</entry>
	<entry>2.2-STABLE after 2.2.7-RELEASE</entry>
	</row>

	<row>
	<entry>227002</entry>
	<entry>September 19, 1998</entry>
	<entry>2.2-STABLE after &man.semctl.2; change</entry>
	</row>

	<row>
	<entry>228000</entry>
	<entry>November 29, 1998</entry>
	<entry>2.2.8-RELEASE</entry>
	</row>

	<row>
	<entry>228001</entry>
	<entry>November 29, 1998</entry>
	<entry>2.2-STABLE after 2.2.8-RELEASE</entry>
	</row>

	<row>
	<entry>300000</entry>
	<entry>February 19, 1996</entry>
	<entry>3.0-CURRENT before &man.mount.2; change</entry>
	</row>

	<row>
	<entry>300001</entry>
	<entry>September 24, 1997</entry>
	<entry>3.0-CURRENT after &man.mount.2; change</entry>
	</row>

	<row>
	<entry>300002</entry>
	<entry>June 2, 1998</entry>
	<entry>3.0-CURRENT after &man.semctl.2; change</entry>
	</row>

	<row>
	<entry>300003</entry>
	<entry>June 7, 1998</entry>
	<entry>3.0-CURRENT after ioctl arg changes</entry>
	</row>

	<row>
	<entry>300004</entry>
	<entry>September 3, 1998</entry>
	<entry>3.0-CURRENT after ELF conversion</entry>
	</row>

	<row>
	<entry>300005</entry>
	<entry>October 16, 1998</entry>
	<entry>3.0-RELEASE</entry>
	</row>

	<row>
	<entry>300006</entry>
	<entry>October 16, 1998</entry>
	<entry>3.0-CURRENT after 3.0-RELEASE</entry>
	</row>

	<row>
	<entry>300007</entry>
	<entry>January 22, 1999</entry>
	<entry>3.0-STABLE after 3/4 branch</entry>
	</row>

	<row>
	<entry>310000</entry>
	<entry>February 9, 1999</entry>
	<entry>3.1-RELEASE</entry>
	</row>

	<row>
	<entry>310001</entry>
	<entry>March 27, 1999</entry>
	<entry>3.1-STABLE after 3.1-RELEASE</entry>
	</row>

	<row>
	<entry>310002</entry>
	<entry>April 14, 1999</entry>
	<entry>3.1-STABLE after C++ constructor/destructor order
	change</entry>
	</row>

	<row>
	<entry>320000</entry>
	<entry></entry>
	<entry>3.2-RELEASE</entry>
	</row>

	<row>
	<entry>320001</entry>
	<entry>May 8, 1999</entry>
	<entry>3.2-STABLE</entry>
	</row>

	<row>
	<entry>320002</entry>
	<entry>August 29, 1999</entry>
	<entry>3.2-STABLE after binary-incompatible IPFW and
	socket changes</entry>
	</row>

	<row>
	<entry>330000</entry>
	<entry>September 2, 1999</entry>
	<entry>3.3-RELEASE</entry>
	</row>

	<row>
	<entry>330001</entry>
	<entry>September 16, 1999</entry>
	<entry>3.3-STABLE</entry>
	</row>

	<row>
	<entry>330002</entry>
	<entry>November 24, 1999</entry>
	<entry>3.3-STABLE after adding &man.mkstemp.3;
	to libc</entry>
	</row>

	<row>
	<entry>340000</entry>
	<entry>December 5, 1999</entry>
	<entry>3.4-RELEASE</entry>
	</row>

	<row>
	<entry>340001</entry>
	<entry>December 17, 1999</entry>
	<entry>3.4-STABLE</entry>
	</row>

	<row>
	<entry>350000</entry>
	<entry>June 20, 2000</entry>
	<entry>3.5-RELEASE</entry>
	</row>

	<row>
	<entry>350001</entry>
	<entry>July 12, 2000</entry>
	<entry>3.5-STABLE</entry>
	</row>

	<row>
	<entry>400000</entry>
	<entry>January 22, 1999</entry>
	<entry>4.0-CURRENT after 3.4 branch</entry>
	</row>

	<row>
	<entry>400001</entry>
	<entry>February 20, 1999</entry>
	<entry>4.0-CURRENT after change in dynamic linker
	handling</entry>
	</row>

	<row>
	<entry>400002</entry>
	<entry>March 13, 1999</entry>
	<entry>4.0-CURRENT after C++ constructor/destructor
	order change</entry>
	</row>

	<row>
	<entry>400003</entry>
	<entry>March 27, 1999</entry>
	<entry>4.0-CURRENT after functioning
	&man.dladdr.3;</entry>
	</row>

	<row>
	<entry>400004</entry>
	<entry>April 5, 1999</entry>
	<entry>4.0-CURRENT after __deregister_frame_info dynamic
	linker bug fix (also 4.0-CURRENT after EGCS 1.1.2
	integration)</entry>
	</row>

	<row>
	<entry>400005</entry>
	<entry>April 27, 1999</entry>
	<entry>4.0-CURRENT after &man.suser.9; API change
	(also 4.0-CURRENT after newbus)</entry>
	</row>

	<row>
	<entry>400006</entry>
	<entry>May 31, 1999</entry>
	<entry>4.0-CURRENT after cdevsw registration
	change</entry>
	</row>

	<row>
	<entry>400007</entry>
	<entry>June 17, 1999</entry>
	<entry>4.0-CURRENT after the addition of so_cred for
	socket level credentials</entry>
	</row>

	<row>
	<entry>400008</entry>
	<entry>June 20, 1999</entry>
	<entry>4.0-CURRENT after the addition of a poll syscall
	wrapper to libc_r</entry>
	</row>

	<row>
	<entry>400009</entry>
	<entry>July 20, 1999</entry>
	<entry>4.0-CURRENT after the change of the kernel's
	<literal>dev_t</literal> type to <literal>struct
	specinfo</literal> pointer</entry>
	</row>

	<row>
	<entry>400010</entry>
	<entry>September 25, 1999</entry>
	<entry>4.0-CURRENT after fixing a hole
	in &man.jail.2;</entry>
	</row>

	<row>
	<entry>400011</entry>
	<entry>September 29, 1999</entry>
	<entry>4.0-CURRENT after the <literal>sigset_t</literal>
	datatype change</entry>
	</row>

	<row>
	<entry>400012</entry>
	<entry>November 15, 1999</entry>
	<entry>4.0-CURRENT after the cutover to the GCC 2.95.2
	compiler</entry>
	</row>

	<row>
	<entry>400013</entry>
	<entry>December 4, 1999</entry>
	<entry>4.0-CURRENT after adding pluggable linux-mode
	ioctl handlers</entry>
	</row>

	<row>
	<entry>400014</entry>
	<entry>January 18, 2000</entry>
	<entry>4.0-CURRENT after importing OpenSSL</entry>
	</row>

	<row>
	<entry>400015</entry>
	<entry>January 27, 2000</entry>
	<entry>4.0-CURRENT after the C++ ABI change in GCC
	2.95.2 from -fvtable-thunks to -fno-vtable-thunks by
	default</entry>
	</row>

	<row>
	<entry>400016</entry>
	<entry>February 27, 2000</entry>
	<entry>4.0-CURRENT after importing OpenSSH</entry>
	</row>

	<row>
	<entry>400017</entry>
	<entry>March 13, 2000</entry>
	<entry>4.0-RELEASE</entry>
	</row>

	<row>
	<entry>400018</entry>
	<entry>March 17, 2000</entry>
	<entry>4.0-STABLE after 4.0-RELEASE</entry>
	</row>

	<row>
	<entry>400019</entry>
	<entry>May 5, 2000</entry>
	<entry>4.0-STABLE after the introduction of delayed
	checksums.</entry>
	</row>

	<row>
	<entry>400020</entry>
	<entry>June 4, 2000</entry>
	<entry>4.0-STABLE after merging libxpg4 code into
	libc.</entry>
	</row>

	<row>
	<entry>400021</entry>
	<entry>July 8, 2000</entry>
	<entry>4.0-STABLE after upgrading Binutils to 2.10.0,
	ELF branding changes, and tcsh in the base
	system.</entry>
	</row>

	<row>
	<entry>410000</entry>
	<entry>July 14, 2000</entry>
	<entry>4.1-RELEASE</entry>
	</row>

	<row>
	<entry>410001</entry>
	<entry>July 29, 2000</entry>
	<entry>4.1-STABLE after 4.1-RELEASE</entry>
	</row>

	<row>
	<entry>410002</entry>
	<entry>September 16, 2000</entry>
	<entry>4.1-STABLE after &man.setproctitle.3; moved from
	libutil to libc.</entry>
	</row>

	<row>
	<entry>411000</entry>
	<entry>September 25, 2000</entry>
	<entry>4.1.1-RELEASE</entry>
	</row>

	<row>
	<entry>411001</entry>
	<entry></entry>
	<entry>4.1.1-STABLE after 4.1.1-RELEASE</entry>
	</row>

	<row>
	<entry>420000</entry>
	<entry>October 31, 2000</entry>
	<entry>4.2-RELEASE</entry>
	</row>

	<row>
	<entry>420001</entry>
	<entry>January 10, 2001</entry>
	<entry>4.2-STABLE after combining libgcc.a and
	libgcc_r.a, and associated GCC linkage
	changes.</entry>
	</row>

	<row>
	<entry>430000</entry>
	<entry>March 6, 2001</entry>
	<entry>4.3-RELEASE</entry>
	</row>

	<row>
	<entry>430001</entry>
	<entry>May 18, 2001</entry>
	<entry>4.3-STABLE after wint_t introduction.</entry>
	</row>

	<row>
	<entry>430002</entry>
	<entry>July 22, 2001</entry>
	<entry>4.3-STABLE after PCI powerstate API
	merge.</entry>
	</row>

	<row>
	<entry>440000</entry>
	<entry>August 1, 2001</entry>
	<entry>4.4-RELEASE</entry>
	</row>

	<row>
	<entry>440001</entry>
	<entry>October 23, 2001</entry>
	<entry>4.4-STABLE after d_thread_t introduction.</entry>
	</row>

	<row>
	<entry>440002</entry>
	<entry>November 4, 2001</entry>
	<entry>4.4-STABLE after mount structure changes (affects
	filesystem klds).</entry>
	</row>

	<row>
	<entry>440003</entry>
	<entry>December 18, 2001</entry>
	<entry>4.4-STABLE after the userland components of smbfs
	were imported.</entry>
	</row>

	<row>
	<entry>450000</entry>
	<entry>December 20, 2001</entry>
	<entry>4.5-RELEASE</entry>
	</row>

	<row>
	<entry>450001</entry>
	<entry>February 24, 2002</entry>
	<entry>4.5-STABLE after the usb structure element
	rename.</entry>
	</row>

	<row>
	<entry>450004</entry>
	<entry>April 16, 2002</entry>
	<entry>4.5-STABLE after the
	<literal>sendmail_enable</literal> &man.rc.conf.5;
	variable was made to take the value
	<literal>NONE</literal>.</entry>
	</row>

	<row>
	<entry>450005</entry>
	<entry>April 27, 2002</entry>
	<entry>4.5-STABLE after moving to XFree86 4 by default
	for package builds.</entry>
	</row>

	<row>
	<entry>450006</entry>
	<entry>May 1, 2002</entry>
	<entry>4.5-STABLE after accept filtering was fixed so
	that is no longer susceptible to an easy DoS.</entry>
	</row>

	<row>
	<entry>460000</entry>
	<entry>June 21, 2002</entry>
	<entry>4.6-RELEASE</entry>
	</row>

	<row>
	<entry>460001</entry>
	<entry>June 21, 2002</entry>
	<entry>4.6-STABLE &man.sendfile.2; fixed to comply with
	documentation, not to count any headers sent against
	the amount of data to be sent from the file.</entry>
	</row>

	<row>
	<entry>460002</entry>
	<entry>July 19, 2002</entry>
	<entry>4.6.2-RELEASE</entry>
	</row>

	<row>
	<entry>460100</entry>
	<entry>June 26, 2002</entry>
	<entry>4.6-STABLE</entry>
	</row>

	<row>
	<entry>460101</entry>
	<entry>June 26, 2002</entry>
	<entry>4.6-STABLE after MFC of `sed -i'.</entry>
	</row>

	<row>
	<entry>460102</entry>
	<entry>September 1, 2002</entry>
	<entry>4.6-STABLE after MFC of many new pkg_install
	features from the HEAD.</entry>
	</row>

	<row>
	<entry>470000</entry>
	<entry>October 8, 2002</entry>
	<entry>4.7-RELEASE</entry>
	</row>

	<row>
	<entry>470100</entry>
	<entry>October 9, 2002</entry>
	<entry>4.7-STABLE</entry>
	</row>

	<row>
	<entry>470101</entry>
	<entry>November 10, 2002</entry>
	<entry>Start generated __std{in,out,err}p references
	rather than __sF. This changes std{in,out,err} from a
	compile time expression to a runtime one.</entry>
	</row>

	<row>
	<entry>470102</entry>
	<entry>January 23, 2003</entry>
	<entry>4.7-STABLE after MFC of mbuf changes to replace
	m_aux mbufs by m_tag's</entry>
	</row>

	<row>
	<entry>470103</entry>
	<entry>February 14, 2003</entry>
	<entry>4.7-STABLE gets OpenSSL 0.9.7</entry>
	</row>

	<row>
	<entry>480000</entry>
	<entry>March 30, 2003</entry>
	<entry>4.8-RELEASE</entry>
	</row>

	<row>
	<entry>480100</entry>
	<entry>April 5, 2003</entry>
	<entry>4.8-STABLE</entry>
	</row>

	<row>
	<entry>480101</entry>
	<entry>May 22, 2003</entry>
	<entry>4.8-STABLE after &man.realpath.3; has been made
	thread-safe</entry>
	</row>

	<row>
	<entry>480102</entry>
	<entry>August 10, 2003</entry>
	<entry>4.8-STABLE 3ware API changes to twe.</entry>
	</row>

	<row>
	<entry>490000</entry>
	<entry>October 27, 2003</entry>
	<entry>4.9-RELEASE</entry>
	</row>

	<row>
	<entry>490100</entry>
	<entry>October 27, 2003</entry>
	<entry>4.9-STABLE</entry>
	</row>

	<row>
	<entry>490101</entry>
	<entry>January 8, 2004</entry>
	<entry>4.9-STABLE after e_sid was added to struct
	kinfo_eproc.</entry>
	</row>

	<row>
	<entry>490102</entry>
	<entry>February 4, 2004</entry>
	<entry>4.9-STABLE after MFC of libmap functionality
	for rtld.</entry>
	</row>

	<row>
	<entry>491000</entry>
	<entry>May 25, 2004</entry>
	<entry>4.10-RELEASE</entry>
	</row>

	<row>
	<entry>491100</entry>
	<entry>June 1, 2004</entry>
	<entry>4.10-STABLE</entry>
	</row>

	<row>
	<entry>491101</entry>
	<entry>August 11, 2004</entry>
	<entry>4.10-STABLE after MFC of revision 20040629 of
	the package tools</entry>
	</row>

	<row>
	<entry>491102</entry>
	<entry>November 16, 2004</entry>
	<entry>4.10-STABLE after VM fix dealing with unwiring
	of fictitious pages</entry>
	</row>

	<row>
	<entry>492000</entry>
	<entry>December 17, 2004</entry>
	<entry>4.11-RELEASE</entry>
	</row>

	<row>
	<entry>492100</entry>
	<entry>December 17, 2004</entry>
	<entry>4.11-STABLE</entry>
	</row>

	<row>
	<entry>492101</entry>
	<entry>April 18, 2006</entry>
	<entry>4.11-STABLE after adding libdata/ldconfig
	directories to mtree files.</entry>
	</row>

	<row>
	<entry>500000</entry>
	<entry>March 13, 2000</entry>
	<entry>5.0-CURRENT</entry>
	</row>

	<row>
	<entry>500001</entry>
	<entry>April 18, 2000</entry>
	<entry>5.0-CURRENT after adding addition ELF header
	fields, and changing our ELF binary branding
	method.</entry>
	</row>

	<row>
	<entry>500002</entry>
	<entry>May 2, 2000</entry>
	<entry>5.0-CURRENT after kld metadata changes.</entry>
	</row>

	<row>
	<entry>500003</entry>
	<entry>May 18, 2000</entry>
	<entry>5.0-CURRENT after buf/bio changes.</entry>
	</row>

	<row>
	<entry>500004</entry>
	<entry>May 26, 2000</entry>
	<entry>5.0-CURRENT after binutils upgrade.</entry>
	</row>

	<row>
	<entry>500005</entry>
	<entry>June 3, 2000</entry>
	<entry>5.0-CURRENT after merging libxpg4 code into
	libc and after TASKQ interface introduction.</entry>
	</row>

	<row>
	<entry>500006</entry>
	<entry>June 10, 2000</entry>
	<entry>5.0-CURRENT after the addition of AGP
	interfaces.</entry>
	</row>

	<row>
	<entry>500007</entry>
	<entry>June 29, 2000</entry>
	<entry>5.0-CURRENT after Perl upgrade to 5.6.0</entry>
	</row>

	<row>
	<entry>500008</entry>
	<entry>July 7, 2000</entry>
	<entry>5.0-CURRENT after the update of KAME code to
	2000/07 sources.</entry>
	</row>

	<row>
	<entry>500009</entry>
	<entry>July 14, 2000</entry>
	<entry>5.0-CURRENT after ether_ifattach() and
	ether_ifdetach() changes.</entry>
	</row>

	<row>
	<entry>500010</entry>
	<entry>July 16, 2000</entry>
	<entry>5.0-CURRENT after changing mtree defaults
	back to original variant, adding -L to follow
	symlinks.</entry>
	</row>

	<row>
	<entry>500011</entry>
	<entry>July 18, 2000</entry>
	<entry>5.0-CURRENT after kqueue API changed.</entry>
	</row>

	<row>
	<entry>500012</entry>
	<entry>September 2, 2000</entry>
	<entry>5.0-CURRENT after &man.setproctitle.3; moved from
	libutil to libc.</entry>
	</row>

	<row>
	<entry>500013</entry>
	<entry>September 10, 2000</entry>
	<entry>5.0-CURRENT after the first SMPng commit.</entry>
	</row>

	<row>
	<entry>500014</entry>
	<entry>January 4, 2001</entry>
	<entry>5.0-CURRENT after <sys/select.h> moved to
	<sys/selinfo.h>.</entry>
	</row>

	<row>
	<entry>500015</entry>
	<entry>January 10, 2001</entry>
	<entry>5.0-CURRENT after combining libgcc.a and
	libgcc_r.a, and associated GCC linkage
	changes.</entry>
	</row>

	<row>
	<entry>500016</entry>
	<entry>January 24, 2001</entry>
	<entry>5.0-CURRENT after change allowing libc and libc_r
	to be linked together, deprecating -pthread
	option.</entry>
	</row>

	<row>
	<entry>500017</entry>
	<entry>February 18, 2001</entry>
	<entry>5.0-CURRENT after switch from struct ucred to
	struct xucred to stabilize kernel-exported API for
	mountd et al.</entry>
	</row>

	<row>
	<entry>500018</entry>
	<entry>February 24, 2001</entry>
	<entry>5.0-CURRENT after addition of CPUTYPE make
	variable for controlling CPU-specific
	optimizations.</entry>
	</row>

	<row>
	<entry>500019</entry>
	<entry>June 9, 2001</entry>
	<entry>5.0-CURRENT after moving machine/ioctl_fd.h to
	sys/fdcio.h</entry>
	</row>

	<row>
	<entry>500020</entry>
	<entry>June 15, 2001</entry>
	<entry>5.0-CURRENT after locale names renaming.</entry>
	</row>

	<row>
	<entry>500021</entry>
	<entry>June 22, 2001</entry>
	<entry>5.0-CURRENT after Bzip2 import.
	Also signifies removal of S/Key.</entry>
	</row>

	<row>
	<entry>500022</entry>
	<entry>July 12, 2001</entry>
	<entry>5.0-CURRENT after SSE support.</entry>
	</row>

	<row>
	<entry>500023</entry>
	<entry>September 14, 2001</entry>
	<entry>5.0-CURRENT after KSE Milestone 2.</entry>
	</row>

	<row>
	<entry>500024</entry>
	<entry>October 1, 2001</entry>
	<entry>5.0-CURRENT after d_thread_t,
	and moving UUCP to ports.</entry>
	</row>

	<row>
	<entry>500025</entry>
	<entry>October 4, 2001</entry>
	<entry>5.0-CURRENT after ABI change for descriptor
	and creds passing on 64 bit platforms.</entry>
	</row>

	<row>
	<entry>500026</entry>
	<entry>October 9, 2001</entry>
	<entry>5.0-CURRENT after moving to XFree86 4 by default
	for package builds, and after the new libc strnstr()
	function was added.</entry>
	</row>

	<row>
	<entry>500027</entry>
	<entry>October 10, 2001</entry>
	<entry>5.0-CURRENT after the new libc strcasestr()
	function was added.</entry>
	</row>

	<row>
	<entry>500028</entry>
	<entry>December 14, 2001</entry>
	<entry>5.0-CURRENT after the userland components of
	smbfs were imported.</entry>
	</row>

	<row>
	<entry>(not changed)</entry>
	<entry></entry>
	<entry>5.0-CURRENT after the new C99 specific-width
	integer types were added.</entry>
	</row>

	<row>
	<entry>500029</entry>
	<entry>January 29, 2002</entry>
	<entry>5.0-CURRENT after a change was made in the return
	value of &man.sendfile.2;.</entry>
	</row>

	<row>
	<entry>500030</entry>
	<entry>February 15, 2002</entry>
	<entry>5.0-CURRENT after the introduction of the
	type <literal>fflags_t</literal>, which is the
	appropriate size for file flags.</entry>
	</row>

	<row>
	<entry>500031</entry>
	<entry>February 24, 2002</entry>
	<entry>5.0-CURRENT after the usb structure element
	rename.</entry>
	</row>

	<row>
	<entry>500032</entry>
	<entry>March 16, 2002</entry>
	<entry>5.0-CURRENT after the introduction of
	Perl 5.6.1.</entry>
	</row>

	<row>
	<entry>500033</entry>
	<entry>April 3, 2002</entry>
	<entry>5.0-CURRENT after the
	<literal>sendmail_enable</literal> &man.rc.conf.5;
	variable was made to take the value
	<literal>NONE</literal>.</entry>
	</row>

	<row>
	<entry>500034</entry>
	<entry>April 30, 2002</entry>
	<entry>5.0-CURRENT after mtx_init() grew a third
	argument.</entry>
	</row>

	<row>
	<entry>500035</entry>
	<entry>May 13, 2002</entry>
	<entry>5.0-CURRENT with Gcc 3.1.</entry>
	</row>

	<row>
	<entry>500036</entry>
	<entry>May 17, 2002</entry>
	<entry>5.0-CURRENT without Perl in /usr/src</entry>
	</row>

	<row>
	<entry>500037</entry>
	<entry>May 29, 2002</entry>
	<entry>5.0-CURRENT after the addition of
	&man.dlfunc.3;</entry>
	</row>

	<row>
	<entry>500038</entry>
	<entry>July 24, 2002</entry>
	<entry>5.0-CURRENT after the types of some struct
	sockbuf members were changed and the structure was
	reordered.</entry>
	</row>

	<row>
	<entry>500039</entry>
	<entry>September 1, 2002</entry>
	<entry>5.0-CURRENT after GCC 3.2.1 import.
	Also after headers stopped using
	_BSD_FOO_T_ and started using _FOO_T_DECLARED.
	This value can also be used as a conservative
	estimate of the start of &man.bzip2.1; package
	support.</entry>
	</row>

	<row>
	<entry>500040</entry>
	<entry>September 20, 2002</entry>
	<entry>5.0-CURRENT after various changes to disk
	functions were made in the name of removing dependency
	on disklabel structure internals.</entry>
	</row>

	<row>
	<entry>500041</entry>
	<entry>October 1, 2002</entry>
	<entry>5.0-CURRENT after the addition of
	&man.getopt.long.3; to libc.</entry>
	</row>

	<row>
	<entry>500042</entry>
	<entry>October 15, 2002</entry>
	<entry>5.0-CURRENT after Binutils 2.13 upgrade, which
	included new FreeBSD emulation, vec, and output
	format.</entry>
	</row>

	<row>
	<entry>500043</entry>
	<entry>November 1, 2002</entry>
	<entry>5.0-CURRENT after adding weak pthread_XXX stubs
	to libc, obsoleting libXThrStub.so.
	5.0-RELEASE.</entry>
	</row>

	<row>
	<entry>500100</entry>
	<entry>January 17, 2003</entry>
	<entry>5.0-CURRENT after branching for
	RELENG_5_0</entry>
	</row>

	<row>
	<entry>500101</entry>
	<entry>February 19, 2003</entry>
	<entry><sys/dkstat.h> is empty and should
	not be included.</entry>
	</row>

	<row>
	<entry>500102</entry>
	<entry>February 25, 2003</entry>
	<entry>5.0-CURRENT after the d_mmap_t interface
	change.</entry>
	</row>

	<row>
	<entry>500103</entry>
	<entry>February 26, 2003</entry>
	<entry>5.0-CURRENT after taskqueue_swi changed to run
	without Giant, and taskqueue_swi_giant added to run
	with Giant.</entry>
	</row>

	<row>
	<entry>500104</entry>
	<entry>February 27, 2003</entry>
	<entry>cdevsw_add() and cdevsw_remove() no
	longer exists.
	Appearance of MAJOR_AUTO allocation facility.</entry>
	</row>

	<row>
	<entry>500105</entry>
	<entry>March 4, 2003</entry>
	<entry>5.0-CURRENT after new cdevsw initialization
	method.</entry>
	</row>

	<row>
	<entry>500106</entry>
	<entry>March 8, 2003</entry>
	<entry>devstat_add_entry() has been replaced by
	devstat_new_entry()</entry>
	</row>

	<row>
	<entry>500107</entry>
	<entry>March 15, 2003</entry>
	<entry>Devstat interface change; see sys/sys/param.h
	1.149</entry>
	</row>

	<row>
	<entry>500108</entry>
	<entry>March 15, 2003</entry>
	<entry>Token-Ring interface changes.</entry>
	</row>

	<row>
	<entry>500109</entry>
	<entry>March 25, 2003</entry>
	<entry>Addition of vm_paddr_t.</entry>
	</row>

	<row>
	<entry>500110</entry>
	<entry>March 28, 2003</entry>
	<entry>5.0-CURRENT after &man.realpath.3; has been made
	thread-safe</entry>
	</row>

	<row>
	<entry>500111</entry>
	<entry>April 9, 2003</entry>
	<entry>5.0-CURRENT after &man.usbhid.3; has been synced
	with NetBSD</entry>
	</row>

	<row>
	<entry>500112</entry>
	<entry>April 17, 2003</entry>
	<entry>5.0-CURRENT after new NSS implementation
	and addition of POSIX.1 getpw_r, getgr_r
	functions</entry>
	</row>

	<row>
	<entry>500113</entry>
	<entry>May 2, 2003</entry>
	<entry>5.0-CURRENT after removal of the old rc
	system.</entry>
	</row>

	<row>
	<entry>501000</entry>
	<entry>June 4, 2003</entry>
	<entry>5.1-RELEASE.</entry>
	</row>

	<row>
	<entry>501100</entry>
	<entry>June 2, 2003</entry>
	<entry>5.1-CURRENT after branching for
	RELENG_5_1.</entry>
	</row>

	<row>
	<entry>501101</entry>
	<entry>June 29, 2003</entry>
	<entry>5.1-CURRENT after correcting the semantics of
	sigtimedwait(2) and sigwaitinfo(2).</entry>
	</row>

	<row>
	<entry>501102</entry>
	<entry>July 3, 2003</entry>
	<entry>5.1-CURRENT after adding the lockfunc and
	lockfuncarg fields to
	&man.bus.dma.tag.create.9;.</entry>
	</row>

	<row>
	<entry>501103</entry>
	<entry>July 31, 2003</entry>
	<entry>5.1-CURRENT after GCC 3.3.1-pre 20030711 snapshot
	integration.</entry>
	</row>

	<row>
	<entry>501104</entry>
	<entry>August 5, 2003</entry>
	<entry>5.1-CURRENT 3ware API changes to twe.</entry>
	</row>

	<row>
	<entry>501105</entry>
	<entry>August 17, 2003</entry>
	<entry>5.1-CURRENT dynamically-linked /bin and /sbin
	support and movement of libraries to /lib.</entry>
	</row>

	<row>
	<entry>501106</entry>
	<entry>September 8, 2003</entry>
	<entry>5.1-CURRENT after adding kernel support for
	Coda 6.x.</entry>
	</row>

	<row>
	<entry>501107</entry>
	<entry>September 17, 2003</entry>
	<entry>5.1-CURRENT after 16550 UART constants moved from
	<filename><dev/sio/sioreg.h></filename> to
	<filename><dev/ic/ns16550.h></filename>.
	Also when libmap functionality was unconditionally
	supported by rtld.</entry>
	</row>

	<row>
	<entry>501108</entry>
	<entry>September 23, 2003</entry>
	<entry>5.1-CURRENT after PFIL_HOOKS API update</entry>
	</row>

	<row>
	<entry>501109</entry>
	<entry>September 27, 2003</entry>
	<entry>5.1-CURRENT after adding kiconv(3)</entry>
	</row>

	<row>
	<entry>501110</entry>
	<entry>September 28, 2003</entry>
	<entry>5.1-CURRENT after changing default operations
	for open and close in cdevsw</entry>
	</row>

	<row>
	<entry>501111</entry>
	<entry>October 16, 2003</entry>
	<entry>5.1-CURRENT after changed layout of
	cdevsw</entry>
	</row>

	<row>
	<entry>501112</entry>
	<entry>October 16, 2003</entry>
	<entry> 5.1-CURRENT after adding kobj multiple
	inheritance</entry>
	</row>

	<row>
	<entry>501113</entry>
	<entry>October 31, 2003</entry>
	<entry> 5.1-CURRENT after the if_xname change in
	struct ifnet</entry>
	</row>

	<row>
	<entry>501114</entry>
	<entry>November 16, 2003</entry>
	<entry> 5.1-CURRENT after changing /bin and /sbin to
	be dynamically linked</entry>
	</row>

	<row>
	<entry>502000</entry>
	<entry>December 7, 2003</entry>
	<entry>5.2-RELEASE</entry>
	</row>

	<row>
	<entry>502010</entry>
	<entry>February 23, 2004</entry>
	<entry>5.2.1-RELEASE</entry>
	</row>

	<row>
	<entry>502100</entry>
	<entry>December 7, 2003</entry>
	<entry>5.2-CURRENT after branching for
	RELENG_5_2</entry>
	</row>

	<row>
	<entry>502101</entry>
	<entry>December 19, 2003</entry>
	<entry>5.2-CURRENT after __cxa_atexit/__cxa_finalize
	functions were added to libc.</entry>
	</row>

	<row>
	<entry>502102</entry>
	<entry>January 30, 2004</entry>
	<entry>5.2-CURRENT after change of default thread
	library from libc_r to libpthread.</entry>
	</row>

	<row>
	<entry>502103</entry>
	<entry>February 21, 2004</entry>
	<entry>5.2-CURRENT after device driver API
	megapatch.</entry>
	</row>

	<row>
	<entry>502104</entry>
	<entry>February 25, 2004</entry>
	<entry>5.2-CURRENT after getopt_long_only()
	addition.</entry>
	</row>

	<row>
	<entry>502105</entry>
	<entry>March 5, 2004</entry>
	<entry>5.2-CURRENT after NULL is made into ((void *)0)
	for C, creating more warnings.</entry>
	</row>

	<row>
	<entry>502106</entry>
	<entry>March 8, 2004</entry>
	<entry>5.2-CURRENT after pf is linked to the build and
	install.</entry>
	</row>

	<row>
	<entry>502107</entry>
	<entry>March 10, 2004</entry>
	<entry>5.2-CURRENT after time_t is changed to a
	64-bit value on sparc64.</entry>
	</row>

	<row>
	<entry>502108</entry>
	<entry>March 12, 2004</entry>
	<entry>5.2-CURRENT after Intel C/C++ compiler support in
	some headers and execve(2) changes to be more strictly
	conforming to POSIX.</entry>
	</row>

	<row>
	<entry>502109</entry>
	<entry>March 22, 2004</entry>
	<entry>5.2-CURRENT after the introduction of the
	bus_alloc_resource_any API</entry>
	</row>

	<row>
	<entry>502110</entry>
	<entry>March 27, 2004</entry>
	<entry>5.2-CURRENT after the addition of UTF-8
	locales</entry>
	</row>

	<row>
	<entry>502111</entry>
	<entry>April 11, 2004</entry>
	<entry>5.2-CURRENT after the removal of the getvfsent(3)
	API</entry>
	</row>

	<row>
	<entry>502112</entry>
	<entry>April 13, 2004</entry>
	<entry>5.2-CURRENT after the addition of the .warning
	directive for make.</entry>
	</row>

	<row>
	<entry>502113</entry>
	<entry>June 4, 2004</entry>
	<entry>5.2-CURRENT after ttyioctl() was made mandatory
	for serial drivers.</entry>
	</row>

	<row>
	<entry>502114</entry>
	<entry>June 13, 2004</entry>
	<entry>5.2-CURRENT after import of the ALTQ
	framework.</entry>
	</row>

	<row>
	<entry>502115</entry>
	<entry>June 14, 2004</entry>
	<entry>5.2-CURRENT after changing sema_timedwait(9) to
	return 0 on success and a non-zero error code on
	failure.</entry>
	</row>

	<row>
	<entry>502116</entry>
	<entry>June 16, 2004</entry>
	<entry>5.2-CURRENT after changing kernel dev_t to be
	pointer to struct cdev *.</entry>
	</row>

	<row>
	<entry>502117</entry>
	<entry>June 17, 2004</entry>
	<entry>5.2-CURRENT after changing kernel udev_t to
	dev_t.</entry>
	</row>

	<row>
	<entry>502118</entry>
	<entry>June 17, 2004</entry>
	<entry>5.2-CURRENT after adding support for
	CLOCK_VIRTUAL and CLOCK_PROF to clock_gettime(2) and
	clock_getres(2).</entry>
	</row>

	<row>
	<entry>502119</entry>
	<entry>June 22, 2004</entry>
	<entry>5.2-CURRENT after changing network interface
	cloning overhaul.</entry>
	</row>

	<row>
	<entry>502120</entry>
	<entry>July 2, 2004</entry>
	<entry>5.2-CURRENT after the update of the package tools
	to revision 20040629.</entry>
	</row>

	<row>
	<entry>502121</entry>
	<entry>July 9, 2004</entry>
	<entry>5.2-CURRENT after marking Bluetooth code as
	non-i386 specific.</entry>
	</row>

	<row>
	<entry>502122</entry>
	<entry>July 11, 2004</entry>
	<entry>5.2-CURRENT after the introduction of the KDB
	debugger framework, the conversion of DDB into a
	backend and the introduction of the GDB
	backend.</entry>
	</row>

	<row>
	<entry>502123</entry>
	<entry>July 12, 2004</entry>
	<entry>5.2-CURRENT after change to make VFS_ROOT take a
	struct thread argument as does vflush. Struct
	kinfo_proc now has a user data pointer. The switch of
	the default X implementation to
	<literal>xorg</literal> was also made at this
	time.</entry>
	</row>

	<row>
	<entry>502124</entry>
	<entry>July 24, 2004</entry>
	<entry>5.2-CURRENT after the change to separate the way
	ports rc.d and legacy scripts are started.</entry>
	</row>

	<row>
	<entry>502125</entry>
	<entry>July 28, 2004</entry>
	<entry>5.2-CURRENT after the backout of the previous
	change.</entry>
	</row>

	<row>
	<entry>502126</entry>
	<entry>July 31, 2004</entry>
	<entry>5.2-CURRENT after the removal of
	kmem_alloc_pageable() and the import of gcc
	3.4.2.</entry>
	</row>

	<row>
	<entry>502127</entry>
	<entry>August 2, 2004</entry>
	<entry>5.2-CURRENT after changing the UMA kernel
	API to allow ctors/inits to fail.</entry>
	</row>

	<row>
	<entry>502128</entry>
	<entry>August 8, 2004</entry>
	<entry>5.2-CURRENT after the change of the
	vfs_mount signature as well as global replacement of
	PRISON_ROOT with SUSER_ALLOWJAIL for the suser(9)
	API.</entry>
	</row>

	<row>
	<entry>503000</entry>
	<entry>August 23, 2004</entry>
	<entry>5.3-BETA/RC before the pfil API change</entry>
	</row>

	<row>
	<entry>503001</entry>
	<entry>September 22, 2004</entry>
	<entry>5.3-RELEASE</entry>
	</row>

	<row>
	<entry>503100</entry>
	<entry>October 16, 2004</entry>
	<entry>5.3-STABLE after branching for RELENG_5_3</entry>
	</row>

	<row>
	<entry>503101</entry>
	<entry>December 3, 2004</entry>
	<entry>5.3-STABLE after addition of glibc style
	&man.strftime.3; padding options.</entry>
	</row>

	<row>
	<entry>503102</entry>
	<entry>February 13, 2005</entry>
	<entry>5.3-STABLE after OpenBSD's nc(1) import
	MFC.</entry>
	</row>

	<row>
	<entry>503103</entry>
	<entry>February 27, 2005</entry>
	<entry>5.4-PRERELEASE after the MFC of the fixes in
	<filename><src/include/stdbool.h></filename> and
	<filename><src/sys/i386/include/_types.h></filename>
	for using the GCC-compatibility of the Intel C/C++
	compiler.</entry>
	</row>

	<row>
	<entry>503104</entry>
	<entry>February 28, 2005</entry>
	<entry>5.4-PRERELEASE after the MFC of the change of
	ifi_epoch from wall clock time to uptime.</entry>
	</row>

	<row>
	<entry>503105</entry>
	<entry>March 2, 2005</entry>
	<entry>5.4-PRERELEASE after the MFC of the fix of
	EOVERFLOW check in vswprintf(3).</entry>
	</row>

	<row>
	<entry>504000</entry>
	<entry>April 3, 2005</entry>
	<entry>5.4-RELEASE.</entry>
	</row>

	<row>
	<entry>504100</entry>
	<entry>April 3, 2005</entry>
	<entry>5.4-STABLE after branching for RELENG_5_4</entry>
	</row>

	<row>
	<entry>504101</entry>
	<entry>May 11, 2005</entry>
	<entry>5.4-STABLE after increasing the default
	thread stacksizes</entry>
	</row>

	<row>
	<entry>504102</entry>
	<entry>June 24, 2005</entry>
	<entry>5.4-STABLE after the addition of sha256</entry>
	</row>

	<row>
	<entry>504103</entry>
	<entry>October 3, 2005</entry>
	<entry>5.4-STABLE after the MFC of if_bridge</entry>
	</row>

	<row>
	<entry>504104</entry>
	<entry>November 13, 2005</entry>
	<entry>5.4-STABLE after the MFC of bsdiff and
	portsnap</entry>
	</row>

	<row>
	<entry>504105</entry>
	<entry>January 17, 2006</entry>
	<entry>5.4-STABLE after MFC of ldconfig_local_dirs
	change.</entry>
	</row>

	<row>
	<entry>505000</entry>
	<entry>May 12, 2006</entry>
	<entry>5.5-RELEASE.</entry>
	</row>

	<row>
	<entry>505100</entry>
	<entry>May 12, 2006</entry>
	<entry>5.5-STABLE after branching for RELENG_5_5</entry>
	</row>

	<row>
	<entry>600000</entry>
	<entry>August 18, 2004</entry>
	<entry>6.0-CURRENT</entry>
	</row>

	<row>
	<entry>600001</entry>
	<entry>August 27, 2004</entry>
	<entry>6.0-CURRENT after permanently enabling PFIL_HOOKS
	in the kernel.</entry>
	</row>

	<row>
	<entry>600002</entry>
	<entry>August 30, 2004</entry>
	<entry>6.0-CURRENT after initial addition of
	ifi_epoch to struct if_data. Backed out after a
	few days. Do not use this value.</entry>
	</row>

	<row>
	<entry>600003</entry>
	<entry>September 8, 2004</entry>
	<entry>6.0-CURRENT after the re-addition of the
	ifi_epoch member of struct if_data.</entry>
	</row>

	<row>
	<entry>600004</entry>
	<entry>September 29, 2004</entry>
	<entry>6.0-CURRENT after addition of the struct inpcb
	argument to the pfil API.</entry>
	</row>

	<row>
	<entry>600005</entry>
	<entry>October 5, 2004</entry>
	<entry>6.0-CURRENT after addition of the "-d
	DESTDIR" argument to newsyslog.</entry>
	</row>

	<row>
	<entry>600006</entry>
	<entry>November 4, 2004</entry>
	<entry>6.0-CURRENT after addition of glibc style
	&man.strftime.3; padding options.</entry>
	</row>

	<row>
	<entry>600007</entry>
	<entry>December 12, 2004</entry>
	<entry>6.0-CURRENT after addition of 802.11 framework
	updates.</entry>
	</row>

	<row>
	<entry>600008</entry>
	<entry>January 25, 2005</entry>
	<entry>6.0-CURRENT after changes to VOP_*VOBJECT()
	functions and introduction of MNTK_MPSAFE flag for
	Giantfree filesystems.</entry>
	</row>

	<row>
	<entry>600009</entry>
	<entry>February 4, 2005</entry>
	<entry>6.0-CURRENT after addition of the cpufreq
	framework and drivers.</entry>
	</row>

	<row>
	<entry>600010</entry>
	<entry>February 6, 2005</entry>
	<entry>6.0-CURRENT after importing OpenBSD's
	nc(1).</entry>
	</row>

	<row>
	<entry>600011</entry>
	<entry>February 12, 2005</entry>
	<entry>6.0-CURRENT after removing semblance of SVID2
	<literal>matherr()</literal> support.</entry>
	</row>

	<row>
	<entry>600012</entry>
	<entry>February 15, 2005</entry>
	<entry>6.0-CURRENT after increase of default thread
	stacks' size.</entry>
	</row>

	<row>
	<entry>600013</entry>
	<entry>February 19, 2005</entry>
	<entry>6.0-CURRENT after fixes in
	<filename><src/include/stdbool.h></filename> and
	<filename><src/sys/i386/include/_types.h></filename>
	for using the GCC-compatibility of the Intel C/C++
	compiler.</entry>
	</row>

	<row>
	<entry>600014</entry>
	<entry>February 21, 2005</entry>
	<entry>6.0-CURRENT after EOVERFLOW checks in
	vswprintf(3) fixed.</entry>
	</row>

	<row>
	<entry>600015</entry>
	<entry>February 25, 2005</entry>
	<entry>6.0-CURRENT after changing the struct if_data
	member, ifi_epoch, from wall clock time to
	uptime.</entry>
	</row>

	<row>
	<entry>600016</entry>
	<entry>February 26, 2005</entry>
	<entry>6.0-CURRENT after LC_CTYPE disk format
	changed.</entry>
	</row>

	<row>
	<entry>600017</entry>
	<entry>February 27, 2005</entry>
	<entry>6.0-CURRENT after NLS catalogs disk format
	changed.</entry>
	</row>

	<row>
	<entry>600018</entry>
	<entry>February 27, 2005</entry>
	<entry>6.0-CURRENT after LC_COLLATE disk format
	changed.</entry>
	</row>

	<row>
	<entry>600019</entry>
	<entry>February 28, 2005</entry>
	<entry>Installation of acpica includes into
	/usr/include.</entry>
	</row>

	<row>
	<entry>600020</entry>
	<entry>March 9, 2005</entry>
	<entry>Addition of MSG_NOSIGNAL flag to send(2)
	API.</entry>
	</row>

	<row>
	<entry>600021</entry>
	<entry>March 17, 2005</entry>
	<entry>Addition of fields to cdevsw</entry>
	</row>

	<row>
	<entry>600022</entry>
	<entry>March 21, 2005</entry>
	<entry>Removed gtar from base system.</entry>
	</row>

	<row>
	<entry>600023</entry>
	<entry>April 13, 2005</entry>
	<entry>LOCAL_CREDS, LOCAL_CONNWAIT socket options added
	to unix(4).</entry>
	</row>

	<row>
	<entry>600024</entry>
	<entry>April 19, 2005</entry>
	<entry>&man.hwpmc.4; and related tools added to
	6.0-CURRENT.</entry>
	</row>

	<row>
	<entry>600025</entry>
	<entry>April 26, 2005</entry>
	<entry>struct icmphdr added to 6.0-CURRENT.</entry>
	</row>

	<row>
	<entry>600026</entry>
	<entry>May 3, 2005</entry>
	<entry>pf updated to 3.7.</entry>
	</row>

	<row>
	<entry>600027</entry>
	<entry>May 6, 2005</entry>
	<entry>Kernel libalias and ng_nat introduced.</entry>
	</row>

	<row>
	<entry>600028</entry>
	<entry>May 13, 2005</entry>
	<entry>POSIX ttyname_r(3) made available through
	unistd.h and libc.</entry>
	</row>

	<row>
	<entry>600029</entry>
	<entry>May 29, 2005</entry>
	<entry>6.0-CURRENT after libpcap updated to v0.9.1 alpha
	096.</entry>
	</row>

	<row>
	<entry>600030</entry>
	<entry>June 5, 2005</entry>
	<entry>6.0-CURRENT after importing NetBSD's
	if_bridge(4).</entry>
	</row>

	<row>
	<entry>600031</entry>
	<entry>June 10, 2005</entry>
	<entry>6.0-CURRENT after struct ifnet was broken out
	of the driver softcs.</entry>
	</row>

	<row>
	<entry>600032</entry>
	<entry>July 11, 2005</entry>
	<entry>6.0-CURRENT after the import of libpcap
	v0.9.1.</entry>
	</row>

	<row>
	<entry>600033</entry>
	<entry>July 25, 2005</entry>
	<entry>6.0-STABLE after bump of all shared library
	versions that had not been changed since
	RELENG_5.</entry>
	</row>

	<row>
	<entry>600034</entry>
	<entry>August 13, 2005</entry>
	<entry>6.0-STABLE after credential argument is added to
	dev_clone event handler. 6.0-RELEASE.</entry>
	</row>

	<row>
	<entry>600100</entry>
	<entry>November 1, 2005</entry>
	<entry>6.0-STABLE after 6.0-RELEASE</entry>
	</row>

	<row>
	<entry>600101</entry>
	<entry>December 21, 2005</entry>
	<entry>6.0-STABLE after incorporating scripts from the
	local_startup directories into the base
	&man.rcorder.8;.</entry>
	</row>

	<row>
	<entry>600102</entry>
	<entry>December 30, 2005</entry>
	<entry>6.0-STABLE after updating the ELF types and
	constants.</entry>
	</row>

	<row>
	<entry>600103</entry>
	<entry>January 15, 2006</entry>
	<entry>6.0-STABLE after MFC of pidfile(3) API.</entry>
	</row>

	<row>
	<entry>600104</entry>
	<entry>January 17, 2006</entry>
	<entry>6.0-STABLE after MFC of ldconfig_local_dirs
	change.</entry>
	</row>

	<row>
	<entry>600105</entry>
	<entry>February 26, 2006</entry>
	<entry>6.0-STABLE after NLS catalog support of
	csh(1).</entry>
	</row>

	<row>
	<entry>601000</entry>
	<entry>May 6, 2006</entry>
	<entry>6.1-RELEASE</entry>
	</row>

	<row>
	<entry>601100</entry>
	<entry>May 6, 2006</entry>
	<entry>6.1-STABLE after 6.1-RELEASE.</entry>
	</row>

	<row>
	<entry>601101</entry>
	<entry>June 22, 2006</entry>
	<entry>6.1-STABLE after the import of csup.</entry>
	</row>

	<row>
	<entry>601102</entry>
	<entry>July 11, 2006</entry>
	<entry>6.1-STABLE after the iwi(4) update.</entry>
	</row>

	<row>
	<entry>601103</entry>
	<entry>July 17, 2006</entry>
	<entry>6.1-STABLE after the resolver update to
	BIND9, and exposure of reentrant version of
	netdb functions.</entry>
	</row>

	<row>
	<entry>601104</entry>
	<entry>August 8, 2006</entry>
	<entry>6.1-STABLE after DSO (dynamic shared
	objects) support has been enabled in
	OpenSSL.</entry>
	</row>

	<row>
	<entry>601105</entry>
	<entry>September 2, 2006</entry>
	<entry>6.1-STABLE after 802.11 fixups changed the
	api for the IEEE80211_IOC_STA_INFO ioctl.</entry>
	</row>

	<row>
	<entry>602000</entry>
	<entry>November 15, 2006</entry>
	<entry>6.2-RELEASE</entry>
	</row>

	<row>
	<entry>602100</entry>
	<entry>September 15, 2006</entry>
	<entry>6.2-STABLE after 6.2-RELEASE.</entry>
	</row>

	<row>
	<entry>602101</entry>
	<entry>December 12, 2006</entry>
	<entry>6.2-STABLE after the addition of Wi-Spy
	quirk.</entry>
	</row>

	<row>
	<entry>602102</entry>
	<entry>December 28, 2006</entry>
	<entry>6.2-STABLE after pci_find_extcap()
	addition.</entry>
	</row>

	<row>
	<entry>602103</entry>
	<entry>January 16, 2007</entry>
	<entry>6.2-STABLE after MFC of dlsym change to look for
	a requested symbol both in specified dso and its
	implicit dependencies.</entry>
	</row>

	<row>
	<entry>602104</entry>
	<entry>January 28, 2007</entry>
	<entry>6.2-STABLE after MFC of ng_deflate(4) and
	ng_pred1(4) netgraph nodes and new compression and
	encryption modes for ng_ppp(4) node.</entry>
	</row>

	<row>
	<entry>602105</entry>
	<entry>February 20, 2007</entry>
	<entry>6.2-STABLE after MFC of BSD licensed version of
	&man.gzip.1; ported from NetBSD.</entry>
	</row>

	<row>
	<entry>602106</entry>
	<entry>March 31, 2007</entry>
	<entry>6.2-STABLE after MFC of PCI MSI and MSI-X
	support.</entry>
	</row>

	<row>
	<entry>602107</entry>
	<entry>April 6, 2007</entry>
	<entry>6.2-STABLE after MFC of ncurses 5.6 and wide
	character support.</entry>
	</row>

	<row>
	<entry>602108</entry>
	<entry>April 11, 2007</entry>
	<entry>6.2-STABLE after MFC of CAM 'SG' peripheral
	device, which implements a subset of Linux SCSI SG
	passthrough device API.</entry>
	</row>

	<row>
	<entry>602109</entry>
	<entry>April 17, 2007</entry>
	<entry>6.2-STABLE after MFC of readline 5.2 patchset
	002.</entry>
	</row>

	<row>
	<entry>602110</entry>
	<entry>May 2, 2007</entry>
	<entry>6.2-STABLE after MFC of pmap_invalidate_cache(),
	pmap_change_attr(), pmap_mapbios(),
	pmap_mapdev_attr(), and pmap_unmapbios() for amd64 and
	i386.</entry>
	</row>

	<row>
	<entry>602111</entry>
	<entry>June 11, 2007</entry>
	<entry>6.2-STABLE after MFC of BOP_BDFLUSH and caused
	breakage of the filesystem modules KBI.</entry>
	</row>

	<row>
	<entry>602112</entry>
	<entry>September 21, 2007</entry>
	<entry>6.2-STABLE after libutil(3) MFC's.</entry>
	</row>

	<row>
	<entry>602113</entry>
	<entry>October 25, 2007</entry>
	<entry>6.2-STABLE after MFC of wide and single byte
	ctype separation. Newly compiled binary that
	references to ctype.h may require a new symbol,
	__mb_sb_limit, which is not available on older
	systems.</entry>
	</row>

	<row>
	<entry>602114</entry>
	<entry>October 30, 2007</entry>
	<entry>6.2-STABLE after ctype ABI forward compatibility
	restored.</entry>
	</row>

	<row>
	<entry>602115</entry>
	<entry>November 21, 2007</entry>
	<entry>6.2-STABLE after back out of wide and single byte
	ctype separation.</entry>
	</row>

	<row>
	<entry>603000</entry>
	<entry>November 25, 2007</entry>
	<entry>6.3-RELEASE</entry>
	</row>

	<row>
	<entry>603100</entry>
	<entry>November 25, 2007</entry>
	<entry>6.3-STABLE after 6.3-RELEASE.</entry>
	</row>

	<row>
	<entry>603101</entry>
	<entry>December 7, 2007</entry>
	<entry>6.3-STABLE after fixing
	multibyte type support in bit macro.</entry>
	</row>

	<row>
	<entry>603102</entry>
	<entry>April 24, 2008</entry>
	<entry>6.3-STABLE after adding l_sysid to struct
	flock.</entry>
	</row>

	<row>
	<entry>603103</entry>
	<entry>May 27, 2008</entry>
	<entry>6.3-STABLE after MFC of the
	<function>memrchr</function> function.</entry>
	</row>

	<row>
	<entry>603104</entry>
	<entry>June 15, 2008</entry>
	<entry>6.3-STABLE after MFC of support for
	<literal>:u</literal> variable modifier in
	make(1).</entry>
	</row>

	<row>
	<entry>604000</entry>
	<entry>October 4, 2008</entry>
	<entry>6.4-RELEASE</entry>
	</row>

	<row>
	<entry>604100</entry>
	<entry>October 4, 2008</entry>
	<entry>6.4-STABLE after 6.4-RELEASE.</entry>
	</row>

	<row>
	<entry>700000</entry>
	<entry>July 11, 2005</entry>
	<entry>7.0-CURRENT.</entry>
	</row>

	<row>
	<entry>700001</entry>
	<entry>July 23, 2005</entry>
	<entry>7.0-CURRENT after bump of all shared library
	versions that had not been changed since
	RELENG_5.</entry>
	</row>

	<row>
	<entry>700002</entry>
	<entry>August 13, 2005</entry>
	<entry>7.0-CURRENT after credential argument is added to
	dev_clone event handler.</entry>
	</row>

	<row>
	<entry>700003</entry>
	<entry>August 25, 2005</entry>
	<entry>7.0-CURRENT after memmem(3) is added to
	libc.</entry>
	</row>

	<row>
	<entry>700004</entry>
	<entry>October 30, 2005</entry>
	<entry>7.0-CURRENT after solisten(9) kernel arguments
	are modified to accept a backlog parameter.</entry>
	</row>

	<row>
	<entry>700005</entry>
	<entry>November 11, 2005</entry>
	<entry>7.0-CURRENT after IFP2ENADDR() was changed to
	return a pointer to IF_LLADDR().</entry>
	</row>

	<row>
	<entry>700006</entry>
	<entry>November 11, 2005</entry>
	<entry>7.0-CURRENT after addition of
	<literal>if_addr</literal> member to <literal>struct
	ifnet</literal> and IFP2ENADDR() removal.</entry>
	</row>

	<row>
	<entry>700007</entry>
	<entry>December 2, 2005</entry>
	<entry>7.0-CURRENT after incorporating scripts from the
	local_startup directories into the base
	&man.rcorder.8;.</entry>
	</row>

	<row>
	<entry>700008</entry>
	<entry>December 5, 2005</entry>
	<entry>7.0-CURRENT after removal of MNT_NODEV mount
	option.</entry>
	</row>

	<row>
	<entry>700009</entry>
	<entry>December 19, 2005</entry>
	<entry>7.0-CURRENT after ELF-64 type changes and symbol
	versioning.</entry>
	</row>

	<row>
	<entry>700010</entry>
	<entry>December 20, 2005</entry>
	<entry>7.0-CURRENT after addition of hostb and vgapci
	drivers, addition of pci_find_extcap(), and changing
	the AGP drivers to no longer map the aperture.</entry>
	</row>

	<row>
	<entry>700011</entry>
	<entry>December 31, 2005</entry>
	<entry>7.0-CURRENT after tv_sec was made time_t on
	all platforms but Alpha.</entry>
	</row>

	<row>
	<entry>700012</entry>
	<entry>January 8, 2006</entry>
	<entry>7.0-CURRENT after ldconfig_local_dirs
	change.</entry>
	</row>

	<row>
	<entry>700013</entry>
	<entry>January 12, 2006</entry>
	<entry>7.0-CURRENT after changes to
	<filename>/etc/rc.d/abi</filename> to support
	<filename>/compat/linux/etc/ld.so.cache</filename>
	being a symlink in a readonly filesystem.</entry>
	</row>

	<row>
	<entry>700014</entry>
	<entry>January 26, 2006</entry>
	<entry>7.0-CURRENT after pts import.</entry>
	</row>

	<row>
	<entry>700015</entry>
	<entry>March 26, 2006</entry>
	<entry>7.0-CURRENT after the introduction of version 2
	of &man.hwpmc.4;'s ABI.</entry>
	</row>

	<row>
	<entry>700016</entry>
	<entry>April 22, 2006</entry>
	<entry>7.0-CURRENT after addition of &man.fcloseall.3;
	to libc.</entry>
	</row>

	<row>
	<entry>700017</entry>
	<entry>May 13, 2006</entry>
	<entry>7.0-CURRENT after removal of ip6fw.</entry>
	</row>

	<row>
	<entry>700018</entry>
	<entry>July 15, 2006</entry>
	<entry>7.0-CURRENT after import of snd_emu10kx.</entry>
	</row>

	<row>
	<entry>700019</entry>
	<entry>July 29, 2006</entry>
	<entry>7.0-CURRENT after import of OpenSSL
	0.9.8b.</entry>
	</row>

	<row>
	<entry>700020</entry>
	<entry>September 3, 2006</entry>
	<entry>7.0-CURRENT after addition of bus_dma_get_tag
	function</entry>
	</row>

	<row>
	<entry>700021</entry>
	<entry>September 4, 2006</entry>
	<entry>7.0-CURRENT after libpcap 0.9.4 and tcpdump 3.9.4
	import.</entry>
	</row>

	<row>
	<entry>700022</entry>
	<entry>September 9, 2006</entry>
	<entry>7.0-CURRENT after dlsym change to look for a
	requested symbol both in specified dso and its
	implicit dependencies.</entry>
	</row>

	<row>
	<entry>700023</entry>
	<entry>September 23, 2006</entry>
	<entry>7.0-CURRENT after adding new sound IOCTLs for the
	OSSv4 mixer API.</entry>
	</row>

	<row>
	<entry>700024</entry>
	<entry>September 28, 2006</entry>
	<entry>7.0-CURRENT after import of OpenSSL
	0.9.8d.</entry>
	</row>

	<row>
	<entry>700025</entry>
	<entry>November 11, 2006</entry>
	<entry>7.0-CURRENT after the addition of libelf.</entry>
	</row>

	<row>
	<entry>700026</entry>
	<entry>November 26, 2006</entry>
	<entry>7.0-CURRENT after major changes on sound
	sysctls.</entry>
	</row>

	<row>
	<entry>700027</entry>
	<entry>November 30, 2006</entry>
	<entry>7.0-CURRENT after the addition of Wi-Spy
	quirk.</entry>
	</row>

	<row>
	<entry>700028</entry>
	<entry>December 15, 2006</entry>
	<entry>7.0-CURRENT after the addition of sctp calls to
	libc</entry>
	</row>

	<row>
	<entry>700029</entry>
	<entry>January 26, 2007</entry>
	<entry>7.0-CURRENT after the GNU &man.gzip.1;
	implementation was replaced with a BSD licensed
	version ported from NetBSD.</entry>
	</row>

	<row>
	<entry>700030</entry>
	<entry>February 7, 2007</entry>
	<entry>7.0-CURRENT after the removal of IPIP tunnel
	encapsulation (VIFF_TUNNEL) from the IPv4 multicast
	forwarding code.</entry>
	</row>

	<row>
	<entry>700031</entry>
	<entry>February 23, 2007</entry>
	<entry>7.0-CURRENT after the modification of
	bus_setup_intr() (newbus).</entry>
	</row>

	<row>
	<entry>700032</entry>
	<entry>March 2, 2007</entry>
	<entry>7.0-CURRENT after the inclusion of ipw(4) and
	iwi(4) firmware.</entry>
	</row>

	<row>
	<entry>700033</entry>
	<entry>March 9, 2007</entry>
	<entry>7.0-CURRENT after the inclusion of ncurses wide
	character support.</entry>
	</row>

	<row>
	<entry>700034</entry>
	<entry>March 19, 2007</entry>
	<entry>7.0-CURRENT after changes to how insmntque(),
	getnewvnode(), and vfs_hash_insert() work.</entry>
	</row>

	<row>
	<entry>700035</entry>
	<entry>March 26, 2007</entry>
	<entry>7.0-CURRENT after addition of a notify mechanism
	for CPU frequency changes.</entry>
	</row>

	<row>
	<entry>700036</entry>
	<entry>April 6, 2007</entry>
	<entry>7.0-CURRENT after import of the ZFS
	filesystem.</entry>
	</row>

	<row>
	<entry>700037</entry>
	<entry>April 8, 2007</entry>
	<entry>7.0-CURRENT after addition of CAM 'SG' peripheral
	device, which implements a subset of Linux SCSI SG
	passthrough device API.</entry>
	</row>

	<row>
	<entry>700038</entry>
	<entry>April 30, 2007</entry>
	<entry>7.0-CURRENT after changing &man.getenv.3;,
	&man.putenv.3;, &man.setenv.3; and &man.unsetenv.3; to
	be POSIX conformant.</entry>
	</row>

	<row>
	<entry>700039</entry>
	<entry>May 1, 2007</entry>
	<entry>7.0-CURRENT after the changes in 700038 were
	backed out.</entry>
	</row>

	<row>
	<entry>700040</entry>
	<entry>May 10, 2007</entry>
	<entry>7.0-CURRENT after the addition of &man.flopen.3;
	to libutil.</entry>
	</row>

	<row>
	<entry>700041</entry>
	<entry>May 13, 2007</entry>
	<entry>7.0-CURRENT after enabling symbol versioning, and
	changing the default thread library to libthr.</entry>
	</row>

	<row>
	<entry>700042</entry>
	<entry>May 19, 2007</entry>
	<entry>7.0-CURRENT after the import of gcc
	4.2.0.</entry>
	</row>

	<row>
	<entry>700043</entry>
	<entry>May 21, 2007</entry>
	<entry>7.0-CURRENT after bump of all shared library
	versions that had not been changed since
	RELENG_6.</entry>
	</row>

	<row>
	<entry>700044</entry>
	<entry>June 7, 2007</entry>
	<entry>7.0-CURRENT after changing the argument for
	vn_open()/VOP_OPEN() from file descriptor index to the
	struct file *.</entry>
	</row>

	<row>
	<entry>700045</entry>
	<entry>June 10, 2007</entry>
	<entry>7.0-CURRENT after changing &man.pam.nologin.8; to
	provide an account management function instead of an
	authentication function to the PAM framework.</entry>
	</row>

	<row>
	<entry>700046</entry>
	<entry>June 11, 2007</entry>
	<entry>7.0-CURRENT after updated 802.11 wireless
	support.</entry>
	</row>

	<row>
	<entry>700047</entry>
	<entry>June 11, 2007</entry>
	<entry>7.0-CURRENT after adding TCP LRO interface
	capabilities.</entry>
	</row>

	<row>
	<entry>700048</entry>
	<entry>June 12, 2007</entry>
	<entry>7.0-CURRENT after
	RFC 3678 API support added to the IPv4 stack.
	Legacy RFC 1724 behavior of the IP_MULTICAST_IF
	ioctl has now been removed; 0.0.0.0/8 may no longer
	be used to specify an interface index.
	struct ipmreqn should be used instead.</entry>
	</row>

	<row>
	<entry>700049</entry>
	<entry>July 3, 2007</entry>
	<entry>7.0-CURRENT after importing pf from OpenBSD
	4.1</entry>
	</row>

	<row>
	<entry>(not changed)</entry>
	<entry></entry>
	<entry>7.0-CURRENT after adding IPv6 support for
	FAST_IPSEC, deleting KAME IPSEC, and renaming
	FAST_IPSEC to IPSEC.</entry>
	</row>

	<row>
	<entry>700050</entry>
	<entry>July 4, 2007</entry>
	<entry>7.0-CURRENT after converting setenv/putenv/etc.
	calls from traditional BSD to POSIX.</entry>
	</row>

	<row>
	<entry>700051</entry>
	<entry>July 4, 2007</entry>
	<entry>7.0-CURRENT after adding new mmap/lseek/etc
	syscalls.</entry>
	</row>

	<row>
	<entry>700052</entry>
	<entry>July 6, 2007</entry>
	<entry>7.0-CURRENT after moving I4B headers to
	include/i4b.</entry>
	</row>

	<row>
	<entry>700053</entry>
	<entry>September 30, 2007</entry>
	<entry>7.0-CURRENT after the addition of support for
	PCI domains</entry>
	</row>

	<row>
	<entry>700054</entry>
	<entry>October 25, 2007</entry>
	<entry>7.0-CURRENT after MFC of wide and single byte
	ctype separation.</entry>
	</row>

	<row>
	<entry>700055</entry>
	<entry>October 28, 2007</entry>
	<entry>7.0-RELEASE, and 7.0-CURRENT after ABI backwards
	compatibility to the FreeBSD 4/5/6 versions of the
	PCIOCGETCONF, PCIOCREAD and PCIOCWRITE IOCTLs was
	MFCed, which required the ABI of the PCIOCGETCONF
	IOCTL to be broken again</entry>
	</row>

	<row>
	<entry>700100</entry>
	<entry>December 22, 2007</entry>
	<entry>7.0-STABLE after 7.0-RELEASE</entry>
	</row>

	<row>
	<entry>700101</entry>
	<entry>February 8, 2008</entry>
	<entry>7.0-STABLE after the MFC of m_collapse().</entry>
	</row>

	<row>
	<entry>700102</entry>
	<entry>March 30, 2008</entry>
	<entry>7.0-STABLE after the MFC of
	kdb_enter_why().</entry>
	</row>

	<row>
	<entry>700103</entry>
	<entry>April 10, 2008</entry>
	<entry>7.0-STABLE after adding l_sysid to struct
	flock.</entry>
	</row>

	<row>
	<entry>700104</entry>
	<entry>April 11, 2008</entry>
	<entry>7.0-STABLE after the MFC of procstat(1).</entry>
	</row>

	<row>
	<entry>700105</entry>
	<entry>April 11, 2008</entry>
	<entry>7.0-STABLE after the MFC of umtx
	features.</entry>
	</row>

	<row>
	<entry>700106</entry>
	<entry>April 15, 2008</entry>
	<entry>7.0-STABLE after the MFC of &man.write.2; support
	to &man.psm.4;.</entry>
	</row>

	<row>
	<entry>700107</entry>
	<entry>April 20, 2008</entry>
	<entry>7.0-STABLE after the MFC of F_DUP2FD command
	to &man.fcntl.2;.</entry>
	</row>

	<row>
	<entry>700108</entry>
	<entry>May 5, 2008</entry>
	<entry>7.0-STABLE after some &man.lockmgr.9; changes,
	which makes it necessary to include
	<filename>sys/lock.h</filename> in order to use
	&man.lockmgr.9;.</entry>
	</row>

	<row>
	<entry>700109</entry>
	<entry>May 27, 2008</entry>
	<entry>7.0-STABLE after MFC of the
	<function>memrchr</function> function.</entry>
	</row>

	<row>
	<entry>700110</entry>
	<entry>August 5, 2008</entry>
	<entry>7.0-STABLE after MFC of kernel NFS lockd
	client.</entry>
	</row>

	<row>
	<entry>700111</entry>
	<entry>August 20, 2008</entry>
	<entry>7.0-STABLE after addition of physically
	contiguous jumbo frame support.</entry>
	</row>

	<row>
	<entry>700112</entry>
	<entry>August 27, 2008</entry>
	<entry>7.0-STABLE after MFC of kernel DTrace
	support.</entry>
	</row>

	<row>
	<entry>701000</entry>
	<entry>November 25, 2008</entry>
	<entry>7.1-RELEASE</entry>
	</row>

	<row>
	<entry>701100</entry>
	<entry>November 25, 2008</entry>
	<entry>7.1-STABLE after 7.1-RELEASE.</entry>
	</row>

	<row>
	<entry>701101</entry>
	<entry>January 10, 2009</entry>
	<entry>7.1-STABLE after <function>strndup</function>
	merge.</entry>
	</row>

	<row>
	<entry>701102</entry>
	<entry>January 17, 2009</entry>
	<entry>7.1-STABLE after cpuctl(4) support
	added.</entry>
	</row>

	<row>
	<entry>701103</entry>
	<entry>February 7, 2009</entry>
	<entry>7.1-STABLE after the merge of
	multi-/no-IPv4/v6 jails.</entry>
	</row>

	<row>
	<entry>701104</entry>
	<entry>February 14, 2009</entry>
	<entry>7.1-STABLE after the store of the suspension
	owner in the struct mount, and introduction of
	vfs_susp_clean method into the struct vfsops.</entry>
	</row>

	<row>
	<entry>701105</entry>
	<entry>March 12, 2009</entry>
	<entry>7.1-STABLE after the incompatible change
	to the kern.ipc.shmsegs sysctl to allow to allocate
	larger SysV shared memory segments on 64bit
	architectures.</entry>
	</row>

	<row>
	<entry>701106</entry>
	<entry>March 14, 2009</entry>
	<entry>7.1-STABLE after the merge of a fix for
	POSIX semaphore wait operations.</entry>
	</row>

	<row>
	<entry>702000</entry>
	<entry>April 15, 2009</entry>
	<entry>7.2-RELEASE</entry>
	</row>

	<row>
	<entry>702100</entry>
	<entry>April 15, 2009</entry>
	<entry>7.2-STABLE after 7.2-RELEASE.</entry>
	</row>

	<row>
	<entry>702101</entry>
	<entry>May 15, 2009</entry>
	<entry>7.2-STABLE after ichsmb(4) was changed to
	use left-adjusted slave addressing to match other
	SMBus controller drivers.</entry>
	</row>

	<row>
	<entry>702102</entry>
	<entry>May 28, 2009</entry>
	<entry>7.2-STABLE after MFC of the
	<function>fdopendir</function> function.</entry>
	</row>

	<row>
	<entry>702103</entry>
	<entry>June 06, 2009</entry>
	<entry>7.2-STABLE after MFC of PmcTools.</entry>
	</row>

	<row>
	<entry>702104</entry>
	<entry>July 14, 2009</entry>
	<entry>7.2-STABLE after MFC of the
	<function>closefrom</function> system call.</entry>
	</row>

	<row>
	<entry>702105</entry>
	<entry>July 31, 2009</entry>
	<entry>7.2-STABLE after MFC of the SYSVIPC ABI
	change.</entry>
	</row>

	<row>
	<entry>702106</entry>
	<entry>September 14, 2009</entry>
	<entry>7.2-STABLE after MFC of the x86 PAT
	enhancements and addition of d_mmap_single() and
	the scatter/gather list VM object type.</entry>
	</row>

	<row>
	<entry>703000</entry>
	<entry>February 9, 2010</entry>
	<entry>7.3-RELEASE</entry>
	</row>

	<row>
	<entry>703100</entry>
	<entry>February 9, 2010</entry>
	<entry>7.3-STABLE after 7.3-RELEASE.</entry>
	</row>

	<row>
	<entry>704000</entry>
	<entry>December 22, 2010</entry>
	<entry>7.4-RELEASE</entry>
	</row>

	<row>
	<entry>704100</entry>
	<entry>December 22, 2010</entry>
	<entry>7.4-STABLE after 7.4-RELEASE.</entry>
	</row>

	<row>
	<entry>800000</entry>
	<entry>October 11, 2007</entry>
	<entry>8.0-CURRENT. Separating wide and single byte
	ctype.</entry>
	</row>

	<row>
	<entry>800001</entry>
	<entry>October 16, 2007</entry>
	<entry>8.0-CURRENT after libpcap 0.9.8 and tcpdump 3.9.8
	import.</entry>
	</row>

	<row>
	<entry>800002</entry>
	<entry>October 21, 2007</entry>
	<entry>8.0-CURRENT after renaming kthread_create()
	and friends to kproc_create() etc.</entry>
	</row>

	<row>
	<entry>800003</entry>
	<entry>October 24, 2007</entry>
	<entry>8.0-CURRENT after ABI backwards compatibility
	to the FreeBSD 4/5/6 versions of the PCIOCGETCONF,
	PCIOCREAD and PCIOCWRITE IOCTLs was added, which
	required the ABI of the PCIOCGETCONF IOCTL to be
	broken again</entry>
	</row>

	<row>
	<entry>800004</entry>
	<entry>November 12, 2007</entry>
	<entry>8.0-CURRENT after agp(4) driver moved from
	src/sys/pci to src/sys/dev/agp</entry>
	</row>

	<row>
	<entry>800005</entry>
	<entry>December 4, 2007</entry>
	<entry>8.0-CURRENT after
	<ulink
	url="http://www.freebsd.org/cgi/cvsweb.cgi/src/sys/kern/kern_mbuf.c#rev1.35">changes
	to the jumbo frame allocator</ulink>.</entry>
	</row>

	<row>
	<entry>800006</entry>
	<entry>December 7, 2007</entry>
	<entry>8.0-CURRENT after the addition of callgraph
	capture functionality to &man.hwpmc.4;.</entry>
	</row>

	<row>
	<entry>800007</entry>
	<entry>December 25, 2007</entry>
	<entry>8.0-CURRENT after kdb_enter() gains a "why"
	argument.</entry>
	</row>

	<row>
	<entry>800008</entry>
	<entry>December 28, 2007</entry>
	<entry>8.0-CURRENT after LK_EXCLUPGRADE option
	removal.</entry>
	</row>

	<row>
	<entry>800009</entry>
	<entry>January 9, 2008</entry>
	<entry>8.0-CURRENT after introduction of
	&man.lockmgr.disown.9;</entry>
	</row>

	<row>
	<entry>800010</entry>
	<entry>January 10, 2008</entry>
	<entry>8.0-CURRENT after the &man.vn.lock.9; prototype
	change.</entry>
	</row>

	<row>
	<entry>800011</entry>
	<entry>January 13, 2008</entry>
	<entry>8.0-CURRENT after the &man.VOP.LOCK.9; and
	&man.VOP.UNLOCK.9; prototype changes.</entry>
	</row>

	<row>
	<entry>800012</entry>
	<entry>January 19, 2008</entry>
	<entry>8.0-CURRENT after introduction of
	&man.lockmgr.recursed.9;, &man.BUF.RECURSED.9; and
	&man.BUF.ISLOCKED.9; and the removal of
	<function>BUF_REFCNT()</function>.</entry>
	</row>

	<row>
	<entry>800013</entry>
	<entry>January 23, 2008</entry>
	<entry>8.0-CURRENT after introduction of the
	<quote>ASCII</quote> encoding.</entry>
	</row>

	<row>
	<entry>800014</entry>
	<entry>January 24, 2008</entry>
	<entry>8.0-CURRENT after changing the prototype of
	&man.lockmgr.9; and removal of
	<function>lockcount()</function> and
	<function>LOCKMGR_ASSERT()</function>.</entry>
	</row>

	<row>
	<entry>800015</entry>
	<entry>January 26, 2008</entry>
	<entry>8.0-CURRENT after extending the types
	of the &man.fts.3; structures.</entry>
	</row>

	<row>
	<entry>800016</entry>
	<entry>February 1, 2008</entry>
	<entry>8.0-CURRENT after adding an argument to
	MEXTADD(9)</entry>
	</row>

	<row>
	<entry>800017</entry>
	<entry>February 6, 2008</entry>
	<entry>8.0-CURRENT after the introduction of
	LK_NODUP and LK_NOWITNESS options in the
	&man.lockmgr.9; space.</entry>
	</row>

	<row>
	<entry>800018</entry>
	<entry>February 8, 2008</entry>
	<entry>8.0-CURRENT after the addition of
	m_collapse.</entry>
	</row>

	<row>
	<entry>800019</entry>
	<entry>February 9, 2008</entry>
	<entry>8.0-CURRENT after the addition of current
	working directory, root directory, and jail
	directory support to the kern.proc.filedesc
	sysctl.</entry>
	</row>

	<row>
	<entry>800020</entry>
	<entry>February 13, 2008</entry>
	<entry>8.0-CURRENT after introduction of
	&man.lockmgr.assert.9; and
	<function>BUF_ASSERT</function> functions.</entry>
	</row>

	<row>
	<entry>800021</entry>
	<entry>February 15, 2008</entry>
	<entry>8.0-CURRENT after introduction of
	&man.lockmgr.args.9; and LK_INTERNAL flag
	removal.</entry>
	</row>

	<row>
	<entry>800022</entry>
	<entry>(backed out)</entry>
	<entry>8.0-CURRENT after changing the default system ar
	to BSD &man.ar.1;.</entry>
	</row>

	<row>
	<entry>800023</entry>
	<entry>February 25, 2008</entry>
	<entry>8.0-CURRENT after changing the prototypes of
	&man.lockstatus.9; and &man.VOP.ISLOCKED.9;, more
	specifically retiring the
	<literal>struct thread</literal> argument.</entry>
	</row>

	<row>
	<entry>800024</entry>
	<entry>March 1, 2008</entry>
	<entry>8.0-CURRENT after axing out the
	<function>lockwaiters</function> and
	<function>BUF_LOCKWAITERS</function> functions,
	changing the return value of
	<function>brelvp</function> from void to int and
	introducing new flags for &man.lockinit.9;.</entry>
	</row>

	<row>
	<entry>800025</entry>
	<entry>March 8, 2008</entry>
	<entry>8.0-CURRENT after adding F_DUP2FD command
	to &man.fcntl.2;.</entry>
	</row>

	<row>
	<entry>800026</entry>
	<entry>March 12, 2008</entry>
	<entry>8.0-CURRENT after changing the priority parameter
	to cv_broadcastpri such that 0 means no
	priority.</entry>
	</row>

	<row>
	<entry>800027</entry>
	<entry>March 24, 2008</entry>
	<entry>8.0-CURRENT after changing the bpf monitoring ABI
	when zerocopy bpf buffers were added.</entry>
	</row>

	<row>
	<entry>800028</entry>
	<entry>March 26, 2008</entry>
	<entry>8.0-CURRENT after adding l_sysid to struct
	flock.</entry>
	</row>

	<row>
	<entry>800029</entry>
	<entry>March 28, 2008</entry>
	<entry>8.0-CURRENT after reintegration of the
	<function>BUF_LOCKWAITERS</function> function and the
	addition of &man.lockmgr.waiters.9;.</entry>
	</row>

	<row>
	<entry>800030</entry>
	<entry>April 1, 2008</entry>
	<entry>8.0-CURRENT after the introduction of the
	&man.rw.try.rlock.9; and &man.rw.try.wlock.9;
	functions.</entry>
	</row>

	<row>
	<entry>800031</entry>
	<entry>April 6, 2008</entry>
	<entry>8.0-CURRENT after the introduction of the
	<function>lockmgr_rw</function> and
	<function>lockmgr_args_rw</function>
	functions.</entry>
	</row>

	<row>
	<entry>800032</entry>
	<entry>April 8, 2008</entry>
	<entry>8.0-CURRENT after the implementation of the
	openat and related syscalls, introduction of the
	O_EXEC flag for the &man.open.2;, and providing the
	corresponding linux compatibility syscalls.</entry>
	</row>

	<row>
	<entry>800033</entry>
	<entry>April 8, 2008</entry>
	<entry>8.0-CURRENT after added &man.write.2; support for
	&man.psm.4; in native operation level. Now arbitrary
	commands can be written to
	<devicename>/dev/psm%d</devicename> and status can be
	read back from it.</entry>
	</row>

	<row>
	<entry>800034</entry>
	<entry>April 10, 2008</entry>
	<entry>8.0-CURRENT after introduction of the
	<function>memrchr</function> function.</entry>
	</row>

	<row>
	<entry>800035</entry>
	<entry>April 16, 2008</entry>
	<entry>8.0-CURRENT after introduction of the
	<function>fdopendir</function> function.</entry>
	</row>

	<row>
	<entry>800036</entry>
	<entry>April 20, 2008</entry>
	<entry>8.0-CURRENT after switchover of 802.11 wireless
	to multi-bss support (aka vaps).</entry>
	</row>

	<row>
	<entry>800037</entry>
	<entry>May 9, 2008</entry>
	<entry>8.0-CURRENT after addition of multi routing
	table support (aka setfib(1), setfib(2)).</entry>
	</row>

	<row>
	<entry>800038</entry>
	<entry>May 26, 2008</entry>
	<entry>8.0-CURRENT after removal of netatm and
	ISDN4BSD. Also, the addition of the
	Compact C Type (CTF) tools.</entry>
	</row>

	<row>
	<entry>800039</entry>
	<entry>June 14, 2008</entry>
	<entry>8.0-CURRENT after removal of sgtty.</entry>
	</row>

	<row>
	<entry>800040</entry>
	<entry>June 26, 2008</entry>
	<entry>8.0-CURRENT with kernel NFS lockd client.</entry>
	</row>

	<row>
	<entry>800041</entry>
	<entry>July 22, 2008</entry>
	<entry>8.0-CURRENT after addition of arc4random_buf(3)
	and arc4random_uniform(3).</entry>
	</row>

	<row>
	<entry>800042</entry>
	<entry>August 8, 2008</entry>
	<entry>8.0-CURRENT after addition of cpuctl(4).</entry>
	</row>

	<row>
	<entry>800043</entry>
	<entry>August 13, 2008</entry>
	<entry>8.0-CURRENT after changing bpf(4) to use a
	single device node, instead of device cloning.</entry>
	</row>

	<row>
	<entry>800044</entry>
	<entry>August 17, 2008</entry>
	<entry>8.0-CURRENT after the commit of the first step of
	the vimage project renaming global variables to be
	virtualized with a V_ prefix with macros to map them
	back to their global names.</entry>
	</row>

	<row>
	<entry>800045</entry>
	<entry>August 20, 2008</entry>
	<entry>8.0-CURRENT after the integration of the
	MPSAFE TTY layer, including changes to various
	drivers and utilities that interact with it.</entry>
	</row>

	<row>
	<entry>800046</entry>
	<entry>September 8, 2008</entry>
	<entry>8.0-CURRENT after the separation of the GDT
	per CPU on amd64 architecture.</entry>
	</row>

	<row>
	<entry>800047</entry>
	<entry>September 10, 2008</entry>
	<entry>8.0-CURRENT after removal of VSVTX, VSGID
	and VSUID.</entry>
	</row>

	<row>
	<entry>800048</entry>
	<entry>September 16, 2008</entry>
	<entry>8.0-CURRENT after converting the kernel NFS mount
	code to accept individual mount options in the
	nmount() iovec, not just one big
	struct nfs_args.</entry>
	</row>

	<row>
	<entry>800049</entry>
	<entry>September 17, 2008</entry>
	<entry>8.0-CURRENT after the removal of &man.suser.9;
	and &man.suser.cred.9;.</entry>
	</row>

	<row>
	<entry>800050</entry>
	<entry>October 20, 2008</entry>
	<entry>8.0-CURRENT after buffer cache API
	change.</entry>
	</row>

	<row>
	<entry>800051</entry>
	<entry>October 23, 2008</entry>
	<entry>8.0-CURRENT after the removal of the
	&man.MALLOC.9; and &man.FREE.9; macros.</entry>
	</row>

	<row>
	<entry>800052</entry>
	<entry>October 28, 2008</entry>
	<entry>8.0-CURRENT after the introduction of accmode_t
	and renaming of VOP_ACCESS 'a_mode' argument
	to 'a_accmode'.</entry>
	</row>

	<row>
	<entry>800053</entry>
	<entry>November 2, 2008</entry>
	<entry>8.0-CURRENT after the prototype change of
	&man.vfs.busy.9; and the introduction of its
	MBF_NOWAIT and MBF_MNTLSTLOCK flags.</entry>
	</row>

	<row>
	<entry>800054</entry>
	<entry>November 22, 2008</entry>
	<entry>8.0-CURRENT after the addition of buf_ring,
	memory barriers and ifnet functions to facilitate
	multiple hardware transmit queues for cards that
	support them, and a lockless ring-buffer
	implementation to enable drivers to more efficiently
	manage queuing of packets.</entry>
	</row>

	<row>
	<entry>800055</entry>
	<entry>November 27, 2008</entry>
	<entry>8.0-CURRENT after the addition of Intel™
	Core, Core2, and Atom support to
	&man.hwpmc.4;.</entry>
	</row>

	<row>
	<entry>800056</entry>
	<entry>November 29, 2008</entry>
	<entry>8.0-CURRENT after the introduction of
	multi-/no-IPv4/v6 jails.</entry>
	</row>

	<row>
	<entry>800057</entry>
	<entry>December 1, 2008</entry>
	<entry>8.0-CURRENT after the switch to the
	ath hal source code.</entry>
	</row>

	<row>
	<entry>800058</entry>
	<entry>December 12, 2008</entry>
	<entry>8.0-CURRENT after the introduction of
	the VOP_VPTOCNP operation.</entry>
	</row>

	<row>
	<entry>800059</entry>
	<entry>December 15, 2008</entry>
	<entry>8.0-CURRENT incorporates the
	new arp-v2 rewrite.</entry>
	</row>

	<row>
	<entry>800060</entry>
	<entry>December 19, 2008</entry>
	<entry>8.0-CURRENT after the addition of makefs.</entry>
	</row>

	<row>
	<entry>800061</entry>
	<entry>January 15, 2009</entry>
	<entry>8.0-CURRENT after TCP Appropriate Byte
	Counting.</entry>
	</row>

	<row>
	<entry>800062</entry>
	<entry>January 28, 2009</entry>
	<entry>8.0-CURRENT after removal of minor(),
	minor2unit(), unit2minor(), etc.</entry>
	</row>

	<row>
	<entry>800063</entry>
	<entry>February 18, 2009</entry>
	<entry>8.0-CURRENT after GENERIC config change to use
	the USB2 stack, but also the addition of
	fdevname(3).</entry>
	</row>

	<row>
	<entry>800064</entry>
	<entry>February 23, 2009</entry>
	<entry>8.0-CURRENT after the USB2 stack is moved to and
	replaces dev/usb.</entry>
	</row>

	<row>
	<entry>800065</entry>
	<entry>February 26, 2009</entry>
	<entry>8.0-CURRENT after the renaming of all functions
	in libmp(3).</entry>
	</row>

	<row>
	<entry>800066</entry>
	<entry>February 27, 2009</entry>
	<entry>8.0-CURRENT after changing USB devfs handling and
	layout.</entry>
	</row>

	<row>
	<entry>800067</entry>
	<entry>February 28, 2009</entry>
	<entry>8.0-CURRENT after adding getdelim(), getline(),
	stpncpy(), strnlen(), wcsnlen(), wcscasecmp(), and
	wcsncasecmp().</entry>
	</row>

	<row>
	<entry>800068</entry>
	<entry>March 2, 2009</entry>
	<entry>8.0-CURRENT after renaming the ushub devclass to
	uhub.</entry>
	</row>

	<row>
	<entry>800069</entry>
	<entry>March 9, 2009</entry>
	<entry>8.0-CURRENT after libusb20.so.1 was renamed to
	libusb.so.1.</entry>
	</row>

	<row>
	<entry>800070</entry>
	<entry>March 9, 2009</entry>
	<entry>8.0-CURRENT after merging IGMPv3 and
	Source-Specific Multicast (SSM) to the IPv4
	stack.</entry>
	</row>

	<row>
	<entry>800071</entry>
	<entry>March 14, 2009</entry>
	<entry>8.0-CURRENT after gcc was patched to use C99
	inline semantics in c99 and gnu99 mode.</entry>
	</row>

	<row>
	<entry>800072</entry>
	<entry>March 15, 2009</entry>
	<entry>8.0-CURRENT after the IFF_NEEDSGIANT flag has
	been removed; non-MPSAFE network device drivers are no
	longer supported.</entry>
	</row>

	<row>
	<entry>800073</entry>
	<entry>March 18, 2009</entry>
	<entry>8.0-CURRENT after the dynamic string token
	substitution has been implemented for rpath and needed
	paths.</entry>
	</row>

	<row>
	<entry>800074</entry>
	<entry>March 24, 2009</entry>
	<entry>8.0-CURRENT after tcpdump 4.0.0 and
	libpcap 1.0.0 import.</entry>
	</row>

	<row>
	<entry>800075</entry>
	<entry>April 6, 2009</entry>
	<entry>8.0-CURRENT after layout of structs vnet_net,
	vnet_inet and vnet_ipfw has been changed.</entry>
	</row>

	<row>
	<entry>800076</entry>
	<entry>April 9, 2009</entry>
	<entry>8.0-CURRENT after adding delay profiles in
	dummynet.</entry>
	</row>

	<row>
	<entry>800077</entry>
	<entry>April 14, 2009</entry>
	<entry>8.0-CURRENT after removing VOP_LEASE() and
	vop_vector.vop_lease.</entry>
	</row>

	<row>
	<entry>800078</entry>
	<entry>April 15, 2009</entry>
	<entry>8.0-CURRENT after struct rt_weight fields have
	been added to struct rt_metrics and struct
	rt_metrics_lite, changing the layout of struct
	rt_metrics_lite. A bump to RTM_VERSION was made, but
	backed out.</entry>
	</row>

	<row>
	<entry>800079</entry>
	<entry>April 15, 2009</entry>
	<entry>8.0-CURRENT after struct llentry pointers are
	added to struct route and struct route_in6.</entry>
	</row>

	<row>
	<entry>800080</entry>
	<entry>April 15, 2009</entry>
	<entry>8.0-CURRENT after layout of struct inpcb has been
	changed.</entry>
	</row>

	<row>
	<entry>800081</entry>
	<entry>April 19, 2009</entry>
	<entry>8.0-CURRENT after the layout of struct
	malloc_type has been changed.</entry>
	</row>

	<row>
	<entry>800082</entry>
	<entry>April 21, 2009</entry>
	<entry>8.0-CURRENT after the layout of struct ifnet has
	changed, and with if_ref() and if_rele() ifnet
	refcounting.</entry>
	</row>

	<row>
	<entry>800083</entry>
	<entry>April 22, 2009</entry>
	<entry>8.0-CURRENT after the implementation of a
	low-level Bluetooth HCI API.</entry>
	</row>

	<row>
	<entry>800084</entry>
	<entry>April 29, 2009</entry>
	<entry>8.0-CURRENT after IPv6 SSM and MLDv2
	changes.</entry>
	</row>

	<row>
	<entry>800085</entry>
	<entry>April 30, 2009</entry>
	<entry>8.0-CURRENT after enabling support for
	VIMAGE kernel builds with one active image.</entry>
	</row>

	<row>
	<entry>800086</entry>
	<entry>May 8, 2009</entry>
	<entry>8.0-CURRENT after adding support for input lines
	of arbitrarily length in patch(1).</entry>
	</row>

	<row>
	<entry>800087</entry>
	<entry>May 11, 2009</entry>
	<entry>8.0-CURRENT after some VFS KPI changes. The
	thread argument has been removed from the FSD parts of
	the VFS. <function>VFS_*</function> functions do not
	need the context any more because it always refers to
	<varname>curthread</varname>. In some special cases,
	the old behavior is retained.</entry>
	</row>

	<row>
	<entry>800088</entry>
	<entry>May 20, 2009</entry>
	<entry>8.0-CURRENT after net80211 monitor mode
	changes.</entry>
	</row>

	<row>
	<entry>800089</entry>
	<entry>May 23, 2009</entry>
	<entry>8.0-CURRENT after adding UDP control block
	support.</entry>
	</row>

	<row>
	<entry>800090</entry>
	<entry>May 23, 2009</entry>
	<entry>8.0-CURRENT after virtualizing interface
	cloning.</entry>
	</row>

	<row>
	<entry>800091</entry>
	<entry>May 27, 2009</entry>
	<entry>8.0-CURRENT after adding hierarchical jails
	and removing global securelevel.</entry>
	</row>

	<row>
	<entry>800092</entry>
	<entry>May 29, 2009</entry>
	<entry>8.0-CURRENT after changing
	<function>sx_init_flags()</function> KPI. The
	<constant>SX_ADAPTIVESPIN</constant> is retired and a
	new <constant>SX_NOADAPTIVE</constant> flag is
	introduced in order to handle the reversed
	logic.</entry>
	</row>

	<row>
	<entry>800093</entry>
	<entry>May 29, 2009</entry>
	<entry>8.0-CURRENT after adding mnt_xflag to
	struct mount.</entry>
	</row>

	<row>
	<entry>800094</entry>
	<entry>May 30, 2009</entry>
	<entry>8.0-CURRENT after adding
	&man.VOP.ACCESSX.9;.</entry>
	</row>

	<row>
	<entry>800095</entry>
	<entry>May 30, 2009</entry>
	<entry>8.0-CURRENT after changing the polling KPI.
	The polling handlers now return the number of packets
	processed. A new
	<constant>IFCAP_POLLING_NOCOUNT</constant> is also
	introduced to specify that the return value is
	not significant and the counting should be
	skipped.</entry>
	</row>

	<row>
	<entry>800096</entry>
	<entry>June 1, 2009</entry>
	<entry>8.0-CURRENT after updating to the new netisr
	implementation and after changing the way we
	store and access FIBs.</entry>
	<!--
	Had been 96 and 97 but were folded because we are
	running out of numbers.
	-->
	</row>

	<row>
	<entry>800097</entry>
	<entry>June 8, 2009</entry>
	<entry>8.0-CURRENT after the introduction of vnet
	destructor hooks and infrastructure.</entry>
	</row>

	<row>
	<entry>800097</entry>
	<entry>June 11, 2009</entry>
	<entry>8.0-CURRENT after the introduction of netgraph
	outbound to inbound path call detection and queuing,
	which also changed the layout of struct
	thread.</entry>
	</row>

	<row>
	<entry>800098</entry>
	<entry>June 14, 2009</entry>
	<entry>8.0-CURRENT after OpenSSL 0.9.8k import.</entry>
	</row>

	<row>
	<entry>800099</entry>
	<entry>June 22, 2009</entry>
	<entry>8.0-CURRENT after NGROUPS update and moving
	route virtualization into its own VImage
	module.</entry>
	</row>

	<row>
	<entry>800100</entry>
	<entry>June 24, 2009</entry>
	<entry>8.0-CURRENT after SYSVIPC ABI change.</entry>
	</row>

	<row>
	<entry>800101</entry>
	<entry>June 29, 2009</entry>
	<entry>8.0-CURRENT after the removal of the
	/dev/net/* per-interface character
	devices.</entry>
	</row>

	<row>
	<entry>800102</entry>
	<entry>July 12, 2009</entry>
	<entry>8.0-CURRENT after padding was added to
	struct sackhint, struct tcpcb, and struct
	tcpstat.</entry>
	</row>

	<row>
	<entry>800103</entry>
	<entry>July 13, 2009</entry>
	<entry>8.0-CURRENT after replacing struct tcpopt
	with struct toeopt in the TOE driver interface
	to the TCP syncache.</entry>
	</row>

	<row>
	<entry>800104</entry>
	<entry>July 14, 2009</entry>
	<entry>8.0-CURRENT after the addition of the
	linker-set based per-vnet allocator.</entry>
	</row>

	<row>
	<entry>800105</entry>
	<entry>July 19, 2009</entry>
	<entry>8.0-CURRENT after version bump for all
	shared libraries that do not have symbol versioning
	turned on.</entry>
	</row>

	<row>
	<entry>800106</entry>
	<entry>July 24, 2009</entry>
	<entry>8.0-CURRENT after introduction of OBJT_SG
	VM object type.</entry>
	</row>

	<row>
	<entry>800107</entry>
	<entry>August 2, 2009</entry>
	<entry>8.0-CURRENT after making the newbus subsystem
	Giant free by adding the newbus sxlock and
	8.0-RELEASE.</entry>
	</row>

	<row>
	<entry>800108</entry>
	<entry>November 21, 2009</entry>
	<entry>8.0-STABLE after implementing EVFILT_USER kevent
	filter.</entry>
	</row>

	<row>
	<entry>800500</entry>
	<entry>January 7, 2010</entry>
	<entry>8.0-STABLE after
	<literal>__FreeBSD_version</literal> bump to make
	<command>pkg_add -r</command> use
	packages-8-stable.</entry>
	</row>

	<row>
	<entry>800501</entry>
	<entry>January 24, 2010</entry>
	<entry>8.0-STABLE after change of the
	<function>scandir(3)</function> and
	<function>alphasort(3)</function> prototypes to
	conform to SUSv4.</entry>
	</row>

	<row>
	<entry>800502</entry>
	<entry>January 31, 2010</entry>
	<entry>8.0-STABLE after addition of
	<function>sigpause(3)</function>.</entry>
	</row>

	<row>
	<entry>800503</entry>
	<entry>February 25, 2010</entry>
	<entry>8.0-STABLE after addition of SIOCGIFDESCR
	and SIOCSIFDESCR ioctls to network interfaces. These
	ioctl can be used to manipulate interface description,
	as inspired by OpenBSD.</entry>
	</row>

	<row>
	<entry>800504</entry>
	<entry>March 1, 2010</entry>
	<entry>8.0-STABLE after MFC of importing x86emu, a
	software emulator for real mode x86 CPU from
	OpenBSD.</entry>
	</row>

	<row>
	<entry>800505</entry>
	<entry>May 18, 2010</entry>
	<entry>8.0-STABLE after MFC of adding liblzma, xz,
	xzdec, and lzmainfo.</entry>
	</row>

	<row>
	<entry>801000</entry>
	<entry>June 14, 2010</entry>
	<entry>8.1-RELEASE</entry>
	</row>

	<row>
	<entry>801500</entry>
	<entry>June 14, 2010</entry>
	<entry>8.1-STABLE after 8.1-RELEASE.</entry>
	</row>

	<row>
	<entry>801501</entry>
	<entry>November 3, 2010</entry>
	<entry>8.1-STABLE after KBI change in struct sysentvec,
	and implementation of PL_FLAG_SCE/SCX/EXEC/SI and
	pl_siginfo for ptrace(PT_LWPINFO) .</entry>
	</row>

	<row>
	<entry>802000</entry>
	<entry>December 22, 2010</entry>
	<entry>8.2-RELEASE</entry>
	</row>

	<row>
	<entry>802500</entry>
	<entry>December 22, 2010</entry>
	<entry>8.2-STABLE after 8.2-RELEASE.</entry>
	</row>

	<row>
	<entry>802501</entry>
	<entry>February 28, 2011</entry>
	<entry>8.2-STABLE after merging DTrace changes,
	including support for userland tracing.</entry>
	</row>

	<row>
	<entry>802502</entry>
	<entry>March 6, 2011</entry>
	<entry>8.2-STABLE after merging log2 and log2f
	into libm.</entry>
	</row>

	<row>
	<entry>802503</entry>
	<entry>May 1, 2011</entry>
	<entry>8.2-STABLE after upgrade of the gcc to the last
	GPLv2 version from the FSF gcc-4_2-branch.</entry>
	</row>

	<row>
	<entry>802504</entry>
	<entry>May 28, 2011</entry>
	<entry>8.2-STABLE after introduction of the KPI and
	supporting infrastructure for modular congestion
	control.</entry>
	</row>

	<row>
	<entry>802505</entry>
	<entry>May 28, 2011</entry>
	<entry>8.2-STABLE after introduction of Hhook and Khelp
	KPIs.</entry>
	</row>

	<row>
	<entry>802506</entry>
	<entry>May 28, 2011</entry>
	<entry>8.2-STABLE after addition of OSD to struct
	tcpcb.</entry>
	</row>

	<row>
	<entry>802507</entry>
	<entry>June 6, 2011</entry>
	<entry>8.2-STABLE after ZFS v28 import.</entry>
	</row>

	<row>
	<entry>802508</entry>
	<entry>June 8, 2011</entry>
	<entry>8.2-STABLE after removal of the schedtail event
	handler and addition of the sv_schedtail method to
	struct sysvec.</entry>
	</row>

	<row>
	<entry>802509</entry>
	<entry>July 14, 2011</entry>
	<entry>8.2-STABLE after merging the SSSE3 support
	into binutils.</entry>
	</row>

	<row>
	<entry>802510</entry>
	<entry>July 19, 2011</entry>
	<entry>8.2-STABLE after addition of
	RFTSIGZMB flag for
	<function>rfork(2)</function>.</entry>
	</row>

	<row>
	<entry>802511</entry>
	<entry>September 9, 2011</entry>
	<entry>8.2-STABLE after addition of automatic detection
	of USB mass storage devices which do not support the
	no synchronize cache SCSI command.</entry>
	</row>

	<row>
	<entry>802512</entry>
	<entry>September 10, 2011</entry>
	<entry>8.2-STABLE after merging of
	re-factoring of auto-quirk.</entry>
	</row>

	<row>
	<entry>802513</entry>
	<entry>October 25, 2011</entry>
	<entry>8.2-STABLE after merging of the MAP_PREFAULT_READ
	flag to <function>mmap(2)</function>.</entry>
	</row>

	<row>
	<entry>802514</entry>
	<entry>November 16, 2011</entry>
	<entry>8.2-STABLE after merging of
	addition of posix_fallocate(2) syscall.</entry>
	</row>

	<row>
	<entry>802515</entry>
	<entry>January 6, 2012</entry>
	<entry>8.2-STABLE after merging of addition of the
	posix_fadvise(2) system call.</entry>
	</row>

	<row>
	<entry>802516</entry>
	<entry>January 16, 2012</entry>
	<entry>8.2-STABLE after merging gperf 3.0.3</entry>
	</row>

	<row>
	<entry>802517</entry>
	<entry>February 15, 2012</entry>
	<entry>8.2-STABLE after introduction of the new
	extensible sysctl(3) interface NET_RT_IFLISTL
	to query address lists (rev
	<svnref>231769</svnref>.</entry>
	</row>

	<row>
	<entry>803000</entry>
	<entry>March 3, 2012</entry>
	<entry>8.3-RELEASE.</entry>
	</row>

	<row>
	<entry>803500</entry>
	<entry>March 3, 2012</entry>
	<entry>8.3-STABLE after branching releng/8.3
	(RELENG_8_3).</entry>
	</row>

	<row>
	+ <entry>804000</entry>
	+ <entry>March 28, 2013</entry>
	+ <entry>releng/8.4 (RELENG_8_4) branch point.</entry>
	+ </row>
	+
	+ <row>
	+ <entry>804500</entry>
	+ <entry>March 28, 2013</entry>
	+ <entry>8.4-STABLE after branching releng/8.4
	+ (RELENG_8_4).</entry>
	+ </row>
	+
	+ <row>
	<entry>900000</entry>
	<entry>August 22, 2009</entry>
	<entry>9.0-CURRENT.</entry>
	</row>

	<row>
	<entry>900001</entry>
	<entry>September 8, 2009</entry>
	<entry>9.0-CURRENT after importing x86emu, a software
	emulator for real mode x86 CPU from OpenBSD.</entry>
	</row>

	<row>
	<entry>900002</entry>
	<entry>September 23, 2009</entry>
	<entry>9.0-CURRENT after implementing the EVFILT_USER
	kevent filter functionality.</entry>
	</row>

	<row>
	<entry>900003</entry>
	<entry>December 2, 2009</entry>
	<entry>9.0-CURRENT after addition of
	<function>sigpause(3)</function> and PIE
	support in csu.</entry>
	</row>

	<row>
	<entry>900004</entry>
	<entry>December 6, 2009</entry>
	<entry>9.0-CURRENT after addition of libulog and its
	libutempter compatibility interface.</entry>
	</row>

	<row>
	<entry>900005</entry>
	<entry>December 12, 2009</entry>
	<entry>9.0-CURRENT after addition of
	<function>sleepq_sleepcnt()</function>, which can be
	used to query the number of waiters on a specific
	waiting queue.</entry>
	</row>

	<row>
	<entry>900006</entry>
	<entry>January 4, 2010</entry>
	<entry>9.0-CURRENT after change of the
	<function>scandir(3)</function> and
	<function>alphasort(3)</function> prototypes to
	conform to SUSv4.</entry>
	</row>

	<row>
	<entry>900007</entry>
	<entry>January 13, 2010</entry>
	<entry>9.0-CURRENT after the removal of utmp(5) and
	the addition of utmpx (see
	<function>getutxent(3)</function>) for improved
	logging of user logins and system events.</entry>
	</row>

	<row>
	<entry>900008</entry>
	<entry>January 20, 2010</entry>
	<entry>9.0-CURRENT after the import of BSDL bc/dc and
	the deprecation of GNU bc/dc.</entry>
	</row>

	<row>
	<entry>900009</entry>
	<entry>January 26, 2010</entry>
	<entry>9.0-CURRENT after the addition of SIOCGIFDESCR
	and SIOCSIFDESCR ioctls to network interfaces. These
	ioctl can be used to manipulate interface description,
	as inspired by OpenBSD.</entry>
	</row>

	<row>
	<entry>900010</entry>
	<entry>March 22, 2010</entry>
	<entry>9.0-CURRENT after the import of zlib
	1.2.4.</entry>
	</row>

	<row>
	<entry>900011</entry>
	<entry>April 24, 2010</entry>
	<entry>9.0-CURRENT after adding soft-updates
	journalling.</entry>
	</row>

	<row>
	<entry>900012</entry>
	<entry>May 10, 2010</entry>
	<entry>9.0-CURRENT after adding liblzma, xz, xzdec,
	and lzmainfo.</entry>
	</row>

	<row>
	<entry>900013</entry>
	<entry>May 24, 2010</entry>
	<entry>9.0-CURRENT after bringing in USB fixes for
	linux(4).</entry>
	</row>

	<row>
	<entry>900014</entry>
	<entry>June 10, 2010</entry>
	<entry>9.0-CURRENT after adding Clang.</entry>
	</row>

	<row>
	<entry>900015</entry>
	<entry>July 22, 2010</entry>
	<entry>9.0-CURRENT after the import of BSD grep.</entry>
	</row>

	<row>
	<entry>900016</entry>
	<entry>July 28, 2010</entry>
	<entry>9.0-CURRENT after adding mti_zone to
	struct malloc_type_internal.</entry>
	</row>

	<row>
	<entry>900017</entry>
	<entry>August 23, 2010</entry>
	<entry>9.0-CURRENT after changing back default grep to
	GNU grep and adding WITH_BSD_GREP knob.</entry>
	</row>

	<row>
	<entry>900018</entry>
	<entry>August 24, 2010</entry>
	<entry>9.0-CURRENT after the
	<function>pthread_kill(3)</function> -generated signal
	is identified as SI_LWP in si_code. Previously,
	si_code was SI_USER.</entry>
	</row>

	<row>
	<entry>900019</entry>
	<entry>August 28, 2010</entry>
	<entry>9.0-CURRENT after addition of the
	MAP_PREFAULT_READ flag to
	<function>mmap(2)</function>.</entry>
	</row>

	<row>
	<entry>900020</entry>
	<entry>September 9, 2010</entry>
	<entry>9.0-CURRENT after adding drain functionality
	to sbufs, which also changed the layout of
	struct sbuf.</entry>
	</row>

	<row>
	<entry>900021</entry>
	<entry>September 13, 2010</entry>
	<entry>9.0-CURRENT after DTrace has grown support
	for userland tracing.</entry>
	</row>

	<row>
	<entry>900022</entry>
	<entry>October 2, 2010</entry>
	<entry>9.0-CURRENT after addition of the BSDL man
	utilities and retirement of GNU/GPL man
	utilities.</entry>
	</row>

	<row>
	<entry>900023</entry>
	<entry>October 11, 2010</entry>
	<entry>9.0-CURRENT after updating xz to git 20101010
	snapshot.</entry>
	</row>

	<row>
	<entry>900024</entry>
	<entry>November 11, 2010</entry>
	<entry>9.0-CURRENT after libgcc.a was replaced
	by libcompiler_rt.a.</entry>
	</row>

	<row>
	<entry>900025</entry>
	<entry>November 12, 2010</entry>
	<entry>9.0-CURRENT after the introduction of the
	modularised congestion control.</entry>
	</row>

	<row>
	<entry>900026</entry>
	<entry>November 30, 2010</entry>
	<entry>9.0-CURRENT after the introduction of Serial
	Management Protocol (SMP) passthrough and the
	XPT_SMP_IO and XPT_GDEV_ADVINFO CAM CCBs.</entry>
	</row>

	<row>
	<entry>900027</entry>
	<entry>December 5, 2010</entry>
	<entry>9.0-CURRENT after the addition of log2 to
	libm.</entry>
	</row>

	<row>
	<entry>900028</entry>
	<entry>December 21, 2010</entry>
	<entry>9.0-CURRENT after the addition of the Hhook
	(Helper Hook), Khelp (Kernel Helpers) and Object
	Specific Data (OSD) KPIs.</entry>
	</row>

	<row>
	<entry>900029</entry>
	<entry>December 28, 2010</entry>
	<entry>9.0-CURRENT after the modification of the TCP
	stack to allow Khelp modules to interact with it via
	helper hook points and store per-connection data in
	the TCP control block.</entry>
	</row>

	<row>
	<entry>900030</entry>
	<entry>January 12, 2011</entry>
	<entry>9.0-CURRENT after the update of libdialog to
	version 20100428.</entry>
	</row>

	<row>
	<entry>900031</entry>
	<entry>February 7, 2011</entry>
	<entry>9.0-CURRENT after the addition of
	<function>pthread_getthreadid_np(3)</function>.</entry>
	</row>

	<row>
	<entry>900032</entry>
	<entry>February 8, 2011</entry>
	<entry>9.0-CURRENT after the removal of the uio_yield
	prototype and symbol.</entry>
	</row>

	<row>
	<entry>900033</entry>
	<entry>February 18, 2011</entry>
	<entry>9.0-CURRENT after the update of binutils to
	version 2.17.50.</entry>
	</row>

	<row>
	<entry>900034</entry>
	<entry>March 8, 2011</entry>
	<entry>9.0-CURRENT after the struct sysvec
	(sv_schedtail) changes.</entry>
	</row>

	<row>
	<entry>900035</entry>
	<entry>March 29, 2011</entry>
	<entry>9.0-CURRENT after the update of base gcc and
	libstdc++ to the last GPLv2 licensed revision.</entry>
	</row>

	<row>
	<entry>900036</entry>
	<entry>April 18, 2011</entry>
	<entry>9.0-CURRENT after the removal of libobjc and
	Objective-C support from the base system.</entry>
	</row>

	<row>
	<entry>900037</entry>
	<entry>May 13, 2011</entry>
	<entry>9.0-CURRENT after importing the libprocstat(3)
	library and fuser(1) utility to the base
	system.</entry>
	</row>

	<row>
	<entry>900038</entry>
	<entry>May 22, 2011</entry>
	<entry>9.0-CURRENT after adding a lock flag argument to
	VFS_FHTOVP(9).</entry>
	</row>

	<row>
	<entry>900039</entry>
	<entry>June 28, 2011</entry>
	<entry>9.0-CURRENT after importing pf from OpenBSD
	4.5.</entry>
	</row>

	<row>
	<entry>900040</entry>
	<entry>July 19, 2011</entry>
	<entry>Increase default MAXCPU for FreeBSD to 64 on
	amd64 and ia64 and to 128 for XLP (mips).</entry>
	</row>

	<row>
	<entry>900041</entry>
	<entry>August 13, 2011</entry>
	<entry>9.0-CURRENT after the implementation of Capsicum
	capabilities; fget(9) gains a rights argument.</entry>
	</row>

	<row>
	<entry>900042</entry>
	<entry>August 28, 2011</entry>
	<entry>Bump shared libraries' version numbers for
	libraries whose ABI has changed in preparation for
	9.0.</entry>
	</row>

	<row>
	<entry>900043</entry>
	<entry>September 2, 2011</entry>
	<entry>Add automatic detection of USB mass storage
	devices which do not support the no synchronize cache
	SCSI command.</entry>
	</row>

	<row>
	<entry>900044</entry>
	<entry>September 10, 2011</entry>
	<entry>Re-factor auto-quirk. 9.0-RELEASE.</entry>
	</row>

	<!-- Note: at one point 900045 was documented as follows, even though
	it was never committed:
	<row>
	<entry>900045</entry>
	<entry>Oct 13, 2011</entry>
	<entry>All non-compatibility system call entry points
	have been prefixed with sys_.</entry>
	</row>
	-->

	<row>
	<entry>900045</entry>
	<entry>January 2, 2012</entry>
	<entry>9-CURRENT after MFC of true/false from
	1000002.</entry>
	</row>

	<row>
	<entry>900500</entry>
	<entry>January 2, 2012</entry>
	<entry>9.0-STABLE.</entry>
	</row>

	<row>
	<entry>900501</entry>
	<entry>January 6, 2012</entry>
	<entry>9.0-STABLE after merging of addition of the
	posix_fadvise(2) system call.</entry>
	</row>

	<row>
	<entry>900502</entry>
	<entry>January 16, 2012</entry>
	<entry>9.0-STABLE after merging gperf 3.0.3</entry>
	</row>

	<row>
	<entry>900503</entry>
	<entry>February 15, 2012</entry>
	<entry>9.0-STABLE after introduction of the new
	extensible sysctl(3) interface NET_RT_IFLISTL
	to query address lists (rev
	<svnref>231768</svnref>).</entry>
	</row>

	<row>
	<entry>900504</entry>
	<entry>March 3, 2012</entry>
	<entry>9.0-STABLE after changes related to mounting
	of filesystem inside a jail (rev
	<svnref>232728</svnref>).</entry>
	</row>

	<row>
	<entry>900505</entry>
	<entry>March 13, 2012</entry>
	<entry>9.0-STABLE after introduction of new tcp(4)
	socket options: TCP_KEEPINIT, TCP_KEEPIDLE,
	TCP_KEEPINTVL, and TCP_KEEPCNT (rev
	<svnref>232945</svnref>).</entry>
	</row>

	<row>
	<entry>901000</entry>
	<entry>August 5, 2012</entry>
	<entry>9.1-RELEASE.</entry>
	</row>

	<row>
	+ <entry>901500</entry>
	+ <entry>August 6, 2012</entry>
	+ <entry>9.1-STABLE after branching releng/9.1
	+ (RELENG_9_1).</entry>
	+ </row>
	+
	+ <row>
	+ <entry>901501</entry>
	+ <entry>November 11, 2012</entry>
	+ <entry>9.1-STABLE after LIST_PREV() added to
	+ queue.h.</entry>
	+ </row>
	+
	+ <row>
	+ <entry>901502</entry>
	+ <entry>November 28, 2012</entry>
	+ <entry>9.1-STABLE after USB serial jitter buffer
	+ requires rebuild of USB serial device modules.</entry>
	+ </row>
	+
	+ <row>
	+ <entry>901503</entry>
	+ <entry>February 21, 2013</entry>
	+ <entry>9.1-STABLE after USB moved to the driver
	+ structure requiring a rebuild of all USB modules.
	+ Also indicates the presence of nmtree.</entry>
	+ </row>
	+
	+ <row>
	+ <entry>901504</entry>
	+ <entry>March 15, 2013</entry>
	+ <entry>9.1-STABLE after install gained -l, -M, -N and
	+ related flags and cat gained the -l option.</entry>
	+ </row>
	+
	+ <row>
	<entry>1000000</entry>
	<entry>September 26, 2011</entry>
	<entry>10.0-CURRENT.</entry>
	</row>

	<row>
	<entry>1000001</entry>
	<entry>November 4, 2011</entry>
	<entry>10-CURRENT after addition of the posix_fadvise(2)
	system call.</entry>
	</row>

	<row>
	<entry>1000002</entry>
	<entry>December 12, 2011</entry>
	<entry>10-CURRENT after defining boolean true/false in
	sys/types.h, sizeof(bool) may have changed (rev
	<svnref>228444</svnref>). 10-CURRENT after xlocale.h
	was introduced (rev
	<svnref>227753</svnref>).</entry>
	</row>

	<row>
	<entry>1000003</entry>
	<entry>December 16, 2011</entry>
	<entry>10-CURRENT after major changes to carp(4),
	changing size of struct in_aliasreq,
	struct in6_aliasreq (rev <svnref>228571</svnref>)
	and straitening arguments check of SIOCAIFADDR (rev
	<svnref>228574</svnref>).</entry>
	</row>

	<row>
	<entry>1000004</entry>
	<entry>January 1, 2012</entry>
	<entry>10-CURRENT after the removal of skpc(9) and the
	addition of memcchr(9) (rev
	<svnref>229200</svnref>).</entry>
	</row>

	<row>
	<entry>1000005</entry>
	<entry>January 16, 2012</entry>
	<entry>10-CURRENT after the removal of support for
	SIOCSIFADDR, SIOCSIFNETMASK, SIOCSIFBRDADDR,
	SIOCSIFDSTADDR ioctls (rev
	<svnref>230207</svnref>).</entry>
	</row>

	<row>
	<entry>1000006</entry>
	<entry>January 26, 2012</entry>
	<entry>10-CURRENT after introduction of read capacity
	data asynchronous notification in the cam(4) layer
	(rev <svnref>230590</svnref>).</entry>
	</row>

	<row>
	<entry>1000007</entry>
	<entry>February 5, 2012</entry>
	<entry>10-CURRENT after introduction of new tcp(4)
	socket options: TCP_KEEPINIT, TCP_KEEPIDLE,
	TCP_KEEPINTVL, and TCP_KEEPCNT (rev
	<svnref>231025</svnref>).</entry>
	</row>

	<row>
	<entry>1000008</entry>
	<entry>February 11, 2012</entry>
	<entry>10-CURRENT after introduction of the new
	extensible sysctl(3) interface NET_RT_IFLISTL
	to query address lists (rev
	<svnref>231505</svnref>).</entry>
	</row>

	<row>
	<entry>1000009</entry>
	<entry>February 25, 2012</entry>
	<entry>10-CURRENT after import of libarchive 3.0.3
	(rev <svnref>232153</svnref>).</entry>
	</row>

	<row>
	<entry>1000010</entry>
	<entry>March 31, 2012</entry>
	<entry>10-CURRENT after xlocale cleanup (rev
	<svnref>233757</svnref>).</entry>
	</row>

	<row>
	<entry>1000011</entry>
	<entry>April 16, 2012</entry>
	<entry>10-CURRENT import of LLVM/Clang 3.1 trunk r154661
	(rev <svnref>234353</svnref>).</entry>
	</row>

	<row>
	<entry>1000012</entry>
	<entry>May 2, 2012</entry>
	<entry>10-CURRENT jemalloc import
	(rev <svnref>234924</svnref>).</entry>
	</row>

	<row>
	<entry>1000013</entry>
	<entry>May 22, 2012</entry>
	<entry>10-CURRENT after byacc import
	(rev <svnref>235788</svnref>).</entry>
	</row>

	<row>
	<entry>1000014</entry>
	<entry>June 27, 2012</entry>
	<entry>10-CURRENT after BSD sort becoming the default
	sort (rev <svnref>237629</svnref>).</entry>
	</row>

	<row>
	<entry>1000015</entry>
	<entry>July 12, 2012</entry>
	<entry>10-CURRENT after import of OpenSSL 1.0.1c
	(rev <svnref>238405</svnref>).</entry>
	</row>

	<row>
	<entry>(not changed)</entry>
	<entry>July 13, 2012</entry>
	<entry>10-CURRENT after the fix for LLVM/Clang 3.1
	regression (rev <svnref>238429</svnref>).</entry>
	</row>

	<row>
	<entry>1000016</entry>
	<entry>August 8, 2012</entry>
	<entry>10-CURRENT after KBI change in &man.ucom.4;
	(rev <svnref>239179</svnref>).</entry>
	</row>

	<row>
	<entry>1000017</entry>
	<entry>August 8, 2012</entry>
	<entry>10-CURRENT after adding streams feature to the
	USB stack (rev <svnref>239214</svnref>).</entry>
	</row>

	<row>
	<entry>1000018</entry>
	<entry>September 8, 2012</entry>
	<entry>10-CURRENT after major rewrite of &man.pf.4;
	(rev <svnref>240233</svnref>).</entry>
	</row>

	<row>
	<entry>1000019</entry>
	<entry>October 6, 2012</entry>
	<entry>10-CURRENT after &man.pfil.9; KBI/KPI changed
	to supply packets in net byte order to AF_INET
	filter hooks (rev <svnref>241245</svnref>).</entry>
	</row>

	<row>
	<entry>1000020</entry>
	<entry>October 16, 2012</entry>
	<entry>10-CURRENT after the network interface cloning
	KPI changed and struct if_clone becoming opaque (rev
	- <svnref>241610</svnref>).</entry>
	+ <svnref>241610</svnref>).</entry>
	</row>

	<row>
	<entry>1000021</entry>
	<entry>October 22, 2012</entry>
	<entry>10-CURRENT after removal of support for
	non-MPSAFE filesystems and addition of support for
	FUSEFS (rev
	<svnref>241519</svnref>,
	<svnref>241897</svnref>).</entry>
	</row>

	<row>
	<entry>1000022</entry>
	<entry>October 22, 2012</entry>
	<entry>10-CURRENT after the entire IPv4 stack switched
	to network byte order for IP packet header storage
	(rev <svnref>241913</svnref>).</entry>
	</row>

	<row>
	<entry>1000023</entry>
	<entry>November 5, 2012</entry>
	<entry>10-CURRENT after jitter buffer in the common USB
	serial driver code, to temporarily store characters
	if the TTY buffer is full. Add flow stop and start
	signals when this happens (rev
	<svnref>242619</svnref>).</entry>
	</row>

	<row>
	<entry>1000024</entry>
	<entry>November 5, 2012</entry>
	<entry>10-CURRENT after clang was made the default
	compiler on i386 and amd64
	(rev <svnref>242624</svnref>).</entry>
	</row>

	<row>
	<entry>1000025</entry>
	<entry>November 17, 2012</entry>
	- <entry>10-CURRENT after the sin6_scope_id member variable
	- in struct sockaddr_in6 was changed to being filled by the
	- kernel before passing the structure to the userland via
	- sysctl or routing socket. This means the KAME-specific
	- embedded scope id in sin6_addr.s6_addr[2] is always
	- cleared in userland application (rev
	- <svnref>243443</svnref>).</entry>
	+ <entry>10-CURRENT after the sin6_scope_id member
	+ variable in struct sockaddr_in6 was changed to being
	+ filled by the kernel before passing the structure to
	+ the userland via sysctl or routing socket. This means
	+ the KAME-specific embedded scope id in
	+ sin6_addr.s6_addr[2] is always cleared in userland
	+ application (rev <svnref>243443</svnref>).</entry>
	</row>

	<row>
	<entry>1000026</entry>
	<entry>January 11, 2013</entry>
	<entry>10-CURRENT after install gained the -N flag (rev
	- <svnref>245313</svnref>). May also be used to indicate
	- the presense of nmtree.</entry>
	+ <svnref>245313</svnref>). May also be used to
	+ indicate the presence of nmtree.</entry>
	</row>

	<row>
	<entry>1000027</entry>
	<entry>January 29, 2013</entry>
	<entry>10-CURRENT after cat gained the -l flag (rev
	<svnref>246083</svnref>).</entry>
	</row>
	+
	+ <row>
	+ <entry>1000030</entry>
	+ <entry>March 12, 2013</entry>
	+ <entry>10-CURRENT after KPI breakage introduced in the
	+ VM subsystem to support read/write locking (rev
	+ <svnref>248084</svnref>).</entry>
	+ </row>
	</tbody>
	</tgroup>
	</table>

	<note>
	<para>Note that 2.2-STABLE sometimes identifies itself as
	<quote>2.2.5-STABLE</quote> after the 2.2.5-RELEASE. The
	pattern used to be year followed by the month, but we
	decided to change it to a more straightforward major/minor
	system starting from 2.2. This is because the parallel
	development on several branches made it infeasible to
	classify the releases simply by their real release dates.
	If you are making a port now, you do not have to worry about
	old -CURRENTs; they are listed here just for your
	reference.</para>
	</note>
	</sect1>

	<sect1 id="dads-after-port-mk">
	<title>Writing Something After
	<filename>bsd.port.mk</filename></title>

	<para>Do not write anything after the <literal>.include
	<bsd.port.mk></literal> line. It usually can be
	avoided by including <filename>bsd.port.pre.mk</filename>
	somewhere in the middle of your <filename>Makefile</filename>
	and <filename>bsd.port.post.mk</filename> at the end.</para>

	<note>
	<para>Include either the
	<filename>bsd.port.pre.mk</filename>/<filename>bsd.port.post.mk</filename>
	pair or <filename>bsd.port.mk</filename> only; do not mix
	these two usages.</para>
	</note>

	<para><filename>bsd.port.pre.mk</filename> only defines a few
	variables, which can be used in tests in the
	<filename>Makefile</filename>,
	<filename>bsd.port.post.mk</filename> defines the rest.</para>

	<para>Here are some important variables defined in
	<filename>bsd.port.pre.mk</filename> (this is not the complete
	list, please read <filename>bsd.port.mk</filename> for the
	complete list).</para>

	<informaltable frame="none" pgwide="0">
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Variable</entry>
	<entry>Description</entry>
	</row>
	</thead>

	<tbody>
	<row>
	<entry><makevar>ARCH</makevar></entry>
	<entry>The architecture as returned by <command>uname
	-m</command> (e.g., <literal>i386</literal>)</entry>
	</row>

	<row>
	<entry><makevar>OPSYS</makevar></entry>
	<entry>The operating system type, as returned by
	<command>uname -s</command> (e.g.,
	<literal>FreeBSD</literal>)</entry>
	</row>

	<row>
	<entry><makevar>OSREL</makevar></entry>
	<entry>The release version of the operating system
	(e.g., <literal>2.1.5</literal> or
	<literal>2.2.7</literal>)</entry>
	</row>

	<row>
	<entry><makevar>OSVERSION</makevar></entry>
	<entry>The numeric version of the operating system; the
	same as <link
	linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>.</entry>
	</row>

	<row>
	<entry><makevar>LOCALBASE</makevar></entry>
	<entry>The base of the <quote>local</quote> tree (e.g.,
	- <literal>/usr/local/</literal>)</entry>
	+ <literal>/usr/local</literal>)</entry>
	</row>

	<row>
	<entry><makevar>PREFIX</makevar></entry>
	<entry>Where the port installs itself (see <link
	linkend="porting-prefix">more on
	<makevar>PREFIX</makevar></link>).</entry>
	</row>
	</tbody>
	</tgroup>
	</informaltable>

	<note>
	<para>If you have to define the variables
	<makevar>USE_IMAKE</makevar> or
	<makevar>MASTERDIR</makevar>, do so before including
	<filename>bsd.port.pre.mk</filename>.</para>
	</note>

	<para>Here are some examples of things you can write after
	<filename>bsd.port.pre.mk</filename>:</para>

	<programlisting># no need to compile lang/perl5 if perl5 is already in system
	.if ${OSVERSION} > 300003
	BROKEN= perl is in system
	-.endif
	-
	-# only one shlib version number for ELF
	-.if ${PORTOBJFORMAT} == "elf"
	-TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}
	-.else
	-TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR}
	-.endif
	-
	-# software already makes link for ELF, but not for a.out
	-post-install:
	-.if ${PORTOBJFORMAT} == "aout"
	- ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
	.endif</programlisting>

	<para>You did remember to use tab instead of spaces after
	<literal>BROKEN=</literal> and
	- <literal>TCL_LIB_FILE=</literal>, did you not?
	<!-- smiley -->:-).</para>
	</sect1>

	<sect1 id="dads-sh-exec">
	<title>Use the <function>exec</function> Statement in Wrapper
	Scripts</title>

	<para>If the port installs a shell script whose purpose is to
	launch another program, and if launching that program is the
	last action performed by the script, make sure to launch the
	program using the <function>exec</function> statement, for
	instance:</para>

	<programlisting>#!/bin/sh
	exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>

	<para>The <function>exec</function> statement replaces the shell
	process with the specified program. If
	<function>exec</function> is omitted, the shell process
	remains in memory while the program is executing, and
	needlessly consumes system resources.</para>
	</sect1>

	<sect1 id="dads-rational">
	<title>Do Things Rationally</title>

	<para>The <filename>Makefile</filename> should do things simply
	and reasonably. If you can make it a couple of lines shorter
	or more readable, then do so. Examples include using a make
	<literal>.if</literal> construct instead of a shell
	<literal>if</literal> construct, not redefining
	<maketarget>do-extract</maketarget> if you can redefine
	<makevar>EXTRACT*</makevar> instead, and using
	<makevar>GNU_CONFIGURE</makevar> instead of
	<literal>CONFIGURE_ARGS
	+= --prefix=&dollar;{PREFIX}</literal>.</para>

	<para>If you find yourself having to write a lot of new code to
	try to do something, please go back and review
	<filename>bsd.port.mk</filename> to see if it contains an
	existing implementation of what you are trying to do. While
	hard to read, there are a great many seemingly-hard problems
	for which <filename>bsd.port.mk</filename> already provides a
	shorthand solution.</para>
	</sect1>

	<sect1 id="dads-cc">
	<title>Respect Both <makevar>CC</makevar> and
	<makevar>CXX</makevar></title>

	<para>The port must respect both <makevar>CC</makevar> and
	<makevar>CXX</makevar> variables. What we mean by this is
	that the port must not set the values of these variables
	absolutely, overriding existing values; instead, it may
	append whatever values it needs to the existing values. This
	is so that build options that affect all ports can be set
	globally.</para>

	<para>If the port does not respect these variables,
	please add <literal>NO_PACKAGE=ignores either cc or
	cxx</literal> to the <filename>Makefile</filename>.</para>

	<para>An example of a <filename>Makefile</filename> respecting
	both <makevar>CC</makevar> and <makevar>CXX</makevar>
	variables follows. Note the <makevar>?=</makevar>:</para>

	<programlisting>CC?= gcc</programlisting>

	<programlisting>CXX?= g++</programlisting>

	<para>Here is an example which respects neither
	<makevar>CC</makevar> nor <makevar>CXX</makevar>
	variables:</para>

	<programlisting>CC= gcc</programlisting>

	<programlisting>CXX= g++</programlisting>

	<para>Both <makevar>CC</makevar> and <makevar>CXX</makevar>
	variables can be defined on FreeBSD systems in
	<filename>/etc/make.conf</filename>. The first example
	defines a value if it was not previously set in
	<filename>/etc/make.conf</filename>, preserving any
	system-wide definitions. The second example clobbers
	anything previously defined.</para>
	</sect1>

	<sect1 id="dads-cflags">
	<title>Respect <makevar>CFLAGS</makevar></title>

	<para>The port must respect the <makevar>CFLAGS</makevar>
	variable. What we mean by this is that the port must not
	set the value of this variable absolutely, overriding the
	existing value; instead, it may append whatever values it
	needs to the existing value. This is so that build options
	that affect all ports can be set globally.</para>

	<para>If it does not, please add <literal>NO_PACKAGE=ignores
	cflags</literal> to the
	<filename>Makefile</filename>.</para>

	<para>An example of a <filename>Makefile</filename> respecting
	the <makevar>CFLAGS</makevar> variable follows. Note the
	<makevar>+=</makevar>:</para>

	<programlisting>CFLAGS+= -Wall -Werror</programlisting>

	<para>Here is an example which does not respect the
	<makevar>CFLAGS</makevar> variable:</para>

	<programlisting>CFLAGS= -Wall -Werror</programlisting>

	<para>The <makevar>CFLAGS</makevar> variable is defined on
	FreeBSD systems in <filename>/etc/make.conf</filename>. The
	first example appends additional flags to the
	<makevar>CFLAGS</makevar> variable, preserving any system-wide
	definitions. The second example clobbers anything previously
	defined.</para>

	<para>You should remove optimization flags from the third party
	<filename>Makefile</filename>s. System
	<makevar>CFLAGS</makevar> contains system-wide optimization
	flags. An example from an unmodified
	<filename>Makefile</filename>:</para>

	<programlisting>CFLAGS= -O3 -funroll-loops -DHAVE_SOUND</programlisting>

	<para>Using system optimization flags, the
	<filename>Makefile</filename> would look similar to the
	following example:</para>

	<programlisting>CFLAGS+= -DHAVE_SOUND</programlisting>
	</sect1>

	<sect1 id="dads-pthread">
	<title>Threading Libraries</title>

	<para>The threading library must be linked to the binaries using
	a special flag <literal>-pthread</literal> on &os;. If
	a port insists on linking <literal>-lpthread</literal>
	directly, patch it to use <literal>-pthread</literal>.</para>

	<note>
	<para>If building the port errors out with
	- <literal>unrecognized option '-pthread'</literal>,
	- it may be desirable to use <command>cc</command> as linker by
	- setting <makevar>CONFIGURE_ENV</makevar> to
	- <literal>LD=${CC}</literal>. The
	- <literal>-pthread</literal> option is not supported by
	- <command>ld</command> directly.</para>
	+ <literal>unrecognized option '-pthread'</literal>, it may be
	+ desirable to use <command>cc</command> as linker by setting
	+ <makevar>CONFIGURE_ENV</makevar> to
	+ <literal>LD=${CC}</literal>. The
	+ <literal>-pthread</literal> option is not supported by
	+ <command>ld</command> directly.</para>
	</note>
	</sect1>

	<sect1 id="dads-freedback">
	<title>Feedback</title>

	<para>Do send applicable changes/patches to the original
	author/maintainer for inclusion in next release of the code.
	This will only make your job that much easier for the next
	release.</para>
	</sect1>

	<sect1 id="dads-readme">
	<title><filename>README.html</filename></title>

	<para>Do not include the <filename>README.html</filename> file.
	This file is not part of the SVN collection but is generated
	using the <command>make readme</command> command.</para>

	<note>
	<para>If <command>make readme</command> fails, make sure that
	the default value of <makevar>ECHO_MSG</makevar> has not
	been modified by the port.</para>
	</note>
	</sect1>

	<sect1 id="dads-noinstall">
	<title>Marking a Port Not Installable with
	<makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or
	<makevar>IGNORE</makevar></title>

	<para>In certain cases users should be prevented from installing
	a port. To tell a user that a port should not be installed,
	there are several <command>make</command> variables that can
	be used in a port's <filename>Makefile</filename>. The value
	of the following <command>make</command> variables will be the
	reason that is given back to users for why the port refuses to
	install itself. Please use the correct
	<command>make</command> variable as each make variable conveys
	radically different meanings to both users, and to automated
	systems that depend on the <filename>Makefile</filename>s,
	such as <link linkend="build-cluster">the ports build
	cluster</link>, <link linkend="freshports">FreshPorts</link>,
	and <link linkend="portsmon">portsmon</link>.</para>

	<sect2 id="dads-noinstall-variables">
	<title>Variables</title>

	<itemizedlist>
	<listitem>
	<para><makevar>BROKEN</makevar> is reserved for ports that
	currently do not compile, install, or deinstall
	correctly. It should be used for ports where the
	problem is believed to be temporary.</para>

	<para>If instructed, the build cluster will still attempt
	to try to build them to see if the underlying problem
	has been resolved. (However, in general, the cluster is
	run without this.)</para>

	<para>For instance, use <makevar>BROKEN</makevar> when a
	port:</para>

	<itemizedlist>
	<listitem>
	<para>does not compile</para>
	</listitem>

	<listitem>
	<para>fails its configuration or installation
	process</para>
	</listitem>

	<listitem>
	<para>installs files outside of
	<filename>${LOCALBASE}</filename></para>
	</listitem>

	<listitem>
	<para>does not remove all its files cleanly upon
	deinstall (however, it may be acceptable, and
	desirable, for the port to leave user-modified files
	behind)</para>
	</listitem>
	</itemizedlist>
	</listitem>

	<listitem>
	<para><makevar>FORBIDDEN</makevar> is used for ports that
	contain a security vulnerability or induce grave concern
	regarding the security of a FreeBSD system with a given
	port installed (e.g., a reputably insecure program or a
	program that provides easily exploitable services).
	Ports should be marked as <makevar>FORBIDDEN</makevar>
	as soon as a particular piece of software has a
	vulnerability and there is no released upgrade. Ideally
	ports should be upgraded as soon as possible when a
	security vulnerability is discovered so as to reduce the
	number of vulnerable FreeBSD hosts (we like being known
	for being secure), however sometimes there is a
	noticeable time gap between disclosure of a
	vulnerability and an updated release of the vulnerable
	software. Do not mark a port
	<makevar>FORBIDDEN</makevar> for any reason other than
	security.</para>
	</listitem>

	<listitem>
	<para><makevar>IGNORE</makevar> is reserved for ports that
	should not be built for some other reason. It should be
	used for ports where the problem is believed to be
	structural. The build cluster will not, under any
	circumstances, build ports marked as
	<makevar>IGNORE</makevar>. For instance, use
	<makevar>IGNORE</makevar> when a port:</para>

	<itemizedlist>
	<listitem>
	<para>compiles but does not run properly</para>
	</listitem>

	<listitem>
	<para>does not work on the installed version of
	&os;</para>
	</listitem>

	<listitem>
	<para>requires &os; kernel sources to build, but the
	user does not have them installed</para>
	</listitem>

	<listitem>
	<para>has a distfile which may not be automatically
	fetched due to licensing restrictions</para>
	</listitem>

	<listitem>
	<para>does not work with some other currently
	installed port (for instance, the port depends on
	<filename role="package">www/apache20</filename> but
	<filename role="package">www/apache22</filename> is
	installed)</para>
	</listitem>
	</itemizedlist>

	<note>
	<para>If a port would conflict with a currently
	installed port (for example, if they install a file in
	the same place that performs a different function),
	<link linkend="conflicts">use
	<makevar>CONFLICTS</makevar> instead</link>.
	<makevar>CONFLICTS</makevar> will set
	<makevar>IGNORE</makevar> by itself.</para>
	</note>
	</listitem>

	<listitem>
	<para>If a port should be marked <makevar>IGNORE</makevar>
	only on certain architectures, there are two other
	convenience variables that will automatically set
	<makevar>IGNORE</makevar> for you:
	<makevar>ONLY_FOR_ARCHS</makevar> and
	<makevar>NOT_FOR_ARCHS</makevar>. Examples:</para>

	<programlisting>ONLY_FOR_ARCHS= i386 amd64</programlisting>

	<programlisting>NOT_FOR_ARCHS= ia64 sparc64</programlisting>

	<para>A custom <makevar>IGNORE</makevar> message can be
	set using <makevar>ONLY_FOR_ARCHS_REASON</makevar> and
	<makevar>NOT_FOR_ARCHS_REASON</makevar>. Per
	architecture entries are possible with
	<makevar>ONLY_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></makevar>
	and
	<makevar>NOT_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></makevar>.</para>
	</listitem>

	<listitem>
	<para>If a port fetches i386 binaries and installs them,
	<makevar>IA32_BINARY_PORT</makevar> should be set. If
	this variable is set, it will be checked whether the
	<filename>/usr/lib32</filename> directory is available
	for IA32 versions of libraries and whether the kernel
	has IA32 compatibility compiled in. If one of these two
	dependencies is not satisfied, <makevar>IGNORE</makevar>
	will be set automatically.</para>
	</listitem>
	</itemizedlist>
	</sect2>

	<sect2 id="dads-noinstall-notes">
	<title>Implementation Notes</title>

	<para>The strings should not be quoted.
	Also, the wording of the string should be somewhat
	different due to the way the information is shown to the
	user. Examples:</para>

	<programlisting>BROKEN= this port is unsupported on FreeBSD 5.x</programlisting>

	<programlisting>IGNORE= is unsupported on FreeBSD 5.x</programlisting>

	<para>resulting in the following output from
	<command>make describe</command>:</para>

	<programlisting>===> foobar-0.1 is marked as broken: this port is unsupported on FreeBSD 5.x.</programlisting>

	<programlisting>===> foobar-0.1 is unsupported on FreeBSD 5.x.</programlisting>
	</sect2>
	</sect1>

	<sect1 id="dads-deprecated">
	<title>Marking a Port for Removal with
	<makevar>DEPRECATED</makevar> or
	<makevar>EXPIRATION_DATE</makevar></title>

	<para>Do remember that <makevar>BROKEN</makevar> and
	<makevar>FORBIDDEN</makevar> are to be used as a temporary
	resort if a port is not working. Permanently broken ports
	should be removed from the tree entirely.</para>

	<para>When it makes sense to do so, users can be warned about
	a pending port removal with <makevar>DEPRECATED</makevar>
	and <makevar>EXPIRATION_DATE</makevar>. The former is
	simply a string stating why the port is scheduled for removal;
	the latter is a string in ISO 8601 format (YYYY-MM-DD). Both
	will be shown to the user.</para>

	<para>It is possible to set <makevar>DEPRECATED</makevar>
	without an <makevar>EXPIRATION_DATE</makevar> (for instance,
	recommending a newer version of the port), but the converse
	does not make any sense.</para>

	<para>There is no set policy on how much notice to give.
	Current practice seems to be one month for security-related
	issues and two months for build issues. This also gives any
	interested committers a little time to fix the
	problems.</para>
	</sect1>

	<sect1 id="dads-dot-error">
	<title>Avoid Use of the <literal>.error</literal>
	Construct</title>

	<para>The correct way for a <filename>Makefile</filename> to
	signal that the port can not be installed due to some external
	factor (for instance, the user has specified an illegal
	combination of build options) is to set a non-blank value to
	<makevar>IGNORE</makevar>. This value will be formatted and
	shown to the user by <command>make install</command>.</para>

	<para>It is a common mistake to use <literal>.error</literal>
	for this purpose. The problem with this is that many
	automated tools that work with the ports tree will fail in
	this situation. The most common occurrence of this is seen
	when trying to build <filename>/usr/ports/INDEX</filename>
	(see <xref linkend="make-describe"/>). However, even more
	trivial commands such as <command>make maintainer</command>
	also fail in this scenario. This is not acceptable.</para>

	<example id="dot-error-breaks-index">
	<title>How to Avoid Using <literal>.error</literal></title>

	<para>Assume that someone has the line</para>

	<programlisting>USE_POINTYHAT=yes</programlisting>

	<para>in <filename>make.conf</filename>. The first of the
	next two <filename>Makefile</filename> snippets will cause
	<command>make index</command> to fail, while the second one
	will not:</para>

	<programlisting>.if USE_POINTYHAT
	.error "POINTYHAT is not supported"
	.endif</programlisting>

	<programlisting>.if USE_POINTYHAT
	IGNORE= POINTYHAT is not supported
	.endif</programlisting>
	</example>
	</sect1>

	<sect1 id="dads-sysctl">
	<title>Usage of <filename>sysctl</filename></title>

	<para>The usage of <filename>sysctl</filename> is discouraged
	except in targets. This is because the evaluation of any
	<literal>makevar</literal>s, such as used during
	<command>make index</command>, then has to run the command,
	further slowing down that process.</para>

	<para>Usage of &man.sysctl.8; should always be done with the
	<makevar>SYSCTL</makevar> variable, as it contains the fully
	qualified path and can be overridden, if one has such a
	special need.</para>
	</sect1>

	<sect1 id="dads-rerolling-distfiles">
	<title>Rerolling Distfiles</title>

	<para>Sometimes the authors of software change the content of
	released distfiles without changing the file's name. You have
	to verify that the changes are official and have been
	performed by the author. It has happened in the past that the
	distfile was silently altered on the download servers with the
	intent to cause harm or compromise end user security.</para>

	<para>Put the old distfile aside, download the new one, unpack
	them and compare the content with &man.diff.1;. If you see
	nothing suspicious, you can update
	<filename>distinfo</filename>. Be sure to summarize the
	differences in your PR or commit log, so that other people
	know that you have taken care to ensure that nothing bad has
	happened.</para>

	<para>You might also want to contact the authors of the software
	and confirm the changes with them.</para>
	</sect1>

	<sect1 id="dads-avoiding-linuxisms">
	<title>Avoiding Linuxisms</title>

	<para>Do not use <filename>/proc</filename> if there are any
	other ways of getting the information, e.g.,
	<function>setprogname(argv[0])</function> in
	<function>main()</function> and then &man.getprogname.3; if
	you want to <quote>know your name</quote>.</para>

	<para>Do not rely on behaviour that is undocumented by
	<acronym>POSIX</acronym>.</para>

	<para>Do not record timestamps in the critical path of the
	application if it also works without. Getting timestamps may
	be slow, depending on the accuracy of timestamps in the
	<acronym>OS</acronym>. If timestamps are really needed,
	determine how precise they have to be and use an
	<acronym>API</acronym> which is documented to just deliver the
	needed precision.</para>

	<para>A number of simple syscalls (for example
	&man.gettimeofday.2;, &man.getpid.2;) are much faster on
	&linux; than on any other operating system due to caching and
	the vsyscall performance optimizations. Do not rely on them
	being cheap in performance-critical applications. In general,
	try hard to avoid syscalls if possible.</para>

	<para>Do not rely on &linux;-specific socket behaviour. In
	particular, default socket buffer sizes are different (call
	&man.setsockopt.2; with <literal>SO_SNDBUF</literal> and
	<literal>SO_RCVBUF</literal>, and while &linux;'s &man.send.2;
	blocks when the socket buffer is full, &os;'s will fail and
	set <literal>ENOBUFS</literal> in errno.</para>

	<para>If relying on non-standard behaviour is required,
	encapsulate it properly into a generic <acronym>API</acronym>,
	do a check for the behaviour in the configure stage, and stop
	if it is missing.</para>

	<para>Check the <ulink
	url="http://www.freebsd.org/cgi/man.cgi">man pages</ulink>
	to see if the function used is a <acronym>POSIX</acronym>
	interface (in the <quote>STANDARDS</quote> section of the man
	page).</para>

	<para>Do not assume that <filename>/bin/sh</filename> is
	<application>bash</application>. Ensure that a command line
	passed to &man.system.3; will work with a
	<acronym>POSIX</acronym> compliant shell.</para>

	<para>A list of common <application>bash</application>isms is
	available <ulink
	url="https://wiki.ubuntu.com/DashAsBinSh">here</ulink>.</para>

	<para>Do not <literal>#include
	<filename><stdint.h></filename></literal> if
	<filename>inttypes.h</filename> is sufficient. This will
	ensure that the software builds on older versions of
	&os;.</para>

	<para>Check that headers are included in the
	<acronym>POSIX</acronym> or man page recommended way, e.g.,
	<filename>sys/types.h</filename> is often forgotten, which is
	not as much of a problem for &linux; as it is for &os;.</para>

	<para>Compile threaded applications with
	<quote>-pthread</quote>, not <quote>-lpthread</quote> or
	variations thereof.</para>

	</sect1>

	<sect1 id="dads-misc">
	<title>Miscellanea</title>

	<para>The files <filename>pkg-descr</filename> and
	<filename>pkg-plist</filename> should each be double-checked.
	If you are reviewing a port and feel they can be worded
	better, do so.</para>

	<para>Do not copy more copies of the GNU General Public License
	into our system, please.</para>

	<para>Please be careful to note any legal issues! Do not let us
	illegally distribute software!</para>
	</sect1>

	</chapter>

	<chapter id="porting-samplem">
	<title>A Sample <filename>Makefile</filename></title>

	<para>Here is a sample <filename>Makefile</filename> that you can
	use to create a new port. Make sure you remove all the extra
	comments (ones between brackets)!</para>

	<para>It is recommended that you follow this format (ordering of
	variables, empty lines between sections, etc.). This format is
	designed so that the most important information is easy to
	locate. We recommend that you use <link
	linkend="porting-portlint">portlint</link> to check the
	<filename>Makefile</filename>.</para>

	<programlisting>[the header...just to make it easier for us to identify the ports.]
	# Created by: Satoshi Asami <asami@FreeBSD.org>
	[The optional <emphasis>Created by:</emphasis> line names the person who originally
	created the port. Note that the <quote>:</quote> is followed by a space
	and not a tab character.
	If this line is present, future maintainers should
	not change or remove it except at the original author's request.]

	# &dollar;FreeBSD&dollar;
	[ ^^^^^^^^^ This will be automatically replaced with RCS ID string by SVN
	when it is committed to our repository. If upgrading a port, do not alter
	this line back to "&dollar;FreeBSD&dollar;". SVN deals with it automatically.]

	[section to describe the port itself and the master site - PORTNAME
	and PORTVERSION are always first, followed by CATEGORIES,
	and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
	PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, will be after that.
	Then comes DISTNAME, EXTRACT_SUFX and/or DISTFILES, and then
	EXTRACT_ONLY, as necessary.]
	PORTNAME= xdvi
	PORTVERSION= 18.2
	CATEGORIES= print
	[do not forget the trailing slash ("/")!
	if you are not using MASTER_SITE_* macros]
	MASTER_SITES= ${MASTER_SITE_XCONTRIB}
	MASTER_SITE_SUBDIR= applications
	PKGNAMEPREFIX= ja-
	DISTNAME= xdvi-pl18
	[set this if the source is not in the standard ".tar.gz" form]
	EXTRACT_SUFX= .tar.Z

	[section for distributed patches -- can be empty]
	PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/
	PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz

	[maintainer; mandatory! This is the person who is volunteering to
	handle port updates, build breakages, and to whom a users can direct
	questions and bug reports. To keep the quality of the Ports Collection
	as high as possible, we no longer accept new ports that are assigned to
	"ports@FreeBSD.org".]
	MAINTAINER= asami@FreeBSD.org
	COMMENT= A DVI Previewer for the X Window System

	[dependencies -- can be empty]
	RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
	LIB_DEPENDS= Xpm:${PORTSDIR}/graphics/xpm

	[this section is for other standard bsd.port.mk variables that do not
	belong to any of the above]
	[If it asks questions during configure, build, install...]
	IS_INTERACTIVE= yes
	[If it extracts to a directory other than ${DISTNAME}...]
	WRKSRC= ${WRKDIR}/xdvi-new
	[If the distributed patches were not made relative to ${WRKSRC}, you
	may need to tweak this]
	PATCH_DIST_STRIP= -p1
	[If it requires a "configure" script generated by GNU autoconf to be run]
	GNU_CONFIGURE= yes
	[If it requires GNU make, not /usr/bin/make, to build...]
	USE_GMAKE= yes
	[If it is an X application and requires "xmkmf -a" to be run...]
	USE_IMAKE= yes
	[et cetera.]

	[non-standard variables to be used in the rules below]
	MY_FAVORITE_RESPONSE= "yeah, right"

	[then the special rules, in the order they are called]
	pre-fetch:
	i go fetch something, yeah

	post-patch:
	i need to do something after patch, great

	pre-install:
	and then some more stuff before installing, wow

	[and then the epilogue]
	.include <bsd.port.mk></programlisting>
	</chapter>

	<chapter id="keeping-up">
	<title>Keeping Up</title>

	<para>The &os; Ports Collection is constantly changing. Here is
	some information on how to keep up.</para>

	<sect1 id="freshports">
	<title>FreshPorts</title>

	<para>One of the easiest ways to learn about updates that have
	already been committed is by subscribing to <ulink
	url="http://www.FreshPorts.org/">FreshPorts</ulink>. You
	can select multiple ports to monitor. Maintainers are
	strongly encouraged to subscribe, because they will receive
	notification of not only their own changes, but also any
	changes that any other &os; committer has made. (These are
	often necessary to keep up with changes in the underlying
	ports framework—although it would be most polite to
	receive an advance heads-up from those committing such
	changes, sometimes this is overlooked or just simply
	impractical. Also, in some cases, the changes are very minor
	in nature. We expect everyone to use their best judgement in
	these cases.)</para>

	<para>If you wish to use FreshPorts, all you need is an account.
	If your registered email address is
	<literal>@FreeBSD.org</literal>, you will see the opt-in link
	on the right hand side of the webpages. For those of you who
	already have a FreshPorts account, but are not using your
	<literal>@FreeBSD.org</literal> email address, just change
	your email to <literal>@FreeBSD.org</literal>, subscribe, then
	change it back again.</para>

	<para>FreshPorts also has a sanity test feature which
	automatically tests each commit to the FreeBSD ports tree. If
	subscribed to this service, you will be notified of any errors
	which FreshPorts detects during sanity testing of your
	commits.</para>
	</sect1>

	<sect1 id="svnweb">
	<title>The Web Interface to the Source Repository</title>

	<para>It is possible to browse the files in the source
	repository by using a web interface. Changes that affect the
	entire port system are now documented in the <ulink
	url="http://svnweb.FreeBSD.org/ports/head/CHANGES">CHANGES</ulink>
	file. Changes that affect individual ports
	are now documented in the <ulink
	url="http://svnweb.FreeBSD.org/ports/head/UPDATING">UPDATING</ulink>
	file. However, the definitive answer to
	any question is undoubtedly to read the source code of <ulink
	url="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.port.mk">bsd.port.mk</ulink>,
	and associated files.</para>
	</sect1>

	<sect1 id="ports-mailling-list">
	<title>The &os; Ports Mailing List</title>

	<para>If you maintain ports, you should consider following the
	&a.ports;. Important changes to the way ports work will be
	announced there, and then committed to
	<filename>CHANGES</filename>.</para>

	<para>If this mailing list is too high volume you may consider
	following &a.ports-announce; which is moderated and has no
	discussion.</para>
	</sect1>

	<sect1 id="build-cluster">
	<title>The &os; Port Building Cluster on
	<hostid role="hostname">pointyhat.FreeBSD.org</hostid></title>

	<para>One of the least-publicized strengths of &os; is that
	an entire cluster of machines is dedicated to continually
	building the Ports Collection, for each of the major OS
	releases and for each Tier-1 architecture. You can find
	the results of these builds at <ulink
	url="http://pointyhat.FreeBSD.org/">package building logs
	and errors</ulink>.</para>

	<para>Individual ports are built unless they are specifically
	marked with <makevar>IGNORE</makevar>. Ports that are
	marked with <makevar>BROKEN</makevar> will still be attempted,
	to see if the underlying problem has been resolved. (This
	is done by passing <makevar>TRYBROKEN</makevar> to the
	port's <filename>Makefile</filename>.)</para>
	</sect1>

	<sect1 id="distfile-survey">
	<title>Portscout: the &os; Ports Distfile Scanner</title>

	<para>The build cluster is dedicated to building the latest
	release of each port with distfiles that have already been
	fetched. However, as the Internet continually changes,
	distfiles can quickly go missing. <ulink
	- url="http://portscout.FreeBSD.org">Portscout</ulink>, the &os;
	- Ports distfile scanner, attempts to query every download site
	- for every port to find out if each distfile is still
	+ url="http://portscout.FreeBSD.org">Portscout</ulink>, the
	+ &os; Ports distfile scanner, attempts to query every download
	+ site for every port to find out if each distfile is still
	available. <application>Portscout</application> can generate
	<acronym>HTML</acronym> reports and send emails about newly
	available ports to those who request them. Unless not
	otherwise subscribed, maintainers are asked to check
	periodically for changes, either by hand or using the
	<acronym>RSS</acronym> feed.</para>

	<para><application>Portscout</application>'s first page gives
	the email address of the port maintainer, the number of ports
	the maintainer is responsible for, the number of those ports
	with new distfiles, and the percentage of those ports that are
	out-of-date. The search function allows for searching by
	email address for a specific maintainer, and for selecting
	whether or not only out-of-date ports should be shown.</para>

	<para>Upon clicking on a maintainer's email address,
	a list of all of their ports is displayed, along with port
	category, current version number, whether or not there is a
	new version, when the port was last updated, and finally when
	it was last checked. A search function on this page allows
	the user to search for a specific port.</para>

	<para>Clicking on a port name in the list displays the
	<ulink url="http://freshports.org">FreshPorts</ulink> port
	information.</para>
	</sect1>

	<sect1 id="portsmon">
	<title>The &os; Ports Monitoring System</title>

	<para>Another handy resource is the <ulink
	url="http://portsmon.FreeBSD.org"> FreeBSD Ports Monitoring
	System</ulink> (also known as <literal>portsmon</literal>).
	This system comprises a database that processes information
	from several sources and allows it to be browsed via a web
	interface. Currently, the ports Problem Reports (PRs), the
	error logs from the build cluster, and individual files from
	the ports collection are used. In the future, this will be
	expanded to include the distfile survey, as well as other
	sources.</para>

	<para>To get started, you can view all information about a
	particular port by using the <ulink
	url="http://portsmon.FreeBSD.org/portoverview.py">
	Overview of One Port</ulink>.</para>

	<para>As of this writing, this is the only resource available
	that maps GNATS PR entries to portnames. (PR submitters do
	not always include the portname in their Synopsis, although we
	would prefer that they did.) So, <literal>portsmon</literal>
	is a good place to start if you want to find out whether an
	existing port has any PRs filed against it and/or any build
	errors; or, to find out if a new port that you may be thinking
	about creating has already been submitted.</para>
	+ </sect1>
	+ </chapter>
	+
	+ <chapter id="appendices">
	+ <title>Appendices</title>
	+
	+ <sect1 id="uses-values">
	+ <title>Values of <makevar>USES</makevar></title>
	+
	+ <table frame="none">
	+ <title>Values of <makevar>USES</makevar></title>
	+
	+ <tgroup cols="2">
	+ <thead>
	+ <row>
	+ <entry>Feature</entry>
	+ <entry>Arguments</entry>
	+ <entry>Description</entry>
	+ </row>
	+ </thead>
	+ <tbody>
	+ &values.uses;
	+ </tbody>
	+ </tgroup>
	+ </table>
	</sect1>
	</chapter>
	</book>
	Index: projects/entities/en_US.ISO8859-1/books/porters-handbook/uses.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/books/porters-handbook/uses.xml (nonexistent)
	+++ projects/entities/en_US.ISO8859-1/books/porters-handbook/uses.xml (revision 41355)
	@@ -0,0 +1,81 @@
	+<!--
	+
	+ The FreeBSD Documentation Project
	+
	+ $FreeBSD$
	+
	+ This file documents the values of the USES make variable. The format is
	+ easy to grasp from the already-added entries below (or use this scheme
	+ below as a skeleton):
	+
	+<row>
	+ <entry><literal>FEATURE</literal></entry>
	+ <entry>ARGUMENTS</entry>
	+ <entry>DESCRIPTION</entry>
	+</row>
	+
	+-->
	+
	+<row>
	+ <entry><literal>bison</literal></entry>
	+ <entry>none, <literal>build</literal>, <literal>run</literal>,
	+ <literal>both</literal></entry>
	+ <entry>Implies that the port uses <filename
	+ role="package">devel/bison</filename> in one way or another. By
	+ default, with no arguments or with the <literal>build</literal>
	+ argument, it implies <command>bison</command> as a build-time
	+ dependency, <literal>run</literal> implies a run-time dependency,
	+ and <literal>both</literal> implies both run-time and build-time
	+ dependencies.</entry>
	+</row>
	+
	+<row>
	+ <entry><literal>cmake</literal></entry>
	+ <entry>none, <literal>outsource</literal></entry>
	+
	+ <entry>The port will use <application>CMake</application> for
	+ configuring and building. With the <literal>outsource</literal>
	+ argument, an out-of-source build will be performed. For more
	+ information see <xref linkend="using-cmake"/>.</entry>
	+</row>
	+
	+<row>
	+ <entry><literal>fuse</literal></entry>
	+ <entry>none</entry>
	+
	+ <entry>Implies the port will depend on the FUSE library and handle
	+ the the dependency on the kernel module depending on the version
	+ of &os;.</entry>
	+</row>
	+
	+<row>
	+ <entry><literal>pathfix</literal></entry>
	+ <entry>none</entry>
	+ <entry>Look for the <filename>Makefile.in</filename> and
	+ <filename>configure</filename> files in the port's associated
	+ sources and fix common paths to make sure they respect the &os;
	+ hierarchy.</entry>
	+</row>
	+
	+<row>
	+ <entry><literal>qmail</literal></entry>
	+ <entry>none, <literal>build</literal>, <literal>run</literal>,
	+ <literal>both</literal>, <literal>vars</literal></entry>
	+ <entry>Implies that the port uses <filename
	+ role="package">mail/qmail</filename> in one way or another.
	+ With the <literal>build</literal> argument, it implies
	+ <command>qmail</command> as a build-time dependency.
	+ <literal>run</literal> implies a run-time dependency. Using no
	+ argument or the <literal>both</literal> argument implies both
	+ run-time and build-time dependencies. <literal>vars</literal>
	+ will only set QMAIL variables for the port to use.</entry>
	+</row>
	+
	+<row>
	+ <entry><literal>zenoss</literal></entry>
	+ <entry>none</entry>
	+ <entry>Implies the port uses <filename
	+ role="package">net-mgmt/zenoss</filename> in one way or another,
	+ but largely is used for building zenoss related zenpack
	+ ports.</entry>
	+</row>

	Property changes on: projects/entities/en_US.ISO8859-1/books/porters-handbook/uses.xml
	___________________________________________________________________
	Added: svn:eol-style
	## -0,0 +1 ##
	+native
	\ No newline at end of property
	Added: svn:keywords
	## -0,0 +1 ##
	+FreeBSD=%H
	\ No newline at end of property
	Index: projects/entities/en_US.ISO8859-1/htdocs/vendors.html
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/vendors.html (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/vendors.html (nonexistent)
	@@ -1,19 +0,0 @@
	-<?xml version="1.0" encoding="iso-8859-1"?>
	-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	-<!-- $FreeBSD$ -->
	-<html>
	- <head>
	- <meta http-equiv="refresh" content="5;url=doc/en_US.ISO8859-1/books/handbook/mirrors.html" />
	- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
	- <title>Vendors who provide FreeBSD</title>
	- </head>
	-
	- <body bgcolor="#ffffff">
	- <p>The list of vendors who carry FreeBSD is available <a
	- href="doc/en_US.ISO8859-1/books/handbook/mirrors.html">as part of
	- the FreeBSD Handbook</a>. You should be automatically redirected
	- there in a few seconds. If not, please follow the link and update
	- your bookmarks. We apologize for the inconvenience.</p>
	- </body>
	-</html>

	Property changes on: projects/entities/en_US.ISO8859-1/htdocs/vendors.html
	___________________________________________________________________
	Deleted: svn:keywords
	## -1 +0,0 ##
	-FreeBSD=%H
	\ No newline at end of property
	Deleted: svn:mime-type
	## -1 +0,0 ##
	-text/sgml
	\ No newline at end of property
	Index: projects/entities/en_US.ISO8859-1/htdocs/availability.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/availability.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/availability.xml (nonexistent)
	@@ -1,27 +0,0 @@
	-<?xml version="1.0" encoding="iso-8859-1"?>
	-<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	-"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	-<!ENTITY title "About FreeBSD's availability">
	-]>
	-
	-<html xmlns="http://www.w3.org/1999/xhtml">
	- <head>
	- <meta http-equiv="refresh" content="5;url=&base;/index.html"/>
	- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
	-
	- <title>&title;</title>
	-
	- <cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	-
	- </head>
	-
	- <body class="navinclude.about">
	-
	- <p>The content of this page has been integrated into the <a
	- href="&base;/index.html">main FreeBSD webpage</a>. You should
	- be automatically redirected there in a few seconds. If not,
	- please follow the link and update your bookmarks.</p>
	-
	- <p>We apologize for the inconvenience.</p>
	- </body>
	-</html>

	Property changes on: projects/entities/en_US.ISO8859-1/htdocs/availability.xml
	___________________________________________________________________
	Deleted: svn:keywords
	## -1 +0,0 ##
	-FreeBSD=%H
	\ No newline at end of property
	Deleted: svn:mime-type
	## -1 +0,0 ##
	-text/sgml
	\ No newline at end of property
	Index: projects/entities/en_US.ISO8859-1/htdocs/Makefile
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/Makefile (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/Makefile (revision 41355)
	@@ -1,118 +1,115 @@
	# $FreeBSD$

	.if exists(Makefile.conf)
	.include "Makefile.conf"
	.endif
	.if exists(../Makefile.inc)
	.include "../Makefile.inc"
	.endif

	# These are turned into validated, normalized HTML files.

	DOCS= about.xml
	DOCS+= administration.xml
	DOCS+= applications.xml
	DOCS+= art.xml
	-DOCS+= availability.xml
	DOCS+= docs.xml
	DOCS+= features.xml
	DOCS+= internet.xml
	DOCS+= logo.xml
	DOCS+= mailto.xml
	DOCS+= privacy.xml
	DOCS+= publish.xml
	DOCS+= relnotes.xml
	DOCS+= send-pr.xml
	DOCS+= support.xml
	DOCS+= where.xml
	DOCS+= 4xx.xml

	XMLDOCS= index:xsl:${XML_NEWS_NEWS}:
	DEPENDSET.index=transtable mirrors news press events \
	advisories notices

	XMLDOCS+= usergroups:${XSL_USERGROUPS}:${XML_USERGROUPS}:
	DEPENDSET.usergroups=transtable usergroups
	PARAMS.usergroups= --param pagename "'FreeBSD User Groups'"

	XMLDOCS+= community::${XML_EVENTS_EVENTS}:
	DEPENDSET.community=usergroups events

	# These will be directly installed.

	DATA= favicon.ico
	DATA+= freebsd.css
	DATA+= google6bb24ed0b804d5e9.html
	DATA+= index.css
	DATA+= robots.txt
	-DATA+= vendors.html

	# Subdirectories
	# XML
	SUBDIR+= advocacy
	SUBDIR+= commercial
	SUBDIR+= community
	SUBDIR+= copyright
	SUBDIR+= developers
	SUBDIR+= docproj
	SUBDIR+= docs
	SUBDIR+= donations
	SUBDIR+= events
	SUBDIR+= gnome
	SUBDIR+= handbook
	SUBDIR+= internal
	SUBDIR+= ipv6
	SUBDIR+= java
	SUBDIR+= marketing
	SUBDIR+= multimedia
	SUBDIR+= news
	SUBDIR+= platforms
	SUBDIR+= portmgr
	SUBDIR+= projects
	SUBDIR+= prstats
	SUBDIR+= releases
	SUBDIR+= releng
	SUBDIR+= search
	SUBDIR+= security
	SUBDIR+= snapshots
	SUBDIR+= support
	-SUBDIR+= tutorials
	.if !defined(WEB_ONLY) \|\| empty(WEB_ONLY)
	SUBDIR+= doc
	SUBDIR+= ports
	.endif
	.if defined(BUILD_RELNOTES)
	SUBDIR+= relnotes
	.endif

	# Non-XML
	SUBDIR+= cgi
	SUBDIR+= gifs
	SUBDIR+= layout
	SUBDIR+= logo

	.if !defined(WEB_LANG) \|\| empty(WEB_LANG)
	WEB_LANG= da_DK.ISO8859-1 \
	de_DE.ISO8859-1 \
	el_GR.ISO8859-7 \
	es_ES.ISO8859-1 \
	fr_FR.ISO8859-1 \
	hu_HU.ISO8859-2 \
	it_IT.ISO8859-15 \
	ja_JP.eucJP \
	mn_MN.UTF-8 \
	nl_NL.ISO8859-1 \
	pt_BR.ISO8859-1 \
	ru_RU.KOI8-R \
	zh_CN.GB2312 \
	zh_TW.Big5
	.endif
	.if !defined(ENGLISH_ONLY) \|\| empty(ENGLISH_ONLY)
	.for _D in ${WEB_LANG}
	SUBDIR+= ../../${_D}/htdocs
	.endfor
	.endif

	WEBDIR?= data

	.include "${DOC_PREFIX}/share/mk/web.site.mk"
	Index: projects/entities/en_US.ISO8859-1/htdocs/about.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/about.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/about.xml (revision 41355)
	@@ -1,113 +1,114 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "About FreeBSD">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.about">

	<h2>What is FreeBSD?</h2>

	<p>FreeBSD is an advanced operating system for x86
	- compatible (including Pentium® and Athlon™), amd64
	+ compatible (including Pentium® and Athlon™),
	+ amd64, x86-64 and x64
	compatible (including Opteron™, Athlon™64,
	and EM64T), ARM, IA-64, PowerPC, PC-98 and UltraSPARC®
	architectures. It is derived from BSD, the version of
	&unix; developed at the
	University of California, Berkeley. It is developed
	and maintained by <a
	href="&base;/doc/en_US.ISO8859-1/articles/contributors/staff-committers.html">a
	large team of individuals</a>. Additional <a
	href="&base;/platforms/index.html">platforms</a> are
	in various stages of development.</p>

	<h2>Cutting edge features</h2>

	<p>FreeBSD offers advanced networking, performance, security
	and compatibility
	<a href="&base;/features.html">features</a>
	today which are still missing in other operating systems,
	even some of the best commercial ones.</p>

	<h2>Powerful Internet solutions</h2>

	<p>FreeBSD makes an ideal
	<a href="&base;/internet.html">Internet or Intranet</a>
	server. It provides robust network services under the heaviest
	loads and uses memory efficiently to maintain good response
	times for thousands of simultaneous user processes.</p>

	<h2>Advanced Embedded Platform</h2>
	<p>FreeBSD brings advanced network operating system
	features to appliance and embedded platforms, from
	higher-end Intel-based appliances to Arm, PowerPC,
	and shortly MIPS hardware platforms. From
	mail and web appliances to routers, time servers,
	and wireless access points, vendors around the
	world rely on FreeBSD's integrated build and
	cross-build environments and advanced features as
	the foundation for their embedded products. And
	the Berkeley open source license lets them decide
	how many of their local changes they want to
	contribute back.</p>

	<h2>Run a huge number of
	applications</h2>

	<p>With over 24,000 ported libraries and <a
	href="&base;/applications.html">applications</a>,
	FreeBSD supports applications for desktop, server,
	appliance, and embedded environments.</p>

	<h2>Easy to install</h2>

	<p>FreeBSD can be installed from a variety of media
	including CD-ROM, DVD, or directly over the network
	using FTP or NFS. All you need are
	<a
	href="&base;/doc/en_US.ISO8859-1/books/handbook/install.html">these
	directions</a>.</p>

	<h2>FreeBSD is <i>free</i></h2>

	<a href="&base;/copyright/daemon.html"><img src="gifs/dae_up3.gif" alt="The BSD Daemon" height="81" width="72" align="right" border="0"/></a>

	<p>While you might expect an operating system with these
	features to sell for a high price, FreeBSD is available
	<a href="&base;/copyright/index.html">free of charge</a>
	and comes with full source code. If you would like to
	purchase or download a copy to try out,
	<a href="&base;/doc/en_US.ISO8859-1/books/handbook/mirrors.html">more
	information is available</a>.</p>

	<h2>Contributing to FreeBSD</h2>

	<p>It is easy to contribute to FreeBSD. All you need to do
	is find a part of FreeBSD which you think could be
	improved and make those changes (carefully and cleanly)
	and submit that back to the Project by means of send-pr
	or a committer, if you know one. This could be anything
	from documentation to artwork to source code. See the
	<a href="&base;/doc/en_US.ISO8859-1/articles/contributing/index.html">Contributing
	to FreeBSD</a> article for more information.</p>

	<p>Even if you are not a programmer, there are other
	ways to contribute to FreeBSD. The <a
	href="http://www.FreeBSDFoundation.org">FreeBSD
	Foundation</a> is a non-profit organization for which
	direct contributions are fully tax deductible. Please
	contact <a
	href="mailto:board@FreeBSDFoundation.org">board@FreeBSDFoundation.org</a>
	for more information or write to: The FreeBSD
	Foundation, P.O. Box 20247, Boulder, CO 80308,
	USA.</p>

	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/administration.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/administration.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/administration.xml (revision 41355)
	@@ -1,502 +1,474 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "FreeBSD Project Administration and Management">
	]>

	+<!-- NOTE: If any alias listed on this page is modified in the
	+ /etc/aliases on the FreeBSD project's mail server,
	+ then this page must be updated. -->
	+
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.about">

	<h2>Introduction</h2>

	<p>This page lists teams, groups and individuals within the
	FreeBSD project with designated project roles and areas of
	responsibility, along with brief descriptions and contact
	information.</p>

	<ul>
	<li>Project Management
	<ul>
	<li><a href="#t-core">Core Team</a></li>
	<li><a href="#t-doceng">Documentation Engineering Team</a></li>
	<li><a href="#t-portmgr">Port Management Team</a></li>
	</ul>
	</li>
	<li>Release Engineering
	<ul>
	<li><a href="#t-re">Primary Release Engineering Team</a></li>
	<li><a href="#t-re-builder">Builders Release Engineering Team</a></li>
	</ul>
	</li>
	<li>Teams
	<ul>
	<li><a href="#t-donations">Donations Team</a></li>
	<li><a href="#t-marketing">Marketing Team</a></li>
	<li><a href="#t-secteam">Security Team</a></li>
	<li><a href="#t-vendor">Vendor Relations</a></li>
	</ul>
	</li>
	<li>Secretaries
	<ul>
	<li><a href="#t-core-secretary">Core Team Secretary</a></li>
	<li><a href="#t-portmgr-secretary">Port Management Team
	Secretary</a></li>
	<li><a href="#t-secteam-secretary">Security Team Secretary</a></li>
	</ul>
	</li>
	<li>Internal Administration
	<ul>
	<li><a href="#t-accounts">Accounts Team</a></li>
	<li><a href="#t-backups">Backup Administrators</a></li>
	<li><a href="#t-bugmeister">Bugmeisters & GNATS
	Administrators</a></li>
	<li><a href="#t-clusteradm">Cluster Administrators</a></li>
	- <li><a href="#t-pcvs">CVS ports Repository Managers</a></li>
	- <li><a href="#t-ncvs">CVS src Repository Managers</a></li>
	<li><a href="#t-cvsup-master">CVSup Mirror Site
	Coordinators</a></li>
	<li><a href="#t-dnsadm">DNS Administrators</a></li>
	<li><a href="#t-mirror-admin">FTP/WWW Mirror Site
	Coordinators</a></li>
	<li><a href="#t-perforce-admin">Perforce Repository
	Administrators</a></li>
	<li><a href="#t-postmaster">Postmaster Team</a></li>
	+ <li><a href="#t-subversion">Subversion Administrators</a></li>
	<li><a href="#t-webmaster">Webmaster Team</a></li>
	</ul>
	</li>
	</ul>

	<hr/>

	<h3><a name="t-core">FreeBSD Core Team</a>
	<<a href="mailto:core@FreeBSD.org">core@FreeBSD.org</a>></h3>

	<p>The FreeBSD Core Team constitutes the project's "Board of Directors",
	responsible for deciding the project's overall goals and direction as
	well as managing specific areas of the FreeBSD project landscape. The
	Core Team is elected by the active developers in the project.</p>

	<ul>
	<li>&a.tabthorpe.email;</li>
	<li>&a.gavin.email;</li>
	<li>&a.jhb.email;</li>
	<li>&a.kib.email;</li>
	<li>&a.theraven.email;</li>
	<li>&a.hrs.email;</li>
	<li>&a.peter.email;</li>
	<li>&a.miwi.email;</li>
	</ul>

	<h3><a name="t-doceng">FreeBSD Documentation Engineering Team</a>
	<<a href="mailto:doceng@FreeBSD.org">doceng@FreeBSD.org</a>></h3>

	<p>The FreeBSD Documentation Engineering Team is responsible for
	defining and following up documentation goals for the committers
	in the Documentation project. The <a
	href="internal/doceng.html">doceng team charter</a>
	describes the duties and responsibilities of the Documentation
	Engineering Team in greater detail.</p>

	<ul>
	<li>&a.gjb.email;</li>
	<li>&a.blackend.email;</li>
	<li>&a.gabor.email;</li>
	<li>&a.hrs.email;</li>
	</ul>

	<h3><a name="t-portmgr">FreeBSD Port Management Team</a>
	<<a href="mailto:portmgr@FreeBSD.org">portmgr@FreeBSD.org</a>></h3>

	<p>The primary responsibility of the FreeBSD Port Management Team is to
	ensure that the FreeBSD Ports Developer community provides a ports
	collection that is functional, stable, up-to-date and full-featured.
	Its secondary responsibility is to coordinate among the committers
	and developers who work on it. The <a
	href="portmgr/charter.html">portmgr team charter</a>
	describes the duties and responsibilities of the Port Management
	Team in greater detail.</p>

	<ul>
	<li>&a.tabthorpe.email;</li>
	<li>&a.marcus.email;</li>
	<li>&a.bapt.email;</li>
	+ <li>&a.bdrewery.email;</li>
	<li>&a.decke.email;</li>
	- <li>&a.beat.email;</li>
	<li>&a.erwin.email;</li>
	- <li>&a.linimon.email;</li>
	<li>&a.itetcu.email;</li>
	<li>&a.miwi.email;</li>
	</ul>

	<hr/>

	<h3><a name="t-re">Primary Release Engineering Team</a>
	<<a href="mailto:re@FreeBSD.org">re@FreeBSD.org</a>></h3>

	<p>The Primary Release Engineering Team is responsible for setting and
	publishing release schedules for official project releases of FreeBSD,
	- announcing code freezes and maintaining <code>RELENG_*</code> branches, among other
	+ announcing code freezes and maintaining <code>releng/*</code> branches, among other
	things. The <a
	href="releng/charter.html">release engineering team charter</a>
	describes the duties and responsibilities of the Primary Release
	Engineering Team in greater detail.</p>

	<ul>
	<li>&a.kib.email;</li>
	<li>&a.blackend.email;</li>
	<li>&a.jpaetzel.email;</li>
	<li>&a.hrs.email;</li>
	<li>&a.kensmith.email; (Lead)</li>
	</ul>

	<h3><a name="t-re-builder">Builders Release Engineering Team</a>
	- <<a href="mailto:re-builder@FreeBSD.org">re-builder@FreeBSD.org</a>></h3>
	+ <<a href="mailto:re-builders@FreeBSD.org">re-builders@FreeBSD.org</a>></h3>

	<p>The builders release engineering team is responsible
	for building and packaging FreeBSD releases on the various supported
	platforms.</p>

	<ul>
	<li>&a.marcel.email;</li>
	<li>&a.nyan.email;</li>
	<li>&a.nwhitehorn.email;</li>
	</ul>

	<hr/>

	<h3><a name="t-donations">Donations Team</a>
	<<a href="mailto:donations@FreeBSD.org">donations@FreeBSD.org</a>></h3>

	<p>The FreeBSD Donations Team is responsible for responding to donations
	offers, establishing donation guidelines and procedures, and coordinating
	donation offers with the FreeBSD developer community. A more detailed
	description of the duties of the Donations Team is available on the <a
	href="donations/">FreeBSD Donations Liaison</a> page.</p>

	<ul>
	<li>&a.tabthorpe.email;</li>
	<li>&a.gjb.email;</li>
	<li>&a.gahr.email;</li>
	<li>&a.pgollucci.email;</li>
	<li>&a.skreuzer.email;</li>
	<li>&a.obrien.email;</li>
	<li>&a.trhodes.email;</li>
	<li>&a.ds.email;</li>
	<li>&a.rwatson.email;</li>
	</ul>

	<h3><a name="t-marketing">Marketing Team</a>
	<<a href="mailto:marketing@FreeBSD.org">marketing@FreeBSD.org</a>></h3>

	<p>Press contact, marketing, interviews, information.</p>

	<ul>
	<li>Steven Beedle <<a
	href="mailto:steven@zna.com">steven@zna.com</a>></li>
	<li>Denise Ebery <<a
	href="mailto:denise@ixsystems.com">denise@ixsystems.com</a>></li>
	<li>&a.deb.email;</li>
	<li>&a.jkoshy.email;</li>
	<li>Dru Lavigne <<a
	href="mailto:dlavigne6@sympatico.ca">dlavigne6@sympatico.ca</a>></li>
	<li>&a.mwlucas.email;</li>
	<li>&a.imp.email;</li>
	<li>Kris Moore <<a
	href="mailto:kris@pcbsd.org">kris@pcbsd.org</a>></li>
	<li>&a.murray.email;</li>
	<li>&a.matt.email;</li>
	<li>Jeremy C. Reed <<a
	href="mailto:reed@reedmedia.net">reed@reedmedia.net</a>></li>
	<li>&a.rwatson.email;</li>
	</ul>


	<h3><a name="t-secteam">Security Team</a>
	<<a href="mailto:secteam@FreeBSD.org">secteam@FreeBSD.org</a>></h3>

	<p>The FreeBSD Security Team (headed by the Security Officer) is
	responsible for keeping the community aware of bugs, exploits and
	security risks affecting the FreeBSD src and ports trees, and to
	promote and distribute information needed to safely run FreeBSD
	systems. Furthermore, it is responsible for resolving software
	bugs affecting the security of FreeBSD and issuing security
	advisories. The <a href="security/charter.html">FreeBSD
	Security Officer Charter</a> describes the duties and
	responsibilities of the Security Officer in greater detail.</p>

	<ul>
	<li>&a.benl.email;</li>
	- <li>&a.bz.email;</li>
	- <li>&a.cperciva.email;</li>
	+ <li>&a.cperciva.email; (Officer Emeritus)</li>
	<li>&a.csjp.email;</li>
	- <li>&a.delphij.email;</li>
	+ <li>&a.delphij.email; (Officer Deputy)</li>
	<li>&a.des.email;</li>
	- <li>&a.gavin.email;</li>
	+ <li>&a.gavin.email; (Core Team Liaison)</li>
	<li>&a.jonathan.email;</li>
	<li>&a.philip.email;</li>
	<li>&a.remko.email;</li>
	<li>&a.rwatson.email;</li>
	<li>&a.simon.email; (Officer)</li>
	<li>&a.stas.email;</li>
	+ <li>&a.trasz.email;</li>
	</ul>

	<h3><a name="t-vendor">Vendor Relations</a>
	<<a href="mailto:vendor-relations@FreeBSD.org">vendor-relations@FreeBSD.org</a>></h3>

	<p>Vendor Relations is responsible for handling email
	from hardware and software vendors. Email sent to Vendor
	Relations is forwarded to the &os; Core Team in addition
	to the &os; Foundation.</p>

	<hr/>

	<h3><a name="t-core-secretary">Core Team Secretary</a>
	<<a href="mailto:core-secretary@FreeBSD.org">core-secretary@FreeBSD.org</a>></h3>

	<p>The FreeBSD Core Team Secretary is a non-voting member of the Core Team,
	responsible for documenting the work done by core, keeping track of the
	core agenda, direct contact with non-core members sending mail to core
	and to be an the interface to the admin team for
	committer/account approval. The Core Team Secretary is also responsible
	for writing and sending out monthly status reports to the FreeBSD
	Developer community, containing a summary of core's latest decisions and
	actions.</p>

	<ul>
	<li>&a.pgj.email;</li>
	</ul>

	<h3><a name="t-portmgr-secretary">Port Management Team Secretary</a>
	<<a href="mailto:portmgr-secretary@FreeBSD.org">portmgr-secretary@FreeBSD.org</a>></h3>

	<p>The FreeBSD Port Management Team Secretary is a non-voting member of the
	Port Management Team, responsible for documenting the work done by portmgr,
	keeping track of voting procedures, and to be an interface to the other
	teams, especially the admin and Core teams. The Port Management Team
	Secretary is also responsible for writing and sending out monthly status
	reports to the FreeBSD Developer community, containing a summary of
	portmgr's latest decisions and actions.</p>

	<ul>
	<li>&a.tabthorpe.email;</li>
	</ul>

	<h3><a name="t-secteam-secretary">Security Team Secretary</a>
	<<a href="mailto:secteam-secretary@FreeBSD.org">secteam-secretary@FreeBSD.org</a>></h3>

	<p>The FreeBSD Security Team Secretary will make sure someone responds to
	incoming emails towards the Security Team. He will acknowledge
	receipt and keep track of the progress within the Security Team.
	If needed the Secretary will contact members of the Security Team to
	let them provide an update on ongoing items. Currently the Security
	Team Secretary does not handle Security Officer Team items.</p>

	<ul>
	<li>&a.remko.email;</li>
	</ul>

	<hr/>

	<h3><a name="t-accounts">Accounts Team</a>
	<!-- admins mail aliases intentionally left incomplete -->
	<accounts@></h3>

	<p>The Accounts Team is responsible for setting up accounts for new
	committers in the project. Requests for new accounts will not be
	acted upon without the proper approval from the appropriate entity.</p>

	<ul>
	- <li>&a.markm.email;</li>
	<li>&a.simon.email;</li>
	- <li>&a.kensmith.email;</li>
	<li>&a.dhw.email;</li>
	</ul>

	<h3><a name="t-backups">Backups Administrators</a>
	<!-- admins mail aliases intentionally left incomplete -->
	<backups@></h3>

	<p>The Backups Administrators handle all backups on the FreeBSD cluster.</p>

	<ul>
	- <li>&a.simon.email;</li>
	- <li>&a.kensmith.email;</li>
	- <li>&a.dhw.email;</li>
	+ <li>&a.simon;</li>
	+ <li>&a.dhw;</li>
	</ul>

	<h3><a name="t-bugmeister">Bugmeisters & GNATS Administrators</a>
	<<a href="mailto:bugmeister@FreeBSD.org">bugmeister@FreeBSD.org</a>></h3>

	<p>The Bugmeisters and GNATS Administrators are responsible for ensuring
	that the maintenance database is in working order, that the entries are
	correctly categorised and that there are no invalid entries. They are
	also responsible for the problem report group.</p>

	<ul>
	<li>&a.eadler.email;</li>
	<li>&a.gavin.email;</li>
	<li>&a.gonzo.email;</li>
	- <li>&a.linimon.email;</li>
	</ul>

	<h3><a name="t-clusteradm">Cluster Administrators</a>
	<!-- admins mail aliases intentionally left incomplete -->
	<clusteradm@></h3>

	<p>The Cluster Administrators consists of the people responsible for
	administrating the machines that the project relies on for its
	distributed work and communication to be synchronised. It
	consists mainly of those people who have physical access to the servers.
	Issues concerning the projects infrastructure or setting up new
	machines should be directed to the cluster administrators.</p>

	<ul>
	<li>&a.bhaga.email;</li>
	<li>&a.brd.email;</li>
	<li>&a.bz.email;</li>
	<li>&a.kensmith.email;</li>
	<li>&a.peter.email;</li>
	<li>&a.sbruno.email;</li>
	<li>&a.simon.email;</li>
	</ul>

	- <h3><a name="t-pcvs">CVS ports Repository Managers</a>
	- <<a href="mailto:pcvs@FreeBSD.org">pcvs@FreeBSD.org</a>></h3>
	-
	- <p>The CVS ports Repository Managers are allowed to directly modify the
	- repository without using the CVS tool. It is their responsibility to
	- ensure that technical problems that arise in the repository are
	- resolved quickly. The CVS ports repository managers have the
	- authority to back out commits if this is necessary to resolve a CVS
	- technical problem. Repo-copy requests should be directed to the
	- repository managers.</p>
	-
	- <ul>
	- <li>&a.marcus.email;</li>
	- <li>&a.joe.email;</li>
	- <li>&a.kuriyama.email;</li>
	- <li>&a.markm.email;</li>
	- <li>&a.simon.email;</li>
	- </ul>
	-
	- <h3><a name="t-ncvs">CVS src Repository Managers</a>
	- <<a href="mailto:ncvs@FreeBSD.org">ncvs@FreeBSD.org</a>></h3>
	-
	- <p>The CVS src Repository Managers are allowed to directly modify the
	- repository without using the CVS tool. It is their responsibility to
	- ensure that technical problems that arise in the repository are
	- resolved quickly. The CVS source repository managers have the
	- authority to back out commits if this is necessary to resolve a CVS
	- technical problem. Repo-copy requests should be directed to the
	- repository managers.</p>
	-
	- <ul>
	- <li>&a.joe.email;</li>
	- <li>&a.kuriyama.email;</li>
	- <li>&a.markm.email;</li>
	- <li>&a.simon.email;</li>
	- <li>&a.peter.email;</li>
	- </ul>
	-
	<h3><a name="t-cvsup-master">CVSup Mirror Site Coordinators</a>
	<<a href="mailto:cvsup-master@FreeBSD.org">cvsup-master@FreeBSD.org</a>></h3>

	<p>The CVSup Mirror Site Coordinators coordinates all the CVSup
	mirror site adminstrators to ensure that they are distributing current
	versions of the software, that they have the capacity to update
	themselves when major updates are in progress, and making it easy for
	the general public to find their closest CVSup mirror.</p>

	<ul>
	<li>&a.kuriyama.email;</li>
	- <li>&a.jdp.email;</li>
	<li>&a.kensmith.email;</li>
	</ul>

	<h3><a name="t-dnsadm">DNS Administrators</a>
	<!-- admins mail aliases intentionally left incomplete -->
	<dnsadm@></h3>

	<p>The DNS Administrators are responsible for managing DNS and related
	services.</p>

	<ul>
	- <li>&a.dg.email;</li>
	- <li>&a.ps.email;</li>
	- <li>&a.kensmith.email;</li>
	- <li>&a.peter.email;</li>
	+ <li>&a.brd;</li>
	+ <li>&a.simon;</li>
	+ <li>&a.peter;</li>
	+ <li>&a.bz;</li>
	</ul>

	<h3><a name="t-mirror-admin">FTP/WWW Mirror Site Coordinators</a>
	<<a href="mailto:mirror-admin@FreeBSD.org">mirror-admin@FreeBSD.org</a>></h3>

	<p>The FTP/WWW Mirror Site Coordinators coordinate all the FTP/WWW
	mirror site adminstrators to ensure that they are distributing current
	versions of the software, that they have the capacity to update
	themselves when major updates are in progress, and making it easy for
	the general public to find their closest FTP/WWW mirror.</p>

	<ul>
	+ <li>&a.brd.email;</li>
	<li>&a.kuriyama.email;</li>
	+ <li>&a.simon.email;</li>
	<li>&a.kensmith.email;</li>
	+ <li>&a.bz.email;</li>
	</ul>

	<h3><a name="t-perforce-admin">Perforce Repository Administrators</a>
	<<a href="mailto:perforce-admin@FreeBSD.org">perforce-admin@FreeBSD.org</a>></h3>

	<p>The Perforce Repository Administrators are responsible for
	administrating the FreeBSD perforce source repository and setting up new
	perforce accounts. All requests concerning new perforce accounts
	for non-committers should be directed to the perforce
	administrators.</p>

	<ul>
	- <li>&a.scottl.email;</li>
	+ <li>&a.gibbs.email;</li>
	<li>&a.kensmith.email;</li>
	<li>&a.gordon.email;</li>
	<li>&a.rwatson.email;</li>
	<li>&a.peter.email;</li>
	- <li>&a.dhw.email;</li>
	</ul>

	<h3><a name="t-postmaster">Postmaster Team</a>
	<<a href="mailto:postmaster@FreeBSD.org">postmaster@FreeBSD.org</a>></h3>

	<p>The Postmaster Team is responsible for mail being correctly delivered
	to the committers' email address, ensuring that the mailing lists work,
	and should take measures against possible disruptions of project mail
	services, such as having troll-, spam- and virus-filters.</p>

	<ul>
	<li>&a.jmb.email;</li>
	<li>&a.brd.email;</li>
	<li>&a.flo.email;</li>
	<li>&a.sahil.email;</li>
	<li>&a.dhw.email;</li>
	+ </ul>
	+
	+ <h3><a name="t-subversion">Subversion Administrators</a> <svnadm@></h3>
	+
	+ <p>The FreeBSD Subversion team is responsible for maintaining the health of
	+ the Subversion Repositories.</p>
	+
	+ <ul>
	+ <li>&a.bz; <<a href="mailto:bz@FreeBSD.org">bz@FreeBSD.org</a>></li>
	+ <li>&a.peter; <<a href="mailto:peter@FreeBSD.org">peter@FreeBSD.org</a>></li>
	+ <li>&a.simon; <<a href="mailto:simon@FreeBSD.org">simon@FreeBSD.org</a>></li>
	</ul>

	<h3><a name="t-webmaster">Webmaster Team</a>
	<<a href="mailto:webmaster@FreeBSD.org">webmaster@FreeBSD.org</a>></h3>

	<p>The FreeBSD Webmaster Team is responsible for keeping the main FreeBSD web
	sites up and running. This means web server configuration, CGI scripts,
	fulltext and mailing list search. Anything web related, technical stuff
	belongs to the scope of the Webmaster Team, excluding bugs in the
	documentation.</p>

	<ul>
	<li>&a.nik.email;</li>
	<li>&a.kuriyama.email;</li>
	<li>&a.simon.email;</li>
	<li>&a.jesusr.email;</li>
	<li>&a.wosch.email;</li>
	</ul>

	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/advocacy/index.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/advocacy/index.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/advocacy/index.xml (revision 41355)
	@@ -1,85 +1,90 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "FreeBSD Advocacy Project">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.about">

	<p>Much of the success which surrounds FreeBSD is due to people advocating its use to
	their friends, colleagues, and employers.</p>

	<p>This page provides links to more information to help you do this.</p>

	<h2>Mailing lists</h2>

	<ul>
	<li><p><a
	href="http://lists.freebsd.org/mailman/listinfo/freebsd-advocacy">FreeBSD
	advocacy mailing list</a></p></li>
	</ul>

	<h2>Web resources</h2>

	<ul>
	+ <li><p><a href="&base;/news/status/status.html">FreeBSD quarterly status reports</a></p>
	+
	+ <p>Quarterly status reports detailing activity within and surrounding FreeBSD.</p></li>
	+ </ul>
	+ <ul>
	<li><p><a href="whyusefreebsd.html">Why Use FreeBSD?</a></p>

	<p>Explanations given by existing users as to why FreeBSD should
	be used.</p></li>
	</ul>
	<ul>
	<li><p><a href="myths.html">*BSD Myths</a></p>

	<p>Describes and debunks some of the myths that surround the *BSD
	projects.</p></li>

	<li><p><a href="&base;/news/press.html">FreeBSD in the Press</a></p>

	<p>Contains many links to articles that have appeared which mention
	FreeBSD.</p></li>
	</ul>

	<h2>Sites using FreeBSD</h2>
	<ul>

	<li><a href="http://uptime.netcraft.com/perf/reports/Hosters"
	name="netcraft">Hosting Providers Performance</a> by Netcraft is
	tracking the reliability of major webhosting services, many of them
	are using FreeBSD.</li>

	<li><a href="http://dmoz.org/Computers/Software/Operating_Systems/Unix/BSD/FreeBSD/" name="dmoz">
	The Open Directory Project's</a> goal is to produce the most
	comprehensive directory of the web by relying on a vast army of
	volunteer editors.</li>

	<li>A brief list of sites using &os; is maintained
	<a href="&base;/handbook/nutshell.html#INTRODUCTION-NUTSHELL-USERS">
	in the handbook</a>.</li>

	</ul>

	<h2>FreeBSD conferences</h2>
	<ul>

	<li><a name="bsdcan" href="http://www.bsdcan.org/">BSDCan</a>, the
	annual BSD Conference held in Ottawa, Canada.</li>

	<li><a name="eurobsdcon" href="http://www.eurobsdcon.org/">EuroBSDCon</a>,
	the annual BSD Conference in Europe.</li>

	<li><a name="asiabsdcon" href="http://asiabsdcon.org/">AsiaBSDCon</a>,
	the annual BSD Conference held in Asia.</li>

	</ul>



	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/cgi/query-pr.cgi
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/cgi/query-pr.cgi (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/cgi/query-pr.cgi (revision 41355)
	@@ -1,901 +1,902 @@
	#!/usr/bin/perl -Tw
	#------------------------------------------------------------------------------
	# GNATS query-pr Interface, Generation III
	#
	# Copyright (C) 2006-2011, Shaun Amott <shaun@FreeBSD.org>
	# 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 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 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$
	#
	# Useful PRs for testing:
	#
	# - ports/147261 - RFC 2047 words, attachments, interjected e-mail (inc.
	# malformed header)
	# - ports/138672 - Lots of attachments, multi-level MIME.
	# - ports/132344 - Base64-encoded attachment.
	#
	# TODO:
	#
	# - Charset and transfer encoding transformation.
	# - Refine linkifier.
	# - Better end-of-diff detection.
	# - Inline patches inside MIME parts (probably just the first part).
	# - Modernise HTML (may require altering site-wide CSS)
	#------------------------------------------------------------------------------

	BEGIN { push @INC, '.'; }

	use CGI;

	use GnatsPR;
	use GnatsPR::SectionIterator;
	use GnatsPR::MIMEIterator;

	#use MIME::EncWords (decode_mimewords); # mail/p5-MIME-EncWords
	sub decode_mimewords { wantarray ? @_ : join ' ', @_; } # Temp. substitute for the above

	require './cgi-style.pl';
	require './query-pr-lib.pl';

	use strict;


	#------------------------------------------------------------------------------
	# Constants
	#------------------------------------------------------------------------------

	use constant EXIT_NOPRS => 1;
	use constant EXIT_DBBUSY => 2;
	use constant EXIT_NOPATCH => 3;


	#------------------------------------------------------------------------------
	# Globals
	#------------------------------------------------------------------------------

	our $valid_category = '[a-z0-9][A-Za-z0-9-_]{1,25}';
	our $valid_pr = '\d{1,8}';

	our $cvsweb_url = 'http://www.FreeBSD.org/cgi/cvsweb.cgi/';
	our $stylesheet = "$main::hsty_base/layout/css/query-pr.css";

	our $iscgi = defined $ENV{'SCRIPT_NAME'};

	# Keep this ahead of CGI

	if (!$iscgi && !exists $ENV{'REQUEST_METHOD'}) {
	# Makes debugging easier
	$ENV{'REQUEST_METHOD'} = 'GET';
	}

	# Stuff from cgi-style.pl

	$main::hsty_base \|\|= '';
	$main::t_style \|\|= '';
	$main::hsty_charset \|\|= '';

	$main::hsty_charset = 'utf-8';

	$main::t_style =
	qq{<link href="$stylesheet" rel="stylesheet" type="text/css" />
	<link rel="search" type="application/opensearchdescription+xml"
	href="http://www.freebsd.org/search/opensearch/query-pr.xml"
	title="FreeBSD Bugs" />
	};

	# Global CGI accessor

	our $q = new CGI;


	#------------------------------------------------------------------------------
	# Environment vars
	#------------------------------------------------------------------------------

	$ENV{'PATH'} = '/bin:/usr/bin:/usr/sbin:/sbin:/usr/local/bin';

	$ENV{'SCRIPT_NAME'} \|\|= $0;


	#------------------------------------------------------------------------------
	# Begin Code
	#------------------------------------------------------------------------------

	main();


	#------------------------------------------------------------------------------
	# Main routine
	#------------------------------------------------------------------------------

	sub main
	{
	my ($PR, $category, $rawdata, $gnatspr);

	binmode STDOUT, ':utf8';

	if ($q->param('pr')) {
	$PR = $q->param('pr');
	} elsif ($q->param('q')) {
	$PR = $q->param('q');
	} elsif ($q->param('prp')) {
	# Legacy param format
	my $prp = $q->param('prp');

	if ($prp =~ /^(\d+)-(\d+)/) {
	my $get = $2;
	$PR = $1;

	$q->param(-name => 'pr', -value => $PR);
	$q->param(-name => 'getpatch', -value => $get);
	} else {
	ErrorExit();
	}
	} else {
	ErrorExit(EXIT_NOPRS);
	}

	if ($PR =~ /^($valid_category)\/($valid_pr)$/) {
	$category = $1;
	$PR = $2;
	}

	length $PR > 0
	or ErrorExit();

	# category may be undef
	$rawdata = DoQueryPR($PR, $category);

	# Dump the raw PR data if requested
	if ($q->param('f') && $q->param('f') eq 'raw') {
	print "Content-type: text/plain; charset=UTF-8\r\n\r\n";
	print $$rawdata;
	Exit();
	}

	# Run PR text through the parser
	$gnatspr = GnatsPR->new($rawdata);

	# User is requesting a patch extraction?
	if ($q->param('getpatch')) {
	my ($patch, $patchnum);

	$patchnum = $q->param('getpatch');
	$patchnum =~ s/[^0-9]+//g;

	$patch = $gnatspr->GetAttachment($patchnum);

	defined $patch
	or ErrorExit(EXIT_NOPATCH);

	printf 'Content-type: %s; charset=UTF-8'."\r\n",
	($patch->isbinary ? 'application/octet-stream' : 'text/plain');

	printf 'Content-Length: %s'."\r\n"
	. 'Content-Disposition: inline; filename="%s"'."\r\n\r\n",
	$patch->size,
	$patch->filename;

	print $patch->data;
	+ print "\n";

	Exit();
	}

	# Otherwise, output PR

	PrintPR($gnatspr);

	Exit();
	}


	#------------------------------------------------------------------------------
	# Func: DoQueryPR()
	# Desc: Invoke the query-pr binary and return the results as a blob of text.
	# Exits gracefully on failure.
	#
	# Args: $PR - PR number
	# $cat - PR category (optional)
	#
	# Retn: \$data - Ref. to raw data.
	#------------------------------------------------------------------------------

	sub DoQueryPR
	{
	my ($PR, $cat) = @_;
	my ($data);

	$PR =~ s/[^0-9]+//g;
	$PR = quotemeta $PR;

	# Note: query-pr.web is just an anti DoS wrapper around query-pr which
	# makes sure we do not run too many query-pr instances at once.
	if (defined $cat) {
	$cat =~ s/[^0-9A-Za-z-]+//g;
	$cat = quotemeta $cat;
	$data = qx(query-pr.web --full --category=${cat} ${PR} 2>&1);
	} else {
	$data = qx(query-pr.web --full ${PR} 2>&1);
	}

	if (!$data or $data =~ /^query-pr(:?\.(:?real\|web))?: /) {
	ErrorExit(EXIT_NOPRS);
	} elsif ($data =~ /^lockf: /) {
	ErrorExit(EXIT_DBBUSY);
	}

	return \$data;
	}


	#------------------------------------------------------------------------------
	# Func: PrintPR()
	# Desc: Output the parsed PR.
	#
	# Args: $gnatspr - GnatsPR instance.
	#
	# Retn: n/a
	#------------------------------------------------------------------------------

	sub PrintPR
	{
	my ($gnatspr) = @_;

	# Page title

	print html_header(
	$q->escapeHTML(
	$gnatspr->FieldSingle('Category')
	. '/'
	. $gnatspr->FieldSingle('Number')
	. ': '
	. $gnatspr->FieldSingle('Synopsis')
	)
	);

	# Header stuff of interest

	print $q->start_table({-class => 'headtable'});

	foreach my $field ('From', 'Date', 'Subject') {
	my $val = $q->escapeHTML(
	scalar decode_mimewords($gnatspr->Header($field))
	);
	print $q->Tr(
	$q->td({-class => 'key'}, $field . ':'),
	$q->td({-class => 'val'}, $val)
	)
	}

	print $q->Tr(
	$q->td({-class => 'key'}, 'Send-pr version:'),
	$q->td({-class => 'val'}, $q->escapeHTML($gnatspr->Header('x-send-pr-version')))
	);

	print $q->end_table;

	# Single fields

	print $q->start_table({-class => 'headtable'});

	foreach my $field (
	'Number',
	'Category',
	'Synopsis',
	'Severity',
	'Priority',
	'Responsible',
	'State',
	'Class',
	'Arrival-Date',
	'Closed-Date',
	'Last-Modified',
	'Originator',
	'Release'
	) {
	my $val = $q->escapeHTML($gnatspr->FieldSingle($field));
	print $q->Tr(
	$q->td({-class => 'key'}, $field . ":"),
	$q->td({-class => 'val'}, $val)
	);
	}

	print $q->end_table;

	# Sections

	my $iter = GnatsPR::SectionIterator->new(
	$gnatspr,
	# Fields we want sections from; this also
	# dictates the order they will come.
	'Organization',
	'Environment',
	'Description',
	'How-To-Repeat',
	'Fix',
	'Release-Note',
	'Audit-Trail',
	'Unformatted'
	);

	my $replynum = 0;
	my $patchnum = 0;

	while (my $item = $iter->next()) {
	# Start of new field
	if (ref $item eq 'GnatsPR::Section::FieldStart') {
	my $text = $item->string();
	$text = $q->escapeHTML($text);
	#print $q->h2($text);
	print $q->table({-class => 'mfieldtable'},
	$q->Tr($q->td({-class => 'blkhead'}, $text)));
	next;
	}

	# A chunk of text
	if (ref $item eq 'GnatsPR::Section::Text') {
	my $text = $item->string();
	$text = $q->escapeHTML($text);
	$text = Linkify($text);
	$text = AddBreaks($text);

	# Table used to ensure text CSS consistency (evil, I know)
	print $q->table($q->tbody($q->Tr($q->td({class => 'mfield'}, $text))))
	if $text;
	#print $q->p($text);

	next;
	}

	# Patch block
	if (ref $item eq 'GnatsPR::Section::Patch') {
	my $text = $item->string();
	$text = $q->escapeHTML($text);
	$text = ColourPatch($text)
	if ($item->type eq 'diff');
	$text = AddBreaks($text); # Unless binary

	print AttachmentHeader($item->{filename}, ++$patchnum);
	print $text;
	print AttachmentFooter();

	next;
	}

	# Audit-Trail state/responsible change block
	if (ref $item eq 'GnatsPR::Section::StateChange') {
	# This must be hard-coded - the old value will still
	# linger in PRs, even if the script moves.
	my $selfurl = "http://www.freebsd.org/cgi/query-pr.cgi?pr="
	. $gnatspr->FieldSingle('Number');

	# Remove the URL, as it is merely clutter
	my $why = $item->why;
	$why =~ s/[\n\s]\Q$selfurl\E[\n\s]$//i;
	$item->why($why);

	print $q->table({-class => 'auditblock', -cellspacing => '1'},
	$q->Tr(
	$q->th(
	{-colspan => 2, -class => 'info'},
	$q->escapeHTML($item->what) . " Changed"
	)
	),

	$q->Tr(
	$q->td({-class => 'key'}, 'From-To:'),
	$q->td(
	$q->escapeHTML(
	$item->from . '->' . $item->to
	)
	)
	),

	$q->Tr(
	$q->td({-class => 'key'}, 'By:'),
	$q->td($q->escapeHTML($item->by))
	),

	$q->Tr(
	$q->td({-class => 'key'}, 'When:'),
	$q->td($q->escapeHTML($item->when))
	),

	$q->Tr(
	$q->td({-class => 'key'}, 'Why:'),
	AddBreaks($q->td($q->escapeHTML($item->why)))
	)
	);

	next;
	}

	# Reply via E-mail
	if (ref $item eq 'GnatsPR::Section::Email') {
	print $q->start_table({-class => 'replyblock',
	-cellspacing => '1'});

	$replynum++;

	print $q->Tr($q->th(
	{-colspan => 2, -class => 'info'},
	'Reply via E-mail '
	. $q->a({href => '#reply'.$replynum,
	name => 'reply'.$replynum}, '[Link]')
	));

	# Try to determine if sender is submitter

	my $fromtag = FromSubmitter($item, $gnatspr)
	? $q->b(' [submitter]') : '';

	# Print header

	foreach my $f ('From', 'To', 'Date') {
	print $q->Tr(
	$q->td({-class => 'key'}, $f . ':'),
	$q->td({-class => 'val'},
	$q->escapeHTML(
	scalar decode_mimewords($item->Header($f))
	)
	.
	(($f eq 'From') ? $fromtag : '')
	)
	);
	}

	print $q->start_Tr;
	print $q->start_td({-colspan => 2});

	# MIME parts

	my $mime_iter = GnatsPR::MIMEIterator->new($item);

	while (my $part = $mime_iter->next()) {
	my $ctype = $part->header('content-type');
	my $elide = 0;

	print $q->hr({-class => 'mimeboundary'})
	unless ($mime_iter->isfirst);

	$part->isattachment
	and ++$patchnum;

	# Skip (inline) HTML parts -- but only if we have
	# a plaintext part. We could possibly be a bit more
	# rigorous in verifying the existence of the latter,
	# but testing for the MIME header or other part will
	# suffice, as it is unlikely a HTML-only e-mail will
	# have more than that single part.
	if ($ctype eq 'text/html' && !$part->isattachment &&
	!$mime_iter->isfirst) {
	$elide = 1;

	# S/MIME signatures - of questionable value here
	} elsif ($ctype eq 'application/pkcs7-signature') {
	$elide = 1;
	}

	if ($elide) {
	if ($part->isattachment) {
	my $url = $q->url(-full => 1, -query => 1);

	my $dlink =
	$q->a({-href => $url . '&getpatch=' . $patchnum},
	'[Download]');

	print $q->div(
	{-class => 'elidemsg'},
	'Attachment of type "' . $q->escapeHTML($ctype)
	. '" ' . $dlink
	);
	} else {
	print $q->div(
	{-class => 'elidemsg'},
	'MIME part of type "' . $q->escapeHTML($ctype)
	. '" elided'
	);
	}

	next;
	}

	$part->isattachment
	and print AttachmentHeader($part->filename, $patchnum);

	if ($part->isbinary) { # Implies isattachment
	print $q->escapeHTML($part->body);
	} else {
	my $text;

	if ($part->header('content-type') eq 'text/plain'
	&& !$part->isattachment) {
	# ColourEmail escapes too
	$text = Linkify(ColourEmail($part->data));
	} else {
	$text = $q->escapeHTML($part->data);
	}

	if ($part->isattachment
	&& $part->filename =~ /\.(?:diff\|patch)\b/i) {
	$text = ColourPatch($text);
	}

	print AddBreaks($text);
	}

	$part->isattachment
	and print AttachmentFooter();
	}

	print $q->end_td;
	print $q->end_Tr;
	}

	print $q->end_table;
	}

	print FooterLinks($gnatspr);

	print html_footer();
	}


	#------------------------------------------------------------------------------
	# Func: AddBreaks()
	# Desc: Convert newlines to HTML break elements.
	#
	# Args: $text - Input
	#
	# Retn: $text - Output
	#------------------------------------------------------------------------------

	sub AddBreaks
	{
	my $text = shift;

	$text =~ s/\n/<br \/>/g;

	return $text;
	}


	#------------------------------------------------------------------------------
	# Func: Linkify()
	# Desc: Perform any fancy formatting on the message (e.g. HTML-ify URLs) and
	# return the result.
	#
	# Args: $html - Input string
	#
	# Retn: $html - Output string
	#------------------------------------------------------------------------------

	sub Linkify
	{
	my ($html) = @_;

	# XXX: clean up

	$html or return '';

	my $iv = 'A-Za-z0-9\-_\/#@\$=\\\\';

	my $scriptname = $q->escapeHTML($ENV{'SCRIPT_NAME'});

	# PR references
	$html =~
	s/(?<![$iv])($valid_category)\/($valid_pr)(?![$iv])/<a href="${scriptname}?pr=$2&cat=$1">$1\/$2<\/a>/g;

	# URLs
	$html =~
	s/((?:https?\|ftps?):\/\/[^\s\/]+\/[][\w=.,\'\~\?\!\&\/\%\$\{\}:;@#+-]*)/<a href="$1">$1<\/a>/g;

	# CVS files
	$html =~
	s/^RCS file: (\/home\/[A-Za-z0-9]+\/(.*?)),v$/RCS file: <a href="$cvsweb_url$2">$1<\/a>,v/mg;

	return $html;
	}


	#------------------------------------------------------------------------------
	# Func: ColourPatch()
	# Desc: Apply 'cdiff' style colours to a patch.
	#
	# Args: $html - Input string
	#
	# Retn: $html - Output string
	#------------------------------------------------------------------------------

	sub ColourPatch
	{
	my ($html) = @_;
	my $res = '';

	# XXX: clean up

	my $plus_s = $q->start_span({-class => 'patch_plusline'});
	my $minus_s = $q->start_span({-class => 'patch_minusline'});
	my $context_s = $q->start_span({-class => 'patch_contextline'});
	my $revinfo_s = $q->start_span({-class => 'patch_revinfo'});
	my $at_s = $q->start_span({-class => 'patch_hunkinfo'});
	my $all_e = $q->end_span;

	# Expand tabs
	while ($html =~ s/\t/" " x (8 - ((length($`)-1) % 8))/e) {};

	foreach my $line (split /\n/, $html) {
	$line =~ s/^(\+.*)$/${plus_s}$1${all_e}/o;
	$line =~ s/^(-.*)$/${minus_s}$1${all_e}/o
	if $line !~ s/^(--- \d+,\d+ ----.*)$/${revinfo_s}$1${all_e}/o;
	$line =~ s/^(\\\* \d+,\d+ \\\.*)$/${revinfo_s}$1${all_e}/o;
	$line =~ s/^(\\\\\\\\\\\\\\\*)$/${revinfo_s}$1${all_e}/o;
	$line =~ s/^(!.*)$/${context_s}$1${all_e}/o;
	$line =~ s/^(@@.*$)/${at_s}$1${all_e}/o;
	$line =~ s/^ / /;
	$res .= "$line\n";
	}

	$res =~ s/\n$//;

	return $res;
	}


	#------------------------------------------------------------------------------
	# Func: ColourEmail()
	# Desc: Colourise quoting levels in e-mails, and escape.
	#
	# Args: $email - Input string
	#
	# Retn: $email - Output string
	#------------------------------------------------------------------------------

	sub ColourEmail
	{
	my ($email) = @_;

	my $result = '';

	foreach my $line (split /\n/, $email) {
	if ($line =~ /^\s((?:>\s)+)(.*)$/) {
	my $levels = $1;
	my $text = $2;
	my $depth;

	$depth = $levels;
	$depth =~ s/[^>]+//g;
	$depth = length $depth;

	$levels =~ s/>/>/g;

	# Vim style rather than mutt

	$result .= $q->span({
	-class => 'quote' . ($depth % 2 ? 0 : 1)
	}, $levels . $q->escapeHTML($text));
	} else {
	$result .= $q->escapeHTML($line);
	}
	$result .= "\n";
	}

	return $result;
	}


	#------------------------------------------------------------------------------
	# Func: Exit()
	# Desc: Exit script.
	#
	# Args: n/a
	#
	# Retn: n/a
	#------------------------------------------------------------------------------

	sub Exit
	{
	# Introduce a short delay, as a DoS protection measure
	select undef, undef, undef, 0.35
	unless !$iscgi;

	exit;
	}


	#------------------------------------------------------------------------------
	# Func: ErrorExit()
	# Desc: Print an error message and exit.
	#
	# Args: $code - EXIT_* code
	#
	# Retn: n/a
	#------------------------------------------------------------------------------

	sub ErrorExit
	{
	my ($code) = @_;

	my $url = $q->url(-full => 1, -query => 1);

	if ($code == EXIT_NOPRS) {
	print html_header("No PRs Matched Query");
	displayform();
	print html_footer();
	} elsif ($code == EXIT_DBBUSY) {
	print html_header("PR Database Busy");
	print $q->p(
	'Please '
	. $q->a({-href => $url}, 'try again')
	. ' later'
	);
	print html_footer();
	} elsif ($code == EXIT_NOPATCH) {
	print "Content-type: text/plain; charset=UTF-8\r\n\r\n";
	print "No such patch!\n";
	}

	Exit();
	}


	#------------------------------------------------------------------------------
	# Func: FromSubmitter()
	# Desc: Try determine if the sender of a reply is the sender of the PR.
	#
	# Args: $item - GnatsPR::Section::Email instance.
	# $gnatspr - GnatsPR instance
	#
	# Retn: $result - Is sender the submitter?
	#------------------------------------------------------------------------------

	sub FromSubmitter
	{
	my ($item, $gnatspr) = @_;

	my $from = lc $item->Header('From');
	my $submitter = lc $gnatspr->Header('From');

	$from =~ s/^.<// and $from =~ s/>.$//;
	$from =~ s/\s+//g;
	$submitter =~ s/^.<// and $submitter =~ s/>.$//;
	$submitter =~ s/\s+//g;

	return $from eq $submitter;
	}


	#------------------------------------------------------------------------------
	# Func: AttachmentHeader()
	# Desc: Construct an attachment block header.
	#
	# Args: $filename - Name of attachment.
	# $patchnum - Patch index.
	#
	# Retn: $text - Header text.
	#------------------------------------------------------------------------------

	sub AttachmentHeader
	{
	my ($filename, $patchnum) = @_;

	my $text = '';

	my $url = $q->url(-full => 1, -query => 1);

	$text .= $q->start_table({-class => 'patchblock', -cellspacing => '1'});
	$text .=
	$q->Tr(
	$q->td({-class => 'info'}, $q->b(
	'Download ' . $q->a({-href => $url . '&getpatch=' . $patchnum},
	$filename)
	))
	);

	$text .= $q->start_tbody;
	$text .= $q->start_Tr;
	$text .= $q->start_td({-class => 'content'});
	$text .= $q->start_pre({-class => 'attachwin'});

	return $text;
	}


	#------------------------------------------------------------------------------
	# Func: AttachmentFooter()
	# Desc: Construct an attachment block footer.
	#
	# Args: n/a
	#
	# Retn: $text - Footer text.
	#------------------------------------------------------------------------------

	sub AttachmentFooter
	{
	my $text = '';

	$text .= $q->end_pre;
	$text .= $q->end_td;
	$text .= $q->end_Tr;
	$text .= $q->end_tbody;
	$text .= $q->end_table;

	return $text;
	}


	#------------------------------------------------------------------------------
	# Func: FooterLinks()
	# Desc: Construct the page footer links (for a valid PR page)
	#
	# Args: $gnatspr - GnatsPR instance.
	#
	# Retn: $text - Footer text.
	#------------------------------------------------------------------------------

	sub FooterLinks
	{
	my ($gnatspr) = @_;

	my $url = $q->url(-full => 1, -query => 1);

	my $pr = $q->escapeHTML($gnatspr->FieldSingle('Number'));
	my $cat = $q->escapeHTML($gnatspr->FieldSingle('Category'));
	my $synopsis = $q->escapeHTML($gnatspr->FieldSingle('Synopsis'));

	my $mail = $gnatspr->Header('From');

	# Try to extract just the e-mail address from the 'From' header
	if ($mail) {
	$mail =~ s/^\s(.)\s*$/$1/;
	$mail =~ s/.<(.)>.*/$1/;
	$mail =~ s/\s$.$\s*//;
	}

	my $replyto = $gnatspr->Header('Reply-To');

	# ... same with the 'Reply-To' header
	if ($replyto) {
	$replyto =~ s/^\s(.)\s*$/$1/;
	$replyto =~ s/.<(.)>.*/$1/;
	$replyto =~ s/\s$.$\s*//;
	}

	# Prefer 'Reply-To' if present
	$mail = $replyto if ($replyto);
	$mail .= '@FreeBSD.org' unless ($mail =~ /@/);

	# Prepare for mailto: link
	$synopsis =~ s/[^a-zA-Z+.@-]/"%" . sprintf("%02X", unpack("C", $&))/eg;
	$mail =~ s/[^a-zA-Z+.@-]/"%" . sprintf("%02X", unpack("C", $&))/eg;

	my $maillink = 'mailto:bug-followup@FreeBSD.org,'
	. "$mail?subject=Re:%20$cat/$pr:%20$synopsis";

	return $q->div({-class => 'footerlinks'},
	$q->a({-href => $maillink}, 'Submit Followup')
	. ' \| ' . $q->a({-href => $url . '&f=raw'}, 'Raw PR')
	. ' \| ' . $q->a({-href => 'query-pr-summary.cgi?query'}, 'Find another PR')
	);
	}
	Index: projects/entities/en_US.ISO8859-1/htdocs/developers/cvs.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/developers/cvs.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/developers/cvs.xml (revision 41355)
	@@ -1,63 +1,66 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "Source code repositories">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.developers">

	<h2>Subversion</h2>

	<p><a href="http://subversion.tigris.org/">Subversion</a>
	is the tool the &os; Project uses for keeping its sources
	under control. Every change (with an accompanying log message
	explaining its purpose) is stored. It can be
	easily viewed from the web interface mentioned below.</p>

	<p>In June 2008, development of the base system moved to a different
	version control system, <a href="http://subversion.tigris.org/">Subversion</a>
	(SVN for short). The <a href="http://svnweb.FreeBSD.org/base/">web
	- interface</a> is available for browsing the repository. All changes are
	- also exported back to the CVS repository.</p>
	+ interface</a> is available for browsing the repository. All changes
	+ to the existing live branches (stable/9 and stable/8) are
	+ also exported back to the legacy CVS repository, however the
	+ CVS repositories are deprecated, and so existing users of them
	+ should move away from doing so.</p>

	<p>In May 2012, the FreeBSD Documentation Project moved from CVS
	to Subversion. Unlike the base system, the documentation SVN
	repository is not exported back to CVS. There is a <a
	href="http://svnweb.FreeBSD.org/doc/">web interface</a>
	available for browsing the contents of the FreeBSD Documentation
	Project SVN repository.</p>

	<p>In July 2012, the FreeBSD Ports tree moved from CVS to
	- Subversion. There is a <a
	- href="http://svnweb.FreeBSD.org/ports/">web interface</a> for
	- browsing the repository. The Ports tree is also exported back
	- to the CVS repository.
	- It will cease to be exported early 2013.</p>
	+ Subversion. There is a <a
	+ href="http://svnweb.FreeBSD.org/ports/">web interface</a> for
	+ browsing the repository. The Ports tree is also exported back
	+ to the legacy CVS repository.
	+ It will cease to be exported early 2013.</p>


	<h2>Legacy - CVS</h2>

	<p><a href="http://www.FreeBSD.org/cgi/man.cgi?cvs">CVS</a> (the
	Concurrent Version System) was the tool that the
	&os; Project used to use to keep
	the sources under control.</p>

	<p>The old web interface can be accessed at <a
	- href="http://www.freebsd.org/cgi/cvsweb.cgi/">the cvsweb instance
	- </a>.</p>
	+ href="http://www.freebsd.org/cgi/cvsweb.cgi/">the cvsweb instance
	+ </a>.</p>

	<h2>Other options</h2>

	<p><a href="&base;/doc/en_US.ISO8859-1/books/handbook/ctm.html">
	- CTM</a> if you are looking for
	- very low overhead, batch-mode access (basically, patches through
	- email).</p>
	+ CTM</a> if you are looking for
	+ very low overhead, batch-mode access (basically, patches through
	+ email).</p>
	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/docs/books.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/docs/books.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/docs/books.xml (revision 41355)
	@@ -1,446 +1,441 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "Books and Articles Online">

	<!ENTITY url.articles "../doc/en_US.ISO8859-1/articles">
	<!ENTITY url.books "../doc/en_US.ISO8859-1/books">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.docs">

	<h2>On this site</h2>

	<p>All the documentation on this site can be downloaded in a variety of
	different formats (HTML, Postscript, PDF, and more) and compression
	schemes (BZip2, Zip) from the <a
	href="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP site</a>.</p>

	<p>Archived copies of the &os; documentation (articles,
	books, and textinfo manuals) are also available online at
	<a href="http://docs.FreeBSD.org/doc/">http://docs.FreeBSD.org/doc/</a>.</p>

	<p>This documentation is provided and maintained by the <a
	href="&base;/docproj/docproj.html">FreeBSD Documentation Project</a>, and we are
	always looking for people to contribute new documentation and maintain
	existing documentation.</p>

	<h3>Books</h3>

	<p><a href="&url.books;/dev-model/index.html">A project
	model for the FreeBSD project</a> (dev-model)<br/>
	A formal study of the organization of the FreeBSD project.</p>

	<p><a href="&url.books;/faq/index.html">The FreeBSD FAQ</a>
	(faq)<br/>
	Frequently Asked Questions, and answers, covering all
	aspects of FreeBSD.</p>

	<p><a href="&url.books;/handbook/index.html">The FreeBSD Handbook</a>
	(handbook)<br/>
	A constantly evolving, comprehensive resource for FreeBSD
	users.</p>

	<p><a href="&url.books;/developers-handbook/index.html">The
	FreeBSD Developers' Handbook</a> (developers-handbook)<br/>
	For people who want to develop software for FreeBSD (and not
	just people who are developing FreeBSD itself).</p>

	<p><a href="&url.books;/arch-handbook/index.html">The
	FreeBSD Architecture Handbook</a> (arch-handbook)<br/>
	For FreeBSD system developers. This book covers the
	architectural details of many important FreeBSD kernel
	subsystems.</p>

	<p><a href="&url.books;/porters-handbook/index.html">The Porter's
	Handbook</a> (porters-handbook)<br/>
	Essential reading if you plan on providing a port of a third
	party piece of software.</p>

	<p><a href="&url.books;/pmake/index.html">The PMake Tutorial</a>
	(pmake)<br/>
	A tutorial for the <em>make</em> utility. This book is essential
	reading for anyone who wants to understand all the details of using
	<em>make</em> of reading and writing makefiles.</p>

	<p><a href="&url.books;/design-44bsd/index.html">Chapter 2
	of "The Design and Implementation of the 4.4BSD Operating
	System"</a> (design-44bsd)<br/>
	Donated by Addison-Wesley, provides a design overview of 4.4BSD,
	from which FreeBSD was originally derived.</p>

	<p><a href="&url.books;/fdp-primer/index.html">The FreeBSD
	Documentation Project Primer for New Contributors</a>
	(fdp-primer)<br/>
	Everything you need to know in order to start contributing to the
	FreeBSD Documentation Project.</p>

	<a name="ARTICLES"></a><h3>Articles</h3>

	<!-- Articles are sorted by pathname -->

	<p><a href="&url.articles;/bsdl-gpl/index.html">Why you should use
	a BSD style license for your Open Source Project</a> (bsdl-gpl)<br/>
	Describes the benefits of releasing code under a BSD
	license.</p>

	<p><a href="&url.articles;/building-products/index.html">Building
	Products with FreeBSD</a> (building-products)<br/>
	How FreeBSD can help you build a better product.</p>

	<p><a href="&url.articles;/casestudy-argentina.com/index.html">Argentina.com : A Case Study</a> (casestudy-argentina.com)<br/>
	How FreeBSD helped a large ISP in Latin America.</p>

	<p><a href="&url.articles;/committers-guide/index.html">The
	Committer's Guide</a> (committers-guide)<br/>
	Introductory information for FreeBSD committers.</p>

	<p><a href="&url.articles;/compiz-fusion/index.html">Installing
	and using Compiz Fusion</a> (compiz-fusion)<br/>
	How to install and use the Compiz Fusion composite window
	manager under FreeBSD.</p>

	<p><a href="&url.articles;/console-server/index.html">Console
	Server Tutorial</a> (console-server)<br/>
	How to setup a FreeBSD based console server with a cheap
	multi-port serial card.</p>

	<p><a href="&url.articles;/contributing/index.html">Contributing
	to FreeBSD</a> (contributing)<br/>
	How to contribute to the FreeBSD Project.</p>

	<p><a href="&url.articles;/contributing-ports/index.html">
	Contributing to the FreeBSD Ports Collection</a>
	(contributing-ports)<br/>
	How to help maintain the FreeBSD Ports Collection.</p>

	<p><a href="&url.articles;/contributors/index.html">The
	List of FreeBSD Contributors</a> (contributors)<br/>
	A list of organizations and individuals who have helped
	enhance FreeBSD.</p>

	<p><a href="&url.articles;/cups/index.html">CUPS on &os;</a>
	(cups)<br/>
	How to setup CUPS with &os;.</p>

	<p><a href="&url.articles;/custom-gcc/index.html">Using
	newer version of GCC and binutils with the &os; Ports
	Collection</a> (custom-gcc)<br/>
	How to use newer versions of the GCC compilers and
	binutils from the &os; ports tree. Custom GCC
	are also discussed.</p>

	<p><a href="&url.articles;/cvs-freebsd/index.html">Setting up a
	CVS repository - The FreeBSD way</a> (cvs-freebsd)<br/>
	How to set up a CVS repository that uses the same CVSROOT
	infrastructure as the FreeBSD project.</p>

	<p><a href="&url.articles;/cvsup-advanced/index.html">CVSup
	Advanced Points</a> (cvsup-advanced)<br/>
	An article with some tips about the subtleties of
	CVSup.</p>

	- <p><a href="&url.articles;/euro/index.html">The Euro symbol
	- on FreeBSD</a> (euro)<br/>
	- How to configure FreeBSD and related applications to display the
	- Euro symbol.</p>
	-
	<p><a href="&url.articles;/explaining-bsd/index.html">Explaining
	BSD</a> (explaining-bsd)<br/>
	An answer to the question ``What is BSD?''</p>

	<p><a href="&url.articles;/fbsd-from-scratch/index.html">FreeBSD
	From Scratch</a> (fbsd-from-scratch)<br/>
	How to automatically compile, install and configure a system from
	scratch (i.e. to an empty file system), including your favorite
	ports.</p>

	<p><a href="&url.articles;/filtering-bridges/index.html">Filtering
	Bridges</a> (filtering-bridges)<br/>
	Configuring firewalls and filtering on FreeBSD hosts acting as
	bridges rather than routers.</p>

	<p><a href="&url.articles;/fonts/index.html">Fonts and
	FreeBSD</a> (fonts)<br/>
	A description of the various font technologies in FreeBSD, and
	how to use them with different programs.</p>

	<p><a href="&url.articles;/freebsd-questions/index.html">How
	to get the best results from the FreeBSD-questions mailing list</a>
	(freebsd-questions)<br/>
	Tips and tricks to help you maximize the chances of getting
	useful information from the -questions mailing list.</p>

	<p><a href="&url.articles;/freebsd-update-server/index.html">Build
	Your Own FreeBSD Update Server</a>
	(freebsd-update-server)<br/>
	Using a FreeBSD Update server allows a system
	administrator to perform fast updates for a number of
	machines from a local mirror.</p>

	<p><a href="&url.articles;/geom-class/index.html">Writing
	a GEOM Class</a> (geom-class)<br/>
	A guide to GEOM internals, and writing your own class.</p>

	<p><a href="&url.articles;/gjournal-desktop/index.html">Implementing
	UFS journaling on a desktop PC</a> (gjournal-desktop)<br/>
	A guide to create UFS partitions configured with journaling
	for desktop use.</p>

	<p><a href="&url.articles;/hubs/index.html">Mirroring FreeBSD</a>
	(hubs)
	<br/>The all in one guide for mirroring the FreeBSD website,
	CVSup servers, FTP servers, and more.</p>

	<p><a href="&url.articles;/ipsec-must/index.html">Independent
	Verification of IPsec Functionality in FreeBSD</a>
	(ipsec-must)<br/>
	A method for experimentally verifying IPsec
	functionality.</p>

	<p><a href="&url.articles;/laptop/index.html">FreeBSD on Laptops</a>
	(laptop)<br/>
	Information about running FreeBSD on a laptop.</p>

	<p><a href="&url.articles;/ldap-auth/index.html">LDAP Authentication</a>
	(ldap-auth)<br/>
	A practical guide about setting up an LDAP server on
	&os; and how to use it for authenticating users.</p>

	<p><a href="&url.articles;/linux-comparison/index.html">FreeBSD: An Open Source Alternative to Linux</a>
	(linux-comparison)<br/>
	A white paper explaining the differences between Linux
	and FreeBSD.</p>

	<p><a href="&url.articles;/linux-emulation/index.html">Linux emulation in &os;</a>
	(linux-emulation)<br/>
	A technical description about the internals of the Linux
	emulation layer in &os;.</p>

	<p><a href="&url.articles;/linux-users/index.html">&os; Quickstart Guide for Linux Users</a>
	(linux-users)<br/>
	An introductionary guide for the users that came from Linux.</p>

	<p><a href="&url.articles;/mailing-list-faq/index.html">Frequently
	Asked Questions About The FreeBSD Mailing Lists</a>
	(mailing-list-faq)<br/>
	How to best use the mailing lists, such as how to help
	avoid frequently-repeated discussions.</p>

	<p><a href="&url.articles;/mh/index.html">An MH Primer</a>
	(mh)<br/>
	An introduction to using the MH mail reader on
	FreeBSD.</p>

	<p><a href="&url.articles;/nanobsd/index.html">Introduction
	to NanoBSD</a> (nanobsd)<br/>
	Information about the NanoBSD tools, which can be used to
	create FreeBSD system images for embedded applications,
	suitable for use on a Compact Flash card (or other mass
	storage medium).</p>

	<p><a href="&url.articles;/new-users/index.html">FreeBSD
	First Steps</a> (new-users)<br/>
	For people coming to FreeBSD and &unix; for the first
	time.</p>

	<p><a href="&url.articles;/p4-primer/index.html">Perforce
	in FreeBSD Development</a> (p4-primer)<br/>
	A guide to the Perforce version control system. It also
	describes how to manage experimental projects with the
	FreeBSD Perforce server.</p>

	<p><a href="&url.articles;/pam/index.html">Pluggable
	Authentication Modules</a> (pam)<br/>
	A guide to the PAM system and modules under
	FreeBSD.</p>

	<p><a href="&url.articles;/portbuild/index.html">Package
	building procedures</a> (portbuild)<br/>
	Describes the approach used by the FreeBSD port
	manager team to regularly build ports into packages.
	It describes the portbuild cluster, as well as the tools
	needed to do incremental, experimental, and official release
	package builds.</p>

	<p><a href="&url.articles;/pr-guidelines/index.html">FreeBSD
	Problem Report Handling Guidelines</a> (pr-guidelines)<br/>
	Recommended practices for handling FreeBSD problem
	reports.</p>

	<p><a href="&url.articles;/problem-reports/index.html">Writing
	FreeBSD Problem Reports</a> (problem-reports)<br/>
	How to best formulate and submit a problem report to the
	FreeBSD Project.</p>

	<p><a href="&url.articles;/pxe/index.html">PXE booting
	FreeBSD</a> (pxe)<br/>
	How to create an Intel PXE server using FreeBSD, and how to
	configure a FreeBSD client to boot from a PXE server.</p>

	<p><a href="&url.articles;/rc-scripting/index.html">Practical
	rc.d scripting in BSD</a> (rc-scripting)<br/>
	A guide to writing new rc.d scripts and understanding those
	already written.</p>

	<p><a href="&url.articles;/relaydelay/index.html">FreeBSD as
	a greylist mail server</a> (relaydelay)<br/>
	Implementing a greylist mail server on FreeBSD
	using Sendmail, MySQL, Perl and the relaydelay
	software. This is an excellent method to use in the
	fight against spam.</p>

	<p><a href="&url.articles;/releng/index.html">FreeBSD
	Release Engineering</a> (releng)<br/>
	Describes the approach used by the FreeBSD release
	engineering team to make production quality releases of the
	FreeBSD Operating System. It describes the tools available
	for those interested in producing customized FreeBSD releases
	for corporate rollouts or commercial productization.</p>

	<p><a href="&url.articles;/releng-packages/index.html">FreeBSD
	Release Engineering for Third Party Packages</a>
	(releng-packages)<br/>
	Describes the approach used by the FreeBSD
	ports management 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 "Ports
	Cluster", 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.</p>

	<p><a href="&url.articles;/remote-install/index.html">Remote
	Installation of the &os; Operating System without a
	Remote Console</a> (remote-install)<br/>
	Describes the remote installation of the &os; operating
	system when the console of the remote system is
	unavailable.</p>

	<p><a href="&url.articles;/serial-uart/index.html">Serial
	and UART devices</a> (serial-uart)<br/>
	Detailed information about the use of serial ports on FreeBSD,
	including several multi-port serial cards.</p>

	<p><a href="&url.articles;/solid-state/index.html">FreeBSD
	and Solid State Devices</a> (solid-state)<br/>
	The use of solid state disk devices in FreeBSD.</p>

	<p><a href="&url.articles;/vm-design/index.html">Design
	elements of the FreeBSD VM system</a> (vm-design)<br/>
	An easy to follow description of the design of the FreeBSD
	virtual memory system.</p>

	<h2>On other web sites</h2>

	<p>Various independent efforts have also produced a great deal of useful
	information about FreeBSD.</p>

	<h3>Articles</h3>

	<ul>
	<li>
	<p>Niels Jorgensen has authored an academic study on the
	dynamics of the FreeBSD development process: <a
	href="http://www.ruc.dk/~nielsj/research/publications/freebsd.pdf">
	``Putting it All in the Trunk, Incremental Software
	Development in the FreeBSD Open Source Project''</a>
	[Information Systems Journal (2001) 11, 321-336].</p>
	</li>

	<li>
	<p><a href="mailto:mckusick@mckusick.com">Kirk McKusick</a>, one
	of the original architects of BSD at U.C. Berkeley, teaches two <a
	href="http://www.mckusick.com/courses/">4.4BSD Kernel
	Internals</a> courses using FreeBSD. For those unable to attend
	the courses in person, a video tape series is also now
	available.</p>
	</li>

	<li>
	<p><a href="http://flag.blackened.net/freebsd/">FreeBSD How-To's for
	the Lazy and Hopeless</a> is another somewhat more light-hearted
	attempt to provide more readable "how-to" style information on
	setting up and configuring FreeBSD.</p>
	</li>

	<li>
	<p><a href="http://www.tldp.org/HOWTO/Linux+FreeBSD.html">The
	Linux+FreeBSD mini-HOWTO</a> describes how to use
	Linux and FreeBSD on the same system. It introduces FreeBSD and
	discusses how the two operating systems can cooperate, e.g. by
	sharing swap space.</p>
	</li>

	<li>
	<p><a href="http://www.nber.org/amd.html">Getting started with AMD on
	FreeBSD</a></p>
	</li>
	<!--
	<li>
	<p><a href="http://ezine.daemonnews.org/200010/blueprints.html">Dynamic
	Kernel Linker (KLD) Facility Programming Tutorial</a>.</p>
	</li>

	<li>
	<p><a href="http://ezine.daemonnews.org/200007/newbus-intro.html">How to
	Write Kernel Drivers with Newbus</a>.</p>
	</li>
	-->
	<li>
	<p><em>Writing an ISA device driver</em>. This document has been
	imported into <a
	href="&url.books;/arch-handbook/index.html">The FreeBSD
	Architecture Handbook</a>.</p>
	</li>

	<li>
	<p><em>FreeBSD Assembly Language Programming Tutorial</em>. This
	document has been imported into <a
	href="&url.books;/developers-handbook/index.html">The FreeBSD
	Developer's Handbook</a>.</p>
	</li>

	<li>
	- <p><a href="http://software.intel.com/sites/oss/pdfs/profiling_debugging_freebsd_kernel_321772.pdf">Profiling
	+ <p><a href="http://software.intel.com/sites/default/files/profiling_debugging_freebsd_kernel_321772.pdf">Profiling
	and Debugging the FreeBSD Kernel</a></p>
	</li>

	<li>
	- <p><a href="http://software.intel.com/sites/oss/pdfs/debugging_buffer_overruns_322486.pdf">Debugging
	+ <p><a href="http://software.intel.com/sites/default/files/debugging_buffer_overruns_322486.pdf">Debugging
	Buffer Overruns in the FreeBSD Kernel</a></p>
	</li>

	<li>
	<p><a href="http://www.cfcl.com/rdm/split_DNS.html">Setting up
	Split DNS on FreeBSD 4.1</a></p>
	</li>

	<li>
	<p><a href="http://people.FreeBSD.org/~fsmp/SMP/SMP.html">The
	SMP support page</a> contains information on the SMP support
	in FreeBSD 4.X and earlier.</p>
	</li>

	<li>
	<p>Appendix A from the college textbook
	<i>Operating Systems Concepts</i> by Silberschatz, Galvin and
	Gagne has been made available online in
	<a href="http://www.wiley.com/college/silberschatz6e/0471417432/pdf/bsd.pdf">PDF format</a>.
	The appendix is dedicated to FreeBSD and offers a good
	introduction to FreeBSD's internals.</p>
	</li>

	</ul>


	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/features.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/features.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/features.xml (revision 41355)
	@@ -1,132 +1,139 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "About FreeBSD's Technological Advances">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.about">

	<h1>&os; offers many unique features.</h1>

	<p>No matter what the application, an operating system should take
	advantage of every resource available. &os;'s focus on
	performance, networking, and storage combines with ease of system
	administration and comprehensive documentation to realize the full
	potential of any computer.</p>

	<h2>A complete operating system based on 4.4BSD.</h2>

	<p>&os;'s distinguished roots derive from the <b>BSD</b>
	software releases from the Computer Systems Research Group at
	the University of California, Berkeley. Over twenty years of
	work have been put into enhancing &os;, adding
	industry-leading scalability, network performance, management
	tools, file systems, and security features. As a result,
	&os; may be found across the Internet, in the operating system
	of core router products, running root name servers, hosting
	major web sites, and as the foundation for widely used desktop
	operating systems. This is only possible because of the
	diverse and world-wide membership of the
	volunteer &os; Project.</p>

	<p><b>&os; 9.0</b>, brings many new features
	and performance enhancements with a special focus on desktop
	support and security features.</p>

	<ul>
	<li><b>Capsicum Capability Mode</b>:
	Capsicum is a set of features for sandboxing support, using
	a capability model in which the capabilities are file
	descriptors. Two new kernel options CAPABILITIES and
	CAPABILITY_MODE have been added to the GENERIC kernel.</li>

	<li><b>Hhook</b>: (Helper Hook) and khelp(9) (Kernel Helpers)
	KPIs have been implemented. These are a superset of
	pfil(9) framework for more general use in the kernel. The
	hhook(9) KPI provides a way for kernel subsystems to export
	hook points that khelp(9) modules can hook to provide
	enhanced or new functionality to the kernel. The khelp(9)
	KPI provides a framework for managing khelp(9) modules,
	which indirectly use the hhook(9) KPI to register their hook
	functions with hook points of interest within the kernel.
	These allow a structured way to dynamically extend the
	kernel at runtime in an ABI preserving manner.</li>
	+
	<li><b>Accounting API:</b> has been implemented. It can keep
	per-process, per-jail, and per-login class resource
	accounting information. Note that this is neither built nor
	installed by default. To build and install this, specify
	options RACCT in the kernel configuration file and rebuild
	the base system as described in the FreeBSD Handbook</li>

	<li><b>Resource-limiting API:</b> has been implemented.
	It works in conjunction with the RACCT resource accounting
	implementation and takes user-configurable actions based on
	the set of rules it maintains and the current resource
	usage. The rctl(8) utility has been added to manage the
	rules in userland. Note that this is neither built nor
	installed by default.</li>

	<li><b>Usb:</b> subsystem now supports USB packet filter.
	This allows capturing packets which go through each USB
	host rchitecture of the packet filter is similar to that of
	bpf. The userland program usbdump(8) has been
	added.</li>

	<li><b>Infiniband support:</b>, OFED (OpenFabrics Enterprise
	Distribution) version 1.5.3 has been imported into the
	base system.</li>

	<li><b>TCP/IP network:</b> stack now supports the mod_cc(9)
	pluggable congestion control framework. This allows TCP
	congestion control algorithms to be implemented as
	dynamically loadable kernel modules. Many kernel
	modules are available: cc_chd(4) for the CAIA-Hamilton-Delay
	algorithm, cc_cubic(4) for the CUBIC algorithm, cc_hd(4)
	for the Hamilton-Delay algorithm, cc_htcp(4) for the H-TCP
	algorithm, cc_newreno(4) for the NewReno algorithm, and
	cc_vegas(4) for the Vegas algorithm. The default algorithm
	can be set by a new sysctl(8) variable
	net.inet.tcp.cc.algorithm.</li>

	<li><b>SU+J:</b> &os;'s Fast File System now supports soft
	- updates with journaling. It introduces an intent log into a
	- softupdates-enabled file system which eliminates the need for
	- background fsck(8) even on unclean shutdowns.</li>
	+ updates with journaling. It introduces an intent log into
	+ a softupdates-enabled file system which eliminates the need
	+ for background fsck(8) even on unclean shutdowns.</li>
	</ul>

	- <p><b>&os; 8.x</b> brings many new
	+ <p><b>&os; 8.x</b> brought many new
	features and performance enhancements. With special focus on
	- a new USB stack, &os;-8.x shipped with experimental support
	- for NFSv4. As well as a new TTY layer. Which improves
	+ a new USB stack, &os;-8.x also shipped with experimental support
	+ for NFSv4. A new TTY layer was introduced, which improves
	scalability and resources handling in SMP enabled systems.</p>

	<ul>
	<li><b>Netisr framework:</b> has been reimplemented for
	parallel threading support. This is a kernel network
	dispatch interface which allows device drivers (and other
	packet sources) to direct packets to protocols for directly
	dispatched or deferred processing. The new implementation
	supports up to one netisr thread per CPU, and several
	benchmarks on SMP machines show substantial performance
	improvement over the previous version.</li>
	+
	+ <li><b>Jail improvements:</b> Jails now support multiple IPv4
	+ and IPv6 addresses per jail, and also support SCTP.
	+ Hierarchies of jails (jails-within-jails) are now supported,
	+ and jails can now be restricted to subsets of available
	+ CPUs.</li>

	<li><b>Linux emulation:</b> layer has been updated to version
	2.6.16 and the default Linux infrastructure port is now
	emulators/linux_base-f10 (Fedora 10)</li>

	<li><b>Network Virtualization:</b> A container ("vimage") has
	been implemented, extending the FreeBSD kernel to maintain
	multiple independent instances of networking state.
	Vimage facilities can be used independently to create fully
	virtualized network topologies, and jail(8) can directly
	take advantage of a fully virtualized network stack.</li>
	</ul>
	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/gnome/index.xsl
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/gnome/index.xsl (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/gnome/index.xsl (revision 41355)
	@@ -1,176 +1,176 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE xsl:stylesheet PUBLIC "-//FreeBSD//DTD FreeBSD XSLT 1.0 DTD//EN"
	"http://www.FreeBSD.org/XML/www/share/xml/xslt10-freebsd.dtd" [
	<!ENTITY base "..">
	<!ENTITY title "The FreeBSD GNOME Project">
	]>
	<!-- $FreeBSD$ -->

	<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
	xmlns:rdf1="http://my.netscape.com/rdf/simple/0.9/"
	xmlns="http://www.w3.org/1999/xhtml"
	exclude-result-prefixes="rdf rdf1" version="1.0">

	<xsl:import href="http://www.FreeBSD.org/XML/www/lang/share/xml/libcommon.xsl"/>
	<xsl:import href="http://www.FreeBSD.org/XML/www/share/xml/xhtml.xsl"/>

	<xsl:variable name="title">&title;</xsl:variable>

	<xsl:template name="process.content">
	<div id="sidewrap">
	&nav.gnome;
	</div> <!-- SIDEWRAP -->

	<div id="contentwrap">
	<div id="rightwrap">
	<div class="rightnav">

	<h2>FreeBSD GNOME News</h2>

	<p>Latest update:
	<xsl:value-of
	select="descendant::month[position() = 1]/name"/>
	<xsl:text> </xsl:text>
	<xsl:value-of
	select="descendant::day[position() = 1]/name"/>,
	<xsl:text> </xsl:text>
	<xsl:value-of
	select="descendant::year[position() = 1]/name"/></p>
	<ul>

	<!-- Pull in the 10 most recent news items -->
	<xsl:for-each select="descendant::event[position() <= 10]">
	<li><a>
	<xsl:attribute name="href">
	newsflash.html#<xsl:call-template name="generate-event-anchor"/>
	</xsl:attribute>
	<xsl:choose>
	<xsl:when test="count(child::title)">
	<xsl:value-of select="title"/><br/>
	</xsl:when>
	<xsl:otherwise>
	<xsl:apply-templates select="p" mode="copy.html"/><br/>
	</xsl:otherwise>
	</xsl:choose>
	</a></li>
	</xsl:for-each>
	<li><a href="newsflash.html">More...</a></li>
	</ul>
	</div> <!-- rightnav -->

	<br />

	<div class="rightnav">

	<h2>GNOME Project News</h2>
	<!-- XXX: (1) does not work at the moment
	(2) should we really copy over GNOME news?

	<ul>
	<xsl:for-each select="document('http://gnomedesktop.org/node/feed')/rss/channel/*[name() = 'item'][position() < 10]">
	<li><a>
	<xsl:attribute name="href">
	<xsl:value-of select="link"/>
	</xsl:attribute>
	<xsl:value-of select="title"/><br/>
	</a></li>
	</xsl:for-each>
	<li><a>
	<xsl:for-each select="document('http://gnomedesktop.org/backend.php')/rss/*[name() = 'channel'][position() = 1]">
	<xsl:attribute name="href">
	<xsl:value-of select="link"/>
	</xsl:attribute>More...
	</xsl:for-each>
	</a></li>
	</ul>
	-->
	</div> <!-- rightnav -->
	</div> <!-- rightwrap -->

	<h1>&title;</h1>

	<h2>What is GNOME?</h2>

	<img src="&base;/gnome/images/gnome.png" align="right"
	border="0" alt="GNOME Logo"/>

	<p>GNOME is a complete graphical desktop for X,
	including everything from a window manager to
	web browsers, audio players, office programs, and
	more.</p>

	<p>The FreeBSD GNOME Project is a team of devoted
	developers and users that manage the
	integration of GNOME and FreeBSD.</p>

	<h2>How to install GNOME</h2>

	<p>The easiest way to install GNOME is to install either of
	the following ports:</p>
	<ul>
	<li>x11/gnome2 (the full desktop)</li>
	<li>x11/gnome2-lite (the minimum desktop environment)</li>
	</ul>

	<p>And, as desired, one or all of:</p>
	<ul>
	<li>x11/gnome2-fifth-toe (common applications)</li>
	<li>x11/gnome2-power-tools (tools/toys for power users)</li>
	<li>editors/gnome2-office (office productivity)</li>
	<li>devel/gnome2-hacker-tools (development tools)</li>
	</ul>

	<h2>Upgrading to GNOME 2.32?</h2>

	<p>If you are upgrading from GNOME 2.30 to GNOME 2.32, read the
	<a href="docs/faq232.html">Upgrade FAQ</a> for upgrade
	instructions.</p>

	<h2>State of the port</h2>

	<p>GNOME for FreeBSD is currently fully supported on
	- 8.1, 8.2, 8-STABLE, 9.0, and 9-STABLE, while 7.3, 7.4, 7-STABLE,
	- and 10.0-CURRENT are provided on a best effort basis.
	+ 8.3, 8-STABLE, 9.0, 9.1, and 9-STABLE, while
	+ 10.0-CURRENT is provided on a best effort basis.
	Most of GNOME has been ported to FreeBSD, but there is still
	<a href="docs/volunteer.html">plenty left to be done</a>!</p>

	<h2>One stop solution shop!</h2>

	<p>GNOME is simple and easy to build using the FreeBSD ports system, but
	sometimes things simply go wrong. If GNOME -- or anything that uses
	GNOME libraries -- is not building the way it should, simply run the
	<a href="/gnome/gnomelogalyzer.sh">gnomelogalyzer.sh</a>
	tool from the directory of the failed port, and let the gnomelogalyzer
	figure out what's wrong and how to fix it!</p>

	<h2>Resources</h2>
	<ul>
	<li><a href="http://www.gnome.org/">GNOME Project</a></li>
	<li><a href="http://developer.gnome.org">GNOME development platform</a></li>
	<li><a href="http://gnomedesktop.org">FootNotes</a></li>
	<li><a href="http://www.gnomejournal.org">GNOME Journal</a></li>
	<li><a href="http://www.gnomefiles.org">GNOME Files</a></li>
	<li><a href="http://planet.gnome.org">Planet GNOME (blogs)</a></li>
	</ul>

	<h2>Related Projects</h2>
	<ul>
	<li><a href="http://www.kde.org/">KDE Project</a></li>
	<li><a href="http://freebsd.kde.org/">KDE on FreeBSD</a></li>
	<li><a href="http://www.opengroup.org/desktop/">CDE (commercial)</a></li>
	</ul>

	<a id="search" name="search"></a>
	<form action="http://freebsd.rambler.ru/srch" method="get">
	<p>Search the freebsd-gnome mailing list archives:</p>
	<input type="text" name="words" size="25"/>
	<input type="hidden" name="rubric" value="122" />
	<input type="submit" value="Search"/>
	</form>

	</div> <!-- contentwrap -->

	<br class="clearboth" />
	</xsl:template>
	</xsl:stylesheet>
	Index: projects/entities/en_US.ISO8859-1/htdocs/index.xsl
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/index.xsl (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/index.xsl (revision 41355)
	@@ -1,324 +1,324 @@
	<?xml version="1.0" encoding="iso-8859-1" ?>
	<!DOCTYPE xsl:stylesheet PUBLIC "-//FreeBSD//DTD FreeBSD XSLT 1.0 DTD//EN"
	"http://www.FreeBSD.org/XML/www/share/xml/xslt10-freebsd.dtd" [
	<!ENTITY title "The FreeBSD Project">
	]>

	<!-- $FreeBSD$ -->

	<xsl:stylesheet version="1.0"
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns="http://www.w3.org/1999/xhtml">

	<xsl:import href="http://www.FreeBSD.org/XML/www/lang/share/xml/libcommon.xsl"/>
	<xsl:import href="http://www.FreeBSD.org/XML/www/share/xml/xhtml.xsl"/>

	<!-- these params should be externally bound. The values
	here are not used actually -->
	<xsl:param name="advisories.xml" select="'none'"/>
	<xsl:param name="notices.xml" select="'none'"/>
	<xsl:param name="mirrors.xml" select="'none'"/>
	<xsl:param name="news.press.xml-master" select="'none'"/>
	<xsl:param name="news.press.xml" select="'none'"/>
	<xsl:param name="news.project.xml-master" select="'none'"/>
	<xsl:param name="news.project.xml" select="'none'"/>
	<xsl:param name="events.xml-master" select="'none'"/>
	<xsl:param name="events.xml" select="'none'"/>
	<xsl:param name="html.header.script.google" select="'IGNORE'"/>

	<xsl:variable name="title">&title;</xsl:variable>

	<xsl:template name="process.content">
	<div id="frontcontainer">
	<div id="frontmain">
	<div id="frontfeaturecontainer">

	<div id="frontfeatureleft">
	<div id="frontfeaturecontent">
	<h1>
	Based on BSD &unix;
	</h1>

	<p>FreeBSD® is an advanced
	operating system for modern server,
	desktop, and embedded computer <a
	href="&base;/platforms/">platforms</a>.
	FreeBSD's code base has undergone
	over thirty years of continuous
	development, improvement, and
	optimization. It is developed and
	maintained by a <a
	href="&base;/doc/en_US.ISO8859-1/articles/contributors/staff-committers.html">large
	team of individuals</a>. FreeBSD
	provides advanced networking,
	impressive security features, and
	world class performance and is used
	by some of the world's <a
	href="&base;/doc/en_US.ISO8859-1/books/handbook/nutshell.html#introduction-nutshell-users">busiest
	web sites</a> and most pervasive
	embedded networking and storage
	devices.</p>

	<div
	id="txtfrontfeaturelink"> »<a
	href="&base;/about.html"
	title="Learn More">Learn More</a>
	</div> <!-- TXTFRONTFEATURELINK -->

	</div> <!-- FRONTFEATURECONTENT -->
	</div> <!-- FRONTFEATURELEFT -->

	<div id="frontfeaturemiddle">
	<div class="frontgetroundbox">
	<div class="frontgettop"><div><b style="display: none">.</b></div></div>
	<div class="frontgetcontent">
	<a href="&base;/where.html">Get FreeBSD Now</a>
	</div> <!-- frontgetcontent -->
	<div class="frontgetbot"><div><b style="display: none">.</b></div></div>
	</div> <!-- frontgetroundbox -->

	<div id="frontreleases">
	<div id="frontreleasescontent" class="txtshortcuts">
	<h2><a href="&base;/releases/">LATEST RELEASES</a></h2>
	<ul id="frontreleaseslist">
	<li>Production: <a
	- href="&u.rel.announce;">&rel.current;</a>, <a href="&u.rel2.announce;">&rel2.current;</a></li>
	+ href="&u.rel.announce;">&rel.current;</a></li>
	<li>Legacy: <a
	- href="&u.rel3.announce;">&rel3.current;</a></li>
	+ href="&u.rel2.announce;">&rel2.current;</a></li>
	<xsl:if test="'&beta.testing;' != 'IGNORE'">
	<li>Upcoming: <a
	href="&base;/where.html#helptest">&betarel.current;-&betarel.vers;</a></li>
	</xsl:if>
	<xsl:if test="'&beta2.testing;' != 'IGNORE'">
	<li>Upcoming: <a
	href="&base;/where.html#helptest">&betarel2.current;-&betarel2.vers;</a></li>
	</xsl:if>
	</ul>
	</div> <!-- FRONTRELEASESCONTENT -->
	</div> <!-- FRONTRELEASES -->
	</div> <!-- FRONTFEATUREMIDDLE -->

	<div id="frontfeatureright">
	<h2 class="blockhide">Language Links</h2>
	<div id="languagenav">
	<ul id="languagenavlist">
	<li>
	<a href="&base;/de/" title="German">de</a>
	</li>
	<li>
	<a href="&base;/" title="English">en</a>
	</li>
	<li>
	<a href="&base;/es/" title="Spanish">es</a>
	</li>
	<li>
	<a href="&base;/fr/" title="French">fr</a>
	</li>
	<li>
	<a href="&base;/hu/" title="Hungarian">hu</a>
	</li>
	<li>
	<a href="&base;/it/" title="Italian">it</a>
	</li>
	<li>
	<a href="&base;/ja/" title="Japanese">ja</a>
	</li>
	<li>
	<a href="&base;/nl/" title="Dutch">nl</a>
	</li>
	<li>
	<a href="&base;/ru/" title="Russian">ru</a>
	</li>
	<li class="last-child">
	<a href="&base;/zh_CN/" title="Chinese (Simplified)">zh_CN</a>
	</li>
	</ul>
	</div> <!-- LANGUAGENAV -->

	<div id="mirror">
	<form action="&cgibase;/mirror.cgi" method="get">
	<div>
	<h2 class="blockhide"><label for="MIRRORSEL">Mirror</label></h2>
	<select id="mirrorsel" name="goto">
	<xsl:call-template name="html-index-mirrors-options-list">
	<xsl:with-param name="mirrors.xml" select="$mirrors.xml" />
	</xsl:call-template>
	</select>
	</div> <!-- unnamed -->
	<input type="submit" value="Go" />
	</form>
	</div> <!-- MIRROR -->

	<div id="frontshortcuts">
	<div id="frontshortcutscontent" class="txtshortcuts">
	<h2>SHORTCUTS</h2>
	<ul id="frontshortcutslist">
	<li>
	<a href="&base;/community/mailinglists.html" title="Mailing Lists">Mailing Lists</a>
	</li>
	<li>
	<a href="&base;/support/bugreports.html" title="Report a Bug">Report a Bug</a>
	</li>
	<li>
	<a href="&base;/doc/en_US.ISO8859-1/books/faq/index.html" title="FAQ">FAQ</a>
	</li>
	<li>
	<a href="&base;/doc/en_US.ISO8859-1/books/handbook/index.html" title="Handbook">Handbook</a>
	</li>
	<li>
	<a href="&base;/ports/index.html" title="Ports">Ports</a>
	</li>

	</ul>
	</div> <!-- FRONTSHORTCUTSCONTENT -->
	</div> <!-- FRONTSHORTCUTS -->

	<div class="frontnewroundbox">
	<div class="frontnewtop"><div><b style="display: none">.</b></div></div>
	<div class="frontnewcontent">
	<a href="&base;/projects/newbies.html">New to FreeBSD?</a>
	</div> <!-- frontnewcontent -->
	<div class="frontnewbot"><div><b style="display: none">.</b></div></div>
	</div> <!-- frontnewroundbox -->
	</div> <!-- FEATURERIGHT -->

	</div> <!-- FRONTFEATURECONTAINER -->

	<br class="clearboth" />
	<div id="frontnemscontainer">
	<div id="frontnews">
	<div id="frontnewscontent" class="txtnewsevent">
	<h2>LATEST NEWS</h2>
	<div class="newseventswrap">

	<xsl:call-template name="html-index-news-project-items">
	<xsl:with-param name="news.project.xml-master" select="$news.project.xml-master" />
	<xsl:with-param name="news.project.xml" select="$news.project.xml" />
	</xsl:call-template>

	<div>
	<ul class="newseventslist">
	<li class="first-child">
	<a href="&base;/news/newsflash.html" title="More News">More News</a>
	</li>
	<li class="last-child">
	<a href="&base;/news/rss.xml" title="News RSS Feed"><img class="rssimage" src="&base;/layout/images/ico_rss.png" width="27" height="12" alt="News RSS Feed" /></a>
	</li>
	</ul>
	</div> <!-- unnamed -->
	</div> <!-- newseventswrap -->

	</div> <!-- FRONTNEWSCONTENT -->
	</div> <!-- FRONTNEWS -->
	<div class="frontseparator"><b style="display: none">.</b></div>
	<div id="frontevents">
	<div id="fronteventscontent" class="txtnewsevent">

	<h2>UPCOMING EVENTS</h2>
	<div class="newseventswrap">

	<xsl:call-template name="html-index-events-items">
	<xsl:with-param name="events.xml-master" select="$events.xml-master" />
	<xsl:with-param name="events.xml" select="$events.xml" />
	</xsl:call-template>

	<div>
	<ul class="newseventslist">
	<li class="only-child">
	<a href="&base;/events/" title="More Events">More Events</a>
	</li>
	</ul>
	</div> <!-- unnamed -->
	</div> <!-- newseventswrap -->

	</div> <!-- FRONTEVENTSCONTENT -->
	</div> <!-- FRONTEVENTS -->
	<div class="frontseparator"><b style="display: none">.</b></div>
	<div id="frontmedia">
	<div id="frontmediacontent" class="txtnewsevent">

	<h2>IN THE MEDIA</h2>
	<div class="newseventswrap">

	<xsl:call-template name="html-index-news-press-items">
	<xsl:with-param name="news.press.xml-master" select="$news.press.xml-master" />
	<xsl:with-param name="news.press.xml" select="$news.press.xml" />
	</xsl:call-template>

	<div>
	<ul class="newseventslist">
	<li class="only-child">
	<a href="&base;/news/press.html" title="More Media">More Media</a>
	</li>
	</ul>
	</div> <!-- unnamed -->
	</div> <!-- newseventswrap -->

	</div> <!-- FRONTMEDIACONTENT -->
	</div> <!-- FRONTMEDIA -->
	<div class="frontseparator"><b style="display: none">.</b></div>
	<div id="frontsecurity">
	<div id="frontsecuritycontent" class="txtnewsevent">

	<h2>SECURITY ADVISORIES</h2>
	<div class="newseventswrap">

	<xsl:call-template name="html-index-advisories-items">
	<xsl:with-param name="advisories.xml" select="$advisories.xml" />
	<xsl:with-param name="type" select="'advisory'" />
	</xsl:call-template>

	<div>
	<ul class="newseventslist">
	<li class="first-child">
	<a href="&base;/security/advisories.html" title="More Security Advisories">More</a>
	</li>
	<li class="last-child">
	<a href="&base;/security/rss.xml" title="Security Advisories RSS Feed"><img class="rssimage" src="&base;/layout/images/ico_rss.png" width="27" height="12" alt="Security Advisories RSS Feed" /></a>
	</li>
	</ul>
	</div> <!-- unnamed -->
	</div> <!-- newseventswrap -->

	<br />
	<h2>ERRATA NOTICES</h2>
	<div class="newseventswrap">

	<xsl:call-template name="html-index-advisories-items">
	<xsl:with-param name="advisories.xml" select="$notices.xml" />
	<xsl:with-param name="type" select="'notice'" />
	</xsl:call-template>

	<div>
	<ul class="newseventslist">
	<li class="first-child">
	<a href="&base;/security/notices.html" title="More Errata Notices">More</a>
	</li>
	<li class="last-child">
	<a href="&base;/security/errata.xml" title="Errata Notices RSS Feed"><img class="rssimage" src="&base;/layout/images/ico_rss.png" width="27" height="12" alt="Errata Notices RSS Feed" /></a>
	</li>
	</ul>
	</div> <!-- unnamed -->
	</div> <!-- newseventswrap -->

	</div> <!-- FRONTSECURITYCONTENT -->
	</div> <!-- FRONTSECURITY -->

	<br class="clearboth" />

	</div> <!-- FRONTNEMSCONTAINER -->
	</div> <!-- FRONTMAIN -->
	</div> <!-- FRONTCONTAINER -->
	</xsl:template>

	<xsl:template name="process.footer">
	&copyright;

	The mark FreeBSD is a registered trademark of The FreeBSD
	Foundation and is used by The FreeBSD Project with the
	permission of <a
	href="http://www.freebsdfoundation.org/documents/Guidelines.shtml">The
	FreeBSD Foundation</a>.
	<a href="&base;/mailto.html" title="&header2.word.contact;">&header2.word.contact;</a>
	</xsl:template>
	</xsl:stylesheet>
	Index: projects/entities/en_US.ISO8859-1/htdocs/internal/Makefile
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/internal/Makefile (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/internal/Makefile (revision 41355)
	@@ -1,50 +1,51 @@
	# $FreeBSD$

	.if exists(../Makefile.conf)
	.include "../Makefile.conf"
	.endif
	.if exists(../Makefile.inc)
	.include "../Makefile.inc"
	.endif

	DOCS= about.xml
	DOCS+= bylaws.xml
	DOCS+= core-vote.xml
	DOCS+= data.xml
	DOCS+= developer.xml
	DOCS+= doceng.xml
	DOCS+= expire-bits.xml
	DOCS+= fortunes.xml
	DOCS+= hats.xml
	DOCS+= i18n.xml
	DOCS+= internal.xml
	DOCS+= machines.xml
	DOCS+= mirror.xml
	DOCS+= new-account.xml
	DOCS+= policies.xml
	+DOCS+= proposing-committers.xml
	DOCS+= releng.xml
	DOCS+= resources.xml
	DOCS+= statistic.xml
	DOCS+= working-with-hats.xml

	INDEXLINK= internal.html

	# build the list of personal homepages of FreeBSD developers only
	# on the main FreeBSD machines
	hostname!= hostname
	.if !empty(hostname:M*.freebsd.org)
	DOCS+= homepage.xml

	.if !make(install)
	.PHONY: homepage.inc
	.endif
	homepage.inc: homepage.pl
	${PERL} ${.CURDIR}/homepage.pl > ${.TARGET}

	homepage.html: homepage.inc
	CLEANFILES+= homepage.inc
	.endif

	DATA+= README.mirror ssh-keys.asc

	.include "${DOC_PREFIX}/share/mk/web.site.mk"
	Index: projects/entities/en_US.ISO8859-1/htdocs/internal/README.mirror
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/internal/README.mirror (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/internal/README.mirror (revision 41355)
	@@ -1,33 +1,33 @@
	-You can (and are encouraged to) mirror the pages with CVSup.
	+You can mirror the web pages with csup.
	If you are running apache as installed from the ports collection the
	following should make a copy of www.freebsd.org available from
	http://wwwN.XX.freebsd.org/. Of course, there are possible
	variations on the method...

	-1) The CVSup file to get the WWW pages
	+1) The csup file to get the WWW pages
	(/usr/local/www/data/freebsd.cvsup in the next step):

	-www release=current host=cvsup.freebsd.org hostbase=/home base=/usr prefix=/usr/local/www/data/www.freebsd.org delete old use-rel-suffix
	+www release=current host=cvsup.freebsd.org base=/usr prefix=/usr/local/www/data/www.freebsd.org delete use-rel-suffix

	2) Add to /etc/crontab

	-1 5 * * * root /usr/local/bin/cvsup -z -g /usr/local/www/data/freebsd.cvsup
	+1 5 * * * root /usr/bin/csup -z -g /usr/local/www/data/freebsd.cvsup

	2) Add to /usr/local/etc/apache/access.conf:

	<Directory /usr/local/www/data/www.freebsd.org/data>
	Options FollowSymLinks Includes
	XBitHack Full
	</Directory>

	3) Add to /usr/local/etc/apache/httpd.conf:

	<VirtualHost wwwN.XX.freebsd.org>
	UserDir disabled
	ServerAdmin webmaster@wwwN.XX.freebsd.org
	DocumentRoot /usr/local/www/data/www.freebsd.org/data
	ServerName wwwN.XX.freebsd.org
	ScriptAlias /cgi/ /usr/local/www/data/www.freebsd.org/data/cgi/
	ErrorLog /var/log/wwwN.XX-error.log
	TransferLog /var/log/wwwN.XX-access.log
	</VirtualHost>

	Property changes on: projects/entities/en_US.ISO8859-1/htdocs/internal/README.mirror
	___________________________________________________________________
	Added: fbsd:nokeywords
	## -0,0 +1 ##
	+yes
	\ No newline at end of property
	Deleted: svn:keywords
	## -1 +0,0 ##
	-FreeBSD=%H
	\ No newline at end of property
	Index: projects/entities/en_US.ISO8859-1/htdocs/internal/about.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/internal/about.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/internal/about.xml (revision 41355)
	@@ -1,126 +1,126 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "About the FreeBSD WWW Server">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.docs">

	<h2>The Machine</h2>

	<img src="../gifs/powerlogo.gif" alt="Powered by FreeBSD" align="right"/> <p>The
	machine <tt>www.FreeBSD.org</tt> is a dual 600MHz Pentium III set
	up with 1024 megabytes of RAM and about 70 gigabytes of disk space.
	The mail processing duties for the domain are handled by
	<tt>hub.FreeBSD.org</tt>, a quad core 2.2GHz AMD64 system with 3072
	megabytes of RAM and about 400 gigabytes disk space. Inbound mail
	is buffered by <tt>mx1.FreeBSD.org</tt> and outbound mail relayed via
	<tt>mx2.FreeBSD.org</tt>, both are dual 3.06 GHz Xeon systems with 1024
	megabytes of RAM and 80 gigabytes of disk.</p>

	<p>
	Naturally, these systems all run FreeBSD. The hardware and network
	connection have been generously provided by <a
	href="http://www.bsdi.com/">BSDi</a>, <a
	href="http://www.yahoo.com/">Yahoo!</a>, and other <a
	href="../donations/donors.html">contributors</a> to the FreeBSD project.
	</p>

	<p>A complete list of all host names in the FreeBSD.org domain
	is available at the <a href="machines.html">The FreeBSD.org Network</a>
	page.
	</p>

	<h2>The Software</h2>

	<img src="../gifs/light_button.png" alt="lighttpd fly light." align="right"/><p>
	These pages are served up by the fast and flexible <a
	href="http://www.lighttpd.net/">lighttpd webserver</a>. In
	addition, there are a few locally crafted CGI scripts.
	Indexing of these pages and the mailing list archive are
	provided by freewais-sf, a derivative of the CNIDR freewais.</p>

	<h2>The Pages</h2>

	<img src="../gifs/lynx.gif" alt="Lynx Friendly logo" align="right"/>

	<p>The original web pages were put together by John Fieber
	<a
	href="http://people.FreeBSD.org/~jfieber/"><jfieber@FreeBSD.org>
	</a> with input from the FreeBSD community and <b>you</b>.
	<a
	href="http://wolfram.schneider.org"><wosch@FreeBSD.org></a>
	was our first webmaster but this responsibility is now shared
	by a larger team of web and documentation contributors.
	The FreeBSD pages are valid XHTML 1.0 Transitional and should
	degrade gracefully on any browser.</p>

	See also the <a href="../docproj/docproj.html">FreeBSD Documentation Project</a>

	<h2>Page Design</h2>

	<p>The current website design was done by <a
	href="http://www.emilyboyd.com">Emily Boyd</a> as part of the
	<a href="http://code.google.com/soc">Google Summer of Code</a>
	program in 2005.</p>

	<p>The original page design was done by <a
	href="http://www.asis.com/~meganm/">Megan McCormack</a></p>

	<h2><a href="../doc/en_US.ISO8859-1/books/fdp-primer/the-website-build.html">
	Building and updating the FreeBSD Web Pages</a></h2>

	&webbuild;

	<h2>Update of the FreeBSD Web Pages</h2>
	<p>
	The FreeBSD Web Pages on <tt>www.FreeBSD.org</tt> are
	currently rebuilt according to the following schedule:</p>
	<table class="tblbasic">
	<tr>
	<th>Time (UTC)</th>
	<th>Build type</th>
	</tr>
	<tr>
	<td><em>XX</em>:23</td>
	<td rowspan="2">English www only, if no other build is running</td>
	</tr>
	<tr>
	<td><em>XX</em>:53</td>
	</tr>
	<tr>
	<td>01:22</td>
	<td>Full build</td>
	</tr>
	<tr>
	<td>09:22</td>
	<td>English only</td>
	</tr>
	<tr>
	<td>13:22</td>
	<td>Full build without PR and port statistics</td>
	</tr>
	<tr>
	<td>17:22</td>
	<td>English only</td>
	</tr>
	</table>

	<p>The recent build status is available <a
	href="http://www.freebsd.org/build/index.cgi">here</a>.</p>

	<h2>Mirroring the FreeBSD Web Pages</h2>
	- <p>You can (and are encouraged to) <a href="mirror.html">mirror</a>
	+ <p>It is possible to <a href="mirror.html">mirror</a>
	the FreeBSD web pages on www.FreeBSD.org.</p>

	<p></p><a href="internal.html">FreeBSD Internal Home</a>

	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/internal/fortunes.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/internal/fortunes.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/internal/fortunes.xml (revision 41355)
	@@ -1,47 +1,47 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "Fortune File Commit Policy">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.docs">

	<h2>Policy</h2>

	<p>Before committing to the fortune file, please remember the
	classic Usenet "rule":</p>

	<p>"Be conservative in what you expect others to accept and liberal
	in what you are prepared to accept."</p>

	<p>If an entry offends more than a couple of FreeBSD committers and
	does not contain any reasonable historical reference, the entry should
	- be in the offensive file. The speaker of the quote is not to be the
	+ not be added. The speaker of the quote is not to be the
	basis for categorizing the quote as offensive.</p>

	<p>Examples of offensive entries:</p>

	<ul>
	<li>Those that belittle groups on the basis of their gender,
	nationality, religion, or lifestyle.</li>
	<li>Profanity, "adult" content.</li>
	</ul>

	<p>If you add new material to the fortunes collection, please be
	extra-diligent about unforeseen objections, and give plenty of
	time for it to settle before MFCing.</p>

	<p>Additional examples may be added to the offensive list above, as
	guidelines, whenever core@ is required to settle a dispute on this
	issue.</p>


	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/internal/mirror.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/internal/mirror.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/internal/mirror.xml (revision 41355)
	@@ -1,70 +1,49 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "Mirroring the FreeBSD Web Pages">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.docs">

	-<p>You can (and are encouraged to) mirror the FreeBSD web pages
	+<p>It is possible to mirror the FreeBSD web pages
	<tt>www.FreeBSD.org</tt>.

	-To do this, you need to obtain and install
	-a program called <em>cvsup</em> on your web server.
	+This can be done using a program called <em>csup</em>.

	-<a href="&url.doc.base;/books/handbook/cvsup.html#CVSUP-INSTALL">CVSup</a> is a software package for
	+csup is a software package in the base system for
	distributing and updating collections of files across a network.</p>

	-<h2>Installing CVSup</h2>
	+<h2>Running csup</h2>

	-<p>You can build and install it from source by the following commands:</p>
	-
	-<pre>
	- # cd /usr/ports/net/cvsup-without-gui
	- # make all install clean
	-</pre>
	-
	-<p>However, installing precompiled package from the FreeBSD
	-<a href="&url.doc.base;/books/handbook/packages-using.html">packages
	-collection</a> may be much easier.
	-Refer to the chapter mentioned for the details.</p>
	-
	-<h2>Running CVSup</h2>
	-
	<p>If you keep your mirrored FreeBSD web pages in the directory
	<tt>/usr/FreeBSD-mirror</tt> and are owned by the user `fred', then
	run the following command as user `fred':</p>

	<pre>
	- $ cvsup supfile-www
	+ $ csup supfile-www
	</pre>

	The file <tt>supfile-www</tt> contain:
	<pre>
	- *default host="cvsup".FreeBSD.org
	+ *default host=cvsup.FreeBSD.org
	*default prefix=/usr/FreeBSD-mirror
	*default base=/usr/local/etc/cvsup
	www release="current" delete use-rel-suffix compress
	</pre>

	<p>This will mirror the FreeBSD web pages into
	<tt>/usr/FreeBSD-mirror</tt>. You can install this into fred's
	-crontab, so that it runs once a day. The pages on www.FreeBSD.org are
	-updated daily at about 4:30am California time.</p>
	-
	-<h2>More Information on CVSup</h2>
	-
	-See the <a href="&url.doc.base;/books/handbook/synching.html#CVSUP">CVSup introduction</a> in the
	-handbook.
	+crontab, so that it runs once a day.</p>

	<p><a href="internal.html">FreeBSD Internal Home</a></p>

	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/internal/new-account.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/internal/new-account.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/internal/new-account.xml (revision 41355)
	@@ -1,139 +1,144 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "New Account Creation Procedure">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.docs">

	<h2>Proposing a new committer</h2>

	<p>If you want to propose a new committer, you should send the following
	information to the appropriate entity:
	</p>
	<ul>
	<li>Information on what established (FreeBSD) track record the
	nominee has. This is <em>not</em> optional.</li>
	<li>Who has volunteered to become the mentor for the new
	committer.</li>
	<li>The email address of the nominee (remarkably often this
	is omitted).</li>
	</ul>

	<p>Any commit bit requests that do not follow the guidelines outlined
	above will be delayed (at best) or earn you negative vibrations from the
	- respective team / team secretary.
	+ respective team / team secretary. For some guidelines on how the
	+ proposal itself should be written, please see <a
	+ href="proposing-committers.html">a brief summary</a>.
	</p>

	<p>Responsible party for this procedure is:</p>
	<ul>
	<li>src --> core@</li>
	<li>doc --> doceng@</li>
	<li>ports --> portmgr@</li>
	</ul>

	<p> You will get ACK after the message is seen, and core@, doceng@ and portmgr@
	will give you a response after voting is finished or when the timeout is hit.
	The timeout for core@ and portmgr@ is set to 7 days while for doceng@ it is
	14 days, however, as indicated, this is just a worst case and team members
	may finish voting earlier.</p>

	<h2>Authorizing A New Account</h2>

	<p>Someone from the list below sends a PGP-signed email to
	accounts@, the person assigned as the mentor to the new
	committer, and copied to core@FreeBSD.org confirming the approval of
	the new account. This email should include a link to this document
	so the mentor/mentee know what is expected of them.</p>

	<p>New account approvals are only valid from these PGP entities:</p>

	<ul>
	<li><p>core-secretary (for src commit bits)</p></li>
	<li><p>portmgr-secretary (for ports commit bits)</p></li>
	<li><p>doceng (for doc commit bits)</p></li>
	</ul>

	<p><i>NOTE: New account requests from anyone other than these
	entities or requests signed with PGP keys other than from these
	entities will not be acted upon. No exceptions. In case of
	a new ports or doc committer the account request email should be
	CC:-ed to core.</i></p>

	<h2>Information Needed From The Mentor</h2>

	<p>The person assigned as the new committers' mentor needs to collect
	and send the following information to accounts@:</p>

	<ul>
	- <li><p><tt>master.passwd</tt> line containing preferred username,
	- shell, and GECOS info (no password is needed)</p></li>
	+ <li><p>username (lowercase a-z and 0-9)</p></li>
	+ <li><p>Full Name (as would go in a GECOS field)</p></li>
	+ <li><p>optional additional GECOS information (phone, location etc)</p></li>
	+ <li><p>shell (sh, csh/tcsh, bash, zsh are available)</p></li>
	<li><p>ssh V2 public key (<strong>version 2 ONLY</strong>)</p></li>
	</ul>

	+ <p>Any non-ASCII characters for the <em>Full Name</em> field should be encoded
	+ in UTF-8. Be aware that we have very limited support for this and caution
	+ that they are likely to be frequently corrupted. The number of characters
	+ should kept to a minimum.</p>
	+
	<p>The mentor is responsible for obtaining this information from the
	new committer in a secure fashion, and providing it to accounts@ in
	a secure fashion. PGP-signed email, with the mentor's public key
	already committed to the Handbook, is the preferred method for the
	mentor to send the information to accounts@. If this is impossible
	for some reason an acceptable substitute is for the mentor to place
	the account information in their home directory on freefall and then
	tell accounts@ where to find it. We need to be sure the account
	information really is coming from the Mentor and unsigned email is
	not sufficient for this these days. Since accounts@ has no way to
	verify anything from the new Committer this information needs to
	be sent to accounts@ by the Mentor, not the new Committer.</p>

	<h2>accounts@ Creates New Account</h2>

	<p>accounts@ creates the new account with the above
	information on the FreeBSD.org cluster and notifies the mentor and
	the new committer.</p>

	<h2>Mentor Activates New Committer's Commit Bit</h2>

	<p>After the new committer confirms that the account works, the mentor
	adds the new committer to the correct <tt>access</tt> file,
	using an appropriate commit message. The commit message should at least
	- contain the committer's full name, the mentor's name and what area
	- the new committer will start to work in. For src and doc commit
	- bits, an entry should also be added to the <tt>mentors</tt> file in
	+ contain the committer's full name and username, the mentor's
	+ name and what area the new committer will start to work in.
	+ An entry should also be added to the <tt>mentors</tt> file in
	the respective Subversion repository to indicate
	the mentor relationship. Having done all that,
	the new committer and mentor jointly go through the first commit
	operations.</p>

	<p>Reading the <a
	href="&base;/doc/en_US.ISO8859-1/articles/committers-guide/index.html">Committer's
	Guide</a> is considered a good first step for new committers, especially
	the <a
	href="&base;/doc/en_US.ISO8859-1/articles/committers-guide/conventions.html">Conventions
	and Traditions</a> section.</p>

	<h2>End Of Mentorship</h2>

	<p>There is no pre-set duration for a mentorship. Once the mentor feels
	the mentee is ready to 'fly solo' the mentor notifies the developer
	- community by removing the entry from the <tt>mentors</tt> file in SVN,
	- or via a forced commit to <tt>access</tt> in CVS with an appropriate
	- commit message.</p>
	+ community by removing the entry from the <tt>mentors</tt> file in
	+ SVN.</p>

	<h2>Transfer Of Mentorship</h2>

	<p>Should a need arise to transfer mentorship for a committer
	please email the responsible party, as described for a new account
	proposal. Typically this request is rubberstamped as-is.
	- In Subversion, the <tt>mentors</tt> file should be updated.
	- In CVS, a forced commit to <tt>access</tt> with an appropriate commit
	- message is to be used to inform the world of the transfer.</p>
	-
	+ In Subversion, the <tt>mentors</tt> file should be updated.</p>

	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/internal/proposing-committers.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/internal/proposing-committers.xml (nonexistent)
	+++ projects/entities/en_US.ISO8859-1/htdocs/internal/proposing-committers.xml (revision 41355)
	@@ -0,0 +1,56 @@
	+<?xml version="1.0" encoding="iso-8859-1"?>
	+<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	+"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	+<!ENTITY title "Proposing Committers">
	+]>
	+
	+<html xmlns="http://www.w3.org/1999/xhtml">
	+ <head>
	+ <title>&title;</title>
	+
	+ <cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	+ </head>
	+
	+ <body class="navinclude.docs">
	+
	+<p>The following paragraphs contain an advice from &a.kib;, member of
	+ the Core Team, who summarizes what constitutes a good proposal, how
	+ you as potential mentor, could increase your chances to have your
	+ mentee granted a commit bit.</p>
	+
	+<p>When proposing somebody, you should just forget for a moment that you
	+ know the candidate personally. After that, look unprejudiced on the
	+ person's activity on the mailing lists, and evaluate the patches
	+ submitted.</p>
	+
	+<p>Now, you can ask yourself, is it enough confidence in both technical
	+ abilities and the social behavior of the candidate, from what you see
	+ only on the media? If you do, then write down the reasons why are
	+ you sure, using the said list of the contributions as the evidence,
	+ and do include the reasoning in the commit bit application.</p>
	+
	+<p>Due to several failures of the premature granting of commit bits, the
	+ Core Team became quite sensitive to these criteria. Most of the
	+ members only see the activity of applicants on the lists, and not
	+ seeing much there causes the cautious choice.</p>
	+
	+<p>The Core Team wants to see a good list of the work already done for
	+ &os; (e.g., the long list of the commits, submitted by the applicant,
	+ the list of PRs opened etc.), which can make us confident that the
	+ person has an established interest in the project, backed by the
	+ technical ability and work done.</p>
	+
	+<p>Also, the history of the good engagement with the community on the
	+ public media, such as mailing list, is a deciding factor too. The
	+ Core Team wants to filter out the controversial personalities, since
	+ it is almost impossible and highly undesirable to revoke the commit
	+ bit, once granted.</p>
	+
	+<p>Vendor-proposed maintainers for the hardware drivers usually approved
	+ without applying the listed criteria. Still, the Core Team requires
	+ an experienced mentor for a vendor committer to avoid unwanted tension
	+ and to make sure that vendor commits follow the Project procedures and
	+ community expectations.</p>
	+
	+ </body>
	+</html>

	Property changes on: projects/entities/en_US.ISO8859-1/htdocs/internal/proposing-committers.xml
	___________________________________________________________________
	Added: svn:keywords
	## -0,0 +1 ##
	+FreeBSD=%H
	\ No newline at end of property
	Added: svn:mime-type
	## -0,0 +1 ##
	+text/sgml
	\ No newline at end of property
	Index: projects/entities/en_US.ISO8859-1/htdocs/layout/css/layout.css
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/layout/css/layout.css (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/layout/css/layout.css (revision 41355)
	@@ -1,529 +1,520 @@
	/*
	* FreeBSD.org - Layout Styles
	*
	* $FreeBSD$
	*/

	/* Container Definitions */

	/* Page Container */

	#containerwrap {
	text-align: center; /* Win IE5 */
	}

	#container {
	margin: 0em auto;
	width: 775px;
	padding: 0;
	padding-top: 0px;
	padding-bottom: 15px;
	text-align: left; /* Win IE5 */
	}

	/* Header */

	#headercontainer {
	padding-bottom: 2px;
	}

	#header {
	position: relative;
	height: 76px;
	margin: 0;
	padding: 0;
	clear: both;
	}

	#headerlogoleft {
	position: relative;
	border: 0px;
	padding: 0px;
	top: 0px;
	margin-left: -4%;
	float: left;
	}

	#headerlogoleft img {
	border: 0px;
	}

	#headerlogoright {
	position: relative;
	border: 0px;
	padding-left: 0px;
	margin-right: -4%;
	float: right;
	}

	#headerlogoright img {
	border: 0px;
	}

	/* Search */

	#search {
	position: relative;
	text-align: right;
	padding: 0;
	margin: 0;
	margin-top: 6px;
	color: #666;
	}

	#search form {
	position: relative;
	top: 5px;
	right: 0;
	margin: 0; /* need for IE Mac */
	text-align: right; /* need for IE Mac */
	white-space: nowrap; /* for Opera */
	}

	#search form label {
	color: #666;
	font-size: 0.8em;
	}

	#search form input {
	font-size: 0.8em;
	}

	#search form #submit {
	font-size: 0.8em;
	background: transparent;
	color: #fff;
	border-right: 1px solid #DADADA;
	border-bottom: 1px solid #DADADA;
	border-top: 1px solid #DADADA;
	border-left: 1px solid #DADADA;
	padding: 1px 5px 1px 5px;
	}

	#search form #words {
	font-size: 0.8em;
	width: 120px;
	border: 1px solid #DADADA;
	background: #FFFFFF;
	color: #666;
	padding: 2px 2px 2px 5px;
	}

	/* Mirror Select */

	#mirror {
	text-align: right;
	padding: 0;
	margin: 0;
	margin-top: 6px;
	color: #666;
	}

	#mirror form {
	padding-top: 5px;
	right: 0;
	margin: 0; /* need for IE Mac */
	text-align: right; /* need for IE Mac */
	white-space: nowrap; /* for Opera */
	}

	#mirror form label {
	color: #666;
	font-size: 0.8em;
	}

	#mirror form select {
	font-size: 0.8em;
	}

	#mirror form #mirrorsel {
	font-size: 0.8em;
	width: 150px;
	border: 1px solid #DADADA;
	background: #FFFFFF;
	color: #666;
	}

	#mirror input {
	font-size: 0.8em;
	background: transparent;
	color: #666;
	border: 1px solid #DADADA;
	}

	/* Content */

	#content {
	clear: both;
	display: block;
	}

	#frontcontainer {
	width: 100%;
	float: left;
	}

	#frontfeaturecontainer {
	clear: both;
	}

	#frontfeatureleft{
	width: 273px;
	margin: 0;
	padding: 0;
	float: left;
	}

	#frontfeatureleft h2 {
	border: none;
	margin-top: 0;
	}

	#frontfeatureleft p {
	margin: 0 0 1em 0;
	}

	#frontfeaturecontent {
	margin: 10px 10px 10px 13px;
	}

	#frontfeaturemiddle {
	float: left;
	margin-top: 20px;
	background: url(../images/beastie.png) no-repeat top left;
	min-height: 196px;
	}

	#frontfeatureright {
	position: relative;
	border: 0px;
	padding: 0px;
	margin: 0px;
	width: 162px;
	float: right;
	}

	/* News/Events/Media/Security Box */

	#frontnemscontainer {
	background: #eee;
	display: inline;
	float: left;
	margin-top: 8px;
	margin-bottom: 8px;
	}

	#frontnews {
	width: 191px;
	margin: 0;
	padding: 0;
	float: left;
	}

	#frontnewscontent {
	margin: 17px 15px 24px 18px;
	}

	#frontevents {
	width: 189px;
	margin: 0;
	padding: 0;
	float: left;
	}

	#fronteventscontent {
	margin: 17px 15px 24px 14px;
	}

	#frontmedia {
	width: 189px;
	margin: 0;
	padding: 0;
	float: left;
	}

	#frontmediacontent {
	margin: 17px 15px 24px 14px;
	}

	#frontsecurity {
	width: 190px;
	margin: 0;
	padding: 0;
	float: left;
	}

	#frontsecuritycontent {
	margin: 17px 15px 24px 14px;
	}

	/* No way to get equal columns in pure CSS - setting height is a temporary hack */
	.frontseparator {
	width: 1px;
	height: 317px;
	margin: 0;
	padding: 0;
	background-color: #fff;
	float: left;
	}

	.newseventswrap {
	padding-left: 5px;
	}

	.newseventslist {
	list-style: none;
	margin: 0;
	padding: 0;
	display: inline;
	}

	.newseventslist img.rssimage {
	display: inline;
	border: 0;
	vertical-align: bottom;
	}

	.newseventslist li {
	padding: 0 0.3em 0 0.5em;
	display: inline;
	border-right: 1px solid #E1E1E1;
	}

	.newseventslist li a {
	}

	.newseventslist li.last-child {
	border-right: 0;
	padding-right: 0;
	}

	.newseventslist li.first-child {
	padding-left: 0;
	}

	.newseventslist li.only-child {
	border-right: 0;
	padding-left: 0;
	}

	/* Shortcuts */

	#frontshortcuts {
	margin: 0;
	padding: 0;
	color: #666;
	}

	#frontshortcutscontent {
	margin: 0;
	padding: 0;
	padding-left: 15px;
	padding-top: 20px;
	}

	#frontshortcutslist {
	margin: 0;
	padding: 0;
	margin-left: 5px;
	margin-top: 5px;
	list-style: none;
	}

	#frontshortcutslist li {
	margin: 0;
	padding-left: 12px;
	background-image: url(../images/blt_red_arrow.png);
	background-repeat: no-repeat;
	background-position: 0px 0.5em;
	}

	/* Latest Releases */

	#frontreleases {
	padding: 0;
	margin: 0;
	margin-left: 162px;
	margin-top: 15px;
	padding-bottom: 20px;
	color: #666;
	width: 155px;
	}

	#frontreleasescontent {
	margin: 0;
	padding: 0;
	}

	#frontreleaseslist {
	margin: 0;
	padding: 0;
	margin-left: 5px;
	margin-top: 5px;
	list-style: none;
	}

	#frontreleaseslist li {
	margin: 0;
	padding-left: 12px;
	background-image: url(../images/blt_red_arrow.png);
	background-repeat: no-repeat;
	background-position: 0px 0.5em;
	}

	/* New User Box */

	/* height and width details */
	.frontnewtop div, .frontnewtop, .frontnewbot div, .frontnewbot {
	width: 100%;
	height: 12px;
	font-size: 1px;
	}

	.frontnewcontent {
	margin: 0;
	padding: 0;
	margin-top: -4px;
	margin-bottom: -4px;
	text-align: center;
	font-size: 1.1em;
	font-weight: bold;
	}

	.frontnewcontent a, .frontnewcontent a:link, .frontnewcontent a:visited, .frontnewcontent a:hover, .frontnewcontent a:active {
	color: #990000;
	text-decoration: none;
	}

	.frontnewroundbox {
	margin: 0;
	margin-top: 30px;
	padding: 0;
	width: 130px;
	background-color: #D8D8D8;
	- -moz-border-radius: 10px;
	- -webkit-border-radius: 10px;
	- -khtml-border-radius: 10px;
	border-radius: 10px;
	}

	/* Donate Button */
	/* height and width details */
	.frontdonatetop div, .frontdonatetop, .frontdonatebot div, .frontdonatebot {
	width: 20%;
	height: 10px;
	font-size: 1px;
	text-align: center;
	}

	.frontdonatecontent {
	margin: 0;
	padding: 0;
	margin-top: -4px;
	margin-bottom: -4px;
	text-align: center;
	font-size: 1.1em;
	font-weight: bold;
	}

	.frontdonatecontent a, .frontdonatecontent a:link, .frontdonatecontent a:visited, .frontdonatecontent a:hover, .frontdonatecontent a:active {
	color: #990000;
	text-decoration: none;
	}

	.frontdonateroundbox {
	margin-top: 10px;
	padding: 0;
	width: 180px;
	background-color: white;
	- -moz-border-radius: 10px;
	- -webkit-border-radius: 10px;
	- -khtml-border-radius: 10px;
	border-radius: 10px;
	}

	/* Get FreeBSD Box */

	/* height and width details */
	.frontgettop div, .frontgettop, .frontgetbot div, .frontgetbot {
	width: 100%;
	height: 18px;
	font-size: 1px;
	}

	.frontgetcontent {
	margin: 0;
	padding: 0;
	margin-top: -8px;
	margin-bottom: -8px;
	text-align: center;
	font-size: 1.4em;
	font-weight: bold;
	}

	.frontgetcontent a, .frontgetcontent a:link, .frontgetcontent a:visited, .frontgetcontent a:hover, .frontgetcontent a:active {
	color: #990000;
	text-decoration: none;
	}

	.frontgetroundbox {
	margin-top: 50px;
	margin-left: 140px;
	padding: 0;
	width: 190px;
	background-color: #FACC2E;
	- -moz-border-radius: 10px;
	- -webkit-border-radius: 10px;
	- -khtml-border-radius: 10px;
	border-radius: 15px;
	}

	/* Secondary Pages */

	#sidewrap {
	float: left;
	width: 166px;
	margin-top: 15px;
	margin-right: -170px;
	}

	#rightwrap {
	float: right;
	width: 166px;
	margin-left: 15px;
	}

	#contentwrap {
	margin-left: 170px;
	padding-top: 15px;
	}

	/* Footer */

	#footer {
	font-size: 0.9em;
	color: #737373;
	line-height: 1.3em;
	padding-top: 5px;
	clear: both;
	}

	/* Misc Classes */

	.clearboth {
	clear: both;
	margin: 0;
	padding: 0;
	}

	.blockhide {
	display: none;
	height: 0;
	width: 0;
	overflow: hidden;
	position: absolute; /* IE5 Mac */
	}

	img {
	border: 0;
	}
	Index: projects/entities/en_US.ISO8859-1/htdocs/news/2012-compromise.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/news/2012-compromise.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/news/2012-compromise.xml (revision 41355)
	@@ -1,340 +1,368 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "FreeBSD.org intrusion announced November 17th 2012">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.about">

	<table class="tblbasic">
	<tbody>
	<tr>
	<td><h2 align="center"><a name="announce">Security Incident on
	FreeBSD Infrastructure</a></h2>

	<b>From:</b> FreeBSD Security Officer <security-officer@FreeBSD.org><br />
	<b>To:</b> FreeBSD Security <FreeBSD-security@FreeBSD.org><br />
	<b>Bcc:</b> freebsd-announce@freebsd.org, freebsd-security-notifications@FreeBSD.org<br />
	<b>Reply-To:</b> secteam@FreeBSD.org<br />
	<b>Subject:</b> Security Incident on FreeBSD Infrastructure<br />

	<p>On Sunday 11th of November, an intrusion was detected on two
	machines within the FreeBSD.org cluster. The affected machines
	were taken offline for analysis. Additionally, a large portion
	of the remaining infrastructure machines were also taken offline
	as a precaution.</p>

	<p>We have found no evidence of any modifications that would put
	any end user at risk. However, we do urge all users to read the
	report available at
	<a href="/news/2012-compromise.html">http://www.freebsd.org/news/2012-compromise.html</a>
	and decide on any required actions themselves. We will continue
	to update that page as further information becomes known. We do
	not currently believe users have been affected given current
	forensic analysis, but we will provide updated information if
	this changes.</p>

	<p>As a result of this event, a number of operational security
	changes are being made at the FreeBSD Project, in order to
	further improve our resilience to potential attacks. We plan,
	therefore, to more rapidly deprecate a number of legacy services,
	such as cvsup distribution of FreeBSD source, in favour of our
	more robust Subversion, freebsd-update, and portsnap models.</p>

	<p>More information is available at
	<a href="/news/2012-compromise.html">http://www.freebsd.org/news/2012-compromise.html</a></p>

	<p>Saturday November 17th, 2012</p>
	</td>
	</tr>
	</tbody>
	</table>
	<br />

	<h2><a name="toc">Table of Contents</a></h2>

	<ul>
	<li><a href="#announce">Announcement</a></li>
	+ <li><a href="#update20130323">Update: 23rd March 2013</a></li>
	+ <li><a href="#update20130303">Update: 3rd March 2013</a></li>
	<li><a href="#update20121229">Update: 29th December 2012</a></li>
	<li><a href="#update20121127">Update: 27th November 2012</a></li>
	<li><a href="#update20121122">Update: 22nd November 2012</a></li>
	<li><a href="#update20121118">Update: 18th November 2012</a></li>
	<li><a href="#details">Initial Details: 17th November 2012</a></li>
	<li><a href="#impact">What is the Impact?</a></li>
	<li><a href="#done">What has FreeBSD.org done about this?</a></li>
	<li><a href="#recommend">Recommendations</a></li>
	</ul>

	+ <h1><a name="update20130323">Update: March 23rd, 2013</a></h1>
	+
	+ <p>Port managers have successfully restored some of the Project's
	+ binary package building capacity. There are some issues left
	+ still to resolve, e.g. how to publish the resulting package sets
	+ in a secure manner or how to build packages seamlessly for 8.x and
	+ 9.x systems on a recent 10.x system that the head node
	+ ("pointyhat") is running, but we are very close to finish with the
	+ preparations required for providing binary packages for the
	+ upcoming 8.4 and further releases.</p>
	+
	+ <p>Unless there are any other major changes, this is planned to be
	+ the last status update to this page. An email will be sent to
	+ the <a href="http://lists.freebsd.org/mailman/listinfo/freebsd-announce">
	+ FreeBSD announcements mailing list</a> when the package build
	+ infrastructure is online and packages are once again available.</p>
	+
	+ <h1><a name="update20130302">Update: March 3rd, 2013</a></h1>
	+
	+ <p>Redports underwent a full security audit, and as a result could
	+ be brought back on line. This took place on the 5th February, and
	+ since then more backend hardware has been added to bring it back
	+ up to full strength. On 11th February, sanity checks for ports
	+ have been turned back on, reenabling generation and update of the
	+ INDEX files used. The portsnap(8) service has been switched from
	+ CVS to SVN on 25th February. The binary package building
	+ infrastructure has undergone a major security review, and as a
	+ result many changes have been made to the code. The review
	+ completed on the 16th February and we are now in the process of
	+ bringing it up on new hardware. At this point, we expect new
	+ binary packages to be available in 2-4 weeks.</p>
	+
	<h1><a name="update20121229">Update: December 29th, 2012</a></h1>

	<p>With the exception of systems relating to the building and testing
	of packages, all FreeBSD.org infrastructure has now been brought
	back online. A full audit of the third party package build
	infrastructure code ("pointyhat") and package testing infrastructure
	("redports") continues, and neither system will be brought back
	online until audits are complete.</p>

	<p>As a result, FreeBSD 9.1-RELEASE will be published with only
	minimal i386 and amd64 (x86_64) precompiled package sets available,
	and with no packages available for other architectures. This
	package set will be available on the DVD image, and are sufficient
	to install either the GNOME or the KDE desktop environment. For any
	other uses, or for any packages not included on the CD, either
	using the most recently available -stable package collection or
	compiling ports from the ports tree are recommended. Packages
	for 9.1-RELEASE will be made available at a later date. Instructions
	for obtaining and updating the ports tree can be found in the
	<a href="/doc/handbook/ports-using.html">
	FreeBSD Handbook</a>.</p>
	-
	- <p>Unless there are any other major changes, this is planned to be
	- the last status update to this page. An email will be sent to
	- the <a href="http://lists.freebsd.org/mailman/listinfo/freebsd-announce">
	- FreeBSD announcements mailing list</a> when the package build
	- infrastructure is online and packages are once again available.</p>

	<h1><a name="update20121127">Update: November 27th, 2012</a></h1>

	<p>Due to the legacy third-party package build controller head
	nodes being offlined pending reinstall, we have been unable to
	build new package sets over the last two weeks. As a result,
	FreeBSD 9.1-RELEASE has been delayed as it was felt that we
	should not ship the release without at least a minimal package
	set available. We are now in a position where we are once
	again able to build third-party packages for both of our
	<a href="/doc/en_US.ISO8859-1/articles/committers-guide/archs.html">
	Tier-1 architectures</a> (i386 and amd64), and are planning on
	releasing it within the next few days with only a slightly
	limited set of packages. Please note that historically we have
	also provided packages on a best-effort basis for some of our
	Tier-2 architectures such as sparc64, ia64 and powerpc. We are
	not currently expecting to be in a position to build any Tier-2
	packages before FreeBSD 9.1 ships, so initially no precompiled
	packages will be available for these platforms. We
	may be in a position to provide some packages for these
	architectures shortly after the release.</p>

	<p>A few reports covering this incident on external tech news
	websites have confused details relating to how this incident
	was discovered. Over the last few weeks, many of our primary
	cluster servers have been either physically relocated and/or
	replaced with new hardware as part of work planned several
	months in advance. The discovery of this incident was
	unrelated to this ongoing cluster maintenance. Several
	service outages in the days surrounding the incident were
	correctly attributed to ongoing cluster work, and were not
	related in any way to the compromise. In parallel with the
	physical upgrades and relocation of servers, we are also
	reworking the network layout in order to provide better
	functionality, security, resilience, and to reduce any impact
	from incidents such as this. Due in a large part to the
	progress already made here, we were able to have full
	confidence in many systems and services so quickly after the
	compromised hosts on the legacy network segment were
	discovered.</p>

	<h1><a name="update20121122">Update: November 22nd, 2012</a></h1>

	<p>Although not mentioned in the original report,
	<a href="/doc/handbook/ctm.html">CTM</a> (another mechanism for
	retrieving FreeBSD source) uses the master trusted Subversion
	repository as the source of its data. Additionally, verification of
	CTM-sourced trees has been completed against the Subversion tree,
	confirming that there are no differences between the two. Our
	experimental Git repository has been similarly verified.</p>

	<p>Work continues on rebuilding internal infrastructure and reinstating
	services taken down during the incident. Web interfaces to the old
	CVS repositories (CVSweb), and to GNATS (our bug-tracking database)
	have been restored amongst other services, and other internal hosts
	are being examined and rebuilt where necessary. A full audit of the
	package building infrastructure is ongoing.</p>

	<p>The FreeBSD Project is investing significant effort into looking
	into both medium and long term infrastructure improvements to increase
	security of the FreeBSD cluster.</p>

	<h1><a name="update20121118">Update: November 18th, 2012</a></h1>

	<p>Newer portsnap(8) snapshots are once again available. The
	generation of these had been suspended as part of the infrastructure
	lockdown, however all machines involved have either been audited or
	reinstalled and so we are now confident that these can be made
	available once more.</p>

	<p>The Subversion to CVS exporter is now up and running again.
	Updates made to the Subversion repository will once again appear in
	repositories available via csup/CVSup. Please note that the use of
	these exports are still deprecated, and users are urged to move to
	one of the supported methods (for example, freebsd-update(8),
	portsnap(8), or Subversion) in order to obtain updates. Note also
	that we are still currently unable to guarantee the integrity of
	past history within the CVS repository, but are confident in the
	integrity of checkouts from the top-of-tree of each branch.</p>

	<p>Please note that due to infrastructure changes, the first update
	through either portsnap(8) or csup(1) is likely to show changes to
	a large number of files. This is nothing to worry about.</p>

	<p>As mentioned in the original announcement, a package set uploaded in
	preparation for the upcoming FreeBSD 9.1-RELEASE could not be verified,
	and so was removed. In order to allow system integrators and end
	users to verify that packages they may have downloaded are not from
	this set, we have provided files containing both
	<a href="/news/2012-compromise/sha256.sums.20121118.txt">sha256</a> and
	<a href="/news/2012-compromise/md5.sums.20121118.txt">md5</a> checksums
	for all removed packages.</p>

	<h1><a name="details">November 17th, 2012</a></h1>
	<h2>Initial details</h2>

	<p>On Sunday 11th November 2012, two machines within the FreeBSD.org
	infrastructure were found to have been compromised. These machines
	were head nodes for the legacy third-party package building
	infrastructure. It is believed that the compromise may have occurred
	as early as the 19th September 2012.</p>

	<p>The compromise is believed to have occurred due to the leak of an
	SSH key from a developer who legitimately had access to the machines
	in question, and was not due to any vulnerability or code exploit
	within FreeBSD.</p>

	<p>To understand the impact of this compromise, you must first
	understand that the FreeBSD operating system is divided into two
	parts: the "base" maintained by the FreeBSD community, and a large
	collection of third-party "packages" distributed by the Project.
	The kernel, system libraries, compiler, core command-line tools
	(e.g., SSH client), and daemons (e.g., sshd(8)) are all in the
	"base". Most information in this advisory refers only to
	third-party packages distributed by the Project.</p>

	<p>No part of the base FreeBSD system has been put at risk. At no
	point has the intruder modified any part of the FreeBSD base system
	software in any way. However, the attacker had access sufficient
	to potentially allow the compromise of third-party packages. No
	evidence of this has been found during in-depth analysis, however
	the FreeBSD Project is taking an extremely conservative view on this
	and is working on the assumption that third-party packages generated
	and distributed within a specific window could theoretically have
	been modified.</p>

	<h2><a name="impact">What is the Impact?</a></h2>

	<p>If you are running a system that has had no third-party packages
	installed or updated on it between the 19th September and 11th
	November 2012, you have no reason to worry.</p>

	<p>The Source, Ports and Documentation Subversion repositories have been
	audited, and we are confident that no changes have been made to them.
	Any users relying on them for updates have no reason to worry.</p>

	<p>We have verified the state of FreeBSD packages and releases currently
	available on ftp.FreeBSD.org. All package sets for existing versions
	of FreeBSD and all available releases have been validated and we can
	confirm that the currently available packages and releases have not
	been modified in any way.</p>

	<p>A package set for the upcoming FreeBSD 9.1-RELEASE had been uploaded
	to the FTP distribution sites in preparation for 9.1-RELEASE. We are
	unable to verify the integrity of this package set, and therefore it
	has been removed and will be rebuilt. Please note that as these
	packages were for a future release, the standard <q>pkg_add -r</q>
	tools to install packages could not have downloaded these packages
	unless they were requested explicitly.</p>

	<p>We unfortunately cannot guarantee the integrity of any packages
	available for installation between 19th September 2012 and 11th
	November 2012, or of any ports compiled from trees obtained via any
	means other than through svn.freebsd.org or one of its mirrors.
	Although we have no evidence to suggest any tampering took place
	and believe such interference is unlikely, we have to recommend you
	consider reinstalling any machine from scratch, using trusted
	sources.</p>

	<p>We can confirm that the freebsd-update(8) binary upgrade mechanism is
	unaffected, as it uses an entirely separate infrastructure. We have
	also verified that the most recently-available portsnap(8) snapshot
	matches the ports Subversion repository, and so can be fully trusted.
	Please note that as a precaution, newer portsnap(8) snapshots are
	currently not being generated.</p>

	<h2><a name="done">What has FreeBSD.org done about this?</a></h2>

	<p>As soon as the incident came to light, the FreeBSD Cluster
	Administration team took the following actions:</p>

	<ul>
	<li>Power down the compromised machines.</li>
	<li>Power down all machines on which the attacker may have had
	access.</li>
	<li>Audit the SVN and Perforce repositories to:
	<ul>
	<li>Verify that there had been no server intrusion.</li>
	<li>Verify that no malicious commits had been made to the
	repository.</li>
	<li>Verify that the SVN repository exactly matched a known-clean
	off-site copy.</li>
	</ul>
	</li>
	<li>Verify that all FreeBSD base release media and install files on
	the master FTP distribution sites are clean.</li>
	<li>Verify all package sets available have checksums that match
	known-good copies stored off-site.</li>
	<li>The package set built for the upcoming 9.1-RELEASE did not have
	an offsite backup to verify against. These have been deleted, and
	will be rebuilt before 9.1 is released.</li>
	<li>All suspect machines are being either reinstalled, retired, or
	thoroughly audited before being brought back online.</li>
	</ul>

	<h2><a name="recommend">At this time, we recommend:</a></h2>

	<ul>
	<li>If you use the already-deprecated cvsup/csup distribution
	mechanisms, you should stop now.</li>
	<li>If you were using cvsup/csup for ports, you should switch to
	portsnap(8) right away. Ports developers should be using
	Subversion already. Further information on preferred mechanisms
	for obtaining and updating the ports tree can be found at
	<a href="/doc/handbook/ports-using.html">
	http://www.freebsd.org/doc/handbook/ports-using.html</a></li>
	<li>If you were using cvs/anoncvs/cvsup/csup for src, you should
	consider either freebsd-update(8) for signed binary distribution
	or Subversion for source. Please see the chapter on <a
	href="/doc/handbook/updating-upgrading.html">updating
	FreeBSD from source</a> in the handbook. Further details on
	using Subversion and a list of official mirrors can be found
	at <a href="/doc/handbook/svn.html">
	http://www.freebsd.org/doc/handbook/svn.html</a></li>
	<li>If you use portsnap(8), you should <tt>portsnap fetch &&
	portsnap extract</tt> to the most recent snapshot. The most recent
	portsnap(8) snapshot has been verified to exactly match the audited
	Subversion repository. Please note that as a precaution, portsnap(8)
	updates have been suspended temporarily.</li>
	<li>Follow best practice security policies to determine how your
	organization may be affected.</li>
	<li>Conduct an audit of your system that uses FreeBSD.org provided
	binary packages. Anything that may have been installed during the
	affected period should be considered suspect. Although we have no
	evidence of any tampering of any packages, you may wish to consider
	rebuilding any affected machine from scratch, or if that is not
	possible, rebuild your ports/packages.</li>
	</ul>

	<p>If you have any further questions about this announcement, please
	contact the <a href="mailto:FreeBSD-security@FreeBSD.org">
	FreeBSD-security@FreeBSD.org</a> mailing list, or for questions
	where public mailing list distribution is inappropriate,
	please contact the <a href="mailto:secteam@FreeBSD.org">FreeBSD
	Security Team</a>.</p>

	<p>This page will be updated as further information is known.</p>
	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/news/status/Makefile
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/news/status/Makefile (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/news/status/Makefile (revision 41355)
	@@ -1,67 +1,69 @@
	# $FreeBSD$

	.if exists(../Makefile.conf)
	.include "../Makefile.conf"
	.endif
	.if exists(../Makefile.inc)
	.include "../Makefile.inc"
	.endif

	DOCS= status.xml

	XMLDOCS= report-2001-06
	XMLDOCS+= report-2001-07
	XMLDOCS+= report-2001-08
	XMLDOCS+= report-2001-09
	XMLDOCS+= report-2001-11
	XMLDOCS+= report-2001-12-2002-01
	XMLDOCS+= report-2002-02-2002-04
	XMLDOCS+= report-2002-05-2002-06
	XMLDOCS+= report-2002-07-2002-08
	XMLDOCS+= report-2002-09-2002-10
	XMLDOCS+= report-2002-11-2002-12
	XMLDOCS+= report-2003-01-2003-02
	XMLDOCS+= report-2003-03-2003-09
	XMLDOCS+= report-2003-10-2003-12
	XMLDOCS+= report-2004-01-2004-02
	XMLDOCS+= report-2004-03-2004-04
	XMLDOCS+= report-2004-05-2004-06
	XMLDOCS+= report-2004-07-2004-12
	XMLDOCS+= report-2005-01-2005-03
	XMLDOCS+= report-2005-03-2005-06
	XMLDOCS+= report-2005-07-2005-10
	XMLDOCS+= report-2005-10-2005-12
	XMLDOCS+= report-2006-01-2006-03
	XMLDOCS+= report-2006-04-2006-06
	XMLDOCS+= report-2006-06-2006-10
	XMLDOCS+= report-2006-10-2006-12
	XMLDOCS+= report-2007-01-2007-03
	XMLDOCS+= report-2007-04-2007-06
	XMLDOCS+= report-2007-07-2007-10
	XMLDOCS+= report-2007-10-2007-12
	XMLDOCS+= report-2008-01-2008-03
	XMLDOCS+= report-2008-04-2008-06
	XMLDOCS+= report-2008-07-2008-09
	XMLDOCS+= report-2008-10-2008-12
	XMLDOCS+= report-2009-01-2009-03
	XMLDOCS+= report-2009-04-2009-09
	XMLDOCS+= report-2009-10-2009-12
	XMLDOCS+= report-2010-01-2010-03
	XMLDOCS+= report-2010-04-2010-06
	XMLDOCS+= report-2010-07-2010-09
	XMLDOCS+= report-2010-10-2010-12
	XMLDOCS+= report-2011-01-2011-03
	XMLDOCS+= report-2011-04-2011-06
	XMLDOCS+= report-2011-07-2011-09
	XMLDOCS+= report-2011-10-2011-12
	XMLDOCS+= report-2012-01-2012-03
	XMLDOCS+= report-2012-04-2012-06
	+XMLDOCS+= report-2012-07-2012-09
	+XMLDOCS+= report-2012-10-2012-12

	XSLT.DEFAULT= report.xsl

	# Install a sample <project> entry.
	DATA= report-sample.xml

	INDEXLINK= status.html

	.include "${DOC_PREFIX}/share/mk/web.site.mk"
	Index: projects/entities/en_US.ISO8859-1/htdocs/news/status/README
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/news/status/README (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/news/status/README (revision 41355)
	@@ -1,156 +1,158 @@
	Compiling status reports - best practices

	1) Call for reports
	- Are usually sent to freebsd-hackers@ CC freebsd-current@ as the lists
	with the most usual suspects for submitting reports. Forward to
	developers@ as well. Also ping individuals which are known to have
	something cooking.
	- The xml-template is at:
	http://www.freebsd.org/news/status/report-sample.xml and the generator
	CGI at: http://www.freebsd.org/cgi/monthly.cgi at the time of this
	writing. Make sure to keep them up to date with regard to categories
	to pick from and place them prominently in the CFR - otherwise people
	submit plain text reports and you have to format them yourself.

	2) In the past we usually had to extend the deadline by a week in order to
	get everybody to report. Starting early with kind reminders seems to
	help ;)

	3) The following groups have written very nice reports for the last rounds:
	portmgr@, secteam@, re@ and deb@ for the FreeBSD Foundation. Various
	conference organizers - depending on the season: BSDCan (info@bsdcan.org)
	May, EuroBSDCon (info@eurobsdcon.org) Sept, AsiaBSDCon
	(secretary@asiabsdcon.org) March. Our readers seem to value
	these reports, so we should try to get them in if at all possible.

	4) Putting it all together:
	- Copy and paste all reports in a single .xml file and use tidy(1) to get
	- it well formatted. Usually <url>'s without a description are missing
	+ it well formatted. Usually <url>s without a description are missing
	the closing "/>" which is the cause for most of the errors you will
	encounter. Sometimes other closing tags are missing.
	- Invoking tidy with the following options seems to cause the fewest
	problems: tidy -xml -i -wrap 74 -latin1 -preserve
	- Some special characters still break with that - noticed when sos@
	submits a report.
	- Remove empty "<help></help>" sections, they cause a strange looking
	newline.
	- The <body> part usually needs a hand to make it proper html. Use <a
	href=""> here, not <url>.
	- Lists come out best if you close the <p> before and start a new one
	after, like:
	... blabla:</p>
	<ul>
	<li>some item</li>
	</ul>
	<p>Some more blabla ...

	-5) After the a couple iterations of the above, wrap the whole thing in a
	+5) After a couple of iterations of the above, wrap the whole thing in a
	report template:

	<?xml version="1.0" encoding="iso-8859-1" ?>
	<!DOCTYPE report PUBLIC "-//FreeBSD//DTD FreeBSD XML Database for Status
	Report//EN"
	"http://www.FreeBSD.org/XML/www/share/xml/statusreport.dtd">
	<!-- $FreeBSD$ -->
	<report>
	<date>
	<month>July-September</month>

	<year>2006</year>
	</date>

	<section>
	<title>Introduction</title>

	<p>SUMMARY GOES HERE</p>

	<p>Thanks to all the reporters for the excellent work! We hope you
	enjoy reading.</p>
	</section>

	<category>
	<name>soc</name>

	<description>Google Summer of Code</description>
	</category>

	<category>
	<name>proj</name>

	<description>Projects</description>
	</category>

	<category>
	<name>team</name>

	<description>FreeBSD Team Reports</description>
	</category>

	<category>
	<name>net</name>

	<description>Network Infrastructure</description>
	</category>

	<category>
	<name>kern</name>

	<description>Kernel</description>
	</category>

	<category>
	<name>docs</name>

	<description>Documentation</description>
	</category>

	<category>
	<name>bin</name>

	<description>Userland Programs</description>
	</category>

	<category>
	<name>arch</name>

	<description>Architectures</description>
	</category>

	<category>
	<name>ports</name>

	<description>Ports</description>
	</category>

	<category>
	<name>misc</name>

	<description>Miscellaneous</description>
	</category>
	</report>

	Categories are subject to change obviously. They come out in the order
	as stated in the report. After another round of tidy(1) try to balance
	the categories. Put things where they belong best, retire categories
	that don't fill up, etc. Adding it to your local build and looking at
	the html helps. Make sure you have an up-to-date doc tree.

	6) Sending it out:
	- - Just prior to committing, build the html locally.
	- - Extract a text version: lynx -dump -nolist report.html > report.txt
	- - Prettify.
	- - Send out To: hackers, CC: current, stable. New email to: announce@ this
	- one needs to be approved. Find somebody who can do that before you
	- start.
	- - Commit. Also update the next due date in status.sgml and link to the
	- new report.
	+ - Commit, hooking the report XML to the build but not linking to it
	+ from anywhere. This gives time for other committers to review and
	+ suggest minor changes.
	+ - After a few days, collate and commit the changes. Also update the
	+ next due date in status.xml and link to the new report.
	- Add a news entry to head/share/xml/news.xml. Template:
	<event>
	<title>June-October, 2006 Status Report</title>

	<p>The June-October, 2006 Status Report is <a
	href="&enbase;/news/status/report-2006-06-2006-10.html">now
	available</a> with 49 entries.</p>
	</event>
	+ - Extract a text version with the command
	+ lynx -dump -nolist report.html > report.txt and prettify it.
	+ - Send out To: hackers, CC: current, stable. New email to: announce@.
	+ This needs to be approved, so find someone who can do that before you
	+ start.

	7) Repeat.
	Index: projects/entities/en_US.ISO8859-1/htdocs/news/status/report-2012-04-2012-06.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/news/status/report-2012-04-2012-06.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/news/status/report-2012-04-2012-06.xml (revision 41355)
	@@ -1,1007 +1,1007 @@
	<?xml version="1.0" encoding="iso-8859-1" ?>
	<!DOCTYPE report PUBLIC "-//FreeBSD//DTD FreeBSD XML Database for Status
	Report//EN" "http://www.FreeBSD.org/XML/www/share/xml/statusreport.dtd">
	<!-- $FreeBSD$ -->
	<report>
	<date>
	<month>April-June</month>

	<year>2012</year>
	</date>

	<section>
	<title>Introduction</title>

	<p>This report covers &os;-related projects between April and June
	2012. This quarter was highlighted by having a new Core Team
	elected, which took office on July 11th to start its work with a
	relatively high number of new members. Note that this is the
	- second of the three reports planned for 2012.</p>
	+ second of the four reports planned for 2012.</p>

	<p>Thanks to all the reporters for the excellent work! This report
	contains 17 entries and we hope you enjoy reading it.</p>

	<p>Please note that the deadline for submissions covering the period
	between July and December 2012 is February 17th, 2013.</p>
	</section>

	<category>
	<name>proj</name>

	<description>Projects</description>
	</category>

	<category>
	<name>bin</name>

	<description>Userland Programs</description>
	</category>

	<category>
	<name>team</name>

	<description>&os; Team Reports</description>
	</category>

	<category>
	<name>kern</name>

	<description>Kernel</description>
	</category>

	<category>
	<name>net</name>

	<description>Network Infrastructure</description>
	</category>

	<category>
	<name>docs</name>

	<description>Documentation</description>
	</category>

	<category>
	<name>arch</name>

	<description>Architectures</description>
	</category>

	<category>
	<name>ports</name>

	<description>Ports</description>
	</category>

	<category>
	<name>misc</name>

	<description>Miscellaneous</description>
	</category>

	<project cat='arch'>
	<title>&os;/arm on ARM Fast Models Simulator for Cortex-A15 MPCore
	Processor</title>

	<contact>
	<person>
	<name>
	<given>Zbigniew</given>
	<common>Bodek</common>
	</name>
	<email>zbb@semihalf.com</email>
	</person>

	<person>
	<name>
	<given>Rafal</given>
	<common>Jaworowski</common>
	</name>
	<email>raj@semihalf.com</email>
	</person>

	<person>
	<name>
	<given>Tomasz</given>
	<common>Nowicki</common>
	</name>
	<email>tn@semihalf.com</email>
	</person>
	</contact>

	<links>
	<url
	href="http://www.arm.com/products/processors/cortex-a/cortex-a15.php">Cortex-A15 product page</url>
	<url
	href="http://www.arm.com/products/tools/models/fast-models.php">Fast Models product page</url>
	</links>

	<body>
	<p>ARM Fast Models is platform which helps software developers
	debug systems in parallel with SoC design, speeding up and
	improving system development. This work is bringing up &os; on
	ARM Fast Models system based on ARM Cortex-A15 and peripheral
	components. It works in single user mode, using a compiled-in
	kernel RAM disk minimal root file system.</p>

	<p>Current &os; support includes:</p>

	<ul>
	<li>L1, L2 cache, Branch Predictor</li>
	<li>Dual-core (SMP) support setup in WB cache mode</li>
	<li>Cortex-A15 integrated Generic Timer</li>
	<li>Drivers for ARM peripheral components:
	<ul>
	<li>PL011 UART controller</li>
	<li>PL390 GIC - Generic Interrupt Controller</li>
	<li>SP804 Dual Timer</li>
	</ul>
	</li>
	</ul>

	<p>Next steps:</p>

	<ul>
	<li>Quad-core (SMP) support</li>
	<li>Multi-user mode</li>
	</ul>
	</body>
	</project>

	<project cat='kern'>
	<title>&os;/at91 Improvements</title>

	<contact>
	<person>
	<name>
	<given>Warner</given>
	<common>Losh</common>
	</name>
	<email>imp@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url
	href="http://wiki.freebsd.org/FreeBSDAtmel">&os; on ATMEL AT91 Wiki</url>
	</links>

	<body>
	<p>&os;'s Atmel support has languished for some time. A number of
	improvements were urgently needed as demand for newer SoCs has
	materialized. New SoC support is not hard, but it does wind up
	copying a lot of code. I have started down the path to make it
	easier to do. I had planned on making it table driven. But
	then I discovered with dts files that Atmel was producing.</p>

	<p>So, I plan on moving to using Atmel's <tt>.dsti</tt> files, or
	variations on them. They have .dsti files for all the AT91SAM9
	parts. This should allow us to support new SoCs and boards
	faster.</p>

	<p>However, there are some challenges with this approach. Pin
	multiplexing seems undefined in Atmel's dts file. Only a few of
	the devices are well-defined at the present time. And the
	encoding seems to be immature.</p>

	<p>So we have a target-rich port that is quite ripe for
	refactoring.</p>
	</body>

	<help>
	<task>Update the base system libfdt to a version that supports
	include.</task>
	<task>Write a <tt>.dtsi</tt> for Atmel AT91RM9200.</task>
	<task>Write <tt>.dti</tt> files for all supported boards.</task>
	<task>Help sort out the pin multiplexing issue.</task>
	<task>Refactor existing board files to make new ones easier in the
	interim.</task>
	<task>Knock yourself out and implement board support for new
	CPUs.</task>
	</help>
	</project>

	<project cat='misc'>
	<title>BSD-Day 2012</title>

	<contact>
	<person>
	<name>
	<given>Gábor</given>
	<common>Páli</common>
	</name>
	<email>pgj@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url href="http://bsdday.eu/2012">BSD-Day 2012 web site</url>
	<url
	href="http://www.youtube.com/playlist?list=PL13D5471D8ECF08C9">Video recordings of the talks at YouTube</url>
	<url
	href="https://picasaweb.google.com/116452848880746560170/BSDDay2012?authkey=Gv1sRgCN3twLrxuaeongE">Event photo album</url>
	</links>

	<body>
	<p>For this year, we moved the time of the event earlier by six
	months, so it was held on May 5, 2012 and it was co-located with
	the Austrian Linuxweeks (Linuxwochen Österreich) in Vienna.
	We had many sponsors, like the freshly joined &os; Foundation,
	iXsystems, FreeBSDMall, BSD Magazine, allBSD.de Projekt, that
	enabled us to continue our previously launched series of
	multi-project BSD developer summits all around Central
	Europe.</p>

	<p>To kick off, there was a "stammtisch" (local beer meetup)
	organized in the downtown of Vienna, at Kolar on the Friday
	evening before the event — as usual. Then it was followed
	by the event on Saturday that brought many interesting topics
	from the world of &os;, OpenBSD and NetBSD: running NetBSD as an
	embedded system for managing VOIP applications, introduction to
	the Capsicum security framework, relayd(8), the load balancer
	and proxy solution for OpenBSD, status update of the
	developments around the &os; ports tree, using DVCSs in clouds,
	firewalling with pfSense, and mfsBSD. Please consult the links
	in the report for the details.</p>
	</body>
	</project>

	<project cat='team'>
	<title>The &os; Core Team</title>

	<contact>
	<person>
	<name>
	<given>Core Team</given>
	</name>
	<email>core@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url
	href="http://docs.FreeBSD.org/cgi/mid.cgi?1342030291.6001.80.camel">Announcement</url>
	</links>

	<body>
	<p>The &os; Project is pleased to announce the completion of the
	2012 Core Team election. The &os; Core Team acts as the
	project's "Board of Directors" and is responsible for approving
	new src committers, resolving disputes between developers,
	appointing sub-committees for specific purposes (security
	officer, release engineering, port managers, webmaster, et
	cetera), and making any other administrative or policy decisions
	as needed. The Core Team has been elected by &os; developers
	every 2 years since 2000.</p>

	<p>Peter Wemm rejoins the Core Team after a two-year hiatus, with
	new members Thomas Abthorpe, Gavin Atkinson, David Chisnall,
	Attilio Rao and Martin Wilke joining incumbents John Baldwin,
	Konstantin Belousov and Hiroki Sato.</p>

	<p>The complete newly elected core team is:</p>

	<ul>
	<li>Thomas Abthorpe <tabthorpe@FreeBSD.org></li>
	<li>Gavin Atkinson <gavin@FreeBSD.org></li>
	<li>John Baldwin <jhb@FreeBSD.org></li>
	<li>Konstantin Belousov <kib@FreeBSD.org></li>
	<li>David Chisnall <theraven@FreeBSD.org></li>
	<li>Attilio Rao <attilio@FreeBSD.org></li>
	<li>Hiroki Sato <hrs@FreeBSD.org></li>
	<li>Peter Wemm <peter@FreeBSD.org></li>
	<li>Martin Wilke <miwi@FreeBSD.org></li>
	</ul>

	<p>The new Core Team would like to thank outgoing members Wilko
	Bulte, Brooks Davis, Warner Losh, Pav Lucistnik, Colin Percival
	and Robert Watson for their service over the past two (and in
	some cases, many more) years.</p>

	<p>The Core Team would also especially like to thank Dag-Erling
	Smørgrav for running the election.</p>
	</body>
	</project>

	<project cat='docs'>
	<title>The &os; Japanese Documentation Project</title>

	<contact>
	<person>
	<name>
	<given>Hiroki</given>
	<common>Sato</common>
	</name>
	<email>hrs@FreeBSD.org</email>
	</person>

	<person>
	<name>
	<given>Ryusuke</given>
	<common>Suzuki</common>
	</name>
	<email>ryusuke@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url href="http://www.FreeBSD.org/ja/">Japanese &os; Web Page</url>
	<url href="http://www.jp.FreeBSD.org/doc-jp/">The &os; Japanese Documentation Project Web Page</url>
	</links>

	<body>
	<p>Our translation work has slightly moved on to handbook from the
	<tt>www/ja</tt> (CVS) or <tt>htdocs</tt> (SVN) subtree, since
	almost translated web page contents were updated to the latest
	English counterparts.</p>

	<p>During this period, we translated the 8.3-RELEASE announcement
	and published it in a timely manner. Newsflash and some other
	updates in the English version were also translated as soon as
	possible.</p>

	<p>For &os; Handbook, translation work of the "cutting-edge" and
	"printing" sections have been completed. Some updates in the
	"linuxemu" and "serialcomms" section were done. At this moment,
	"bsdinstall", "cutting-edge", "desktop", "install",
	"introduction", "kernelconfig", "mirrors", "multimedia",
	"pgpkeys", "ports", "printing", and "x11" chapters are
	synchronized with the English versions.</p>
	</body>

	<help>
	<task>Further translation work of outdated documents in
	<tt>ja_JP.eucJP</tt> subtree.</task>
	</help>
	</project>

	<project cat='team'>
	<title>&os; Documentation Project</title>

	<contact>
	<person>
	<email>freebsd-doc@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url href="http://wiki.freebsd.org/GoogleCodeIn/2011Status"/>
	<url href="http://wiki.freebsd.org/201208DevSummit"/>
	<url href="http://wiki.freebsd.org/DocIdeaList"/>
	</links>

	<body>
	<p>We continue to make progress in committing the work produced as
	part of Google Code-In 2011; an overview of the status is at <a
	href="http://wiki.freebsd.org/GoogleCodeIn/2011Status">http://wiki.freebsd.org/GoogleCodeIn/2011Status</a>.
	Doc committers and GCIN mentors are encouraged to go through the
	list and help shepherd outstanding tasks into the tree.</p>

	<p>We are planning a full day of Documentation Summit on the day
	preceding the August 2012 DevSummit in Cambridge, UK. This
	follows a successful DocSummit day held at BSDCan in May 2012.
	Further details are available at: <a
	href="http://wiki.freebsd.org/201208DevSummit">http://wiki.freebsd.org/201208DevSummit</a>.</p>

	<p>A doc sprint took place over IRC (<tt>#bsddocs on</tt> EFnet)
	in early July, setting out plans for reviving the marketing team
	and a strong desire for a new, more organized website.</p>

	<p>A lot of progress and momentum has built up with creating and
	updating documentation and website content over the last few
	months. Also read the doceng report for the recent
	infrastructure improvements.</p>

	<p>Anyone wishing to help with this effort is welcome to join us
	and say hello either on the freebsd-doc mailing list, or
	<tt>#bsddocs</tt> on EFnet IRC.</p>
	</body>

	<help>
	<task>Review the website content and remove outdated parts or
	update when applicable.</task>

	<task>Go through the doc idea list on the wiki and start working
	them out.</task>
	</help>
	</project>

	<project cat='bin'>
	<title>&os; Services Control (fsc)</title>

	<contact>
	<person>
	<name>
	<given>Tom</given>
	<common>Rhodes</common>
	</name>
	<email>trhodes@FreeBSD.org</email>
	</person>
	</contact>

	<body>
	<p>FSC has been moved into the ports system (see
	<tt>sysutils/fsc</tt>) and continues to improve outside of the
	ports tree. Some interesting work is being done in the area of
	services control, system boot, and a simplification of the
	process. Stay tuned for more information in status reports that
	follow.</p>
	</body>

	<help>
	<task>Test, test, test. Feedback is really important to this
	project.</task>
	</help>
	</project>

	<project cat='ports'>
	<title>&os; Haskell Ports</title>

	<contact>
	<person>
	<name>
	<given>Gábor</given>
	<common>PÁLI</common>
	</name>
	<email>pgj@FreeBSD.org</email>
	</person>

	<person>
	<name>
	<given>Ashish</given>
	<common>SHUKLA</common>
	</name>
	<email>ashish@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url
	href="http://wiki.freebsd.org/Haskell">&os; Haskell wiki page</url>
	<url
	href="https://github.com/freebsd-haskell/freebsd-haskell/">&os; Haskell ports repository</url>
	</links>

	<body>
	<p>We are proud to announce that the &os; Haskell Team has updated
	the Haskell Platform to 2012.2.0.0, GHC to 7.4.1 as well as
	updated existing ports to their latest stable versions. We also
	added a number of new Haskell ports, and their count in &os;
	Ports tree is now 336.</p>
	</body>

	<help>
	<task>Test GHC to work with clang/LLVM.</task>
	<task>Add an option to the <tt>lang/ghc</tt> port to be able to
	build it with already installed GHC instead of requiring a
	separate GHC bootstrap tarball.</task>
	<task>Commit pending Haskell ports to the &os; Ports tree.</task>
	<task>Add more ports to the Ports Collection.</task>
	</help>
	</project>

	<project cat='ports'>
	<title>KDE/&os;</title>

	<contact>
	<person>
	<name>
	<given>KDE</given>
	<common>FreeBSD</common>
	</name>
	<email>kde@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url href="http://FreeBSD.kde.org">KDE/&os; home page</url>
	<url href="http://FreeBSD.kde.org/area51.php">area51</url>
	</links>

	<body>
	<p>The team has made many releases and upstreamed many fixes and
	patches. The latest round of releases include:</p>

	<ul>
	<li>KDE SC: 4.8.3, 4.8.4 (in ports) and 4.8.95 (in area51)</li>
	<li>Qt: 4.8.1, 4.8.2</li>
	<li>PyQt: 4.9.1; SIP: 4.13.2; QScintilla 2.6.1</li>
	<li>KDevelop: 2.3.1; KDevPlatform: 1.3.1</li>
	<li>Calligra: 2.4.2, 2.4.3</li>
	<li>Amarok: 2.5.90 (in area51)</li>
	<li>CMake: 2.8.8</li>
	<li>Digikam (and KIPI-plugins): 2.6.0</li>
	</ul>

	<p>As a result — according to PortScout — kde@ has 393
	ports, of which 91% are up-to-date.</p>

	<p>The team is always looking for more testers and porters so
	please contact us and visit our home page.</p>
	</body>

	<help>
	<task>Test KDE SC 4.8.95.</task>
	<task>Test KDE PIM 4.8.95.</task>
	<task>Update out-of-date ports, see <a
	- href="http://portscout.org/kde@freebsd.org.html">PortScout</a> for a
	+ href="http://portscout.FreeBSD.org/kde@freebsd.org.html">PortScout</a> for a
	list.</task>
	</help>
	</project>

	<project cat='net'>
	<title>Multipath TCP (MPTCP) for &os;</title>

	<contact>
	<person>
	<name>
	<given>Nigel</given>
	<common>Williams</common>
	</name>
	<email>njwilliams@swin.edu.au</email>
	</person>

	<person>
	<name>
	<given>Lawrence</given>
	<common>Stewart</common>
	</name>
	<email>lastewart@swin.edu.au</email>
	</person>

	<person>
	<name>
	<given>Grenville</given>
	<common>Armitage</common>
	</name>
	<email>garmitage@swin.edu.au</email>
	</person>
	</contact>

	<links>
	<url href="http://caia.swin.edu.au/newtcp/mptcp/"/>
	<url
	href="http://tools.ietf.org/html/draft-ietf-mptcp-multiaddressed-09">TCP Extensions for Multipath Operation with Multiple Addresses (draft)</url>
	<url
	href="http://mptcp.info.ucl.ac.be/">"MultiPath TCP — Linux Kernel implementation" home page</url>
	</links>

	<body>
	<p>Work is underway to create an IETF draft-compatible Multipath
	TCP implementation for the &os; kernel.</p>

	<p>A key goal of the project is to create a research platform to
	investigate a range of multipath related transport issues
	including congestion control, retransmission strategy and packet
	scheduling policy. We also aim to provide full interoperability
	with the Linux kernel implementation being developed at
	Université catholique de Louvain.</p>

	<p>We expect to release code and results at the project's home
	page as it progresses.</p>
	</body>
	</project>

	<project cat='net'>
	<title>SMP-Friendly pf(4)</title>

	<contact>
	<person>
	<name>
	<given>Gleb</given>
	<common>Smirnoff</common>
	</name>
	<email>glebius@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url
	href="http://svnweb.freebsd.org/base/projects/pf/head/">Project SVN branch</url>

	<url
	href="http://lists.freebsd.org/pipermail/freebsd-pf/2012-June/006643.html">Alpha announcement email thread</url>
	</links>

	<body>
	<p>The project is aimed at moving the <tt>pf(4)</tt> packet filter
	out of single mutex, as well as in general improving of its &os;
	port.</p>

	<p>The project is near its finish, the code is planned to go into
	head after more testing and benchmarking. If you are interested
	in details, please see the corresponding email thread on
	freebsd-pf (see links).</p>
	</body>

	<help>
	<task>Rewrite the <tt>pf(4)</tt> <tt>ioctl()</tt> interface so
	that it does not utilize in-kernel structures. That would make
	ABI more stable and ease future development.</task>
	</help>
	</project>

	<project cat='ports'>
	<title>Portbuilder</title>

	<contact>
	<person>
	<name>
	<given>David</given>
	<common>Naylor</common>
	</name>
	<email>naylor.b.david@gmail.com</email>
	</person>
	</contact>

	<links>
	<url
	href="https://github.com/DragonSA/portbuilder">Git Repository</url>
	<url
	href="https://github.com/DragonSA/portbuilder/blob/0.1.5.2/README">README</url>
	<url
	href="https://github.com/DragonSA/portbuilder/blob/0.1.5.2/TODO">TODO</url>
	</links>

	<body>
	<p>Since the last update there has been 2 feature releases and 4
	bug-fix releases. A highlight of the changes made:</p>

	<ul>
	<li>Support has been added for:</li>
	<ul>
	<li><tt>-j</tt>: controlling concurrency per stage</li>
	<li>pkgng: next generation package manager</li>
	<li>installing packages via repository</li>
	<li>dynamic defaults (loaded from
	<tt>/etc/make.conf</tt>)</li>
	<li>new options framework (aka OptionsNG)</li>
	</ul>

	<li>Some of the fixes include:</li>
	<ul>
	<li>correct assertions</li>
	<li>correct build logic</li>
	<li>retry when kevent receives <tt>EINTR</tt></li>
	<li>correctly detecting installed ports</li>
	<li>many fixes in the build logic</li>
	</ul>
	</ul>

	<p>A benchmark was run timing portbuilder against a standard ports
	build of KDE (<tt>x11/kde4</tt>) in a clean <tt>chroot(8)</tt>
	environment. Portbuilder achieved a build time of 2:21:16
	compared to ports build time of 4:47:21 for an decreased build
	time of 51% from using portbuilder.</p>
	</body>
	</project>

	<project cat='team'>
	<title>The &os; Port Management Team</title>

	<contact>
	<person>
	<name>
	<given>Thomas</given>
	<common>Abthorpe</common>
	</name>
	<email>portmgr-secretary@FreeBSD.org</email>
	</person>

	<person>
	<name>
	<given>Port</given>
	<common>Management Team</common>
	</name>
	<email>portmgr@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url href="http://www.FreeBSD.org/ports/" />
	<url
	href="http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributing-ports/" />
	<url href="http://portsmon.freebsd.org/index.html" />
	<url href="http://www.freebsd.org/portmgr/index.html" />
	<url href="http://blogs.freebsdish.org/portmgr/" />
	<url href="http://www.twitter.com/freebsd_portmgr/" />
	<url href="http://www.facebook.com/portmgr" />
	</links>

	<body>
	<p>The ports tree slowly approaches 24,000 ports. The PR count
	still is close to 1200.</p>

	<p>In Q2 we added 7 new committers and took in one commit bit for
	safe keeping.</p>

	<p>The Ports Management team have been running -exp runs on an
	ongoing basis, verifying how base system updates may affect the
	ports tree, as well as providing QA runs for major ports
	updates. Of note, -exp runs were done for:</p>

	<ul>
	<li>automake update</li>
	<li>cmake update</li>
	<li>xorg update</li>
	<li>png update</li>
	<li>Fix make reinstall</li>
	<li>Implement <tt>USE_QT4</tt> in <tt>bsd.ports.mk</tt></li>
	<li>KDE4 update</li>
	<li>XFCE4 update</li>
	<li>bison update</li>
	<li>perl5.14 as default</li>
	<li>ruby1.9 as default</li>
	<li>ruby1.8 update</li>
	<li>bsdsort regression test</li>
	</ul>

	<p>A lot of focus during this period was put into getting the
	ports tree into a ready state for &os; 9.1.</p>

	<p>A significant step forward was the implementation of
	OptionsNG.</p>

	<p>A record number of Port Managers attended BSDCan 2012, with
	five being present to partake in the week of events, culminating
	in a portmgr PR closing session that dealt with 18 PRs in one
	day. You can see a group photo at <a
	href="http://www.facebook.com/portmgr"/>. While you are
	there, please click on the "Like" icon.</p>

	<p>Beat Gaetzi has been doing ongoing tests with the ports tree to
	ensure a smooth transition from CVS to Subversion. The tree was
	successfully migrated the weekend of June 14, 2012.</p>
	</body>

	<help>
	<task>Looking for help getting <a
	href="http://wiki.freebsd.org/PortsAndClang">ports to build with
	clang</a>.</task>

	<task>Looking for help fixing <a
	href="http://wiki.freebsd.org/PortsFailingOnCurrent">ports
	broken on CURRENT</a>. (List needs updating, too.)</task>

	<task>Looking for help with <a
	href="http://wiki.freebsd.org/PortsBrokenOnTier2Architectures">Tier-2
	architectures</a>.</task>

	<task><a
	href="http://wiki.freebsd.org/PortsBrokenBySrcChanges">ports
	broken by src changes</a>.</task>

	<task><a
	href="http://wiki.freebsd.org/PortsFailingOnPointyhat">ports
	failing on pointyhat</a>.</task>

	<task><a
	href="http://wiki.freebsd.org/PortsFailingOnPointyhatWest">ports
	failing on pointyhat-west</a>.</task>

	<task><a href="http://wiki.freebsd.org/Trybroken">ports that are
	marked as <tt>BROKEN</tt></a>.</task>

	<task><a href="http://wiki.freebsd.org/WhenDidThatPortBreak">When
	did that port break</a>?</task>

	<task>Most ports PRs are assigned, we now need to focus on
	testing, committing and closing.</task>
	</help>
	</project>

	<project cat='ports'>
	<title>Redports</title>

	<contact>
	<person>
	<name>
	<given>Bernhard</given>
	<common>Froehlich</common>
	</name>
	<email>decke@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url href="http://www.redports.org/"/>
	</links>

	<body>
	<p>There was good progress in the last half a year and a lot of
	support from different parties to make redports a stable and
	fast service.</p>

	<p>A long known security concern within tinderbox was raised at
	the BSD-Day in Vienna which was addressed by beat. That
	improves security and isolation of the concurrent running jobs a
	lot and gives me peace of mind.</p>

	<p>We also recently got two beefy machines from the &os;
	Foundation which increases computing power a lot. So no more
	backlogs and your jobs finish much quicker.</p>

	<p>But as usual now that we have enough power I was able to make
	another promise come true and integrated Ports QAT functionality
	into redports. Ports QAT was an automated services that did a
	buildtest after each commit to the official &os; ports tree. If
	a build fails it sends out mails and logfiles to the committer.
	That finds bad commits quickly and allows the committer to fix
	it before the first user notices. The former service stopped
	about 2 years ago and we had no proper replacement for that task
	at hand. Now that this is fully integrated into redports it
	also gives us all the nice benefits of a common platform.</p>
	</body>

	<help>
	<task>Automatic build incoming patches from Ports PRs in redports
	and send results to GNATS database.</task>

	<task>People want an GCC testing environment on redports where all
	ports are build with <tt>lang/gcc47</tt>. To make that happen
	we need to patch the ports framework to handle that and
	correctly bootstrap with base GCC. This also gives us the
	possibility to build all our binary packages with a modern gcc
	and is easy to use for regular users. Contributors?</task>
	</help>
	</project>

	<project cat='bin'>
	<title>Replacing the Regular Expression Code</title>

	<contact>
	<person>
	<name>
	<given>Gábor</given>
	<common>Kövesdán</common>
	</name>
	<email>gabor@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url href="http://laurikari.net/tre/">TRE home page</url>
	</links>

	<body>
	<p>It has been decided to implement the optimizations and
	extensions as a more isolated layer and not directly in TRE
	itself. Since the last report there has been some progress in
	this direction and the code has been significantly refactored.
	It does not work yet in this new form but it is close to a
	working state. Apart from this, the multiple pattern matching
	needs some debugging and some minor features are missing.</p>
	</body>

	<help>
	<task>Finish multiple pattern heuristic regex matching.</task>
	<task>Implement GNU-specific regex extensions.</task>
	<task>Test performance, standard-compliance and correct
	behavior.</task>
	</help>
	</project>

	<project cat='ports'>
	<title>BSD-licensed Sort Utility (GNU sort(1) Replacement)</title>

	<contact>
	<person>
	<name>
	<given>Oleg</given>
	<common>Moskalenko</common>
	</name>
	<email>oleg.moskalenko@citrix.com</email>
	</person>

	<person>
	<name>
	<given>Gábor</given>
	<common>Kövesdán</common>
	</name>
	<email>gabor@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url
	href="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/bsdsort/">&os; port of BSD sort(1)</url>
	<url
	href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/sort.html">IEEE Std 1003.1-2008 sort(1) specification</url>
	</links>

	<body>
	<p>BSD <tt>sort(1)</tt> has been made the default sort utility in
	10-CURRENT. It is compatible with the latest GNU
	<tt>sort(1)</tt>, version 8.15, except that the multi-threaded
	mode is not enabled by default.</p>
	</body>

	<help>
	<task>When the track record of the BSD <tt>sort(1)</tt> allows,
	remove GNU <tt>sort(1)</tt> from -CURRENT.</task>

	<task>Improve reliability of the multi-threaded sort and
	investigate the possibility of making it the default compilation
	mode.</task>

	<task>Investigate possibility of factoring out the sort
	functionality into a standalone library so that other utilities
	can also make use of it.</task>
	</help>
	</project>

	<project cat='ports'>
	<title>Xorg on &os;</title>

	<contact>
	<person>
	<name>
	<given>Martin</given>
	<common>Wilke</common>
	</name>
	<email>miwi@FreeBSD.org</email>
	</person>

	<person>
	<name>
	<given>Koop</given>
	<common>Mast</common>
	</name>
	<email>kwm@FreeBSD.org</email>
	</person>

	<person>
	<name>
	<given>Niclas</given>
	<common>Zeising</common>
	</name>
	<email>zeising@FreeBSD.org</email>
	</person>

	<person>
	<name>
	<given>Eitan</given>
	<common>Adler</common>
	</name>
	<email>eadler@FreeBSD.org</email>
	</person>
	</contact>

	<links>
	<url href="http://wiki.freebsd.org/Xorg"/>
	<url href="http://trillian.chruetertee.ch/ports/browser/trunk"/>
	</links>

	<body>
	<p>During the beginning of this period, an update to the xorg
	distribution for &os; was made, dubbed xorg 7.5.2. This update
	included a new flag, <tt>WITH_NEW_XORG</tt>, to get a more
	recent xorg distribution for those with modern hardware. To get
	KMS support for recent Intel graphics chipsets <tt>WITH_KMS</tt>
	must also be set. This requires a recent &os; 10-CURRENT or
	&os; 9-STABLE.</p>
	</body>

	<help>
	<task>Switch to use FreeGLUT instead of libGLUT, since the latter
	is old and has there is no upstream support or releases any
	more. Work on this is mostly done.</task>

	<task>Update the xorg distribution to what is in the development
	repository. The xorg project recently did a new release, and
	the development repository contains this release. It needs more
	testing before it can be merged, and a CFT was sent out in the
	beginning of June. Work on this is ongoing.</task>

	<task>Decide how to handle the new and old xorg distributions. In
	recent xorg, a lot of legacy driver support has been dropped,
	therefore we need to maintain two xorg distributions to not
	loose a lot of hardware drivers. Currently, this is done by
	setting the flag <tt>WITH_NEW_XORG</tt> in
	<tt>/etc/make.conf</tt>, but a more practical solution is
	needed. This is especially important since the flag is not very
	user friendly, and since there currently will be no official
	packages for the new distribution.</task>
	</help>
	</project>
	</report>
	Index: projects/entities/en_US.ISO8859-1/htdocs/news/status/report-2012-07-2012-09.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/news/status/report-2012-07-2012-09.xml (nonexistent)
	+++ projects/entities/en_US.ISO8859-1/htdocs/news/status/report-2012-07-2012-09.xml (revision 41355)
	@@ -0,0 +1,713 @@
	+<?xml version="1.0" encoding="iso-8859-1" ?>
	+<!DOCTYPE report PUBLIC "-//FreeBSD//DTD FreeBSD XML Database for Status Report//EN" "http://www.FreeBSD.org/XML/www/share/xml/statusreport.dtd" >
	+<!-- $FreeBSD$ -->
	+<report>
	+ <date>
	+ <month>July-September</month>
	+
	+ <year>2012</year>
	+ </date>
	+
	+ <section>
	+ <title>Introduction</title>
	+
	+ <p>This report covers &os;-related projects between July and
	+ September 2012. This is the third of the four reports planned for
	+ 2012.</p>
	+
	+ <p>Highlights from this quarter include successful participation in
	+ Google Summer of Code, major work in areas of the source and
	+ ports trees, and a Developer Summit attended by over 30
	+ developers.</p>
	+
	+ <p>Thanks to all the reporters for the excellent work! This report
	+ contains 12 entries and we hope you enjoy reading it.</p>
	+ </section>
	+
	+ <category>
	+ <name>proj</name>
	+
	+ <description>Projects</description>
	+ </category>
	+
	+ <category>
	+ <name>team</name>
	+
	+ <description>&os; Team Reports</description>
	+ </category>
	+
	+ <category>
	+ <name>kern</name>
	+
	+ <description>Kernel</description>
	+ </category>
	+
	+ <category>
	+ <name>docs</name>
	+
	+ <description>Documentation</description>
	+ </category>
	+
	+ <category>
	+ <name>ports</name>
	+
	+ <description>Ports</description>
	+ </category>
	+
	+ <category>
	+ <name>misc</name>
	+
	+ <description>Miscellaneous</description>
	+ </category>
	+
	+ <category>
	+ <name>soc</name>
	+
	+ <description>&os; in Google Summer of Code</description>
	+ </category>
	+
	+ <project cat='proj'>
	+ <title>&os; on Altera FPGAs</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Brooks</given>
	+ <common>Davis</common>
	+ </name>
	+ <email>brooks@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Robert</given>
	+ <common>Watson</common>
	+ </name>
	+ <email>rwatson@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Bjoern</given>
	+ <common>Zeeb</common>
	+ </name>
	+ <email>bz@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://www.cl.cam.ac.uk/research/security/ctsrd/">
	+ CTSRD Project</url>
	+
	+ <url
	+ href="http://www.cl.cam.ac.uk/research/security/ctsrd/cheri.html">
	+ CHERI</url>
	+ </links>
	+
	+ <body>
	+ <p>In the course of developing the <a
	+ href="http://www.cl.cam.ac.uk/research/security/ctsrd/cheri.html">
	+ CHERI processor</a> as part of the <a
	+ href="http://www.cl.cam.ac.uk/research/security/ctsrd/">CTSRD
	+ project</a> SRI International's Computer Science Laboratory and
	+ the University of Cambridge Computer Laboratory have developed
	+ support for a number of general purpose IP cores for Altera FPGAs
	+ including the Altera Triple Speed Ethernet (ATSE) MAC core, the
	+ Altera University Program SD Card core, and the Altera JTAG UART.
	+ We have also added support for general access to memory mapped
	+ devices on the Avalon bus via the avgen bus. We have implemented
	+ both nexus and flattened device tree (FDT) attachments for these
	+ devices.</p>
	+
	+ <p>In addition to these softcore we have developed support for
	+ the Terasic multi-touch LCD and are working to provide support
	+ for the Terasic HDMI Transmitter Daughter Card. Both of these
	+ work with common development and/or reference boards for Altera
	+ FPGAs. They do require additional IP cores which we plan to
	+ release to the open source community in the near future.</p>
	+
	+ <p>With exception of the ATSE and HDMI drivers we have merged all
	+ of these changes to &os;-CURRENT. We anticipate that these
	+ drivers will be useful for users who with to run &os; on either
	+ hard or soft core CPUs on Altera FPGAs.</p>
	+
	+ <p>This work has been sponsored by DARPA, AFRL, and Google.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='proj'>
	+ <title>Native iSCSI Target</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Edward Tomasz</given>
	+ <common>Napierała</common>
	+ </name>
	+ <email>trasz@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ </links>
	+
	+ <body>
	+ <p>During the July-September time period, the Native iSCSI Target
	+ project was officially started under sponsorship from the &os;
	+ Foundation. Before the end of September I've written ctld(8), the
	+ userspace part of the target, responsible for handling
	+ configuration, accepting incoming connections, performing
	+ authentication and iSCSI parameter negotiation, and handing off
	+ connections to the kernel. For the time being, I've reused some
	+ parts of protocol-handling code from the istgt project; since
	+ ctld(8) only handles the Login phase, the code can be rewritten
	+ in a much simpler and shorter way in the future.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='proj'>
	+ <title>Parallel rc.d execution</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Kuan-Chung</given>
	+ <common>Chiu</common>
	+ </name>
	+ <email>buganini@gmail.com</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Kilian</given>
	+ </name>
	+ <email>kklimek@uos.de</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="https://github.com/buganini/rcexecr" />
	+ <url href="https://github.com/kil/rcorder" />
	+ </links>
	+
	+ <body>
	+ <p>There are two implementations to make rc.d execution parallel.
	+ Compared to Kil's rcorder, rcexecr brings more concurrence and
	+ provides more flexibility than older "early_late_divider"
	+ mechanism but require more invasive /etc patch. Both
	+ implementations have switch to toggle parallel execution. Further
	+ modification/integration needs more discussion.</p>
	+ </body>
	+
	+ <help>
	+ <task>Refine /etc/rc.d/* to eliminate unnecessary waiting.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='team'>
	+ <title>&os; Bugbusting Team</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Eitan</given>
	+ <common>Adler</common>
	+ </name>
	+ <email>eadler@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Gavin</given>
	+ <common>Atkinson</common>
	+ </name>
	+ <email>gavin@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Oleksandr</given>
	+ <common>Tymoshenko</common>
	+ </name>
	+ <email>gonzo@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://www.FreeBSD.org/support.html#gnats" />
	+ <url href="https://wiki.freebsd.org/BugBusting" />
	+ </links>
	+
	+ <body>
	+ <p>In August, Eitan Adler (eadler@) and Oleksandr Tymoshenko
	+ (gonzo@) joined the Bugmeister team. At the same time, Remko
	+ Lodder and Volker Werth stepped down. We extend our thanks to
	+ Volker and Remko for their work in the past, and welcome
	+ Oleksandr and Eitan. Eitan and Oleksandr have been working hard
	+ on migrating from GNATS, and have made significant progress on
	+ evaluating new software, and creating scripts to export data
	+ from GNATS.</p>
	+
	+ <p>The bugbusting team continue work on trying to make the
	+ contents of the GNATS PR database cleaner, more accessible and
	+ easier for committers to find and resolve PRs, by tagging PRs
	+ to indicate the areas involved, and by ensuring that there is
	+ sufficient info within each PR to resolve each issue.</p>
	+
	+ <p>As always, anybody interested in helping out with the PR
	+ queue is welcome to join us in #freebsd-bugbusters on EFnet. We
	+ are always looking for additional help, whether your interests
	+ lie in triaging incoming PRs, generating patches to resolve
	+ existing problems, or simply helping with the database
	+ housekeeping (identifying duplicate PRs, ones that have already
	+ been resolved, etc). This is a great way of getting more
	+ involved with &os;!</p>
	+ </body>
	+
	+ <help>
	+ <task>Further research into tools suitable to replace
	+ GNATS.</task>
	+
	+ <task>Get more users involved with triaging PRs as they come
	+ in.</task>
	+
	+ <task>Assist committers with closing PRs.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='team'>
	+ <title>The &os; Core Team</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Core Team</given>
	+ </name>
	+ <email>core@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <body>
	+ <p>Along with the change in the Core Team membership, several
	+ related roles changed hands. Gabor Pali assumed the role of core
	+ secretary from Gavin Atkinson, and David Chisnall replaced Robert
	+ Watson as liaison to the &os; Foundation. The Core Team felt
	+ there was no longer a need for a formal security team liaison, so
	+ that role was retired.</p>
	+
	+ <p>In the third quarter, the Core Team granted access for 2 new
	+ committers and took 2 commit bits into safekeeping.</p>
	+
	+ <p>The Core Team worked with the Port Management Team and Cluster
	+ Administrators to set a date to stop providing CVS exports for
	+ the ports repository, which is February 28, 2013. In the
	+ meantime, the CVS export for 9.1-RELEASE was restored.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='team'>
	+ <title>&os; Foundation</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Deb</given>
	+ <common>Goodkin</common>
	+ </name>
	+ <email>deb@FreeBSDFoundation.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url
	+ href="http://www.freebsdfoundation.org/press/2012Jul-newsletter.shtml">
	+ Semi-annual newsletter</url>
	+ </links>
	+
	+ <body>
	+ <p>The Foundation hosted and sponsored the Cambridge &os;
	+ developer summit in August 2012.</p>
	+
	+ <p>We were represented at the following conferences: OSCON July
	+ 2012, Texas LinuxFest, and Ohio LinuxFest.</p>
	+
	+ <p>We negotiated/supervised Foundation funded projects:
	+ Distributed Security Audit Logging, Capsicum Component
	+ Framework, Native iSCSI Target Scoping, and Growing UFS
	+ Filesystems Online.</p>
	+
	+ <p>We negotiated, supervised, and funded hardware needs for
	+ &os; co-location centers.</p>
	+
	+ <p>We welcomed Kirk McKusick to our board of directors. He took
	+ over the responsibility of managing our investments.</p>
	+
	+ <p>We visited companies to discuss their &os; use and to help
	+ facilitate collaboration with the Project.</p>
	+
	+ <p>We managed &os; vendor community mailing list and
	+ meetings.</p>
	+
	+ <p>We created a high quality &os; 9 brochure to help promote
	+ &os;.</p>
	+
	+ <p>Published our <a
	+ href="http://www.freebsdfoundation.org/press/2012Jul-newsletter.shtml">
	+ semi-annual newsletter</a> that highlighted Foundation
	+ funded projects, travel grants for
	+ developers, conferences sponsored and other ways the Foundation
	+ supported the &os; Project.</p>
	+
	+ <p>We hired a technical writer to help with &os;
	+ marketing/promotional material.</p>
	+
	+ <p>We began work on redesigning our website.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='kern'>
	+ <title>&os; on ARMv6/ARMv7</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>freebsd-arm mailing list</given>
	+ </name>
	+ <email>freebsd-arm@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ </links>
	+
	+ <body>
	+ <p>Support for ARMv6 and ARMv7 architecture has been merged from
	+ project branch to HEAD. This code covers the following parts:
	+ <ul>
	+ <li>General ARMv6/ARMv7 kernel bits (pmap, cache, assembler
	+ routines, etc...)</li>
	+ <li>ARM Generic Interrupt Controller driver</li>
	+ <li>Improved thread-local storage for cpus >=ARMv6</li>
	+ <li>Driver for SMSC LAN95XX and LAN8710A ethernet controllers</li>
	+ <li>Marvell MV78x60 support (multiuser, ARMADA XP kernel config)</li>
	+ <li>TI OMAP4 and AM335x support (multiuser, no GPU or graphics
	+ support, kernel configs for Pandaboard and Beaglebone)</li>
	+ <li>LPC32x0 support (multiuser, frame buffer works with SSD1289
	+ LCD controller. Embedded Artists EA3250 kernel config)</li>
	+ </ul>
	+ </p>
	+
	+ <p>This work was a result of a joint effort by many people,
	+ including but not limited to: Grzegorz Bernacki (gber@),
	+ Aleksander Dutkowski, Ben R. Gray (bgray@), Olivier Houchard
	+ (cognet@), Rafal Jaworowski (raj@) and Semihalf team, Tim
	+ Kientzle (kientzle@), Jakub Wojciech Klama (jceel@), Ian Lepore
	+ (ian@), Warner Losh (imp@), Damjan Marion (dmarion@), Lukasz
	+ Plachno, Stanislav Sedov (stas@), Mark Tinguely and Andrew
	+ Turner (andrew@). Thanks to all, who contributed by
	+ submitting code, testing and giving valuable advice.</p>
	+ </body>
	+
	+ <help>
	+ <task>More hardware bring-ups and more drivers</task>
	+
	+ <task>Finish SMP support</task>
	+
	+ <task>VFP/NEON support</task>
	+ </help>
	+ </project>
	+
	+ <project cat='docs'>
	+ <title>The &os; Japanese Documentation Project</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Hiroki</given>
	+ <common>Sato</common>
	+ </name>
	+ <email>hrs@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Ryusuke</given>
	+ <common>Suzuki</common>
	+ </name>
	+ <email>ryusuke@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://www.FreeBSD.org/ja/">Japanese &os; Web
	+ Page</url>
	+
	+ <url href="http://www.jp.FreeBSD.org/doc-jp/">The &os; Japanese
	+ Documentation Project Web Page</url>
	+ </links>
	+
	+ <body>
	+ <p>Web page (htdocs): Newsflash and some other updates in the
	+ English version were translated to keep them up-to-date.
	+ Especially "security incident on &os; infrastructure" was
	+ translated and published in a timely manner.</p>
	+
	+ <p>&os; Handbook: Big update in the "advanced-networking". With
	+ this update, merging translation results from the handbook in the
	+ local repository of Japanese documentation project into the main
	+ repository was completed. This chapter is still outdated and
	+ needs more work. The other sections have also constantly been
	+ updated. Especially, new subsection "Using pkgng for Binary
	+ Package Management" was added to "ports" section and "Using
	+ subversion" subsection was added to "mirrors" section.</p>
	+
	+ <p>Article: Some progress was made in "Writing &os; Problem
	+ Reports" and "Writing &os; Problem Reports" articles.</p>
	+ </body>
	+
	+ <help>
	+ <task>Further translation work of outdated documents in the
	+ <tt>ja_JP.eucJP</tt> subtree.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='ports'>
	+ <title>KDE/&os;</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>KDE</given>
	+ <common>FreeBSD</common>
	+ </name>
	+ <email>kde@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://FreeBSD.kde.org">KDE/&os; home page</url>
	+ <url href="http://FreeBSD.kde.org/area51.php">area51</url>
	+ </links>
	+
	+ <body>
	+ <p>The KDE/&os; team have continued to improve the experience of
	+ KDE software and Qt under &os;. The latest round of improvements
	+ include:
	+ <ul>
	+ <li>Fixes for building Qt with libc++ and C++11</li>
	+
	+ <li>Fixes for Solid-related crashes</li>
	+
	+ <li>Fix battery detection in battery monitor plasmoid</li>
	+ </ul>
	+ </p>
	+
	+ <p>The team has also made many releases and upstreamed many fixes
	+ and patches. The latest round of releases include:
	+ <ul>
	+ <li>KDE SC: 4.9.1 (area51) and 4.8.4 (ports)</li>
	+
	+ <li>Qt: 4.8.3 (area51)</li>
	+
	+ <li>PyQt: 4.9.4 (area51); QScintilla 2.6.2 (area51); SIP:
	+ 4.13.3 (area51)</li>
	+
	+ <li>Calligra: 2.4.3, 2.5-RC2, 2.5.0. 2.5.1, 2.5.2 (area51) and
	+ 2.4.3, 2.5.0, 2.5.1 (ports)</li>
	+
	+ <li>Amarok: 2.6.0 (area51)</li>
	+
	+ <li>CMake: 2.8.9 (ports)</li>
	+
	+ <li>Digikam (and KIPI-plugins): 2.7.0, 2.8.0, 2.9.0 (area51)
	+ and 2.7.0, 2.9.0 (ports)</li>
	+
	+ <li>QtCreator: 2.6.0-beta (area51)</li>
	+
	+ <li>many smaller ports</li>
	+ </ul>
	+ </p>
	+
	+ <p>The team is always looking for more testers and porters so
	+ please contact us at kde@FreeBSD.org and visit our home page at
	+ <a href="http://FreeBSD.kde.org">http://FreeBSD.kde.org</a>.</p>
	+ </body>
	+
	+ <help>
	+ <task>Please see 2012 Q4 Status Report</task>
	+
	+ <task>Updating out-of-date ports, see
	+ <a href="http://portscout.FreeBSD.org/kde@freebsd.org.html">PortScout</a>
	+ for a list</task>
	+ </help>
	+ </project>
	+
	+ <project cat='ports'>
	+ <title>Ports Collection</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Thomas</given>
	+ <common>Abthorpe</common>
	+ </name>
	+ <email>portmgr-secretary@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Port</given>
	+ <common>Management Team</common>
	+ </name>
	+ <email>portmgr@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://www.FreeBSD.org/ports/" />
	+
	+ <url href="http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributing-ports/" />
	+
	+ <url href="http://portsmon.freebsd.org/index.html" />
	+
	+ <url href="http://www.freebsd.org/portmgr/index.html" />
	+
	+ <url href="http://blogs.freebsdish.org/portmgr/" />
	+
	+ <url href="http://www.twitter.com/freebsd_portmgr/" />
	+
	+ <url href="http://www.facebook.com/portmgr" />
	+ </links>
	+
	+ <body>
	+ <p>The ports tree approaches 24,000 ports, while the PR count
	+ still is above 1000.</p>
	+
	+ <p>In Q3 we added 2 new committers and took in two commits bit
	+ for safe keeping.</p>
	+
	+ <p>The Ports Management team had performed multiple -exp runs,
	+ verifying how base system updates may affect the ports tree,
	+ as well as providing QA runs for major ports updates.</p>
	+
	+ <p>Beat Gaetzi took over the role of sending out fail mails, a
	+ role that Pav Lucistnik had previously held. Beat also undertook
	+ the task of converting the Ports tree from CVS to Subversion.</p>
	+
	+ <p>Florent Thoumie stepped down from his role on portmgr, he was
	+ instrumental in maintaining the legacy pkg_* code.</p>
	+ </body>
	+
	+ <help>
	+ <task>Most ports PRs are assigned, we now need to focus on
	+ testing, committing and closing.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='misc'>
	+ <title>&os; Developer Summit, Cambridge, UK</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Robert</given>
	+ <common>Watson</common>
	+ </name>
	+ <email>rwatson@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="https://wiki.freebsd.org/201208DevSummit">Developer
	+ Summit Home Page</url>
	+ </links>
	+
	+ <body>
	+ <p>In the end of August, there was an "off-season" Developer
	+ Summit held in Cambridge, UK at the University of Cambridge
	+ Computer Laboratory. This was a three-day event, with a
	+ documentation summit scheduled for the day before. The three
	+ days of the main event were split into three sessions, with two
	+ tracks in each. Some of them even involved ARM developers from
	+ the neighborhoods which proven to be productive, and led to
	+ further engagement between the &os; community and ARM.</p>
	+
	+ <p>The schedule was finalized on the first day, spawning a
	+ plethora of topics to discuss, followed by splitting into groups.
	+ A short summary from each of the groups was presented in the
	+ final session and then published at the event's home page on the
	+ &os; wiki. This summit contributed greatly to arriving to a
	+ tentative plan for throwing the switch to make clang the default
	+ compiler on HEAD. This was further discussed on the mailing list,
	+ and has now happened, bringing us one big step closer to a
	+ GPL-free &os; 10. As part of the program, an afternoon of short
	+ talks from researchers in the Cambridge Computer Laboratory
	+ involved either operating systems work in general or &os; in
	+ particular. Robert Watson showed off a tablet running &os; on a
	+ MIPS-compatible soft-core processor running on an Altera
	+ FPGA.</p>
	+
	+ <p>In association with the event, a dinner was hosted by St. John's
	+ college and co-sponsored by Google and the &os; Foundation. The
	+ day after the conference, a trip was organized to Bletchley Park,
	+ which was celebrating Turing's centenary in 2012.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='soc'>
	+ <title>Google Summer of Code 2012</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>
	+ </given>
	+ <common>&os; Summer of Code Administrators</common>
	+ </name>
	+ <email>soc-admins@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://www.freebsd.org/projects/summerofcode.html">
	+ FreeBSD Summer of Code page</url>
	+
	+ <url href="https://wiki.freebsd.org/SummerOfCode2012">Summer of
	+ Code 2012 projects</url>
	+ </links>
	+
	+ <body>
	+ <p>Over the Summer of 2012, &os; were once again granted a
	+ place to participate in the Google Summer of Code program. We
	+ received a total of 32 project proposals, and were ultimately
	+ given 15 slots for university students to work on open source
	+ projects mentored by existing &os; developers.</p>
	+
	+ <p>We were able to accept a wide spread of proposals, covering
	+ both the base system and the ports infrastructure. We had
	+ students working on file systems, file integrity checking, and
	+ parallelization in the ports collection. Students worked on
	+ kernel infrastructure, including one project to support CPU
	+ resource limits on users, processes and jails, and one student
	+ improving the BSD callout(9) and timer facilities. Two students
	+ worked on the ARM platform, widely used in embedded systems and
	+ smart phones; one student worked on a significant cleanup and
	+ improvements to the Flattened Device Tree implementation code,
	+ while the other ported &os; to the OMAP3-based BeagleBoard-xM
	+ device. One student worked on improving IPv6 support in
	+ userland tools, whilst another worked on BIOS emulation for the
	+ BHyVE BSD-licensed hypervisor, new in &os; 10. Other students
	+ worked on EFI boot support, userland lock profiling and an
	+ automated kernel crash reporting system.</p>
	+
	+ <p>Overall, a significant proportion of the code produced has
	+ or will be integrated into &os; in one form or another. All of
	+ the work is available in our Summer Of Code Subversion
	+ repository, and some of the work has already been merged back
	+ into the main repositories.</p>
	+
	+ <p>&os; is once again grateful to Google for being selected to
	+ participate in Summer of Code 2012.</p>
	+ </body>
	+ </project>
	+</report>

	Property changes on: projects/entities/en_US.ISO8859-1/htdocs/news/status/report-2012-07-2012-09.xml
	___________________________________________________________________
	Added: svn:eol-style
	## -0,0 +1 ##
	+native
	\ No newline at end of property
	Added: svn:keywords
	## -0,0 +1 ##
	+FreeBSD=%H
	\ No newline at end of property
	Added: svn:mime-type
	## -0,0 +1 ##
	+text/xml
	\ No newline at end of property
	Index: projects/entities/en_US.ISO8859-1/htdocs/news/status/report-2012-10-2012-12.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/news/status/report-2012-10-2012-12.xml (nonexistent)
	+++ projects/entities/en_US.ISO8859-1/htdocs/news/status/report-2012-10-2012-12.xml (revision 41355)
	@@ -0,0 +1,1456 @@
	+<?xml version="1.0" encoding="iso-8859-1" ?>
	+<!DOCTYPE report PUBLIC "-//FreeBSD//DTD FreeBSD XML Database for Status Report//EN" "http://www.FreeBSD.org/XML/www/share/xml/statusreport.dtd" >
	+<!-- $FreeBSD$ -->
	+<report>
	+ <date>
	+ <month>October-December</month>
	+
	+ <year>2012</year>
	+ </date>
	+
	+ <section>
	+ <title>Introduction</title>
	+
	+ <p>This report covers &os;-related projects between October and
	+ December 2012. This is the last of four reports planned for 2012.</p>
	+
	+ <p>Highlights from this status report include a very successful
	+ EuroBSDCon 2012 conference and associated FreeBSD Developer Summit,
	+ both held in Warsaw, Poland. Other highlights are several projects
	+ related to the FreeBSD port to the ARM architecture, extending
	+ support for platforms, boards and CPUs, improvements to the
	+ performance of the pf(4) firewall, and a new native iSCSI target.</p>
	+
	+ <p>Thanks to all the reporters for the excellent work! This report
	+ contains 27 entries and we hope you enjoy reading it.</p>
	+
	+ <p>The deadline for submissions covering the period between January
	+ and March 2013 is April 21st, 2013.</p>
	+ </section>
	+
	+ <category>
	+ <name>proj</name>
	+
	+ <description>Projects</description>
	+ </category>
	+
	+ <category>
	+ <name>bin</name>
	+
	+ <description>Userland Programs</description>
	+ </category>
	+
	+ <category>
	+ <name>team</name>
	+
	+ <description>&os; Team Reports</description>
	+ </category>
	+
	+ <category>
	+ <name>kern</name>
	+
	+ <description>Kernel</description>
	+ </category>
	+
	+ <category>
	+ <name>docs</name>
	+
	+ <description>Documentation</description>
	+ </category>
	+
	+ <category>
	+ <name>arch</name>
	+
	+ <description>Architectures</description>
	+ </category>
	+
	+ <category>
	+ <name>ports</name>
	+
	+ <description>Ports</description>
	+ </category>
	+
	+ <category>
	+ <name>misc</name>
	+
	+ <description>Miscellaneous</description>
	+ </category>
	+
	+ <project cat='arch'>
	+ <title>&os; on BeagleBone</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Tim</given>
	+ <common>Kientzle</common>
	+ </name>
	+ <email>kientzle@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Oleksandr</given>
	+ <common>Tymoshenko</common>
	+ </name>
	+ <email>gonzo@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Damjan</given>
	+ <common>Marion</common>
	+ </name>
	+ <email>dmarion@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Brett</given>
	+ <common>Wynkoop</common>
	+ </name>
	+ <email>wynkoop@wynn.com</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ </links>
	+
	+ <body>
	+ <p>&os; on BeagleBone is benefiting from the general work on ARM
	+ stability being done by many people, and is proving to be a nice
	+ testbed for our ARMv7 support. All ongoing work is happening now
	+ directly in -CURRENT and we expect it to be in pretty good shape
	+ by the time 10.0 ships.</p>
	+
	+ <p>The network driver is now pretty stable; the system should be
	+ useful as a small network device.</p>
	+
	+ <p>Occasional system snapshots are being built and advertised for
	+ people to test. Ask on freebsd-arm@ if you'd like to try the
	+ newest one.</p>
	+ </body>
	+
	+ <help>
	+ <task>We need someone to finish the USB driver. Ask if you'd like
	+ to take this over.</task>
	+
	+ <task>MMCSD performance is still rather poor.</task>
	+
	+ <task>There's been discussion of how to improve the GPIO
	+ configuration and pinmux handling to simplify hardware
	+ experimentation. If we had more people to help build drivers, we
	+ could start supporting some of the BeagleBone capes.</task>
	+
	+ <task>Mostly we just need people to use it and report any issues
	+ they encounter.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='proj'>
	+ <title>BHyVe</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Neel</given>
	+ <common>Natu</common>
	+ </name>
	+ <email>neel@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Peter</given>
	+ <common>Grehan</common>
	+ </name>
	+ <email>grehan@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="https://wiki.FreeBSD.org/BHyVe" />
	+ <url href="http://www.bhyve.org/" />
	+ </links>
	+
	+ <body>
	+ <p>BHyVe is a type-2 hypervisor for &os;/amd64 hosts with Intel
	+ VT-x and EPT CPU support. The bhyve project branch was merged
	+ into CURRENT on Jan 18. Work is progressing on performance, ease
	+ of use, AMD SVM support, and being able to run non-&os; operating
	+ systems.</p>
	+ </body>
	+
	+ <help>
	+ <task>1. Booting Linux/*BSD/Windows</task>
	+
	+ <task>2. Moving the codebase to a more modular design consisting
	+ of a small base and loadable modules</task>
	+
	+ <task>3. Various hypervisor features such as suspend/resume/live
	+ migration/sparse disk support</task>
	+ </help>
	+ </project>
	+
	+ <project cat='bin'>
	+ <title>BSD-licenced patch(1)</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Pedro</given>
	+ <common>Giffuni</common>
	+ </name>
	+ <email>pfg@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Gabor</given>
	+ <common>Kovesdan</common>
	+ </name>
	+ <email>gabor@FreeBSD.org</email>
	+ </person>
	+ <person>
	+ <name>
	+ <given>Xin</given>
	+ <common>Li</common>
	+ </name>
	+ <email>delphij@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://code.google.com/p/bsd-patch/">Home for BSD
	+ patch (deprecated)</url>
	+ </links>
	+
	+ <body>
	+ <p>&os; has been using for a while a very old version of GNU
	+ patch that is partially under the GPLv2. The original GNU patch
	+ utility is based on an initial implementation by Larry Wall that
	+ was not actually copyleft. OpenBSD did many enhancements to an
	+ older non-copyleft version of patch, this version was later
	+ adopted and further refined by DragonFlyBSD and NetBSD but there
	+ was no centralized development of the tool and &os; kept working
	+ independently. In less than a week we took the version in
	+ DragonFlyBSD and adapted the &os; enhancements to make it behave
	+ nearer to the version used natively in &os;. Most of the work was
	+ done by Pedro Giffuni, adapting patches from sepotvin@ and ed@,
	+ and additional contributions were done by Christoph Mallon, Gabor
	+ Kovesdan and Xin Li. As a result of this we now have a new
	+ version of patch committed in head/usr.bin/patch that you can try
	+ by using WITH_BSD_PATCH in your builds. The new patch(1) doesn't
	+ support the &os;-specific -I and -S options which don't seem
	+ necessary. In GNU patch -I actually means 'ignore whitespaces'
	+ and we now support it too.</p>
	+ </body>
	+
	+ <help>
	+ <task>Testing. A lot more testing.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='kern'>
	+ <title>Common Flash Interface (CFI) driver improvements</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Brooks</given>
	+ <common>Davis</common>
	+ </name>
	+ <email>brooks@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ </links>
	+
	+ <body>
	+ <p>The Common Flash Interface provides a common programming
	+ interface for a wide range of NOR flash devices commonly found in
	+ embedded systems. I have developed a number of improvements to
	+ the cfi(4) device when used on Intel StrataFlash parts.
	+ Unnecessary erase cycles are now avoided, devices that require
	+ single word writes only write changed words, and multi-word
	+ writes are supported for Intel and Sharp devices. Additionally
	+ the timeout code has been reworked and no longer imposes unneeded
	+ latency on operations taking less than 100us. With all of these
	+ changes streaming write speed has improved by more than an order
	+ of magnitude. Once these changes are reviewed they will be
	+ committed to HEAD.</p>
	+
	+ <p>This work was sponsored by DARPA and AFRL.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='proj'>
	+ <title>Native iSCSI Target</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Edward Tomasz</given>
	+ <common>Napierała</common>
	+ </name>
	+ <email>trasz@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ </links>
	+
	+ <body>
	+ <p>During the October-December time period, the Native iSCSI
	+ Target project progressed to the working prototype stage. Most of
	+ this time was spent writing kernel-based part, an iSCSI frontend
	+ to the CAM Target Layer. The frontend handles iSCSI Full Feature
	+ phase after ctld(8) hands off the connection. The istgt-derived
	+ code in ctld(8) was rewritten from scratch; now it's much shorter
	+ and more readable. The ctladm(8) utility gained iSCSI-specific
	+ subcommands to handle tasks such as listing iSCSI sessions or
	+ forcing disconnection. The target works correctly with the &os;
	+ initiator.</p>
	+ </body>
	+ </project>
	+
	+ <project cat="proj">
	+ <title>NFS Version 4</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Rick</given>
	+ <common>Macklem</common>
	+ </name>
	+ <email>rmacklem@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <body>
	+ <p>The NFSv4.1 client, including support for pNFS for the Files
	+ Layout only, has now been committed to head/current. Work on
	+ NFSv4.1 server support has just been started and will hopefully
	+ be ready for head/current this summer. The client side disk
	+ caching of delegated files is progressing and the code is under
	+ projects/nfsv4-packrats in the subversion repository. Someone is
	+ working on server side referrals and, as such, I hope this might
	+ make it into 10.0 as well.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='proj'>
	+ <title>Unprivileged install and image creation</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Brooks</given>
	+ <common>Davis</common>
	+ </name>
	+ <email>brooks@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ </links>
	+
	+ <body>
	+ <p>In order to make it easier to build releases and embedded
	+ system disk images I have been adding infrastructure to allow
	+ the install and packaging stages to the &os; build progress to
	+ run without root privilege. To this end I have added two
	+ options to the toplevel build system: The
	+ <tt>-DDB_FROM_SRC</tt> option allows the install to proceed
	+ when the required set of passwd and group entires does not
	+ match the host system. The <tt>-DNO_ROOT</tt> option causes
	+ files to be installed as the running user and for metadata such
	+ as owner, group, suid bits, and file flags to be logged in a
	+ <tt>${DESTDIR}/METALOG</tt> file.</p>
	+
	+ <p>This work required the import of NetBSD's <tt>mtree</tt> and
	+ the addition of a number of features from NetBSD to
	+ <tt>install</tt>. I have added all &os; features to NetBSD's
	+ <tt>mtree</tt> and imported it as <tt>nmtree</tt>. Before &os;
	+ 10.0 is released I will replace our version. I have also added
	+ all required features to <tt>install</tt>. Changes to
	+ <tt>makefs</tt> were required to parse the contents of the
	+ <tt>METALOG</tt> file.</p>
	+
	+ <p>These new features required importing new versions of the
	+ pwcache(3) and vis(3) APIs from NetBSD so those portions of
	+ libc.</p>
	+
	+ <p>In addition to modifying build infrastructure to use the new
	+ features of <tt>mtree</tt> and <tt>install</tt>. I corrected a
	+ number of cases of files being installed by programs other than
	+ <tt>install</tt> or being installed more than once. A few known
	+ instances of duplicate directories in the output exist, but the
	+ results are usable in some contexts.</p>
	+
	+ <p>I plan to MFC these changes as far back as the stable/8
	+ branch to make it possible to build all supported releases
	+ without root privilege.</p>
	+
	+ <p>This work was sponsored by DARPA and AFRL.</p>
	+ </body>
	+
	+ <help>
	+ <task>Add support for <tt>-DNO_ROOT</tt> to
	+ <tt>src/release/Makefile</tt> so that releases can be built
	+ without root privilege.</task>
	+
	+ <task>Create a tool to install partition tables and file system
	+ images in disk image files without the use of <tt>mdctl</tt>,
	+ <tt>gpart</tt>, and <tt>dd</tt>.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='kern'>
	+ <title>SMP-Friendly pf(4)</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Gleb</given>
	+ <common>Smirnoff</common>
	+ </name>
	+ <email>glebius@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ </links>
	+
	+ <body>
	+ <p>The project is aimed at moving the pf(4) packet filter out of
	+ a single mutex, as well as in general improving of the &os; port.
	+ The project has reached its main goal. The pf(4) is no longer
	+ covered by single mutex and contention on network stack on pf(4)
	+ is now very low. The code is production ready. The projects/pf
	+ branch had been merged to the head branch and will be available
	+ in 10.0-RELEASE.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='arch'>
	+ <title>&os; on Raspberry Pi</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Oleksandr</given>
	+ <common>Tymoshenko</common>
	+ </name>
	+ <email>gonzo@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ </links>
	+
	+ <body>
	+ <p>&os; is running on Raspberry Pi and supports the following
	+ peripherals:</p>
	+ <ul>
	+ <li>USB controller</li>
	+ <li>SDHC controller</li>
	+ <li>Network</li>
	+ <li>Framebuffer (HDMI and composite)</li>
	+ <li>GPIO</li>
	+ <li>VCHI interface</li>
	+ </ul>
	+ <p>Videocore tests (OpenGL, video decoding, audio, display access)
	+ work with current VCHI driver implementation.</p>
	+ </body>
	+
	+ <help>
	+ <task>Add DMA mode support to USB driver. Some proof-of-concept
	+ code is done but more work required to finish it.</task>
	+
	+ <task>Re-implement VCHI driver with more &os;-friendly
	+ locking.</task>
	+
	+ <task>Implement more drivers: SPI, PWM, audio.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='proj'>
	+ <title>pxe_http -- booting &os; from apache</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Sean</given>
	+ <common>Bruno</common>
	+ </name>
	+ <email>sbruno@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url
	+ href="http://svnweb.FreeBSD.org/base/user/sbruno/pxe_http_head/">
	+ svn repo of project</url>
	+ </links>
	+
	+ <body>
	+ <p>Currently works with VirtualBox VMs and Apache 2.2 port.</p>
	+ </body>
	+
	+ <help>
	+ <task>Lots and lots of compile warnings exist with clang and gcc.
	+ This really needs to be investigated.</task>
	+
	+ <task>Better support for other webservers. Currently needs Apache
	+ to work.</task>
	+
	+ <task>Needs another pass at basic documentation. Current
	+ documentation is actually quite good from the original</task>
	+
	+ <task>Network stack needs audit. I'm not sure if the
	+ HTTP/TCP/UDP/IP code is original or based on something
	+ else.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='proj'>
	+ <title>UEFI</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Benno</given>
	+ <common>Rice</common>
	+ </name>
	+ <email>benno@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="https://wiki.FreeBSD.org/UEFI" />
	+
	+ <url href="http://svnweb.FreeBSD.org/base/projects/uefi/" />
	+ </links>
	+
	+ <body>
	+ <p>There is code in the projects/uefi branch that can build a
	+ working 64-bit loader for UEFI. This loader can load a kernel and
	+ boot to a mountroot prompt on a serial console on a system with
	+ ≤ 1GB of RAM. Full multiuser has not yet been tested. Work is
	+ progressing towards having a working syscons. The issue
	+ preventing boot on systems with > 1GB of RAM has not yet been
	+ found. UEFI-compatible boot media can be generated using in-tree
	+ tools, however there are issues with detecting the CD filesystem
	+ and using it as the load default. The 64-bit UEFI loader can load
	+ a 32-bit kernel but currently cannot hand over to it due to a
	+ lack of code to switch to 32-bit mode. Further research is
	+ required into Secure Boot.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='bin'>
	+ <title>bsdconfig(8)</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Devin</given>
	+ <common>Teske</common>
	+ </name>
	+ <email>dteske@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url
	+ href="http://svnweb.FreeBSD.org/base/head/usr.sbin/bsdconfig/">
	+ Dev Tree</url>
	+
	+ <url href="http://freshports.org/sysutils/bsdconfig/">Ports
	+ Tree</url>
	+
	+ <url href="http://druidbsd.sf.net/download/bsdconfig/">Dev
	+ Depot</url>
	+ </links>
	+
	+ <body>
	+ <p>bsdconfig(8) is actively being developed in HEAD under the
	+ WITH_BSDCONFIG build-requirement. Snapshots are occasionally
	+ taken and made available through the ports system to make testing
	+ on 9.0-RELEASE or higher easier on the testers. Currently HEAD is
	+ far beyond the version 0.7.3 sitting in ports. Upcoming changes
	+ will push this to version 0.8 bringing in the necessary
	+ frameworks required for in-depth package management and
	+ distribution maintenance (read: one step closer to full 1.0
	+ release).</p>
	+ </body>
	+ </project>
	+
	+ <project cat='team'>
	+ <title>&os; Core Team</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Core Team</given>
	+ </name>
	+ <email>core@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <body>
	+ <p>In the fourth quarter, the Core Team granted access for 7 new
	+ committers, and took 1 commit bit in for safekeeping.</p>
	+
	+ <p>The Core Team oversaw the response to the security incident in
	+ November in cooperation with the security team, port managers,
	+ and cluster administrators. For more information on the fallouts
	+ and response see the
	+ <a href="http://www.FreeBSD.org/news/2012-compromise.html">
	+ official announcement</a>. As a result, 9.1-RELEASE was delayed
	+ until late December and was released with a limited set of binary
	+ packages. The Core Team continues to work with developers to
	+ rebuild, review, and restore the package building infrastructure
	+ along with redports/QAT.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='team'>
	+ <title>&os; Documentation Engineering</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Glen</given>
	+ <common>Barber</common>
	+ </name>
	+ <email>gjb@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Marc</given>
	+ <common>Fonvieille</common>
	+ </name>
	+ <email>blackend@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Gábor</given>
	+ <common>Kövesdán</common>
	+ </name>
	+ <email>gabor@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Hiroki</given>
	+ <common>Sato</common>
	+ </name>
	+ <email>hrs@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://www.FreeBSD.org/internal/doceng.html">
	+ Documentation Engineering Team Charter</url>
	+ </links>
	+
	+ <body>
	+ <p>The translations/, projects/ and user/ directories of the doc
	+ repository have been opened with the announced policies in
	+ effect. These branches are now actively used for translations
	+ work, editing the upcoming printed version of the Handbook,
	+ and some doc infrastructure improvements.</p>
	+
	+ <p>The next phase of the infrastructure improvements is in
	+ progress. It will migrate to real XML tools (with the exception
	+ of Jade) for validation and rendering. At the same time, the
	+ DocBook schema will be updated to 4.5.</p>
	+
	+ <p>After long discussions, Google Analytics has been enabled on
	+ &os;.org webpages but access to statistical data has to be
	+ solicited from the Documentation Engineering Team on an
	+ individual and one time basis.</p>
	+
	+ <p>Since July, we have added two doc committers and one
	+ translator.</p>
	+ </body>
	+
	+ <help>
	+ <task>Help the ongoing work on printed edition of the
	+ Handbook.</task>
	+
	+ <task>Finish the migration to XML tools.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='team'>
	+ <title>&os; Foundation</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Deb</given>
	+ <common>Goodkin</common>
	+ </name>
	+ <email>deb@FreeBSDFoundation.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ </links>
	+
	+ <body>
	+ <p>A strong year-end <a
	+ href="http://www.FreeBSDFoundation.org/announcements.shtml#fundraising">
	+ fundraising campaign</a> led to the raising $770,000 in 2012.
	+ Thank you to everyone who made a donation to support &os;!</p>
	+
	+ <p>We published our <a
	+ href="http://www.FreeBSDFoundation.org/press/2012Dec-newsletter.shtml">
	+ year-end newsletter</a> that highlighted everything we did to
	+ support the &os; Project and community during the second half of
	+ the year.</p>
	+
	+ <p>We were a Gold Sponsor for EuroBSDCon. We also attended the
	+ conference and developer summit. Erwin Lansing organized and
	+ chaired the Ports and Package Summit and Vendor Summit at
	+ EuroBSDCon 2012. We attended MeetBSD developer summit
	+ November 2012.</p>
	+
	+ <p>George Neville-Neil organized and the Foundation sponsored the
	+ Bay Area Vendor Summit November 2012. We were represented at
	+ LISA.</p>
	+
	+ <p>Kirk McKusick taught a tutorial and gave a keynote at EuroBSDCon
	+ 2012, and Justin Gibbs gave a talk at ZFS Day, October 2012.</p>
	+
	+ <p>We talked to DNS server software vendors and participated in
	+ discussions on our DNS implementation, specifically with regard
	+ to DNSSEC validation, at CENTR Tech September 2012 (Amsterdam,
	+ the Netherlands) and EuroBSDCon.</p>
	+
	+ <p>We visited companies to discuss their &os; use and to help
	+ facilitate collaboration with the Project.</p>
	+
	+ <p>Robert Watson published <a href="http://queue.acm.org/detail.cfm?id=2430732">
	+ ACM Queue and Communications of the ACM: A decade of OS
	+ access-control extensibility</a> and Kirk McKusick
	+ published <a href="http://queue.acm.org/detail.cfm?id=2367378">
	+ ACM Queue and Communications of the ACM: Disks from the
	+ Perspective of a File System</a>.</p>
	+
	+ <p>We negotiated/supervised Foundation funded projects: porting
	+ &os; to the Efika ARM platform, Capsicum Component Framework,
	+ Native iSCSI Target implementation, and EUFI.</p>
	+
	+ <p>We negotiated/supervised/funded hardware needs in &os;
	+ co-location centers.</p>
	+
	+ <p>Many board members provided support for recovery efforts
	+ following the security compromise of &os;.org systems in late
	+ 2012.</p>
	+
	+ <p>We completed negotiation and provided legal counsel for the
	+ new website privacy policy for the &os; Project.</p>
	+
	+ <p>We are now an industrial partner in the
	+ Cambridge/Imperial/Edinburgh EPSRC REMS project on the Rigorous
	+ Engineering of Mainstream Systems.</p>
	+
	+ <p>We coordinated the Foundation's discussion of Jira/Java;
	+ conclusion, will continue to be supportive of OpenJDK and not
	+ restart proprietary JDK support.</p>
	+
	+ <p>We implemented a donor management database to help with our
	+ fundraising efforts. We also began working on automating the
	+ donation process.</p>
	+
	+ <p>We started the Faces of &os; Series where we share the story of
	+ a Foundation grant recipient periodically. This allows us to
	+ spotlight people who received Foundation funding to work on
	+ development projects, run conferences, travel to conferences,
	+ and advocate for &os;.</p>
	+
	+ <p>We hired two technical staff members.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='team'>
	+ <title>Postmaster</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>David</given>
	+ <common>Wolfskill</common>
	+ </name>
	+ <email>postmaster@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ </links>
	+
	+ <body>
	+ <p>The postmaster team has expanded, with the addition of
	+ Florian Smeets (flo@FreeBSD.org).</p>
	+
	+ <p>We have implemented a Mailman "handler" to drop duplicate
	+ messages when both copies are sent to the same list (under
	+ both the "long" (e.g., "freebsd-current") and "short"
	+ (e.g., "current") names).</p>
	+
	+ <p>We have created several new mailing lists:</p>
	+ <ul>
	+ <li>freebsd-course: educational course on &os;</li>
	+ <li>freebsd-numerics: Discussions of high quality
	+ implementation of libm functions.</li>
	+ <li>freebsd-snapshots: &os; Development Snapshot
	+ Announcements</li>
	+ <li>freebsd-tcltk: &os;-specific Tcl/Tk discussions</li>
	+ </ul>
	+
	+ <p>We have also removed old mailing lists:</p>
	+ <ul>
	+ <li>freebsd-binup</li>
	+ <li>freebsd-www (merged into freebsd-doc)</li>
	+ </ul>
	+ </body>
	+ </project>
	+
	+ <project cat='kern'>
	+ <title>AMD GPUs kernel-modesetting support</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Alexander</given>
	+ <common>Kabaev</common>
	+ </name>
	+ <email>kan@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Jean-Sébastien</given>
	+ <common>Pédron</common>
	+ </name>
	+ <email>dumbbell@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Konstantin</given>
	+ <common>Belousov</common>
	+ </name>
	+ <email>kib@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="https://wiki.FreeBSD.org/AMD_GPU">Project status on
	+ the wiki</url>
	+
	+ <url href="http://people.FreeBSD.org/~kib/misc/ttm.1.patch">
	+ Initial TTM port</url>
	+ </links>
	+
	+ <body>
	+ <p>Jean-Sébastien Pédron started to port the AMD GPUs driver
	+ from Linux to &os; 10-CURRENT in January 2013. This work is based
	+ on a previous effort by Alexander Kabaev. Konstantin Belousov
	+ provided the initial port of the TTM memory manager.</p>
	+
	+ <p>As of this writing, the driver is building but the tested
	+ device fails to attach.</p>
	+
	+ <p>Status updates will be posted to the &os; wiki.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='kern'>
	+ <title>Unmapped I/O</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Jeff</given>
	+ <common>Roberson</common>
	+ </name>
	+ <email>jeff@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Konstantin</given>
	+ <common>Belousov</common>
	+ </name>
	+ <email>kib@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url
	+ href="http://people.FreeBSD.org/~kib/misc/unmapped.13.patch">The
	+ patch.</url>
	+ </links>
	+
	+ <body>
	+ <p>A well-known performance problem of &os; on large SMP
	+ hardware is the need to invalidate TLB for all CPUs when
	+ instantiating and destroying the VMIO buffers. Invalidation is
	+ performed by sending inter-processor interrupt broadcast, which
	+ disrupts the execution path of each CPU, and induces latency
	+ on the request itself. Since most I/O requests processing require
	+ creation of the buffers to hold the data in the kernel, TLB
	+ invalidation becomes an obstacle for I/O scalability on
	+ many-CPU machines.</p>
	+
	+ <p>The work done for flushing the TLBs is especially meaningless
	+ since most mappings created are not used for anything but copying
	+ the data from the usermode to the kernel page cache forth and
	+ back. Most architectures have already established facilities to
	+ perform such copies using much faster techniques, for instance,
	+ the direct map on amd64, or specially reserved per-CPU page
	+ frames or TLB entries on other architectures.</p>
	+
	+ <p>Jeff Roberson unified the machine-specific parts of the
	+ busdma(9), making a common set of low-level functions available
	+ on each architecture. This was committed as r246713. The end
	+ result is that the new types of the load functions can be added
	+ in the single, machine-independent place. In particular, it is
	+ easy to modify the drivers to accept the 'unmapped' bio requests,
	+ which lists the vm pages for the device dma engine, instead of
	+ the virtual address of the kernel buffer.</p>
	+
	+ <p>Konstantin Belousov developed the changes for buffer cache
	+ which allow the VMIO buffers to not map the referenced pages, and
	+ used the feature for UFS. Per-architecture pmap_copy_pages(9)
	+ methods were added to facilitate fast copying between user I/O
	+ buffers and pages of unmapped buffers. The unmapped buffers
	+ create the unmapped bio requests for the drivers, support for
	+ which was made possible by Jeff's patch.</p>
	+
	+ <p>Tests show that even on a small 4-core machine, the system
	+ time for reading files on UFS is reduced by 30%.</p>
	+ </body>
	+
	+ <help>
	+ <task>Test the patch, in particular, on non-x86
	+ architectures.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='docs'>
	+ <title>The &os; Japanese Documentation Project</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Hiroki</given>
	+ <common>Sato</common>
	+ </name>
	+ <email>hrs@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Ryusuke</given>
	+ <common>Suzuki</common>
	+ </name>
	+ <email>ryusuke@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://www.FreeBSD.org/ja/">Japanese &os; Web
	+ Page</url>
	+
	+ <url href="http://www.jp.FreeBSD.org/doc-jp/">The &os; Japanese
	+ Documentation Project Web Page</url>
	+ </links>
	+
	+ <body>
	+ <p>The ja_JP.eucJP subtree has constantly been updated since the
	+ last status report.</p>
	+
	+ <p>In &os; Handbook, translation work of the "users" section has
	+ been completed. "linuxemu" and "serialcomms" were updated and
	+ subsection "Subversion mirror site" was newly added to "mirrors"
	+ section.</p>
	+ </body>
	+
	+ <help>
	+ <task>Further translation work of outdated documents in the
	+ <tt>ja_JP.eucJP</tt> subtree.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='arch'>
	+ <title>&os; on AARCH64</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Andrew</given>
	+ <common>Turner</common>
	+ </name>
	+ <email>andrew@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="https://github.com/zxombie/aarch64-freebsd-sandbox" />
	+
	+ <url
	+ href="http://www.arm.com/products/tools/models/fast-models/foundation-model.php" />
	+ </links>
	+
	+ <body>
	+ <p>Work has started on porting &os; to AARCH64, ARM's new 64-bit
	+ architecture, using the ARMv8 Foundation Model software. GCC and
	+ binutils have been ported to &os; and work started on kernel
	+ initialization, including MMU setup.</p>
	+ </body>
	+
	+ <help>
	+ <task>Get the MMU working</task>
	+
	+ <task>Get system register documentation from ARM</task>
	+
	+ <task>Port clang AArch64 to &os;</task>
	+
	+ <task>Bring the code into a &os; project branch</task>
	+ </help>
	+ </project>
	+
	+ <project cat='arch'>
	+ <title>Compiler improvements for &os;/ARMv6</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Andrew</given>
	+ <common>Turner</common>
	+ </name>
	+ <email>andrew@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ </links>
	+
	+ <body>
	+ <p>&os;/ARM architecture is now supported by the in-tree clang
	+ compiler. ARM EABI support is now available for both clang and
	+ gcc along with the older and less documented OABI. There are
	+ several outstanding issues, once they are fixed EABI will be
	+ made default.</p>
	+ </body>
	+
	+ <help>
	+ <task>Test EABI builds</task>
	+
	+ <task>Fix exception handling for EABI</task>
	+
	+ <task>Test clang builds</task>
	+
	+ <task>Get clang to work natively on EABI-based ARM system.
	+ Currently it works only as cross-compiler for ARM EABI.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='ports'>
	+ <title>&os; Haskell Ports</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Gábor</given>
	+ <common>PÁLI</common>
	+ </name>
	+ <email>pgj@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Ashish</given>
	+ <common>SHUKLA</common>
	+ </name>
	+ <email>ashish@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://wiki.FreeBSD.org/Haskell">&os; Haskell wiki
	+ page</url>
	+
	+ <url href="https://github.com/FreeBSD-haskell/FreeBSD-haskell/">
	+ &os; Haskell ports repository</url>
	+ </links>
	+
	+ <body>
	+ <p>We are proud to announce that the &os; Haskell Team has
	+ updated the Haskell Platform to 2012.4.0.0, GHC to 7.4.2 as well
	+ as updated existing ports to their latest stable versions. All
	+ Haskell ports are also updated to use new OPTIONS framework, and
	+ now, building with dynamic libraries (DYNAMIC) is on by default.
	+ GHC also uses GCC 4.6 and binutils 2.22 from ports. We also added
	+ a number of new Haskell ports, and their count in &os; Ports tree
	+ is now 368.</p>
	+ </body>
	+
	+ <help>
	+ <task>Test GHC to work with clang/LLVM.</task>
	+
	+ <task>Commit pending Haskell ports to the &os; Ports tree.</task>
	+
	+ <task>Add more ports to the Ports Collection.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='ports'>
	+ <title>KDE/&os;</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>KDE</given>
	+ <common>FreeBSD</common>
	+ </name>
	+ <email>kde@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://FreeBSD.kde.org">KDE/FreeBSD home page</url>
	+
	+ <url href="http://FreeBSD.kde.org/area51.php">area51</url>
	+ </links>
	+
	+ <body>
	+ <p>The KDE/&os; team have continued to improve the experience of
	+ KDE software and Qt under &os;. The latest round of improvements
	+ include:</p>
	+ <ul>
	+ <li>Fix handling of Removable property in solid engine</li>
	+
	+ <li>Fix management of backlight with UPower (requires
	+ acpi_video(4))</li>
	+
	+ <li>Installing spell-checking dictionaries with a dependency of
	+ KDE-locale ports</li>
	+ </ul>
	+
	+ <p>The team has also made many releases and upstreamed many fixes
	+ and patches. The latest round of releases include:</p>
	+ <ul>
	+ <li>KDE SC: 4.9.2 (area51)</li>
	+
	+ <li>PyQt: 4.9.5 (area51); SIP: 4.14 (area51)</li>
	+
	+ <li>KDevelop: 4.4.0, 4.4.1 (area51); KDevPlatform: 1.4.0, 1.4.1
	+ (area51)</li>
	+
	+ <li>Calligra: 2.5.3, 2.5.4 (area51)</li>
	+
	+ <li>CMake: 2.8.10.1</li>
	+
	+ <li>Many smaller ports</li>
	+ </ul>
	+
	+ <p>The team is always looking for more testers and porters so
	+ please contact us at kde@FreeBSD.org and visit our home page at
	+ <a href="http://FreeBSD.kde.org">http://FreeBSD.kde.org</a>.</p>
	+ </body>
	+
	+ <help>
	+ <task>Updating out-of-date ports, see
	+ <a href="http://portscout.FreeBSD.org/kde@freebsd.org.html">PortScout</a>
	+ for a list</task>
	+ </help>
	+ </project>
	+
	+ <project cat='ports'>
	+ <title>Ports Collection</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Thomas</given>
	+ <common>Abthorpe</common>
	+ </name>
	+ <email>portmgr-secretary@FreeBSD.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Port</given>
	+ <common>Management Team</common>
	+ </name>
	+ <email>portmgr@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://www.FreeBSD.org/ports/" />
	+
	+ <url
	+ href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/contributing-ports/" />
	+
	+ <url href="http://portsmon.FreeBSD.org/index.html" />
	+
	+ <url href="http://www.FreeBSD.org/portmgr/index.html" />
	+
	+ <url href="http://blogs.FreeBSDish.org/portmgr/" />
	+
	+ <url href="http://www.twitter.com/freebsd_portmgr/" />
	+
	+ <url href="http://www.facebook.com/portmgr" />
	+ </links>
	+
	+ <body>
	+ <p>The ports tree crossed the threshold of 24,000 ports, while the
	+ PR count still is close to 1600.</p>
	+
	+ <p>In Q4 we added five new committers and took in two commit bits
	+ for safe keeping.</p>
	+
	+ <p>In the tradition of recruiting new portmgr@ at conferences, we
	+ added Bernhard Froehlich to our ranks. He is the one responsible
	+ for redports.org</p>
	+
	+ <p>Pav Lucistnik stepped down from his role on portmgr, he was
	+ one of our principles doing -exp runs and well known for sending
	+ failmails.</p>
	+
	+ <p>In the well publicised compromise, the pointyhat machines were
	+ broken into and subsequently taken down, isolated and sanitised.
	+ As a pre-emptive move redports/QAT were also taken down. Work is
	+ under way to restore the services.</p>
	+
	+ <p>Mark Linimon began a from-scratch test install on one of his
	+ own spare machines with the purpose of documenting all the
	+ missing steps from the portbuild article. While doing so, he
	+ further overhauled the codebase to both make it easier to
	+ install, and to further refactor it in light of a security review
	+ (still ongoing at time of this writing). Once this is complete,
	+ the next task will be to reinstall all existing machines from
	+ scratch.</p>
	+ </body>
	+
	+ <help>
	+ <task>Most ports PRs are assigned, we now need to focus on
	+ testing, committing and closing.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='ports'>
	+ <title>Xfce</title>
	+
	+ <contact>
	+ <person>
	+ <email>xfce@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="https://wiki.FreeBSD.org/Xfce" />
	+ </links>
	+
	+ <body>
	+ <p>A major update has been made to
	+ <strong>Thunar</strong> (file manager for the Xfce Desktop
	+ Environment).</p>
	+
	+ <p><em>1.6.x</em> series introduce lots of improvements, most
	+ noticeably is <strong>tabs support</strong>, and the performance
	+ has been improved.</p>
	+ </body>
	+
	+ <help>
	+ <task>Try to fix HSTS (HTTP Strict Transport Security) feature in
	+ Midori with Vala 0.12.1 (works fine with Vala ≥ 0.14.x)</task>
	+
	+ <task>Replace libxfce4gui (deprecated and not maintained by
	+ upstream) by libxfce4ui in order to enhance support for Xfce ≥
	+ 4.10.</task>
	+
	+ <task>Test core and plugins (panel, Thunar) with GLib ≥ 4.32
	+ (to replace deprecated and removed functions introduced since
	+ GLib 2.30).</task>
	+
	+ <task>Fix gtk-xfce-engine with Gtk+ ≥ 3.6.</task>
	+ </help>
	+ </project>
	+
	+ <project cat='soc'>
	+ <title>Google Summer of Code 2013</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>
	+ </given>
	+ <common>FreeBSD Summer of Code Administrators</common>
	+ </name>
	+ <email>soc-admins@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://www.FreeBSD.org/projects/summerofcode.html">
	+ FreeBSD Summer of Code page</url>
	+
	+ <url
	+ href="http://google-opensource.blogspot.co.uk/2013/02/flip-bits-not-burgers-google-summer-of.html">
	+ Google announcement of Summer of Code 2013</url>
	+
	+ <url
	+ href="http://www.google-melange.com/gsoc/homepage/google/gsoc2013">
	+ Google's GSoC 2013 page (including timeline)</url>
	+
	+ <url href="http://en.wikipedia.org/wiki/Google_Summer_of_Code">
	+ GSoC Wikipedia page</url>
	+ </links>
	+
	+ <body>
	+ <p>Since 2005 Google has run its yearly Summer of Code program,
	+ in which Google awards stipends to students who successfully
	+ complete projects with participating Open Source organisations.
	+ &os; has participated in GSoC every year since its inception,
	+ and with the announcement that Google will once again run the
	+ program in 2013 hopes to participate once more.</p>
	+
	+ <p>Google have not yet opened the application period for
	+ mentoring organisations, but once it does &os; plans to apply.
	+ Assuming that we are successful in our application to
	+ participate, we will publish a large list of ideas for possible
	+ projects shortly after. Students may then apply to do one of
	+ those projects, or suggest their own idea for a project. After
	+ the application period, &os; will discover how many student
	+ slots we have been allocated, at which point successful
	+ students will take some time to plan their project, gather
	+ required information and discuss their plans with their
	+ mentors, before having around 12 weeks to develop their
	+ code.</p>
	+
	+ <p>In the eight years of &os;'s participation in Google Summer
	+ of Code, approximately 150 students have successfully complete
	+ projects with us, covering a wide spread of areas of both the
	+ source and ports trees. Of these, 22 students continued
	+ participating with &os; and subsequently became full &os;
	+ committers, many later going on to mentor Summer of Code
	+ students themselves.</p>
	+
	+ <p>Whether &os; has been successful in being selected to be a
	+ participating organisation in Google Summer of Code 2013 should
	+ be announced in early April.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='misc'>
	+ <title>EuroBSDcon 2012</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>EuroBSDcon</given>
	+ <common>Organizers</common>
	+ </name>
	+ <email>oc-2012@eurobsdcon.org</email>
	+ </person>
	+
	+ <person>
	+ <name>
	+ <given>Gabor</given>
	+ <common>Pali</common>
	+ </name>
	+ <email>pgj@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://2012.eurobsdcon.org/">EuroBSDcon 2012 web
	+ site</url>
	+
	+ <url href="http://www.youtube.com/user/eurobsdcon">EuroBSDcon
	+ YouTube channel</url>
	+ </links>
	+
	+ <body>
	+ <p>The 11th European BSD Conference took place in Warsaw, Poland
	+ at the Warsaw University of Technology with a large number of
	+ visitors. It started up with two tracks of tutorials, featuring
	+ FreeNAS, pfSense, DTrace, PF, development of NetBSD drivers, and
	+ an overall introduction to the &os; operating system given by
	+ Kirk McKusick. There we also had opening and closing keynotes,
	+ supplemented with 22 talks on different topics related to &os;,
	+ OpenBSD, NetBSD, FreeNAS and PC-BSD: BHyVe, configuration
	+ management with puppet, improvements in the OpenBSD cryptographic
	+ framework, tuning ZFS, server load balancing in DNS, running &os;
	+ on embedded systems, e.g MIPS and ARM, and challenges in identity
	+ management and authentication.</p>
	+
	+ <p>The conference also had a dedicated track presented by the
	+ attendees of the &os; developer summit and open to all, where one
	+ could learn more about what is happening currently in the
	+ Project: results of Google Summer of Code 2012, architectural
	+ changes in the &os; documentation tree, ILNP, advancements in
	+ package building and development of pkg(8), and a status report
	+ on the USB stack.</p>
	+ </body>
	+ </project>
	+
	+ <project cat='misc'>
	+ <title>&os; Developer Summit, Warsaw</title>
	+
	+ <contact>
	+ <person>
	+ <name>
	+ <given>Gabor</given>
	+ <common>Pali</common>
	+ </name>
	+ <email>pgj@FreeBSD.org</email>
	+ </person>
	+ </contact>
	+
	+ <links>
	+ <url href="http://wiki.FreeBSD.org/201210DevSummit">Home page of
	+ the summit</url>
	+ </links>
	+
	+ <body>
	+ <p>We had 53 &os; developers and invited guests attending the
	+ &os; Developer Summit organized as part of EuroBSDcon 2012 in
	+ Warsaw, Poland at the Warsaw University of Technology. This year
	+ EuroBSDcon organizers again offered us their generous support in
	+ helping with keeping the event running smooth, helping with
	+ registrations, renting the venue, and providing food for keeping
	+ attendees satisfied and happy.</p>
	+
	+ <p>The Warsaw developer summit spanned over 3 days and had 9
	+ working groups on various topics. We improved last year's layout
	+ inherited from the Canadian summits because it has worked well
	+ earlier but could use some further refinements. On both the first
	+ and second days, we ran the working groups, ranging from the
	+ standard matters, discussing issues with the USB stack, the
	+ compiler toolchain, the Ports Collection, or the documentation to
	+ some experimental ones, e.g. arranging an operating systems
	+ course focusing on &os;. In addition to this, similarly to last
	+ year, one of the working groups was about gathering vendors to
	+ present their ideas and engage in discussion with the developers
	+ on their needs from the Project. Finally, on the third day, there
	+ were a number of exciting work-in-progress reports given in a
	+ dedicated Developer Summit track at the main conference.</p>
	+
	+ <p>Photos and slides for the most of the talks are available on
	+ the home page of the summit.</p>
	+ </body>
	+ </project>
	+</report>

	Property changes on: projects/entities/en_US.ISO8859-1/htdocs/news/status/report-2012-10-2012-12.xml
	___________________________________________________________________
	Added: svn:eol-style
	## -0,0 +1 ##
	+native
	\ No newline at end of property
	Added: svn:keywords
	## -0,0 +1 ##
	+FreeBSD=%H
	\ No newline at end of property
	Added: svn:mime-type
	## -0,0 +1 ##
	+text/xml
	\ No newline at end of property
	Index: projects/entities/en_US.ISO8859-1/htdocs/news/status/status.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/news/status/status.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/news/status/status.xml (revision 41355)
	@@ -1,197 +1,201 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "FreeBSD Quarterly Status Reports">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.about">

	- <h2>Next submissions due: February 17th, 2013</h2>
	+ <h2>Next submissions due: April 21st, 2013</h2>

	<p>Use the <a href="http://www.FreeBSD.org/cgi/monthly.cgi">xml
	generator</a> or download and edit the <a href="report-sample.xml">
	xml-template</a>. Submissions should be submitted by e-mail to
	<a href="mailto:monthly@FreeBSD.org">monthly@FreeBSD.org</a>.</p>

	<hr/>

	<p>One of the benefits of the FreeBSD development model is a focus on
	centralized design and implementation, in which the operating system is
	maintained in a central repository, and discussed on centrally maintained
	lists. This allows for a high level of coordination between authors of
	various components of the system, and allows policies to be enforced over
	the entire system, covering issues ranging from architecture to style.
	However, as the FreeBSD developer community has grown, and the rate of
	both mailing list traffic and tree modifications has increased, making it
	difficult even for the most dedicated developer to remain on top of all
	the work going on in the tree.</p>

	<p>The FreeBSD Quarterly Development Status Report attempts to address this
	problem by providing a vehicle that allows developers to make the broader
	community aware of their on-going work on FreeBSD, both in and out of the
	central source repository. For each project and sub-project, a one
	paragraph summary is included, indicating progress since the last summary.
	If it is a new project, or if a project has not submitted any prior status
	reports, a short description may precede the status information.</p>

	<p>These status reports may be reproduced in whole or in part, as long as the
	source is clearly identified and appropriate credit given.</p>

	<h2>2012</h2>

	<ul>
	+ <li><a href="report-2012-10-2012-12.html">October, 2012 -
	+ December, 2012</a></li>
	+ <li><a href="report-2012-07-2012-09.html">July, 2012 -
	+ September, 2012</a></li>
	<li><a href="report-2012-04-2012-06.html">April, 2012 -
	June, 2012</a></li>
	<li><a href="report-2012-01-2012-03.html">January, 2012 -
	March, 2012</a></li>
	</ul>

	<h2>2011</h2>

	<ul>
	<li><a href="report-2011-10-2011-12.html">October, 2011 -
	December, 2011</a></li>
	<li><a href="report-2011-07-2011-09.html">July, 2011 -
	September, 2011</a></li>
	<li><a href="report-2011-04-2011-06.html">April, 2011 -
	June, 2011</a></li>
	<li><a href="report-2011-01-2011-03.html">January, 2011 -
	March, 2011</a></li>
	</ul>

	<h2>2010</h2>

	<ul>
	<li><a href="report-2010-10-2010-12.html">October, 2010 -
	December, 2010</a></li>
	<li><a href="report-2010-07-2010-09.html">July, 2010 -
	September, 2010</a></li>
	<li><a href="report-2010-04-2010-06.html">April, 2010 -
	June, 2010</a></li>
	<li><a href="report-2010-01-2010-03.html">January, 2010 -
	March, 2010</a></li>
	</ul>

	<h2>2009</h2>

	<ul>
	<li><a href="report-2009-10-2009-12.html">October, 2009 -
	December, 2009</a></li>
	<li><a href="report-2009-04-2009-09.html">April, 2009 -
	September, 2009</a></li>
	<li><a href="report-2009-01-2009-03.html">January, 2009 -
	March, 2009</a></li>
	</ul>

	<h2>2008</h2>

	<ul>
	<li><a href="report-2008-10-2008-12.html">October, 2008 -
	December, 2008</a></li>
	<li><a href="report-2008-07-2008-09.html">July, 2008 -
	September, 2008</a></li>
	<li><a href="report-2008-04-2008-06.html">April, 2008 -
	June, 2008</a></li>
	<li><a href="report-2008-01-2008-03.html">January, 2008 -
	March, 2008</a></li>
	</ul>

	<h2>2007</h2>

	<ul>
	<li><a href="report-2007-10-2007-12.html">October, 2007 -
	December, 2007</a></li>
	<li><a href="report-2007-07-2007-10.html">July, 2007 -
	October, 2007</a></li>
	<li><a href="report-2007-04-2007-06.html">April, 2007 -
	June, 2007</a></li>
	<li><a href="report-2007-01-2007-03.html">January, 2007 -
	March, 2007</a></li>
	</ul>

	<h2>2006</h2>

	<ul>
	<li><a href="report-2006-10-2006-12.html">October, 2006 -
	December, 2006</a></li>
	<li><a href="report-2006-06-2006-10.html">June, 2006 -
	October, 2006</a></li>
	<li><a href="report-2006-04-2006-06.html">April, 2006 -
	June, 2006</a></li>
	<li><a href="report-2006-01-2006-03.html">January, 2006 -
	March, 2006</a></li>
	</ul>

	<h2>2005</h2>

	<ul>
	<li><a href="report-2005-10-2005-12.html">October, 2005 -
	December, 2005</a></li>
	<li><a href="report-2005-07-2005-10.html">July, 2005 -
	October, 2005</a></li>
	<li><a href="report-2005-03-2005-06.html">March, 2005 -
	June, 2005</a></li>
	<li><a href="report-2005-01-2005-03.html">January, 2005 -
	March, 2005</a></li>
	</ul>

	<h2>2004</h2>

	<ul>
	<li><a href="report-2004-07-2004-12.html">July, 2004 -
	December, 2004</a></li>
	<li><a href="report-2004-05-2004-06.html">May, 2004 -
	June, 2004</a></li>
	<li><a href="report-2004-03-2004-04.html">March, 2004 -
	April, 2004</a></li>
	<li><a href="report-2004-01-2004-02.html">January, 2004 -
	February, 2004 </a></li>
	</ul>

	<h2>2003</h2>

	<ul>
	<li><a href="report-2003-10-2003-12.html">October, 2003 -
	December, 2003 </a></li>
	<li><a href="report-2003-03-2003-09.html">March, 2003 -
	September, 2003 </a></li>
	<li><a href="report-2003-01-2003-02.html">January, 2003 -
	February, 2003 </a></li>
	</ul>

	<h2>2002</h2>

	<ul>
	<li><a href="report-2002-11-2002-12.html">November, 2002 -
	December, 2002 </a></li>
	<li><a href="report-2002-09-2002-10.html">September, 2002 -
	October, 2002 </a></li>
	<li><a href="report-2002-07-2002-08.html">July, 2002 - August, 2002
	</a></li>
	<li><a href="report-2002-05-2002-06.html">May, 2002 - June, 2002
	</a></li>
	<li><a href="report-2002-02-2002-04.html">February, 2002 - April,
	2002</a></li>
	<li><a href="report-2001-12-2002-01.html">December, 2001 - January,
	2002</a></li>
	</ul>

	<h2>2001</h2>

	<ul>
	<li><a href="report-2001-11.html">November, 2001</a></li>
	<li><a href="report-2001-09.html">September, 2001</a></li>
	<li><a href="report-2001-08.html">August, 2001</a></li>
	<li><a href="report-2001-07.html">July, 2001</a></li>
	<li><a href="report-2001-06.html">June, 2001</a></li>
	</ul>

	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/platforms/amd64.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/platforms/amd64.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/platforms/amd64.xml (revision 41355)
	@@ -1,78 +1,79 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "FreeBSD/amd64 Project">
	<!ENTITY email 'freebsd-amd64'>
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.developers">

	<a href="../gifs/daemon_hammer.jpg"><img src="../gifs/daemon_hammer-tn15.jpg" align="right" border="0" alt="BSD Daemon swinging a sledge hammer"/></a>

	<p>This page contains information of the FreeBSD port to <a
	href="http://www.amd.com/">AMD's</a> AMD64 and <a
	- href="http://developer.intel.com/technology/intel64/index.htm">Intel®
	+ href="http://www.intel.com/info/em64t">Intel®
	64</a> architecture. The
	- AMD64 architecture was previously known as x86-64 or ``Hammer.''
	+ AMD64 architecture was previously known as <q>Hammer</q>.
	The Intel 64 architecture was previously known as Yamhill,
	Clackamas Technology (CT), IA-32e, and EM64T (Extended Memory 64-bit
	- Technology).</p>
	+ Technology). Generically, the platform is often known as
	+ <q>x86-64</q> or <q>x64</q>.</p>

	<p>The AMD Opteron™, AMD Athlon™ 64, AMD Turion™
	64 and newer AMD Sempron™ processors use the AMD64
	architecture.</p>

	- <p>The Intel vPro™, Intel Celeron D (some models since ``Prescott''),
	+ <p>The Intel vPro™, Intel Celeron D (some models since <q>Prescott</q>),
	Intel Centrino® Duo, Intel Centrino® Pro,
	Intel Viiv™, Intel Core™2 Extreme, Intel Core™2 Quad,
	Intel Core™2 Duo, Intel Xeon (3000-sequence, 5000-sequence, and
	7000-sequence) processors use the Intel®64 architecture.</p>

	<h3>Status</h3>

	<p>FreeBSD/amd64 runs in 64-bit multiuser mode, in both
	Uniprocessor and Multiprocessor mode.</p>

	<p>The AMD64 platform is currently a <a
	href="&base;/doc/en_US.ISO8859-1/articles/committers-guide/archs.html">Tier
	1</a> FreeBSD platform.</p>

	<h3>FreeBSD/amd64 Specific Resources</h3>
	<ul>
	<li><a href="http://lists.freebsd.org/mailman/listinfo/freebsd-amd64">FreeBSD/amd64 mailing list</a></li>
	</ul>

	<h3>Other Links of Interest</h3>
	<h4>AMD64 Documentation</h4>
	<ul>
	<li><a href="http://support.amd.com/us/Processor_TechDocs/32200.pdf">
	AMD x86-64 Architecture Specification</a></li>
	<li><a href="http://support.amd.com/us/Processor_TechDocs/24592_APM_v1.pdf">
	AMD64 Architecture Application Programmer's Manual</a></li>
	<li><a href="http://support.amd.com/us/Processor_TechDocs/24593_APM_v2.pdf">
	AMD64 Architecture System Programmer's Manual</a></li>
	<li><a href="http://www.x86-64.org/documentation/abi.pdf">
	AMD x86-64 DRAFT Processor-specific Application Binary Interface Specification</a></li>
	</ul>

	<h4>Software Tools</h4>
	<ul>
	<li><a href="http://www.x86-64.org/downloads.html">Bochs and Simics
	Simulators and Tools</a></li>
	</ul>

	<h4>Related Projects</h4>
	<ul>
	<li><a href="http://www.amd64.org/">Linux / AMD64</a></li>
	<li><a href="http://www.NetBSD.org/Ports/amd64/">NetBSD/amd64</a></li>
	</ul>

	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/projects/newbies.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/projects/newbies.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/projects/newbies.xml (revision 41355)
	@@ -1,227 +1,236 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title 'Resources for Newbies'>
	<!ENTITY url.articles "&base;/doc/en_US.ISO8859-1/articles">
	<!ENTITY url.books "&base;/doc/en_US.ISO8859-1/books">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.docs">

	<p>The following resources are some of those which &os;
	newbies have found most helpful when learning to use &os;.
	Please send corrections and additions to
	<a href="mailto:freebsd-doc@FreeBSD.org">FreeBSD-doc@FreeBSD.org</a>.</p>

	<ul>
	<li><a href="#web-site">Using the &os; web site</a></li>
	<li><a href="#fbsd">Learning about &os;</a></li>
	<li><a href="#derived">Learning about &os;-derived projects</a></li>
	<li><a href="#unix">Learning about &unix;</a></li>
	<li><a href="#xwin">Learning about the X Window System</a></li>
	<li><a href="#people">Helping other people</a></li>
	</ul>


	<h2><a name="web-site">Using the &os; web site</a></h2>

	<p>This web site is the main source of up to date information about
	&os;. Newbies have found the following pages particularly helpful:</p>

	<ul>
	<li><p><a href="&base;/search/search.html">Search</a> the Handbook and FAQ, the
	whole web site, or the &os; mailing list archives.</p></li>

	<li><p>The <a href="&base;/docs.html">Documentation</a> page has links to the
	Handbook and FAQ, tutorials, information about contributing to the
	Documentation Project, documents in languages other than English,
	online manual pages, and much more.</p></li>

	<li><p>The <a href="&base;/support.html">Support</a> page contains a wealth of
	information about &os;, including mailing lists, user groups, web
	and FTP sites, release information, and links to some sources of
	&unix; information.</p></li>
	</ul>

	<h2><a name="fbsd">Learning about &os;</a></h2>

	<ul>
	<li><p>You should most probably look for the
	<a href="&u.rel.announce;">latest mainstream release</a>.
	(See the Handbook for why you should <strong>not</strong> be tempted
	by any of the other branches.) Before you begin, carefully read the
	<a href="&url.books;/handbook/install.html">installation instructions</a>,
	as well as each one of the *.TXT files in the FTP directory
	or on the installation CD. They are there because they contain information
	that you will need. Also pick up the latest
	<a href="&base;/releases/index.html">errata file</a>
	from the web site, in case it has been updated.</p></li>

	<li><p>A number of <a href="&base;/docs/books.html#ARTICLES">short
	articles and tutorials</a> are available. The short tutorial,
	<a href="&url.articles;/new-users/index.html">For
	People New to Both &os; and Unix</a>, is popular with absolute
	beginners. You do not have to know much about anything to enjoy
	this one.</p></li>

	<li><p>There is a lot of documentation to help for setting up ppp.
	You might start with the <a
	href="&url.books;/handbook/ppp-and-slip.html">PPP and SLIP</a>
	chapter of the &os; Handbook and explore the
	<a href="http://www.awfulhak.org/ppp.html">ppp page</a>
	for links to the other valuable information and the latest updates.</p></li>

	<li><p>The <a href="&url.books;/handbook/index.html">&os; Handbook</a> and <a
	href="&url.books;/faq/index.html">Frequently Asked Questions (FAQ)</a> are the
	main documents for &os;. Essential reading, they contain a lot of
	material for newbies as well as some pretty advanced stuff. Do not
	worry if you are unable to understand the advanced sections. The handbook
	contains the installation instructions and also provides lists of
	books and on-line resources, and the FAQ has a troubleshooting
	section.</p></li>

	<li><p>Join the &os;-Questions mailing list to see the questions you
	were too afraid to ask, and their answers. Subscribe by filling out
	the following form:
	<a href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions">http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions</a>.
	You can look up old questions and
	answers via the <a href="&base;/search/search.html#mailinglists">search</a>
	page.</p></li>

	+ <li><p>The main newsgroup for &os; is <a
	+ href="news:comp.unix.bsd.freebsd.misc">comp.unix.bsd.freebsd.misc</a>.
	+ General UNIX questions are dealt with in the newsgroup <a
	+ href="news:comp.unix.questions">comp.unix.questions</a> and the
	+ associated <a
	+ href="ftp://rtfm.mit.edu/pub/usenet/news.answers/unix-faq/faq/">FAQ</a>
	+ from the RMIT FTP site. Newbies are likely to be most
	+ interested in sections 1 and 2 initially.</p></li>
	+
	<li><p><a href="&cgibase;/man.cgi">Manual pages</a> are good
	for reference but not always
	the best introduction for a novice. The more you work with man pages
	the more familiar they become. Some are very good for newbies, so
	always check them out. The ppp man page, for example, is more like a
	tutorial.</p></li>
	</ul>

	<h2><a name="derived">Learning about &os;-derived projects</a></h2>

	<p>&os; is widely used as a building block for other commercial
	and open-source operating systems. Some of the most widely used
	and publicly available systems are listed below.</p>

	<ul>
	<li><p><a href="http://www.pcbsd.org">PC-BSD</a> is a &os;
	derivative with a graphical installer and impressive desktop
	tools aimed at ease of use for the casual computer
	user.</p></li>

	<li><p>Apple's <a href="http://www.apple.com/macosx">Mac OS
	X</a>
	is <a href="http://www.apple.com/server/macosx/technology/unix.html">based
	in part</a> on &os; and includes a rich &unix; foundation in
	addition to the proprietary Apple user interface.</p></li>
	</ul>

	<h2><a name="unix">Learning about &unix;</a></h2>

	<p>Many of the problems we have as newbies come from being unfamiliar
	with the UNIX commands, needed to fix our &os; problems.
	Without a UNIX background you will be faced with two things to learn
	at once. Fortunately a lot of resources are available to make this
	easier.</p>

	<ul>
	<li><p>The <a href="&url.books;/handbook/basics.html">&unix;
	Basics</a> chapter of the &os; Handbook covers the basic
	commands and functionality of &os; operating system. Most
	of information provided in this document is also relevant for
	any other &unix;-like operating system.</p></li>

	<li><p>There are many easy books, such as the "Dummies" guides, in any
	large book shop. If you want something really easy, take a look at
	what is available and pick one that seems to speak your language.
	Pretty soon you will want to move on to a book that gives more
	coverage.</p></li>

	<li><p>Another popular book is <em>UNIX Power Tools</em> by Jerry Peek,
	Tim O'Reilly and Mike Loukides, published by O'Reilly and
	Associates. It is organized as a series of short articles each of
	which solves a problem, and these articles are cross-referenced to
	other articles with related material. Though not specifically aimed
	at newbies, the design makes it ideal for a newbie with a burning
	question or the odd few minutes to browse. More elementary material
	is near the front of the book, but there are short easy articles
	throughout.</p></li>

	<li>
	<p>A <a href="http://www.cs.duke.edu/csl/docs/unix_course/">UNIX
	Introductory Course</a> from Ohio State University is
	available online in HTML format.</p>
	</li>

	<li>
	<p>A <a href="http://www.cs.duke.edu/csl/docs/sysadmin_course/">UNIX
	System Administration Course</a> from Ohio State University
	is available online in HTML format.</p>
	</li>

	<li><p><a href="http://www.mcsr.olemiss.edu/unixhelp/">UNIXhelp
	for Users</a> is another introductory guide which is available in
	HTML at a mirror site near you, or can be installed on your own
	system.</p></li>

	<li><p>Many other web sites hold lists of UNIX tutorials and reference
	material. One of the best places to start looking is the
	little known search engine <a
	href="https://google.com">Google</a>.</p>
	</li>
	</ul>

	<h2><a name="xwin">Learning about the X Window System</a></h2>

	<p>The X Window System is used with a number of operating systems,
	including &os;. The documentation for X can be found at the
	<a href="http://www.x.org/">X.Org Foundation</a>
	web site.
	Beware, much of this documentation is reference material which is
	more likely to be difficult for newcomers to digest.</p>

	<ul>
	<li><p>Before you can get X running exactly the way you like, you will need
	to choose a window manager.
	Visit the <a href="http://xwinman.org/">Window Managers for X</a>
	page and follow the link to the introduction to find out about window
	managers, then return and read "The Basics". Then go back and compare
	the different types that are available. (Bonus: there is another
	beginners guide to UNIX there too.)
	Most, if not all, of these window managers are available to
	install from the &os; Ports Collection.</p></li>
	</ul>

	<h2><a name="people">Helping other people</a></h2>

	<p>Everyone has something to contribute to the &os; community, even
	newbies! Some are busy working with the new advocacy group and some have
	become involved with the
	<a href="&base;/docproj/docproj.html">Documentation Project</a> as reviewers.
	Other &os; newbies might have particular skills and experiences to
	share, either computer related or not, or just want to meet new
	newbies and make them feel welcome. There are always people around
	who help others simply because they like to.</p>

	<p>Friends who run &os; are a great resource. No book can replace
	chatting on the phone or across a pizza with someone who has the
	same interests, enjoys similar accomplishments, and faces the same
	challenges. If you do not have many friends who use &os;,
	consider using your old &os; CDs to create some more.</p>

	<p><a href="&base;/usergroups.html">User groups</a> are
	good places to meet other &os; users. If there is no one nearby,
	you might consider starting one!</p>

	<p>Before talking to real humans about your new skills, you might
	want to check the <a
	href="http://www.catb.org/jargon/">Jargon File</a>.</p>

	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/projects/projects.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/projects/projects.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/projects/projects.xml (revision 41355)
	@@ -1,387 +1,381 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "FreeBSD Development Projects">

	<!ENTITY url.articles "../doc/en_US.ISO8859-1/articles">
	<!ENTITY url.books "../doc/en_US.ISO8859-1/books">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.developers">

	<a name="development"></a>

	<p>In addition to the mainstream development path of FreeBSD, a number
	of developer groups are working on the cutting edge to expand
	FreeBSD's range of applications in new directions. Follow the links
	below to learn more about these exciting projects.</p>

	If you feel that a project is missing, please send the URL and a short
	description (3-10 lines) to
	<a href="../mailto.html">www@FreeBSD.org</a>.

	<p>In addition, some of these projects regularly submit status reports,
	which can be viewed on the <a href="../news/status/status.html">status
	reports page</a>.</p>

	<ul>
	<li><a href="#documentation">Documentation</a></li>
	<li><a href="../advocacy/index.html">Advocacy</a></li>
	<li><a href="#applications">Applications</a></li>
	<li><a href="#networking">Networking</a></li>
	<li><a href="#storage">Storage</a></li>
	<li><a href="#kernelandsecurity">Kernel and Security</a></li>
	<li><a href="#devicedrivers">Device drivers</a></li>
	<li><a href="#architecture">Architecture</a></li>
	<li><a href="#misc">Misc</a></li>
	<li><a href="summerofcode.html">Google Summer of Code</a></li>
	</ul>

	<a name="documentation"></a>
	<h3>Documentation</h3>
	<ul>
	<li><a href="../docproj/docproj.html">FreeBSD Documentation Project</a>:
	The FreeBSD Documentation Project is a group of people who maintain
	and write the documentation (such as the Handbook and FAQ) for the
	FreeBSD project. If you want to help with the documentation project,
	subscribe to the freebsd-doc@FreeBSD.org
	mailing list and participate.</li>

	<li><a name="newbies" href="newbies.html">FreeBSD Resources for Newbies</a>:
	A list of resources to help those new to FreeBSD and &unix; in
	general.</li>

	-<li><a name="BSDsites" href="http://mirrorlist.FreeBSD.org/">
	-RELEASE/SNAP finder for FreeBSD FTP servers</a>:
	-A resource that would allow anyone to find a FTP server that contains
	-particular releases and SNAP of FreeBSD. The database is updated daily
	-at 3am Melbourne time (10 hours ahead of UTC).</li>
	-
	<li><a name="diary" href="http://www.freebsddiary.org/">The FreeBSD
	Diary</a>: A collection of how-to entries aimed at UNIX
	novices. The aim is to provide a set of step-by-step guides to
	installing and configuring various ports.</li>

	<li><a href="&url.books;/developers-handbook/index.html">
	The FreeBSD Developers' Handbook</a></li>

	<li><a href="&url.articles;/contributing-ports/index.html">
	Contributing to the FreeBSD Ports Collection</a></li>

	</ul>

	<a name="applications"></a>
	<h3>Applications</h3>
	<ul>
	<li><a name="java" href="../java/index.html">&java; on FreeBSD</a>:
	This contains information on where to obtain the latest &jdk; for
	FreeBSD, how to install and run it, and a list of &java; software that
	you may find interesting.</li>

	<li><a name="gnome" href="../gnome/index.html">GNOME on FreeBSD</a>:
	This contains information on where to obtain the latest GNOME for
	FreeBSD, how to install and run it, latest project news and
	updates, FAQ covering FreeBSD-specific GNOME issues, application
	porting guidelines and much more.</li>

	<li><a name="kde" href="http://freebsd.kde.org">KDE on FreeBSD</a>:
	This contains links to the latest KDE releases for FreeBSD, as well as
	documentation and tutorials about how to install and run KDE on
	FreeBSD. Project news and a FreeBSD-specific FAQ are also
	available.</li>

	<li><a name="mono" href="http://www.mono-project.com/Mono:FreeBSD">
	Mono on FreeBSD</a>:
	Here you can find information about the state of Mono and C# for FreeBSD.</li>

	<li><a name="openoffice" href="http://porting.openoffice.org/freebsd/">
	OpenOffice.org on FreeBSD</a>:
	Information about the various OpenOffice.org ports.</li>

	<li><a href="../ports/index.html">FreeBSD Ports Collection</a>:
	The FreeBSD Ports Collection provides an easy way to compile and
	install a wide range of applications with a minimum amount of effort.
	A list of current ports is available along with a search mechanism
	to see if a specific application exists in the Ports Collection.</li>

	<li><a href="http://people.FreeBSD.org/~fenner/portsurvey/">FreeBSD Ports distfiles survey</a>:
	A list which checks the Ports Collection for unfetchable distfiles
	and provides a summary for each port.</li>

	<li><a href="http://FreshPorts.org/">FreshPorts</a>: Provides the most up-to-date list of
	ports and port changes. Add your favourite ports to your watch list and receive email
	notification of any changes.</li>

	<li><a href="http://pointyhat.FreeBSD.org/">Pointyhat</a>: Is a server which
	checks the Ports Collection and keeps package building logs and error
	logs for each port.</li>
	</ul>

	<a name="networking"></a>
	<h3>Networking</h3>
	<ul>
	<li><a name="netperf" href="&base;/projects/netperf/index.html">Netperf</a>:
	Network stack optimization for the FreeBSD 5.x and 6.x kernels, a follow-on
	to the SMPng network stack locking work for FreeBSD 5.3. This project is
	exploring and implementing optimizations strategies for a multi-threaded
	network stack.</li>
	<li><a name="kame" href="http://www.kame.net/">KAME Project</a>: A free IPv6/IPsec stack for BSD.</li>
	<li><a name="SYSLOG-SECURE" href="http://www.faqs.org/rfcs/rfc3164.html">SYSLOG-SECURE</a>:
	In August 2001 a standard of syslog was made: RFC3164. This RFC
	describes some extensions to add security to syslog. A project
	started in 2002 to adapt RFC3164 to the FreeBSD version of syslog and to add
	some security extensions, at least syslog-sign. Both libc and syslogd will
	be modified. And optionally some tools to verify or manage the security
	would be made.
	All help is welcome. Send an email to albert@ons-huis.net for info.</li>
	</ul>

	<a name="storage"></a>
	<h3>Storage</h3>
	<ul>
	<li><a name="afs" href="http://www.stacken.kth.se/projekt/arla/">Arla</a>:
	A free AFS client implementation. The main goal is to
	make a fully functional client with all capabilities of normal AFS.
	Other planned and implemented things are all the normal management
	tools and a server.</li>

	<li><a name="bigdisk" href="&base;/projects/bigdisk/index.html">Big Disk</a>:
	The goal of the <em>Large data storage in FreeBSD</em> project is to make
	FreeBSD ready for multi-terabyte drive/volume capacities and file systems.</li>

	<li><a name="coda" href="http://www.coda.cs.cmu.edu/">Coda</a>:
	A distributed filesystem. Among its features are disconnected
	operation, good security model, server replication and persistent
	client side caching.</li>

	<li><a name="journaling" href="http://www.ece.cmu.edu/~ganger/papers/">
	Journaling versus Soft Updates</a>: Asynchronous Meta-data Protection in File Systems.</li>

	<li><a name="tcfs" href="http://www.tcfs.unisa.it/">TCFS</a>:
	A Transparent Cryptographic File System that is a suitable
	solution to the problem of privacy for distributed filesystem. By a
	deeper integration between the encryption service and the filesystem,
	it results in a complete transparency of use to the user
	applications. Files are stored in encrypted form and are decrypted
	before they are read. The encryption/decryption process takes place on
	the client machine and thus the encryption/decryption key never
	travels on the network.</li>

	<li><a name="Tertiary" href="http://now.cs.berkeley.edu/Td/">Tertiary Disk</a>:
	A storage system architecture to create large disk storage systems
	that avoid the disadvantages of custom built disk arrays. The
	name comes from twin goals: to have the cost per megabyte and
	capacity of tape libraries and the performance of magnetic
	disks. We use commodity, off the shelf components to develop a
	scalable, low cost, terabyte capacity disk system. Our target is
	to build a complete storage system with about 30-50% extra to
	the cost of the raw disk. Tertiary Disk uses PCs connected by a
	switched network to host a large number of disks. Our prototype
	consists of 20 200MHz PC PCs, which host 370 8GB disks. The PCs
	are connected through a 100Mbps Ethernet switch.</li>

	<li><a name="vinum" href="http://www.vinumvm.org/">Vinum</a>:
	A logical volume manager modeled after the VERITAS volume manager™.
	However, it is not a clone of Veritas, and attempts to solve a
	number of problems more elegantly than Veritas. It also offers
	features that Veritas does not have.</li>

	<li><a name="PathConvert" href="http://www.tamacom.com/pathconvert/">
	The PathConvert project</a>: A project to develop utilities which make
	conversion between absolute path name and relative path name. It
	brings benefits mainly to the users of NFS and WWW.</li>
	</ul>

	<a name="kernelandsecurity"></a>
	<h3>Kernel, security</h3>
	<ul>
	<li><a name="lotteryscheduling"
	href="http://www.cs.cmu.edu/~dpetrou/research.html">
	Lottery Scheduling Kernel</a>: This work is based on
	Waldspurger's lottery scheduling algorithm, which implements
	proportional-share resource management. The primary advantages
	are that users have strict control over the relative execution
	rates of their processes, and users are load-insulated from each
	other, preventing one user from dominating the CPU.</li>

	<li><a name="openbsm" href="http://www.OpenBSM.org/">OpenBSM</a>: An open
	source implementation of Sun's Basic Security Module (BSM) Audit API and file
	format. OpenBSM provides the userland libraries, tools, and documentation
	for the TrustedBSD audit implementation that will be integrated into
	FreeBSD.</li>

	<li><a name="trustedbsd" href="http://www.TrustedBSD.org/">TrustedBSD</a>:
	Provides a set of trusted operating system extensions to the FreeBSD operating
	system. This includes features such as fine-grained privileges (capabilities),
	Access Control Lists, and Mandatory Access Control. These features are
	being integrated back into the base FreeBSD distribution, as well as being
	ported to other BSD-derived systems.</li>

	<li><a name="kernelstresstest"
	href="http://www.holm.cc/stress/">Kernel Stress Test Suite</a>: The
	purpose of this stress test is to crash the system. The stress test
	is composed of small test programs and scripts. Each test targets a
	specific area of the kernel. The key concept of this test suite is
	chaos. Each test sleeps for a random number of seconds before it
	starts up in a random number of invocations.</li>

	</ul>

	<a name="devicedrivers"></a>
	<h3>Device drivers</h3>
	<ul>

	<li><a name="busdma" href="&base;/projects/busdma/index.html">busdma
	and SMPng driver conversion</a>: busdma provides a portable abstraction
	to the Direct Memory Access (DMA) hardware primitives used by many high
	performance device drivers. By using this abstraction, device driver
	authors avoid adding platform-specific DMA management code, improving
	the portability of drivers between hardware architectures. This page
	also tracks the progress of drivers towards being SMPng-safe.</li>

	<li><a name="deviceframework" href="http://people.FreeBSD.org/~dfr/devices.html">
	A New Device Framework for FreeBSD</a></li>

	<li><a name="atm" href="http://chuck.cranor.org/p/bsdatm.pdf"> BSD ATM: implementation of ATM internetworking under 4.4BSD</a>:
	New computer applications in areas such as multimedia, imaging,
	and distributed computing demand high levels of performance from
	computer networks. ATM-based networking solutions provide one
	possible alternative to meeting these performance needs.
	However, the complexity of ATM over traditional networks such as
	Ethernet has proven to be a barrier to its being used. In this
	paper we present the design and implementation of BSD ATM, a
	light-weight and efficient ATM software layer for BSD-based
	operating systems that requires minimal changes to the operating
	system. BSD ATM can be used both for IP-based networking traffic
	and for ``native'' ATM traffic.</li>

	<li><a name="homeauto" href="http://people.FreeBSD.org/~fsmp/HomeAuto/HomeAuto.html">Home Automation</a>:
	Using FreeBSD to run appliance controllers, infra-red controllers,
	automated telephone systems, and more.</li>

	<li><a name="tokenring" href="http://www.jurai.net/~winter/tr/">The FreeBSD Token-Ring Project</a>:
	Information, files, patches, and documentation about adding Token Ring
	support to FreeBSD.</li>

	<li><a name="xircomcem">Xircom CEM Ethernet Driver</a>: A mailing list exists for further
	development of Scott Mitchell's Xircom CEM ethernet driver. Send
	<tt>subscribe freebsd-xircom</tt> to <a
	href="mailto:majordomo@lovett.com">majordomo@lovett.com</a> to
	join.</li>
	</ul>

	<a name="architecture"></a>
	<h3>Architecture</h3>
	<ul>
	<li><a name="ia64" href="../platforms/ia64/index.html">
	Porting FreeBSD to IA-64 systems</a>:
	This project is responsible for porting FreeBSD to the IA-64
	architecture. Direct any questions specific to this project to the
	freebsd-ia64@FreeBSD.org mailing list. </li>

	<li><a name="ppc" href="../platforms/ppc.html">Porting FreeBSD to PowerPC® systems</a>:
	Contains information on the FreeBSD PPC port, such as mailing list
	information and so on.</li>

	<li><a name="sparc" href="../platforms/sparc.html">Porting FreeBSD to SPARC® systems</a>:
	Contains information on the FreeBSD SPARC port including a FAQ,
	some early boot code, information on SPARC processors and motherboards,
	and other SPARC projects.</li>

	<li><a name="sysvr4" href="http://slash.dotat.org/~newton/freebsd-svr4/">
	SysVR4 Emulation</a>: This page describes an SysVR4 emulator for
	FreeBSD. It is currently capable of running (or walking, in some
	cases) a wide-ish variety of SysV executables taken from Solaris™/x86
	2.5.1 and 2.6 systems. I have reason to believe that it will also run
	SCO UnixWare and SCO OpenServer binaries.</li>

	<li><a name="oskit" href="http://www.cs.utah.edu/flux/oskit/">The OSKit</a>:
	The OSKit is a framework and a set of 31 component libraries oriented
	to operating systems, together with extensive documentation. By
	providing in a modular way not only most of the infrastructure
	"grunge" needed by an OS, but also many higher-level components, the
	OSKit's goal is to lower the barrier to entry to OS R&D and to
	lower its costs. The OSKit makes it vastly easier to create a new OS,
	port an existing OS to the x86 (or in the future, to other
	architectures supported by the OSkit), or enhance an OS to support a
	wider range of devices, filesystem formats, executable formats, or
	network services. The OSKit also works well for constructing OS-related
	programs, such as boot loaders or OS-level servers atop a
	microkernel.</li>
	</ul>

	<a name="misc"></a>
	<h3>Misc</h3>
	<ul>
	<li><a name="nanobsd" href="&url.articles;/nanobsd/index.html">NanoBSD</a>:
	NanoBSD is a tool designed to create a possibly reduced FreeBSD
	system image, which is suited to fit on a Compact Flash card
	(or other mass storage medium) in a way which is suitable for
	use in appliance like applications. The FreeBSD documentation
	collection includes an introductory
	<a href="&url.articles;/nanobsd/index.html">article about NanoBSD</a>,
	which includes useful tips about setting up, running and
	using NanoBSD.</li>

	<li><a name="global" href="http://www.gnu.org/software/global/global.html">GLOBAL</a>:
	A common source code tag system that works the same way across
	diverse environments. Currently, it supports the shell command line,
	the nvi editor, web browser, the emacs editor, and the elvis editor,
	and the supported languages are C, Yacc, and Java.</li>

	<li><a name="enterman" href="http://ezine.daemonnews.org/199908/enteruser.html">Enteruser</a>: A Replacement for adduser.</li>

	<li><a name="acpi"
	href="&base;/projects/acpi/">ACPI on FreeBSD</a>:
	A Project created to get ACPI working smoothly on FreeBSD.</li>

	<li><a name="binup"
	href="http://www.daemonology.net/freebsd-update/">Binary
	Updater</a>: FreeBSD Update is a system for automatically
	building, distributing, fetching, and applying binary security
	updates for FreeBSD. This makes it possible to easily track
	the FreeBSD security branches without the need for fetching
	the source tree and recompiling (except on the machine
	building the updates, of course). Updates are
	cryptographically signed; they are also distributed as binary
	diffs using a binary diff tool, which dramatically reduces
	the bandwidth used.</li>

	<li><a name="c99" href="&base;/projects/c99/index.html">The
	FreeBSD C99 & &posix; Conformance Project</a>: This project aims to
	implement all requirements of the ISO 9899:1999 (C99) and
	IEEE 1003.1-2001 (POSIX) standards.</li>

	<li><a name="cvsweb" href="cvsweb.html">CVSweb</a>: A WWW
	interface for CVS repositories with which you can browse a file
	hierarchy on your browser to view each file's revision history
	in a very handy manner.</li>

	<li><a name="flcl"
	href="http://laptop.bsdgroup.de/freebsd/"> The FreeBSD
	Laptop Compatibility List</a>: A comprehensive database of
	laptops and PCMCIA cards that work with FreeBSD. This site
	contains detailed information about known hardware and
	software issues.</li>

	<li><a name="tetintegration" href="http://wiki.freebsd.org/TetIntegration">TET
	Integration</a>: The Test Execution Toolkit from <a
	href="http://www.opengroup.org/">The Open Group</a> is a
	light-weight open-source test execution framework that
	supports distributed testing. This project investigates
	using TET and existing TET-based open-source standards-compliance
	test suites (VSX-PCTS, VSC-Lite, VSTH-Lite, VSW5 and others) in
	FreeBSD.</li>

	</ul>


	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/releases/8.4R/schedule.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/releases/8.4R/schedule.xml (nonexistent)
	+++ projects/entities/en_US.ISO8859-1/htdocs/releases/8.4R/schedule.xml (revision 41355)
	@@ -0,0 +1,134 @@
	+<?xml version="1.0" encoding="iso-8859-1"?>
	+<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	+"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	+<!ENTITY email 'freebsd-qa'>
	+<!ENTITY local.rel "8.4">
	+<!ENTITY title "FreeBSD &local.rel; Release Process">
	+]>
	+
	+<html xmlns="http://www.w3.org/1999/xhtml">
	+<head>
	+ <title>&title;</title>
	+
	+ <cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	+ </head>
	+
	+ <body class="navinclude.download">
	+
	+ <h1>Introduction</h1>
	+
	+ <p>This is the release schedule for FreeBSD &local.rel;. For more
	+ information about the release engineering process, please see the <a
	+ href="&base;/releng/index.html">Release Engineering</a> section of the
	+ web site.</p>
	+
	+ <p>General discussions about the pending release and known issues should be
	+ sent to the public
	+ <a href="mailto:FreeBSD-stable@FreeBSD.org">freebsd-stable</a> mailing list.
	+ </p>
	+
	+ <h1>Schedule</h1>
	+
	+ <table class="tblbasic">
	+ <tr class="heading">
	+ <td>Action</td>
	+ <td>Expected</td>
	+ <td>Actual</td>
	+ <td>Description</td>
	+ </tr>
	+
	+ <tr>
	+ <td>Initial release schedule announcement</td>
	+ <td>-</td>
	+ <td>08 February 2013</td>
	+ <td>Release Engineers send announcement email to developers with a
	+ rough schedule.</td>
	+ </tr>
	+
	+ <tr>
	+ <td>Announce <tt>doc/</tt> tree slush</td>
	+ <td>-</td>
	+ <td>28 February 2013</td>
	+ <td>Notification of the impending <tt>doc/</tt> tree slush
	+ should be sent to <tt>doc@</tt>.</td>
	+ </tr>
	+
	+ <tr>
	+ <td>Code freeze begins</td>
	+ <td>08 March 2013</td>
	+ <td>08 March 2013</td>
	+ <td>Release Engineers announce that all further commits to the
	+ stable/8 branch will require explicit approval.
	+ Certain blanket approvals will be granted for narrow areas of
	+ development, documentation improvements, etc.</td>
	+ </tr>
	+
	+ <tr>
	+ <td>BETA1</td>
	+ <td>20 March 2013</td>
	+ <td>22 March 2013</td>
	+ <td>First beta test snapshot.</td>
	+ </tr>
	+
	+ <tr>
	+ <td><tt>doc/</tt> tree slush</td>
	+ <td>17 March 2013</td>
	+ <td>17 March 2013</td>
	+ <td>Non-essential commits to the <tt>en_US.ISO8859-1/</tt>
	+ subtree should be delayed from this point until after the
	+ <tt>doc/</tt> tree tagging, to give translation teams time to
	+ synchronize their work.</td>
	+ </tr>
	+
	+ <tr>
	+ <td>releng/&local.rel; branch</td>
	+ <td>18 March 2013</td>
	+ <td>28 March 2013</td>
	+ <td>Subversion branch created, propagated to CVS; future
	+ release engineering proceeds on this branch.</td>
	+ </tr>
	+
	+ <tr>
	+ <td>RC1</td>
	+ <td>30 March 2013</td>
	+ <td>-</td>
	+ <td>First release candidate.</td>
	+ </tr>
	+
	+ <tr>
	+ <td>RC2</td>
	+ <td>05 April 2013</td>
	+ <td>-</td>
	+ <td>Second release candidate.</td>
	+ </tr>
	+
	+ <tr>
	+ <td>RELEASE build</td>
	+ <td>12 April 2013</td>
	+ <td>-</td>
	+ <td>&local.rel;-RELEASE build.</td>
	+ </tr>
	+
	+ <tr>
	+ <td>RELEASE announcement</td>
	+ <td>19 April 2013</td>
	+ <td>-</td>
	+ <td>&local.rel;-RELEASE press release.</td>
	+ </tr>
	+
	+ <tr>
	+ <td>Turn over to the secteam</td>
	+ <td>-</td>
	+ <td>-</td>
	+ <td>releng/&local.rel; branch is handed over to
	+ the FreeBSD Security Officer Team in one or two weeks after the
	+ announcement.</td>
	+ </tr>
	+ </table>
	+<!--
	+ <h1>Internal Status / TODO</h1>
	+ <a href="http://wiki.freebsd.org/Releng/8.4TODO">http://wiki.freebsd.org/Releng/8.4TODO</a>
	+-->
	+
	+ </body>
	+</html>

	Property changes on: projects/entities/en_US.ISO8859-1/htdocs/releases/8.4R/schedule.xml
	___________________________________________________________________
	Added: svn:keywords
	## -0,0 +1 ##
	+FreeBSD=%H
	\ No newline at end of property
	Added: svn:mime-type
	## -0,0 +1 ##
	+text/sgml
	\ No newline at end of property
	Index: projects/entities/en_US.ISO8859-1/htdocs/releases/8.4R/Makefile
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/releases/8.4R/Makefile (nonexistent)
	+++ projects/entities/en_US.ISO8859-1/htdocs/releases/8.4R/Makefile (revision 41355)
	@@ -0,0 +1,14 @@
	+# $FreeBSD$
	+
	+.if exists(../Makefile.conf)
	+.include "../Makefile.conf"
	+.endif
	+.if exists(../Makefile.inc)
	+.include "../Makefile.inc"
	+.endif
	+
	+DOCS+= schedule.xml
	+
	+DATA= docbook.css
	+
	+.include "${DOC_PREFIX}/share/mk/web.site.mk"

	Property changes on: projects/entities/en_US.ISO8859-1/htdocs/releases/8.4R/Makefile
	___________________________________________________________________
	Added: svn:keywords
	## -0,0 +1 ##
	+FreeBSD=%H
	\ No newline at end of property
	Index: projects/entities/en_US.ISO8859-1/htdocs/releases/8.4R/docbook.css
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/releases/8.4R/docbook.css (nonexistent)
	+++ projects/entities/en_US.ISO8859-1/htdocs/releases/8.4R/docbook.css (revision 41355)
	@@ -0,0 +1,242 @@
	+/*
	+ * Copyright (c) 2001, 2003, 2010 The FreeBSD Documentation Project
	+ * 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 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$
	+ */
	+
	+BODY ADDRESS {
	+ line-height: 1.3;
	+ margin: .6em 0;
	+}
	+
	+BODY BLOCKQUOTE {
	+ margin-top: .75em;
	+ line-height: 1.3;
	+ margin-bottom: .75em;
	+}
	+
	+HTML BODY {
	+ margin: 1em 8% 1em 10%;
	+ line-height: 1.2;
	+}
	+
	+.LEGALNOTICE {
	+ font-size: small;
	+ font-variant: small-caps;
	+}
	+
	+BODY DIV {
	+ margin: 0;
	+}
	+
	+DL {
	+ margin: .8em 0;
	+ line-height: 1.2;
	+}
	+
	+DIV.CALLOUTLIST DT {
	+ float: left;
	+ width: 1em;
	+}
	+
	+DIV.CALLOUTLIST DD {
	+ clear: right;
	+ margin-bottom: 1ex;
	+}
	+
	+BODY FORM {
	+ margin: .6em 0;
	+}
	+
	+H1, H2, H3, H4, H5, H6,
	+DIV.EXAMPLE P B,
	+.QUESTION,
	+DIV.TABLE P B,
	+DIV.PROCEDURE P B {
	+ color: #990000;
	+}
	+
	+BODY H1, BODY H2, BODY H3, BODY H4, BODY H5, BODY H6 {
	+ line-height: 1.3;
	+ margin-left: 0;
	+}
	+
	+BODY H1, BODY H2 {
	+ margin: .8em 0 0 -4%;
	+}
	+
	+BODY H3, BODY H4 {
	+ margin: .8em 0 0 -3%;
	+}
	+
	+BODY H5 {
	+ margin: .8em 0 0 -2%;
	+}
	+
	+BODY H6 {
	+ margin: .8em 0 0 -1%;
	+}
	+
	+BODY HR {
	+ margin: .6em;
	+ border-width: 0 0 1px 0;
	+ border-style: solid;
	+ border-color: #cecece;
	+}
	+
	+BODY IMG.NAVHEADER {
	+ margin: 0 0 0 -4%;
	+}
	+
	+OL {
	+ margin: 0 0 0 5%;
	+ line-height: 1.2;
	+}
	+
	+BODY PRE {
	+ margin: .75em 0;
	+ line-height: 1.0;
	+ font-family: monospace;
	+}
	+
	+BODY TD, BODY TH {
	+ line-height: 1.2;
	+}
	+
	+UL, BODY DIR, BODY MENU {
	+ margin: 0 0 0 5%;
	+ line-height: 1.2;
	+}
	+
	+HTML {
	+ margin: 0;
	+ padding: 0;
	+}
	+
	+BODY P B.APPLICATION {
	+ color: #000000;
	+}
	+
	+.FILENAME {
	+ color: #007a00;
	+}
	+
	+SVNREF {
	+ color: #007a00;
	+}
	+
	+.GUIMENU, .GUIMENUITEM, .GUISUBMENU,
	+.GUILABEL, .INTERFACE,
	+.SHORTCUT, .SHORTCUT .KEYCAP {
	+ font-weight: bold;
	+}
	+
	+.GUIBUTTON {
	+ background-color: #CFCFCF;
	+ padding: 2px;
	+}
	+
	+.ACCEL {
	+ background-color: #F0F0F0;
	+ text-decoration: underline;
	+}
	+
	+.SCREEN {
	+ padding: 1ex;
	+}
	+
	+.PROGRAMLISTING {
	+ padding: 1ex;
	+ background-color: #eee;
	+ border: 1px solid #ccc;
	+ line-height: 1.1;
	+}
	+
	+@media screen { /* hide from IE3 */
	+ a[href]:hover { background: #ffa }
	+}
	+
	+.INFORMALTABLE, .TABLE TH {
	+ padding-left: 02.em;
	+ text-align: left;
	+}
	+
	+BLOCKQUOTE, .EXAMPLE, .PROGRAMLISTING {
	+ -moz-border-radius: 6px;
	+ -webkit-border-radius: 6px;
	+ -khtml-border-radius: 6px;
	+ border-radius: 6px;
	+}
	+
	+BLOCKQUOTE {
	+ padding: 0 2ex;
	+}
	+
	+BLOCKQUOTE.NOTE {
	+ color: #222;
	+ background: #eee;
	+ border: 1px solid #ccc;
	+ width: 85%;
	+}
	+
	+BLOCKQUOTE.TIP {
	+ color: #004F00;
	+ background: #d8ecd6;
	+ border: 1px solid green;
	+ width: 85%;
	+}
	+
	+BLOCKQUOTE.IMPORTANT {
	+ font-style:italic;
	+ border: 1px solid #a00;
	+ border-left: 12px solid #c00;
	+}
	+
	+BLOCKQUOTE.WARNING {
	+ color: #9F1313;
	+ background: #f8e8e8;
	+ border: 1px solid #e59595;
	+ width: 85%;
	+}
	+
	+BLOCKQUOTE.CAUTION {
	+ color: #3E3535;
	+ background: #FFC;
	+ border: 1px solid #e59595;
	+ width: 85%;
	+}
	+
	+.EXAMPLE {
	+ background: #fefde6;
	+ border: 1px solid #f1bb16;
	+ margin: 1em 0;
	+ padding: 0.2em 2em;
	+ width: 90%;
	+}
	+
	+.INFORMALTABLE TABLE.CALSTABLE TR TD {
	+ padding-left: 1em;
	+ padding-right: 1em;
	+}

	Property changes on: projects/entities/en_US.ISO8859-1/htdocs/releases/8.4R/docbook.css
	___________________________________________________________________
	Added: svn:keywords
	## -0,0 +1 ##
	+FreeBSD=%H
	\ No newline at end of property
	Index: projects/entities/en_US.ISO8859-1/htdocs/releases/Makefile
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/releases/Makefile (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/releases/Makefile (revision 41355)
	@@ -1,26 +1,26 @@
	# $FreeBSD$

	.if exists(../Makefile.conf)
	.include "../Makefile.conf"
	.endif
	.if exists(../Makefile.inc)
	.include "../Makefile.inc"
	.endif

	DOCS?= index.xml

	SUBDIR= 1.1 1.1.5 2.0 2.0.5R 2.1R 2.1.5R 2.1.6R 2.1.7R 2.2R
	SUBDIR+= 2.2.1R 2.2.2R 2.2.5R 2.2.6R 2.2.7R 2.2.8R 3.0R 3.1R 3.2R
	SUBDIR+= 3.3R 3.4R 3.5R 4.0R 4.1R 4.1.1R 4.2R 4.3R 4.4R 4.5R 4.6R
	SUBDIR+= 4.6.2R 4.7R 4.8R 4.9R 4.10R 4.11R
	SUBDIR+= 5.0R 5.1R 5.2R 5.2.1R 5.3R 5.4R 5.5R
	SUBDIR+= 6.0R 6.1R 6.2R 6.3R 6.4R
	SUBDIR+= 7.0R 7.1R 7.2R 7.3R 7.4R
	-SUBDIR+= 8.0R 8.1R 8.2R 8.3R
	+SUBDIR+= 8.0R 8.1R 8.2R 8.3R 8.4R
	SUBDIR+= 9.0R 9.1R

	.if defined $(NEW_BUILD)
	SUBDIR=
	.endif

	.include "${DOC_PREFIX}/share/mk/web.site.mk"
	Index: projects/entities/en_US.ISO8859-1/htdocs/releases/index.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/releases/index.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/releases/index.xml (revision 41355)
	@@ -1,616 +1,617 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "Release Information">
	]>
	<!-- $FreeBSD$ -->

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.download">
	<img alt="FreeBSD Releases" src="../gifs/releases.jpg" height="200" width="300" align="right" border="0"/>

	<p>FreeBSD releases are classified into "Production Releases" and
	"Legacy Releases". The former are best suited to users looking
	for the latest new features; the latter are for users wishing to
	stay with a more conservative upgrade strategy.</p>

	<p>Releases are further classified by the length of time they will
	be supported by the Security Officer into "Normal" and "Extended"
	releases.</p>

	<p>Documentation files for each release are available for viewing in
	HTML format on the <a href="&base;/relnotes.html">Release
	Documentation</a> page.</p>

	<a name="supported-releases"></a>
	<h2>Currently Supported Releases</h2>

	<p>Complete information about the release date, the classifcation
	type, and the estimated End-Of-Life (EOL) for currently supported
	releases can be found on the <a
	href="&base;/security/security.html#sup"> Supported Releases</a>
	section of the <a href="&base;/security/security.html">FreeBSD
	Security Information</a> page.</p>

	<a name="current"></a>
	<h2>Most Recent Release(s)</h2>

	<h3>Production Releases</h3>
	<p><b>Release &rel.current;</b> (&rel.current.date;)
	<em>
	<a href="&u.rel.announce;">Announcement</a> :
	<a href="&u.rel.notes;">Release Notes</a> :
	<a href="&u.rel.installation;">Installation Instructions</a> :
	<a href="&u.rel.hardware;">Hardware Notes</a> :
	<a href="&u.rel.readme;">Readme</a> :
	<a href="&u.rel.errata;">Errata</a>
	</em></p>

	+ <p><b>Release 9.0</b> (January 2012)
	+ <em>
	+ <a href="9.0R/announce.html">Announcement</a>:
	+ <a href="9.0R/relnotes.html">Release Notes</a>:
	+ <a href="9.0R/installation.html">Installation Instructions</a>:
	+ <a href="9.0R/hardware.html">Hardware Notes</a>:
	+ <a href="9.0R/readme.html">Readme</a>:
	+ <a href="9.0R/errata.html">Errata</a>
	+ </em></p>
	+
	+ <h3>Legacy Releases</h3>
	<p><b>Release &rel2.current;</b> (&rel2.current.date;)
	<em>
	<a href="&u.rel2.announce;">Announcement</a> :
	<a href="&u.rel2.notes;">Release Notes</a> :
	<a href="&u.rel2.installation;">Installation Instructions</a> :
	<a href="&u.rel2.hardware;">Hardware Notes</a> :
	<a href="&u.rel2.readme;">Readme</a> :
	<a href="&u.rel2.errata;">Errata</a>
	</em></p>

	- <h3>Legacy Releases</h3>
	- <p><b>Release &rel3.current;</b> (&rel3.current.date;)
	- <em>
	- <a href="&u.rel3.announce;">Announcement</a> :
	- <a href="&u.rel3.notes;">Release Notes</a> :
	- <a href="&u.rel3.hardware;">Hardware Notes</a> :
	- <a href="&u.rel3.readme;">Readme</a> :
	- <a href="&u.rel3.errata;">Errata</a>
	- </em></p>
	-
	<a name="future"></a>
	<h2>Future Releases</h2>

	<p>For the schedule of upcoming releases, or for more information
	about the release engineering process, please visit the <a
	href="&base;/releng/index.html">Release Engineering</a>
	page.</p>

	<p>The latest snapshots from our <a
	href="&base;/doc/en_US.ISO8859-1/books/handbook/current-stable.html#STABLE">FreeBSD-STABLE</a>
	and <a
	href="&base;/doc/en_US.ISO8859-1/books/handbook/current-stable.html#CURRENT">FreeBSD-CURRENT</a>
	branches are also available. Please see <a
	href="../where.html">Getting FreeBSD</a> for details.</p>

	<!-- <a name="prior-supported"></a>
	<h2>Prior Releases Still Being Supported</h2> -->

	<a name="prior-unsupported"></a>
	<h2>Prior Releases Which Have Reached End-Of-Life</h2>

	<p>Complete historical information about the release date, the
	classification type, and the effective End-Of-Life (EOL) for
	these releases may be found on the <a
	href="&base;/security/security.html#unsup">Unsupported
	Releases</a> section of the <a
	href="&base;/security/security.html">FreeBSD Security
	Information</a> page.</p>

	<ul>
	- <li><b>9.0</b> (January 2012)
	- <em>
	- <a href="9.0R/announce.html">Announcement</a>:
	- <a href="9.0R/relnotes.html">Release Notes</a>:
	- <a href="9.0R/installation.html">Installation Instructions</a>:
	- <a href="9.0R/hardware.html">Hardware Notes</a>:
	- <a href="9.0R/readme.html">Readme</a>:
	- <a href="9.0R/errata.html">Errata</a>
	- </em></li>
	-
	<li><b>8.2</b> (February 2011)
	<em>
	<a href="8.2R/announce.html">Announcement</a>:
	<a href="8.2R/relnotes.html">Release Notes</a>:
	<a href="8.2R/hardware.html">Hardware Notes</a>:
	<a href="8.2R/readme.html">Readme</a>:
	<a href="8.2R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>8.1</b> (July 2010)
	<em>
	<a href="8.1R/announce.html">Announcement</a>:
	<a href="8.1R/relnotes.html">Release Notes</a>:
	<a href="8.1R/hardware.html">Hardware Notes</a>:
	<a href="8.1R/readme.html">Readme</a>:
	<a href="8.1R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>8.0</b> (November 2009)
	<em>
	<a href="8.0R/announce.html">Announcement</a>:
	<a href="8.0R/relnotes.html">Release Notes</a>:
	<a href="8.0R/hardware.html">Hardware Notes</a>:
	<a href="8.0R/readme.html">Readme</a>:
	<a href="8.0R/errata.html">Errata</a>
	+ </em>
	+ </li>
	+
	+ <li><b>7.4</b> (February 2011)
	+ <em>
	+ <a href="7.4R/announce.html">Announcement</a>:
	+ <a href="7.4R/relnotes.html">Release Notes</a>:
	+ <a href="7.4R/hardware.html">Hardware Notes</a>:
	+ <a href="7.4R/readme.html">Readme</a>:
	+ <a href="7.4R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>7.3</b> (March 2010)
	<em>
	<a href="7.3R/announce.html">Announcement</a>:
	<a href="7.3R/relnotes.html">Release Notes</a>:
	<a href="7.3R/hardware.html">Hardware Notes</a>:
	<a href="7.3R/readme.html">Readme</a>:
	<a href="7.3R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>7.2</b> (May 2009)
	<em>
	<a href="7.2R/announce.html">Announcement</a>:
	<a href="7.2R/relnotes.html">Release Notes</a>:
	<a href="7.2R/hardware.html">Hardware Notes</a>:
	<a href="7.2R/readme.html">Readme</a>:
	<a href="7.2R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>7.1</b> (January 2009)
	<em>
	<a href="7.1R/announce.html">Announcement</a>:
	<a href="7.1R/relnotes.html">Release Notes</a>:
	<a href="7.1R/hardware.html">Hardware Notes</a>:
	<a href="7.1R/readme.html">Readme</a>:
	<a href="7.1R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>7.0</b> (February 2008)
	<em>
	<a href="7.0R/announce.html">Announcement</a>:
	<a href="7.0R/relnotes.html">Release Notes</a>:
	<a href="7.0R/hardware.html">Hardware Notes</a>:
	<a href="7.0R/readme.html">Readme</a>:
	<a href="7.0R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>6.4</b> (November 2008)
	<em>
	<a href="6.4R/announce.html">Announcement</a>:
	<a href="6.4R/relnotes.html">Release Notes</a>:
	<a href="6.4R/hardware.html">Hardware Notes</a>:
	<a href="6.4R/installation.html">Installation Notes</a>:
	<a href="6.4R/readme.html">Readme</a>:
	<a href="6.4R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>6.3</b> (January 2008)
	<em>
	<a href="6.3R/announce.html">Announcement</a>:
	<a href="6.3R/relnotes.html">Release Notes</a>:
	<a href="6.3R/hardware.html">Hardware Notes</a>:
	<a href="6.3R/installation.html">Installation Notes</a>:
	<a href="6.3R/readme.html">Readme</a>:
	<a href="6.3R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>6.2</b> (January 2007)
	<em>
	<a href="6.2R/announce.html">Announcement</a>:
	<a href="6.2R/relnotes.html">Release Notes</a>:
	<a href="6.2R/hardware.html">Hardware Notes</a>:
	<a href="6.2R/installation.html">Installation Notes</a>:
	<a href="6.2R/readme.html">Readme</a>:
	<a href="6.2R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>6.1</b> (May 2006)
	<em>
	<a href="6.1R/announce.html">Announcement</a>:
	<a href="6.1R/relnotes.html">Release Notes</a>:
	<a href="6.1R/hardware.html">Hardware Notes</a>:
	<a href="6.1R/installation.html">Installation Notes</a>:
	<a href="6.1R/readme.html">Readme</a>:
	<a href="6.1R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>6.0</b> (November 2005)
	<em>
	<a href="6.0R/announce.html">Announcement</a>:
	<a href="6.0R/relnotes.html">Release Notes</a>:
	<a href="6.0R/hardware.html">Hardware Notes</a>:
	<a href="6.0R/installation.html">Installation Notes</a>:
	<a href="6.0R/readme.html">Readme</a>:
	<a href="6.0R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>5.5</b> (May 2006)
	<em>
	<a href="./5.5R/announce.html">Announcement</a>:
	<a href="./5.5R/relnotes.html">Release Notes</a>:
	<a href="./5.5R/hardware.html">Hardware Notes</a>:
	<a href="./5.5R/installation.html">Installation Notes</a>:
	<a href="./5.5R/readme.html">Readme</a>:
	<a href="./5.5R/errata.html">Errata</a>:
	</em>
	</li>

	<li><b>5.4</b> (May 2005)
	<em>
	<a href="./5.4R/announce.html">Announcement</a>:
	<a href="./5.4R/relnotes.html">Release Notes</a>:
	<a href="./5.4R/hardware.html">Hardware Notes</a>:
	<a href="./5.4R/installation.html">Installation Notes</a>:
	<a href="./5.4R/readme.html">Readme</a>:
	<a href="./5.4R/errata.html">Errata</a>:
	<a href="./5.4R/migration-guide.html">Migration Guide</a>
	</em>
	</li>

	<li><b>5.3</b> (November 2004)
	<em>
	<a href="./5.3R/announce.html">Announcement</a>:
	<a href="./5.3R/relnotes.html">Release Notes</a>:
	<a href="./5.3R/hardware.html">Hardware Notes</a>:
	<a href="./5.3R/installation.html">Installation Notes</a>:
	<a href="./5.3R/readme.html">Readme</a>:
	<a href="./5.3R/errata.html">Errata</a>:
	<a href="./5.3R/migration-guide.html">Migration Guide</a>
	</em>
	</li>

	<li><b>5.2.1</b> (February 2004)
	<em>
	<a href="./5.2.1R/announce.html">Announcement</a>:
	<a href="./5.2.1R/relnotes.html">Release Notes</a>:
	<a href="./5.2.1R/hardware.html">Hardware Notes</a>:
	<a href="./5.2.1R/installation.html">Installation Notes</a>:
	<a href="./5.2.1R/readme.html">Readme</a>:
	<a href="./5.2.1R/errata.html">Errata</a>:
	<a href="./5.2.1R/early-adopter.html">Early Adopter's Guide</a>
	</em>
	</li>

	<li><b>5.2</b> (January 2004)
	<em>
	<a href="./5.2R/announce.html">Announcement</a>:
	<a href="./5.2R/relnotes.html">Release Notes</a>:
	<a href="./5.2R/hardware.html">Hardware Notes</a>:
	<a href="./5.2R/installation.html">Installation Notes</a>:
	<a href="./5.2R/readme.html">Readme</a>:
	<a href="./5.2R/errata.html">Errata</a>:
	<a href="./5.2R/early-adopter.html">Early Adopter's Guide</a>
	</em>
	</li>

	<li><b>5.1</b> (June, 2003)
	<em>
	<a href="./5.1R/announce.html">Announcement</a>:
	<a href="./5.1R/relnotes.html">Release Notes</a>:
	<a href="./5.1R/hardware.html">Hardware Notes</a>:
	<a href="./5.1R/installation.html">Installation Notes</a>:
	<a href="./5.1R/readme.html">Readme</a>:
	<a href="./5.1R/errata.html">Errata</a>:
	<a href="./5.1R/early-adopter.html">Early Adopter's Guide</a>
	</em>
	</li>

	<li><b>5.0</b> (January, 2003)
	<em>
	<a href="./5.0R/announce.html">Announcement</a>:
	<a href="./5.0R/relnotes.html">Release Notes</a>:
	<a href="./5.0R/hardware.html">Hardware Notes</a>:
	<a href="./5.0R/installation.html">Installation Notes</a>:
	<a href="./5.0R/readme.html">Readme</a>:
	<a href="./5.0R/errata.html">Errata</a>:
	<a href="./5.0R/early-adopter.html">Early Adopter's Guide</a>
	</em>
	</li>

	<li><b>4.11</b> (January, 2005)
	<em>
	<a href="./4.11R/announce.html">Announcement</a>:
	<a href="./4.11R/relnotes.html">Release Notes</a>:
	<a href="./4.11R/hardware.html">Hardware Notes</a>:
	<a href="./4.11R/installation.html">Installation Notes</a>:
	<a href="./4.11R/readme.html">Readme</a>:
	<a href="./4.11R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.10</b> (May, 2004)
	<em>
	<a href="./4.10R/announce.html">Announcement</a>:
	<a href="./4.10R/relnotes.html">Release Notes</a>:
	<a href="./4.10R/hardware.html">Hardware Notes</a>:
	<a href="./4.10R/installation.html">Installation Notes</a>:
	<a href="./4.10R/readme.html">Readme</a>:
	<a href="./4.10R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.9</b> (October, 2003)
	<em>
	<a href="./4.9R/announce.html">Announcement</a>:
	<a href="./4.9R/relnotes.html">Release Notes</a>:
	<a href="./4.9R/hardware.html">Hardware Notes</a>:
	<a href="./4.9R/installation.html">Installation Notes</a>:
	<a href="./4.9R/readme.html">Readme</a>:
	<a href="./4.9R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.8</b> (April, 2003)
	<em>
	<a href="./4.8R/announce.html">Announcement</a>:
	<a href="./4.8R/relnotes.html">Release Notes</a>:
	<a href="./4.8R/hardware.html">Hardware Notes</a>:
	<a href="./4.8R/installation.html">Installation Notes</a>:
	<a href="./4.8R/readme.html">Readme</a>:
	<a href="./4.8R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.7</b> (October, 2002)
	<em>
	<a href="./4.7R/announce.html">Announcement</a>:
	<a href="./4.7R/relnotes.html">Release Notes</a>:
	<a href="./4.7R/hardware.html">Hardware Notes</a>:
	<a href="./4.7R/installation.html">Installation Notes</a>:
	<a href="./4.7R/readme.html">Readme</a>:
	<a href="./4.7R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.6.2</b> (August, 2002)
	<em>
	<a href="./4.6.2R/announce.html">Announcement</a>:
	<a href="./4.6.2R/relnotes.html">Release Notes</a>:
	<a href="./4.6.2R/hardware.html">Hardware Notes</a>:
	<a href="./4.6.2R/readme.html">Readme</a>:
	<a href="./4.6.2R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.6</b> (June, 2002)
	<em>
	<a href="./4.6R/announce.html">Announcement</a>:
	<a href="./4.6R/relnotes.html">Release Notes</a>:
	<a href="./4.6R/hardware.html">Hardware Notes</a>:
	<a href="./4.6R/installation.html">Installation Notes</a>:
	<a href="./4.6R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.5</b> (January, 2002)
	<em>
	<a href="./4.5R/announce.html">Announcement</a>:
	<a href="./4.5R/notes.html">Release Notes</a>:
	<a href="./4.5R/hardware.html">Hardware Notes</a>:
	<a href="./4.5R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.4</b> (September, 2001)
	<em>
	<a href="./4.4R/announce.html">Announcement</a>:
	<a href="./4.4R/notes.html">Release Notes</a>:
	<a href="./4.4R/hardware.html">Hardware Notes</a>:
	<a href="./4.4R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.3</b> (April, 2001)
	<em>
	<a href="./4.3R/announce.html">Announcement</a>:
	<a href="./4.3R/notes.html">Release Notes</a>:
	<a href="./4.3R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.2</b> (November, 2000)
	<em>
	<a href="./4.2R/announce.html">Announcement</a>:
	<a href="./4.2R/notes.html">Release Notes</a>:
	<a href="./4.2R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.1.1</b> (September, 2000)
	<em>
	<a href="./4.1.1R/announce.html">Announcement</a> :
	<a href="./4.1.1R/notes.html">Release Notes</a> :
	<a href="./4.1.1R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.1</b> (July, 2000)
	<em>
	<a href="./4.1R/announce.html">Announcement</a>:
	<a href="./4.1R/notes.html">Release Notes</a>:
	<a href="./4.1R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>4.0</b> (March, 2000)
	<em>
	<a href="./4.0R/announce.html">Announcement</a>:
	<a href="./4.0R/notes.html">Release Notes</a>:
	<a href="./4.0R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>3.5</b> (June, 2000)
	<em>
	<a href="./3.5R/announce.html">Announcement</a>:
	<a href="./3.5R/notes.html">Release Notes</a>:
	<a href="./3.5R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>3.4</b> (December, 1999)
	<em>
	<a href="./3.4R/announce.html">Announcement</a>:
	<a href="./3.4R/notes.html">Release Notes</a>:
	<a href="./3.4R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>3.3</b> (September, 1999)
	<em>
	<a href="./3.3R/announce.html">Announcement</a> :
	<a href="./3.3R/notes.html">Release Notes</a> :
	<a href="./3.3R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>3.2</b> (May, 1999)
	<em>
	<a href="./3.2R/announce.html">Announcement</a> :
	<a href="./3.2R/notes.html">Release Notes</a> :
	<a href="./3.2R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>3.1</b> (February, 1999)
	<em>
	<a href="./3.1R/announce.html">Announcement</a> :
	<a href="./3.1R/notes.html">Release Notes</a> :
	<a href="./3.1R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>3.0</b> (October, 1998)
	<em>
	<a href="./3.0R/announce.html">Announcement</a> :
	<a href="./3.0R/notes.html">Release Notes</a> :
	<a href="./3.0R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>2.2.8</b> (December, 1998)
	<em>
	<a href="./2.2.8R/announce.html">Announcement</a> :
	<a href="./2.2.8R/notes.html">Release Notes</a> :
	<a href="./2.2.8R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>2.2.7</b> (July, 1998)
	<em>
	<a href="./2.2.7R/announce.html">Announcement</a> :
	<a href="./2.2.7R/notes.html">Release Notes</a> :
	<a href="./2.2.7R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>2.2.6</b> (March, 1998)
	<em>
	<a href="./2.2.6R/announce.html">Announcement</a> :
	<a href="./2.2.6R/notes.html">Release Notes</a> :
	<a href="./2.2.6R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>2.2.5</b> (October, 1997)
	<em>
	<a href="./2.2.5R/announce.html">Announcement</a> :
	<a href="./2.2.5R/notes.html">Release Notes</a> :
	<a href="./2.2.5R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>2.2.2</b> (May, 1997)
	<em>
	<a href="./2.2.2R/notes.html">Release Notes</a> :
	<a href="./2.2.2R/errata.html">Errata</a>
	</em>
	</li>

	<li><b>2.2.1</b> (April, 1997)
	<em>
	<a href="./2.2.1R/notes.html">Release Notes</a>
	</em>
	</li>

	<li><b>2.2</b> (March, 1997)
	<em>
	<a href="./2.2R/announce.html">Announcement</a> :
	<a href="./2.2R/notes.html">Release Notes</a>
	</em>
	</li>

	<li><b>2.1.7</b> (February, 1997)
	<em>
	<a href="./2.1.7R/announce.html">Announcement</a> :
	<a href="./2.1.7R/notes.html">Release Notes</a>
	</em>
	</li>

	<li><b>2.1.6</b> (December, 1996)
	<em>
	<a href="./2.1.6R/announce.html">Announcement</a> :
	<a href="./2.1.6R/notes.html">Release Notes</a>
	</em>
	</li>

	<li><b>2.1.5</b> (July, 1996)
	<em>
	<a href="./2.1.5R/announce.html">Announcement</a> :
	<a href="./2.1.5R/notes.html">Release Notes</a>
	</em>
	</li>

	<li><b>2.1</b> (November, 1995)
	<em>
	<a href="./2.1R/announce.html">Announcement</a> :
	<a href="./2.1R/notes.html">Release Notes</a>
	</em>
	</li>

	<li><b>2.0.5</b> (June, 1995)
	<em>
	<a href="./2.0.5R/announce.html">Announcement</a> :
	<a href="./2.0.5R/notes.html">Release Notes</a>
	</em>
	</li>

	<li><b>2.0</b> (November, 1994)
	<em>
	<a href="./2.0/announce.html">Announcement</a> :
	<a href="./2.0/notes.html">Release Notes</a>
	</em>
	</li>

	<li><b>1.1.5.1</b> (July, 1994)</li>

	<li><b>1.1.5</b>
	<em>
	<a href="./1.1.5/RELNOTES.FreeBSD">Release Notes</a>
	</em>
	</li>

	<li><b>1.1</b> (May, 1994)
	<em>
	<a href="./1.1/RELNOTES.FreeBSD">Release Notes</a>
	</em>
	</li>

	<li><b>1.0</b> (November, 1993)</li>
	</ul>

	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/releng/charter.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/releng/charter.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/releng/charter.xml (revision 41355)
	@@ -1,74 +1,74 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "Charter for the Release Engineering Team">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.developers">

	<p>The Release Engineering Team has the following responsibilities
	:</p>

	<ul>
	<li><p>Setting and publishing the release schedule for Official
	Project releases of FreeBSD.</p></li>

	<li><p>Documenting and formalizing the RE procedures, so that the
	process can continually be reviewed and improved. This includes
	more documentation about the ports cluster and package split
	procedures.</p></li>

	<li><p>Setting and publishing "Code Freeze" dates, and acting as a
	change-review committee to decide which changes may be made to a
	branch during a code freeze. This includes freezes for HEAD when
	approaching a .0 release as well as the traditional
	- <tt>RELENG_*</tt> code freeze pending a -STABLE release.</p></li>
	+ <tt>releng/*</tt> code freeze pending a -STABLE release.</p></li>

	- <li><p>Creation and maintenance of <tt>RELENG_*</tt> branches of the
	+ <li><p>Creation and maintenance of <tt>releng/*</tt> branches of the
	<tt>src/</tt> tree. This includes final authority over what
	commits are made (and remain in) the -STABLE branch prior to the
	branching of a release branch.</p></li>

	<li><p>Working with core and/or the FreeBSD Foundation to codify a
	set of guidelines that vendors must meet if they are to be allowed
	to call a product "FreeBSD", or an "Official FreeBSD
	release".</p></li>

	<li><p>Testing and integrating required packages from the ports
	collection onto the official project release media. Portmgr@ is
	responsible for managing the <tt>ports/</tt> code freeze and
	providing a complete package build of the re-distributable ports.
	re@ is then responsible for splitting those packages onto
	different ISOs as required by the release media. re@ is
	ultimately responsible for ensuring that all of the required
	packages are available on the FreeBSD release media, but portmgr@
	cooperation is essential.</p></li>

	<li><p>Coordinating with the FreeBSD Documentation Project, to
	ensure that a consistent set of documentation is provided for the
	release. This includes the ability to request that large
	disruptive changes not be made to the documentation set in the
	weeks leading up to a release.</p></li>

	<li><p>Coordinating with the security officer team to ensure that
	pending FreeBSD releases are not affected by recently disclosed
	vulnerabilities. Also, approximately 1 week after a release,
	- change approval control of release branches (<tt>RELENG_X_Y</tt>)
	+ change approval control of release branches (<tt>releng/X.Y/</tt>)
	is transfered from the release engineers to the security-officer
	team. The exact transfer date is to be worked out by the two
	parties once it is clear that the release was a success. A heads
	up message should be sent to developers@ at that time.</p></li>

	<li><p>Sending out messages to announce@FreeBSD.org on behalf of
	the project to announce new releases of FreeBSD.</p></li>
	</ul>

	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/releng/index.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/releng/index.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/releng/index.xml (revision 41355)
	@@ -1,462 +1,460 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY email 're'>
	<!ENTITY title "Release Engineering Information">
	<!ENTITY contact.re '<a xmlns="http://www.w3.org/1999/xhtml" href="mailto:re@FreeBSD.org">re@FreeBSD.org</a>'>
	<!ENTITY contact.so '<a xmlns="http://www.w3.org/1999/xhtml" href="mailto:security-officer@FreeBSD.org">security-officer@FreeBSD.org</a>'>
	<!ENTITY contact.portmgr '<a xmlns="http://www.w3.org/1999/xhtml" href="mailto:portmgr@FreeBSD.org">portmgr@FreeBSD.org</a>'>
	<!ENTITY contact.doc '<a xmlns="http://www.w3.org/1999/xhtml" href="mailto:freebsd-doc@FreeBSD.org">freebsd-doc@FreeBSD.org</a>'>
	<!ENTITY contact.doceng '<a xmlns="http://www.w3.org/1999/xhtml" href="mailto:doceng@FreeBSD.org">doceng@FreeBSD.org</a>'>
	<!ENTITY contact.www '<a xmlns="http://www.w3.org/1999/xhtml" href="mailto:freebsd-www@FreeBSD.org">freebsd-www@FreeBSD.org</a>'>
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.developers">

	<p>This page contains documentation about the FreeBSD release
	engineering process.</p>

	<ul>
	<li><a href="#schedule">Upcoming Release Schedule</a></li>
	<li><a href="#freeze">Code Freeze Status</a></li>
	<li><a href="&base;/releng/charter.html">Charter for the Release
	Engineering Team</a></li>
	<li><a href="#docs">Release Engineering Documentation</a></li>
	<li><a href="#team">Current Release Engineering Team</a></li>
	<li><a href="#faq">Frequently Asked Questions</a></li>

	<!--
	<li>General information about committing to -STABLE.</li>
	-->
	</ul>

	<h2><a name="schedule" id="schedule">Upcoming Release Schedule</a></h2>

	<p>NOTE: Release dates are approximate and may be subject to
	schedule slippage.</p>

	<table class="tblbasic">
	<tr>
	<th>Date</th>
	<th>Event</th>
	<th>Information</th>
	</tr>

	<tr>
	<td>TBD</td>
	<td>&os; 8.4</td>
	- <td><!-- <a href="&base;/releases/8.4R/schedule.html">Target Schedule</a> --></td>
	+ <td><a href="&base;/releases/8.4R/schedule.html">Target Schedule</a></td>
	</tr>

	<tr>
	<td>TBD</td>
	<td>&os; 9.2</td>
	<td><!-- <a href="&base;/releases/9.2R/schedule.html">Target Schedule</a> --></td>
	</tr>
	</table>

	<h2><a name="freeze" id="freeze">Code-Freeze Status</a></h2>

	<p>The following table lists the code freeze status for the major
	branches of the <tt>src/</tt> subtree of the FreeBSD CVS
	repository. Commits to any branch listed as "frozen" must first
	be reviewed and approved by the relevant contact party. The
	status of other subtrees such as <tt>ports/</tt> and <tt>doc/</tt>,
	is also provided below.</p>

	<table class="tblbasic">
	<tr>
	<th>Branch</th>
	<th>Status</th>
	<th>Contact</th>
	<th>Notes</th>
	</tr>

	<tr>
	<td><tt>HEAD</tt></td>
	<td>Open</td>
	<td>committers</td>
	<td>Active development branch for 10-CURRENT.</td>
	</tr>

	<tr>
	<td><tt>stable/9</tt></td>
	<td>Open</td>
	<td>committers</td>
	<td>Development branch for FreeBSD 9-STABLE.</td>
	</tr>

	<tr>
	<td><tt>releng/9.1</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 9.1 supported errata fix branch.</td>
	</tr>

	<tr>
	<td><tt>releng/9.0</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 9.0 supported errata fix branch.</td>
	</tr>

	<tr>
	<td><tt>RELENG_8</tt></td>
	<td>Open</td>
	<td>committers</td>
	<td>Development branch for 8-STABLE.</td>
	</tr>

	<tr>
	<td><tt>RELENG_8_3</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 8.3 supported errata fix branch.</td>
	</tr>

	<tr>
	<td><tt>RELENG_8_2</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 8.2 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_8_1</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 8.1 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_8_0</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 8.0 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_7</tt></td>
	<td>Open</td>
	<td>committers</td>
	- <td>Development branch for 7-STABLE.</td>
	+ <td>Maintenance branch for 7-STABLE (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_7_4</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	- <td>FreeBSD 7.4 supported errata fix branch.</td>
	+ <td>FreeBSD 7.4 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_7_3</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 7.3 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_7_2</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 7.2 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_7_1</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 7.1 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_7_0</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 7.0 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_6</tt></td>
	<td>Open</td>
	<td>committers</td>
	<td>Maintenance branch for 6-STABLE (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_6_4</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 6.4 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_6_3</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 6.3 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_6_2</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 6.2 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_6_1</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 6.1 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_6_0</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 6.0 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_5</tt></td>
	<td>Open</td>
	<td>committers</td>
	<td>Maintenance branch for 5-STABLE (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_5_5</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 5.5 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_5_4</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 5.4 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_5_3</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 5.3 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_5_2</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 5.2 / 5.2.1 security fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_5_1</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 5.1 security fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_5_0</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 5.0 security fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_4</tt></td>
	<td>Open</td>
	<td>committers</td>
	<td>Maintenance branch for 4-STABLE (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_4_11</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 4.11 errata fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_4_10</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 4.10 security fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_4_9</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 4.9 security fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_4_8</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 4.8 security fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_4_7</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 4.7 security fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_4_6</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 4.6 security fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_4_5</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 4.5 security fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_4_4</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 4.4 security fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_4_3</tt></td>
	<td>Frozen</td>
	<td>&contact.so;</td>
	<td>FreeBSD 4.3 security fix branch (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_3</tt></td>
	<td>Open</td>
	<td>committers</td>
	<td>Maintenance branch for 3-STABLE (not officially supported).</td>
	</tr>

	<tr>
	<td><tt>RELENG_2_2</tt></td>
	<td>Open</td>
	<td>committers</td>
	<td>Maintenance branch for 2.2-STABLE (not officially supported).</td>
	</tr>

	<tr class="heading">
	<th>Subtree</th>
	<th>Status</th>
	<th>Contact</th>
	<th>Notes</th>
	</tr>

	<tr>
	<td><tt>ports/</tt></td>
	<td>Open</td>
	<td>&contact.portmgr;</td>
	<td>FreeBSD Ports Collection.</td>
	</tr>

	<tr>
	<td><tt>doc/</tt></td>
	<td>Open</td>
	<td>&contact.doc;</td>
	<td>SGML/XML based documentation set.</td>
	</tr>
	</table>

	<h2><a name="docs" id="docs">Release Engineering Documentation</a></h2>

	<ul>
	<li><p><a href="&base;/doc/en_US.ISO8859-1/articles/releng/index.html">FreeBSD
	Release Engineering</a><br/>

	<small>Describes the approach used by the FreeBSD release
	engineering team to make production quality releases of the
	FreeBSD Operating System. It describes the tools available
	for those interested in producing customized FreeBSD releases
	for corporate rollouts or commercial
	productization.</small></p></li>

	<li><p><a href="&base;/doc/en_US.ISO8859-1/articles/releng-packages/index.html">FreeBSD
	Release Engineering for Third Party Packages</a><br/>

	<small>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 "Ports
	Cluster", 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.</small></p></li>
	</ul>

	<h2><a name="team" id="team">Release Engineering Team</a></h2>

	<p>The primary release engineering team is responsible for approving
	<a href="&base;/doc/en_US.ISO8859-1/books/handbook/freebsd-glossary.html#MFC-GLOSSARY">MFC</a>
	requests during code freezes, setting release schedules, and all of
	the other responsibilities laid out in our <a
	href="&base;/releng/charter.html">charter</a>.</p>

	<p><strong>Primary RE Team
	(<a href="mailto:re@FreeBSD.org">re@FreeBSD.org</a>)</strong> :
	&a.re.members; form the primary release engineering
	decision-making group.</p>

	<p>The builders release engineering team is responsible
	for building and packaging FreeBSD releases on the various supported
	platforms.</p>

	<p><strong>Builders REs (<a
	href="mailto:re-builders@FreeBSD.org">re-builders@FreeBSD.org</a>)</strong> :
	&a.re-builders;</p>

	<p>The third party packages in the Ports Collection are managed by the
	portmgr@ team. Among many other responsibilities, the port managers
	keep the ports cluster running smoothly to produce binary
	packages.</p>

	<p><strong>Package Builders (&contact.portmgr;)</strong> :
	&a.portmgr.members;</p>

	<h2><a name="faq" id="faq">Frequently Asked Questions</a></h2>

	<p>Where can I find the release directory or ISO images for older
	FreeBSD releases?</p>

	<p>The FreeBSD Project does not maintain a centralized historical
	archive of old release ISO images, but there are still many
	- options. First, a large collection of the old releases (many
	+ options. A large collection of the old releases (many
	complete with the package sets) is at <a
	href="ftp://ftp-archive.FreeBSD.org/pub/FreeBSD-Archive/old-releases/">
	ftp://ftp-archive.FreeBSD.org/pub/FreeBSD-Archive/old-releases/</a>.
	- Second, try looking on <a
	- href="http://mirrorlist.FreeBSD.org">http://mirrorlist.FreeBSD.org</a>.
	If you are unable to find an FTP mirror that still contains the
	release you are looking for, then you can email CD-ROM vendors to
	see if they have any old releases available. In September 2003,
	we know of a case where FreeBSD 1.1 was used in a court of law to
	invalidate a bogus software patent. Clearly, older releases can
	be very important in some situations.</p>


	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/search/sitemap.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/search/sitemap.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/search/sitemap.xml (revision 41355)
	@@ -1,1681 +1,1681 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE sitemap PUBLIC "-//FreeBSD//DTD FreeBSD XML Database for Sitemap//EN"
	"http://www.FreeBSD.org/XML/www/share/xml/sitemap.dtd">
	<sitemap>
	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>

	<term>
	<text>Applications</text>
	<destination>&base;/applications.html</destination>
	</term>

	<term>
	<text>Hittinger, Mark</text>
	<destination>&base;/applications.html</destination>
	</term>

	<term>
	<text>WinNet Communications</text>
	<destination>&base;/applications.html</destination>
	</term>

	<term>
	<text>Internet services</text>
	<destination>&base;/applications.html</destination>
	</term>

	<term>
	<text>X Windows workstation</text>
	<destination>&base;/applications.html</destination>
	</term>

	<term>
	<text>Networking</text>
	<destination>&base;/applications.html</destination>
	</term>

	<term>
	<text>Software development</text>
	<destination>&base;/applications.html</destination>
	</term>

	<term>
	<text>Net surfing</text>
	<destination>&base;/applications.html</destination>
	</term>

	<term>
	<text>Education and research</text>
	<destination>&base;/applications.html</destination>
	</term>

	<term>
	<text>FreeBSD Art</text>
	<destination>&base;/art.html</destination>
	</term>

	<term>
	<text>Art, FreeBSD</text>
	<destination>&base;/art.html</destination>
	</term>

	<term>
	<text>Commercial Vendors</text>
	<destination>&base;/commercial/commercial.html</destination>
	</term>

	<term>
	<text>Vendors, commercial</text>
	<destination>&base;/commercial/commercial.html</destination>
	</term>

	<term>
	<text>Commercial Vendors, Consulting</text>
	<destination>&base;/commercial/consult_bycat.html</destination>
	</term>

	<term>
	<text>Consulting, Commercial Vendors</text>
	<destination>&base;/commercial/consult_bycat.html</destination>
	</term>

	<term>
	<text>Commercial Vendors, Hardware</text>
	<destination>&base;/commercial/hardware.html</destination>
	</term>

	<term>
	<text>Hardware, Commercial Vendors</text>
	<destination>&base;/commercial/hardware.html</destination>
	</term>

	<term>
	<text>Commercial Vendors, Software</text>
	<destination>&base;/commercial/software.html</destination>
	</term>

	<term>
	<text>Software, Commercial Vendors</text>
	<destination>&base;/commercial/software.html</destination>
	</term>

	<term>
	<text>Commercial Vendors, Miscellaneous</text>
	<destination>&base;/commercial/misc.html</destination>
	</term>

	<term>
	<text>Miscellaneous, Commercial Vendors</text>
	<destination>&base;/commercial/misc.html</destination>
	</term>

	<term>
	<text>Mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>non-English mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Brazilian Portuguese</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Simplified Chinese</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Czech</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, German</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, French</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Hungarian</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Indonesian</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Italian</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Japanese</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Korean</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Latvian</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Netherlands</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Polish</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Portuguese</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Russian</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Slovakian</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Spanish</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Swedish</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Mailing lists, Turkish</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Brazilian Portuguese mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Simplified Chinese mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Czech mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>German mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>French mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Hungarian mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Polish mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Portuguese mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Japanese mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Hungarian mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Indonesian mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Russian mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Indonesian mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Italian mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Japanese mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Korean mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Latvian mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Netherlands mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Polish mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Portuguese mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Russian mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Slovakian mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Spanish mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Swedish mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Turkish mailing lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</term>

	<term>
	<text>Newsgroups</text>
	<destination>&base;/community/newsgroups.html</destination>
	</term>

	<term>
	<text>Web Resources, mirrors</text>
	<destination>&base;/community/webresources.html</destination>
	</term>

	<term>
	<text>BSD Daemon</text>
	<destination>&base;/copyright/daemon.html</destination>
	</term>

	<term>
	<text>Daemon, BSD</text>
	<destination>&base;/copyright/daemon.html</destination>
	</term>

	<term>
	<text>Nemeth, Evi</text>
	<destination>&base;/copyright/daemon.html</destination>
	</term>

	<term>
	<text>Lassiter, John</text>
	<destination>&base;/copyright/daemon.html</destination>
	</term>

	<term>
	<text>Hosokawa, Tatsumi</text>
	<destination>&base;/copyright/daemon.html</destination>
	</term>

	<term>
	<text>McKusick, Marshall Kirk</text>
	<destination>&base;/copyright/daemon.html</destination>
	</term>

	<term>
	<text>Copyright</text>
	<destination>&base;/copyright/license.html</destination>
	</term>

	<term>
	<text>License</text>
	<destination>&base;/copyright/license.html</destination>
	</term>

	<term>
	<text>Trademark legend</text>
	<destination>&base;/copyright/trademarks.html</destination>
	</term>

	<term>
	<text>CVS Repository</text>
	<destination>&base;/developers/cvs.html</destination>
	</term>

	<term>
	<text>CTM</text>
	<destination>&base;/developers/cvs.html</destination>
	</term>

	<term>
	<text>CVSup</text>
	<destination>&base;/developers/cvs.html</destination>
	</term>

	<term>
	<text>SVN Repository</text>
	<destination>&base;/developers/cvs.html</destination>
	</term>

	<term>
	<text>anoncvs</text>
	<destination>&base;/developers/cvs.html</destination>
	</term>

	<term>
	<text>Japanese Handbook</text>
	<destination>&base;/doc/ja_JP.eucJP/books/handbook/index.html</destination>
	</term>

	<term>
	<text>Handbook, Japanese</text>
	<destination>&base;/doc/ja_JP.eucJP/books/handbook/index.html</destination>
	</term>

	<term>
	<text>Frequently Asked Questions (FAQ)</text>
	<destination>&base;/doc/en_US.ISO8859-1/books/faq/index.html</destination>
	</term>

	<term>
	<text>FAQ</text>
	<destination>&base;/doc/en_US.ISO8859-1/books/faq/index.html</destination>
	</term>

	<term>
	<text>Documentation Project</text>
	<destination>&base;/docproj/docproj.html</destination>
	</term>

	<term>
	<text>Project, Documentation</text>
	<destination>&base;/docproj/docproj.html</destination>
	</term>

	<term>
	<text>Goals, documentation</text>
	<destination>&base;/docproj/docproj.html</destination>
	</term>

	<term>
	<text>FAQ, Documentation Project</text>
	<destination>&base;/docproj/docproj.html</destination>
	</term>

	<term>
	<text>Handbook, Documentation Project</text>
	<destination>&base;/docproj/docproj.html</destination>
	</term>

	<term>
	<text>Contributing, Documentation Project</text>
	<destination>&base;/docproj/docproj.html</destination>
	</term>

	<term>
	<text>Submitting corrections, Documentation Project</text>
	<destination>&base;/docproj/docproj.html</destination>
	</term>

	<term>
	<text>Submitting new material, Documentation Project</text>
	<destination>&base;/docproj/docproj.html</destination>
	</term>

	<term>
	<text>SGML, Documentation Project</text>
	<destination>&base;/docproj/docproj.html</destination>
	</term>

	<term>
	<text>Linuxdoc, Documentation Project</text>
	<destination>&base;/docproj/docproj.html</destination>
	</term>

	<term>
	<text>Docbook, Documentation Project</text>
	<destination>&base;/docproj/docproj.html</destination>
	</term>

	<term>
	<text>Guidelines, Documentation Project</text>
	<destination>&base;/docproj/docproj.html</destination>
	</term>

	<term>
	<text>Documentation</text>
	<destination>&base;/docs.html</destination>
	</term>

	<term>
	<text>Handbook</text>
	<destination>&base;/docs.html</destination>
	</term>

	<term>
	<text>Books</text>
	<destination>&base;/docs/books.html</destination>
	</term>

	<term>
	<text>Manual Pages</text>
	<destination>&cgibase;/man.cgi</destination>
	</term>

	<term>
	<text>Donations</text>
	<destination>&base;/donations/index.html</destination>
	</term>

	<term>
	<text>Events</text>
	<destination>&base;/events/events.html</destination>
	</term>

	<term>
	<text>Features</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>4.4BSD, A complete operating system</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>Berkeley, University of California</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>UCB</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>Computer Systems Research Group</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>CSRG</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>Merged virtual memory and filesystem buffer cache</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>virtual memory</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>buffer cache</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>Compatibility, SCO</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>Compatibility, System V Release 4</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>Compatibility, Linux</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>SCO, Compatibility</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>System V Release 4, Compatibility</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>Linux, Compatibility</text>
	<destination>&base;/features.html</destination>
	</term>

	<term>
	<text>Statistics for this server</text>
	<destination>&base;/internal/about.html</destination>
	</term>

	<term>
	<text>Fieber, John</text>
	<destination>&base;/internal/about.html</destination>
	</term>

	<term>
	<text>Apache http server</text>
	<destination>&base;/internal/about.html</destination>
	</term>

	<term>
	<text>http server</text>
	<destination>&base;/internal/about.html</destination>
	</term>

	<term>
	<text>WWW server www.FreeBSD.org</text>
	<destination>&base;/internal/about.html</destination>
	</term>

	<term>
	<text>hub.FreeBSD.org</text>
	<destination>&base;/internal/about.html</destination>
	</term>

	<term>
	<text>BSDi, network connection</text>
	<destination>&base;/internal/about.html</destination>
	</term>

	<term>
	<text>Network connection, BSDi</text>
	<destination>&base;/internal/about.html</destination>
	</term>

	<term>
	<text>Core Bylaws</text>
	<destination>&base;/internal/bylaws.html</destination>
	</term>

	<term>
	<text>Bylaws, Core</text>
	<destination>&base;/internal/bylaws.html</destination>
	</term>

	<term>
	<text>Charter, Doceng Team</text>
	<destination>&base;/internal/doceng.html</destination>
	</term>

	<term>
	<text>Doceng Team Charter</text>
	<destination>&base;/internal/doceng.html</destination>
	</term>

	<term>
	<text>Documentation Project, doceng</text>
	<destination>&base;/internal/doceng.html</destination>
	</term>

	<term>
	<text>Mirroring the FreeBSD Web Pages</text>
	<destination>&base;/internal/mirror.html</destination>
	</term>

	<term>
	<text>rsync</text>
	<destination>&base;/internal/mirror.html</destination>
	</term>

	<term>
	<text>Internet</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>TCP/IP protocols</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>NFS</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>NIS</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>SNMP</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>FTP</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>DNS/BIND</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>SLIP</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>MBONE</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>SAMBA</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>PCNFS</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>Appletalk</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>Novell</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>TCP extensions</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>RFC-1323</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>networking</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>FTP Server ftp.FreeBSD.org, configuration</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>Yahoo</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>High performance and security</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>Encryption software</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>secure shells</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>Kerberos</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>end-to-end encryption</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>secure RPC facilities</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>O'Brien, Michael</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>SunExpert</text>
	<destination>&base;/internet.html</destination>
	</term>

	<term>
	<text>IPv6 in FreeBSD</text>
	<destination>&base;/ipv6/index.html</destination>
	</term>

	<term>
	<text>IPv6-only Support</text>
	<destination>&base;/ipv6/ipv6only.html</destination>
	</term>

	<term>
	<text>World IPv6 Day</text>
	<destination>&base;/ipv6/w6d.html</destination>
	</term>

	<term>
	<text>IPv6 Day, World</text>
	<destination>&base;/ipv6/w6d.html</destination>
	</term>

	<term>
	<text>Contact us</text>
	<destination>&base;/mailto.html</destination>
	</term>

	<term>
	<text>Questions about this WWW server</text>
	<destination>&base;/mailto.html</destination>
	</term>

	<term>
	<text>Questions about the contents of this WWW server</text>
	<destination>&base;/mailto.html</destination>
	</term>

	<term>
	<text>Questions about FreeBSD</text>
	<destination>&base;/mailto.html</destination>
	</term>

	<term>
	<text>News flash</text>
	<destination>&base;/news/newsflash.html</destination>
	</term>

	<term>
	<text>Press releases, News</text>
	<destination>&base;/news/newsflash.html</destination>
	</term>

	<term>
	<text>Bi-monthly status reports</text>
	<destination>&base;/news/status/status.html</destination>
	</term>

	<term>
	<text>FreeBSD Status Reports</text>
	<destination>&base;/news/status/status.html</destination>
	</term>

	<term>
	<text>Status Reports</text>
	<destination>&base;/news/status/status.html</destination>
	</term>

	<term>
	<text>AMD64</text>
	<destination>&base;/platforms/amd64.html</destination>
	</term>

	<term>
	<text>Athlon64</text>
	<destination>&base;/platforms/amd64.html</destination>
	</term>

	<term>
	<text>FreeBSD/amd64</text>
	<destination>&base;/platforms/amd64.html</destination>
	</term>

	<term>
	<text>Opteron</text>
	<destination>&base;/platforms/amd64.html</destination>
	</term>

	<term>
	<text>x86-64</text>
	<destination>&base;/platforms/amd64.html</destination>
	</term>

	<term>
	<text>ARM</text>
	<destination>&base;/platforms/arm.html</destination>
	</term>

	<term>
	<text>FreeBSD/ARM</text>
	<destination>&base;/platforms/arm.html</destination>
	</term>

	<term>
	<text>StrongARM</text>
	<destination>&base;/platforms/arm.html</destination>
	</term>

	<term>
	<text>FreeBSD/ia64</text>
	<destination>&base;/platforms/ia64/index.html</destination>
	</term>

	<term>
	<text>IA-64</text>
	<destination>&base;/platforms/ia64/index.html</destination>
	</term>

	<term>
	<text>Itanium</text>
	<destination>&base;/platforms/ia64/index.html</destination>
	</term>

	<term>
	<text>FreeBSD/MIPS</text>
	<destination>&base;/platforms/mips.html</destination>
	</term>

	<term>
	<text>MIPS, FreeBSD</text>
	<destination>&base;/platforms/mips.html</destination>
	</term>

	<term>
	<text>SGI MIPS, FreeBSD</text>
	<destination>&base;/platforms/mips.html</destination>
	</term>

	<term>
	<text>FreeBSD/pc98</text>
	<destination>&base;/platforms/pc98.html</destination>
	</term>

	<term>
	<text>NEC PC-98x1</text>
	<destination>&base;/platforms/pc98.html</destination>
	</term>

	<term>
	<text>PC-98</text>
	<destination>&base;/platforms/pc98.html</destination>
	</term>

	<term>
	<text>FreeBSD/PowerPC</text>
	<destination>&base;/platforms/ppc.html</destination>
	</term>

	<term>
	<text>FreeBSD/ppc</text>
	<destination>&base;/platforms/ppc.html</destination>
	</term>

	<term>
	<text>PowerPC</text>
	<destination>&base;/platforms/ppc.html</destination>
	</term>

	<term>
	<text>FreeBSD/sparc64</text>
	<destination>&base;/platforms/sparc.html</destination>
	</term>

	<term>
	<text>Sparc64</text>
	<destination>&base;/platforms/sparc.html</destination>
	</term>

	<term>
	<text>Sparc</text>
	<destination>&base;/platforms/sparc.html</destination>
	</term>

	<term>
	<text>UltraSparc</text>
	<destination>&base;/platforms/sparc.html</destination>
	</term>

	<term>
	<text>FreeBSD/sun4v</text>
	<destination>&base;/platforms/sun4v.html</destination>
	</term>

	<term>
	<text>sun4v</text>
	<destination>&base;/platforms/sun4v.html</destination>
	</term>

	<term>
	<text>UltraSparc-T1</text>
	<destination>&base;/platforms/sun4v.html</destination>
	</term>

	<term>
	<text>xbox</text>
	<destination>&base;/platforms/xbox.html</destination>
	</term>

	<term>
	<text>FreeBSD/xbox</text>
	<destination>&base;/platforms/xbox.html</destination>
	</term>

	<term>
	<text>Ports Collection</text>
	<destination>&base;/ports/index.html</destination>
	</term>

	<term>
	<text>Press, in the</text>
	<destination>&base;/news/press.html</destination>
	</term>

	<term>
	<text>Press Releases, Official</text>
	<destination>&base;/news/pressreleases.html</destination>
	</term>

	<term>
	<text>Privacy Policy</text>
	<destination>&base;/privacy.html</destination>
	</term>

	<term>
	<text>Java</text>
	<destination>&base;/java/index.html</destination>
	</term>

	<term>
	<text>GNOME</text>
	<destination>&base;/gnome/index.html</destination>
	</term>

	<term>
	<text>Newbies Project</text>
	<destination>&base;/projects/newbies.html</destination>
	</term>

	<term>
	<text>Retail Outlets for FreeBSD</text>
	<destination>&base;/doc/en_US.ISO8859-1/books/handbook/mirrors.html</destination>
	</term>

	<term>
	<text>Project ideas</text>
	- <destination>&base;/projects/ideas/index.html</destination>
	+ <destination>https://wiki.freebsd.org/IdeasPage</destination>
	</term>

	<term>
	<text>busdma and SMPng driver conversion project</text>
	<destination>&base;/projects/busdma/index.html</destination>
	</term>

	<term>
	<text>SMPng driver conversion</text>
	<destination>&base;/projects/busdma/index.html</destination>
	</term>

	<term>
	<text>C99 & POSIX Conformance Project</text>
	<destination>&base;/projects/c99/index.html</destination>
	</term>

	<term>
	<text>POSIX Conformance</text>
	<destination>&base;/projects/c99/index.html</destination>
	</term>

	<term>
	<text>Related Publications</text>
	<destination>&base;/publish.html</destination>
	</term>

	<term>
	<text>Publications, Related</text>
	<destination>&base;/publish.html</destination>
	</term>

	<term>
	<text>Covers, Publications</text>
	<destination>&base;/publish.html</destination>
	</term>

	<term>
	<text>Daemon, Covers</text>
	<destination>&base;/publish.html</destination>
	</term>

	<term>
	<text>Recent announcements about FreeBSD Releases</text>
	<destination>&base;/releases/index.html</destination>
	</term>

	<term>
	<text>Release Information</text>
	<destination>&base;/releases/index.html</destination>
	</term>

	<term>
	<text>Release Engineering Information</text>
	<destination>&base;/releng/index.html</destination>
	</term>

	<term>
	<text>Charter, Release Engineering Team</text>
	<destination>&base;/releng/charter.html</destination>
	</term>

	<term>
	<text>Release Engineering Team Charter</text>
	<destination>&base;/releng/charter.html</destination>
	</term>

	<term>
	<text>Release Documentation</text>
	<destination>&base;/relnotes.html</destination>
	</term>

	<term>
	<text>Search Services</text>
	<destination>search.html</destination>
	</term>

	<term>
	<text>Ports Changes, Search</text>
	<destination>search.html</destination>
	</term>

	<term>
	<text>Search, Ports Changes</text>
	<destination>search.html</destination>
	</term>

	<term>
	<text>Message-ID, Search</text>
	<destination>search.html</destination>
	</term>

	<term>
	<text>Search, Message-ID</text>
	<destination>search.html</destination>
	</term>

	<term>
	<text>Usenet News, Search</text>
	<destination>search.html</destination>
	</term>

	<term>
	<text>Newsgroups, Search</text>
	<destination>search.html</destination>
	</term>

	<term>
	<text>Search, Usenet News</text>
	<destination>search.html</destination>
	</term>

	<term>
	<text>Cross reference of the FreeBSD kernel</text>
	<destination>search.html</destination>
	</term>

	<term>
	<text>XR, Cross reference of the FreeBSD kernel</text>
	<destination>search.html</destination>
	</term>

	<term>
	<text>Kernel, Cross reference</text>
	<destination>search.html</destination>
	</term>

	<term>
	<text>Searching Hints</text>
	<destination>searchhints.html</destination>
	</term>

	<term>
	<text>Security Guide</text>
	<destination>&base;/security/security.html</destination>
	</term>

	<term>
	<text>Submit a FreeBSD problem report</text>
	<destination>&base;/send-pr.html</destination>
	</term>

	<term>
	<text>Bug report, submit</text>
	<destination>&base;/send-pr.html</destination>
	</term>

	<term>
	<text>Support</text>
	<destination>&base;/support.html </destination>
	</term>

	<term>
	<text>GNATS Problem Report Database</text>
	<destination>&base;/support/bugreports.html</destination>
	</term>

	<term>
	<text>Bug reports, view</text>
	<destination>&base;/support/bugreports.html</destination>
	</term>

	<term>
	<text>Bug reports, search</text>
	<destination>&base;/support/bugreports.html</destination>
	</term>

	<term>
	<text>User Groups</text>
	<destination>&base;/usergroups.html</destination>
	</term>

	<term>
	<text>Getting FreeBSD</text>
	<destination>&base;/where.html</destination>
	</term>

	<term>
	<text>Commercial software</text>
	<destination>&base;/where.html</destination>
	</term>

	<term>
	<text>4.4BSD Documents</text>
	<destination>http://docs.freebsd.org/44doc/</destination>
	</term>

	<term>
	<text>BSD Documents</text>
	<destination>http://docs.freebsd.org/44doc/</destination>
	</term>

	<term>
	<text>Documents, 4.4BSD</text>
	<destination>http://docs.freebsd.org/44doc/</destination>
	</term>

	<term>
	<text>Info Documents</text>
	<destination>http://docs.freebsd.org/info/</destination>
	</term>

	<term>
	<text>GNU Info Documents</text>
	<destination>http://docs.freebsd.org/info/</destination>
	</term>

	<term>
	- <text>Logo design competition</text>
	- <destination>http://logo-contest.FreeBSD.org/</destination>
	+ <text>Logo</text>
	+ <destination>&base;/logo.html</destination>
	</term>

	<term>
	<text>Security Advisories</text>
	<destination>http://security.freebsd.org</destination>
	</term>

	<term>
	<text>Advisories, security</text>
	<destination>http://security.freebsd.org</destination>
	</term>

	<term>
	<text>SA</text>
	<destination>http://security.freebsd.org</destination>
	</term>

	<term>
	<text>Source Code</text>
	<destination>http://fxr.watson.org/</destination>
	</term>

	<term>
	<text>German web pages</text>
	<destination>&base;/de/index.html</destination>
	</term>

	<term>
	<text>Spanish web pages</text>
	<destination>&base;/es/index.html</destination>
	</term>

	<term>
	<text>Russian web pages</text>
	<destination>&base;/ru/index.html</destination>
	</term>

	<term>
	<text>French web pages</text>
	<destination>&base;/fr/index.html</destination>
	</term>

	<term>
	<text>Italian web pages</text>
	<destination>&base;/it/index.html</destination>
	</term>

	<term>
	<text>Japanese web pages</text>
	<destination>&base;/ja/index.html</destination>
	</term>

	<term>
	<text>Project Staff</text>
	<destination>&base;/administration.html</destination>
	</term>

	<term>
	<text>Staff, Project</text>
	<destination>&base;/administration.html</destination>
	</term>

	<term>
	<text>Who's Who</text>
	<destination>&base;/administration.html</destination>
	</term>

	<term>
	<text>Officers, Project</text>
	<destination>&base;/administration.html</destination>
	</term>

	<category name="About">
	<item>
	<text>Features</text>
	<destination>&base;/features.html</destination>
	</item>

	<item>
	<text>Releases</text>
	<destination>&base;/releases/index.html</destination>
	</item>

	<item>
	<text>Installation</text>
	<destination>&base;/doc/en_US.ISO8859-1/books/handbook/install.html</destination>
	</item>

	<item>
	<text>Supported Hardware</text>
	<destination>&u.rel.hardware;</destination>
	</item>

	<item>
	<text>Mirrors</text>
	<destination>&base;/doc/en_US.ISO8859-1/books/handbook/mirrors.html</destination>
	</item>

	<item>
	<text>Applications</text>
	<destination>&base;/applications.html</destination>
	</item>

	<item>
	<text>Java</text>
	<destination>&base;/java/index.html</destination>
	</item>

	<item>
	<text>GNOME</text>
	<destination>&base;/gnome/index.html</destination>
	</item>

	<item>
	<text>Ports</text>
	<destination>&base;/ports/index.html</destination>
	</item>

	<item>
	<text>Commercial Vendors</text>
	<destination>&base;/commercial/commercial.html</destination>
	</item>

	<item>
	<text>Administration</text>
	<destination>&base;/administration.html</destination>
	</item>
	</category>

	<category name="Get FreeBSD">
	<item>
	<text>Get FreeBSD</text>
	<destination>&base;/where.html</destination>
	</item>

	<item>
	<text>Release Information</text>
	<destination>&base;/releases/index.html</destination>
	</item>

	<item>
	<text>Snapshot Releases</text>
	<destination>&base;/snapshots/index.html</destination>
	</item>

	<item>
	<text>Ported Applications</text>
	<destination>&base;/ports/index.html</destination>
	</item>
	</category>

	<category name="Documentation">
	<item>
	<text>Books</text>
	<destination>&base;/docs/books.html</destination>
	</item>

	<item>
	<text>Handbook</text>
	<destination>&base;/doc/en_US.ISO8859-1/books/handbook/index.html</destination>
	</item>

	<item>
	<text>FAQ</text>
	<destination>&base;/doc/en_US.ISO8859-1/books/faq/index.html</destination>
	</item>

	<item>
	<text>Manual Pages</text>
	<destination>&cgibase;/man.cgi</destination>
	</item>

	<item>
	<text>Other Documentation</text>
	<destination>http://docs.freebsd.org/</destination>
	</item>

	<item>
	<text>Publications</text>
	<destination>&base;/publish.html</destination>
	</item>

	<item>
	<text>Translations</text>
	<destination>&base;/docproj/translations.html</destination>
	</item>

	<item>
	<text>Bibliography</text>
	<destination>&base;/doc/en_US.ISO8859-1/books/handbook/bibliography.html</destination>
	</item>
	</category>

	<category name="Community">
	<item>
	<text>Mailing Lists</text>
	<destination>&base;/community/mailinglists.html</destination>
	</item>

	<item>
	<text>IRC</text>
	<destination>&base;/community/irc.html</destination>
	</item>

	<item>
	<text>Newsgroups</text>
	<destination>&base;/community/newsgroups.html</destination>
	</item>

	<item>
	<text>User Groups</text>
	<destination>&base;/usergroups.html</destination>
	</item>

	<item>
	<text>Web Resources</text>
	<destination>&base;/community/webresources.html</destination>
	</item>
	</category>

	<category name="Developers">
	<item>
	<text>Developers' Handbook</text>
	<destination>&base;/doc/en_US.ISO8859-1/books/developers-handbook/index.html</destination>
	</item>

	<item>
	<text>Porter's Handbook</text>
	<destination>&base;/doc/en_US.ISO8859-1/books/porters-handbook/</destination>
	</item>

	<item>
	<text>CVS Repository</text>
	<destination>&base;/developers/cvs.html</destination>
	</item>

	<item>
	<text>Release Engineering</text>
	<destination>&base;/releng/index.html</destination>
	</item>

	<item>
	<text>Platforms</text>
	<destination>&base;/platforms/index.html</destination>
	</item>

	<item>
	<text>Project Ideas</text>
	- <destination>&base;/projects/ideas/index.html</destination>
	+ <destination>https://wiki.freebsd.org/IdeasPage</destination>
	</item>

	<item>
	<text>Contributing</text>
	<destination>&base;/doc/en_US.ISO8859-1/articles/contributing/index.html</destination>
	</item>
	</category>

	<category name="Support">
	<item>
	<text>Commercial Vendors</text>
	<destination>&base;/commercial/commercial.html</destination>
	</item>

	<item>
	<text>Security Information</text>
	<destination>&base;/security/security.html</destination>
	</item>

	<item>
	<text>Bug Reports</text>
	<destination>&base;/support/bugreports.html</destination>
	</item>

	<item>
	<text>Web Resources</text>
	<destination>&base;/support/webresources.html</destination>
	</item>
	</category>

	<category name="Foundation">
	<item>
	<text>The FreeBSD Foundation</text>
	<destination>http://www.freebsdfoundation.org/</destination>
	</item>
	</category>

	<category name="News">
	<item>
	<text>Newsflash</text>
	<destination>&base;/news/newsflash.html</destination>
	</item>

	<item>
	<text>Official Press Releases</text>
	<destination>&base;/news/pressreleases.html</destination>
	</item>

	<item>
	<text>FreeBSD in the press</text>
	<destination>&base;/news/press.html</destination>
	</item>

	<item>
	<text>Events</text>
	<destination>&base;/events/events.html</destination>
	</item>

	<item>
	<text>Status Reports</text>
	<destination>&base;/news/status/status.html</destination>
	</item>
	</category>

	<category name="Platforms">
	<item>
	<text>FreeBSD/amd64</text>
	<destination>&base;/platforms/amd64.html</destination>
	</item>

	<item>
	<text>FreeBSD/ARM</text>
	<destination>&base;/platforms/arm.html</destination>
	</item>

	<item>
	<text>FreeBSD/i386</text>
	<destination>&base;/platforms/i386.html</destination>
	</item>

	<item>
	<text>FreeBSD/ia64</text>
	<destination>&base;/platforms/ia64/index.html</destination>
	</item>

	<item>
	<text>FreeBSD/MIPS</text>
	<destination>&base;/platforms/mips.html</destination>
	</item>

	<item>
	<text>FreeBSD/pc98</text>
	<destination>&base;/platforms/pc98.html</destination>
	</item>

	<item>
	<text>FreeBSD/ppc</text>
	<destination>&base;/platforms/ppc.html</destination>
	</item>

	<item>
	<text>FreeBSD/sparc64</text>
	<destination>&base;/platforms/sparc.html</destination>
	</item>

	<item>
	<text>FreeBSD/sunv4</text>
	<destination>&base;/platforms/sun4v.html</destination>
	</item>

	<item>
	<text>FreeBSD/xbox</text>
	<destination>&base;/platforms/xbox.html</destination>
	</item>
	</category>

	<category name="Projects">
	<item>
	<text>ACPI</text>
	<destination>&base;/projects/acpi/index.html</destination>
	</item>

	<item>
	<text>Bigdisk</text>
	<destination>&base;/projects/bigdisk/index.html</destination>
	</item>

	<item>
	<text>Busdma and SMPng driver conversion</text>
	<destination>&base;/projects/busdma/index.html</destination>
	</item>

	<item>
	<text>C99 & POSIX® Conformance</text>
	<destination>&base;/projects/c99/index.html</destination>
	</item>

	<item>
	<text>CVSweb</text>
	<destination>&base;/projects/cvsweb.html</destination>
	</item>

	<item>
	<text>FreeBSD Project Ideas</text>
	- <destination>&base;/projects/ideas/index.html</destination>
	+ <destination>https://wiki.freebsd.org/IdeasPage</destination>
	</item>

	<item>
	<text>FreeBSD/MIPS</text>
	<destination>&base;/projects/mips/index.html</destination>
	</item>

	<item>
	<text>Network Performance (netperf)</text>
	<destination>&base;/projects/netperf/index.html</destination>
	</item>
	</category>
	</sitemap>
	Index: projects/entities/en_US.ISO8859-1/htdocs/security/security.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/security/security.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/security/security.xml (revision 41355)
	@@ -1,472 +1,477 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "FreeBSD Security Information">
	]>
	<!-- $FreeBSD$ -->

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.support">

	<h2>Introduction</h2>

	<p>This web page is designed to assist both new and experienced
	users in the area of FreeBSD security. FreeBSD takes security
	very seriously and is constantly working on making the operating
	system as secure as possible.</p>

	<h2>Table of Contents</h2>

	<ul>
	<li><a href="#how">How and where to report a FreeBSD security issue</a></li>
	<li><a href="#sec">Information about the FreeBSD Security Officer</a></li>
	<li><a href="#pol">Information handling policies</a></li>
	<li><a href="#sup">Supported FreeBSD Releases</a></li>
	<li><a href="#unsup">Unsupported FreeBSD Releases</a></li>
	</ul>

	<h2>Other Security Links</h2>

	<ul>
	<li><a href="charter.html">Charter for the Security Officer and Team</a></li>
	<li><a href="advisories.html">List of FreeBSD Security Advisories</a></li>
	<li><a href="notices.html">List of FreeBSD Errata Notices</a></li>
	<li><a href="&base;/doc/en_US.ISO8859-1/books/handbook/security-advisories.html">
	Reading FreeBSD Security Advisories</a></li>
	</ul>

	<a name="how"></a>
	<h2>How and where to report a FreeBSD security issue</h2>

	<p>All FreeBSD security issues should be reported to the <a
	href="mailto:secteam@FreeBSD.org">FreeBSD Security Team</a>
	or, if a higher level of confidentiality is required, PGP encrypted to the <a
	href="mailto:security-officer@FreeBSD.org">Security Officer Team</a>
	using the <a href="so_public_key.asc">Security Officer PGP key</a>.
	All reports should at least contain:</p>

	<ul>
	<li>A description of the vulnerability.</li>
	<li>What versions of FreeBSD seem to be affected if possible.</li>
	<li>Any plausible workaround.</li>
	<li>Example code if possible.</li>
	</ul>

	<p>After this information has been reported the Security Officer or
	a Security Team delegate will get back with you.</p>

	<h3>Spam filters</h3>

	<p>Due to high volume of spam the main security contact mail
	addresses are subject to spam filtering. If you cannot contact
	the FreeBSD Security Officers or Security Team due to spam filters
	(or suspect your mail has been filtered), please send mail to
	<tt>security-officer-<em>XXXX</em>@FreeBSD.org</tt> with
	<em>XXXX</em> replaced with <tt>3432</tt> instead of the normal
	addresses. Note that this address will be changed periodically so
	check back here for the latest address. Mails to this address
	will go to the FreeBSD Security Officer Team.</p>

	<a name="sec"></a>
	<h2>The FreeBSD Security Officer Team and the FreeBSD Security Team</h2>

	<p>In order that the FreeBSD Project may respond to vulnerability
	reports in a timely manner, there are three members of the Security
	Officer mail alias: the Security Officer,
	Deputy Security Officer, and one Core Team member.
	Therefore, messages sent to the <a
	href="mailto:security-officer@FreeBSD.org"><security-officer@FreeBSD.org></a>
	mail alias are currently delivered to:</p>

	<table>
	<tr valign="top">
	<td>&a.simon.email;</td>
	<td>Security Officer</td>
	</tr>
	<tr valign="top">
	<td>&a.cperciva.email;</td>
	<td>Security Officer Emeritus</td>
	</tr>
	<tr valign="top">
	<td>&a.rwatson.email;</td>
	<td>Release Engineering liaison,<br/>
	TrustedBSD Project liaison, system security architecture expert</td>
	</tr>
	+ <tr valign="top">
	+ <td>&a.delphij; <a
	+ href="mailto:delphij@FreeBSD.org"><delphij@FreeBSD.org></a></td>
	+ <td>Deputy Security Officer</td>
	+ </tr>
	</table>

	<p>The Security Officer is supported by the <a
	href="&base;/administration.html#t-secteam" >FreeBSD Security
	Team</a> <a
	href="mailto:secteam@FreeBSD.org"><secteam@FreeBSD.org></a>,
	a small group of committers vetted by the Security Officer.</p>

	<a name="pol"></a>
	<h2>Information handling policies</h2>

	<p>As a general policy, the FreeBSD Security Officer favors full
	disclosure of vulnerability information after a reasonable delay
	to permit safe analysis and correction of a vulnerability, as well
	as appropriate testing of the correction, and appropriate
	coordination with other affected parties.</p>

	<p>The Security Officer <em>will</em> notify one or more of the
	FreeBSD Cluster Admins of
	vulnerabilities that put the FreeBSD Project's resources under
	immediate danger.</p>

	<p>The Security Officer may bring additional FreeBSD developers or
	outside developers into discussion of a submitted security
	vulnerability if their expertise is required to fully understand
	or correct the problem. Appropriate discretion will be exercised
	to minimize unnecessary distribution of information about the
	submitted vulnerability, and any experts brought in will act in
	accordance of Security Officer policies. In the past, experts
	have been brought in based on extensive experience with highly
	complex components of the operating system, including FFS, the VM
	system, and the network stack.</p>

	<p>If a FreeBSD release process is underway, the FreeBSD Release
	Engineer may also be notified that a vulnerability exists, and its
	severity, so that informed decisions may be made regarding the
	release cycle and any serious security bugs present in software
	associated with an up-coming release. If requested, the Security
	Officer will not share information regarding the nature of the
	vulnerability with the Release Engineer, limiting information flow
	to existence and severity.</p>

	<p>The FreeBSD Security Officer has close working relationships with
	a number of other organizations, including third-party vendors
	that share code with FreeBSD (the OpenBSD, NetBSD and DragonFlyBSD
	projects, Apple, and other vendors deriving software from FreeBSD,
	as well as the Linux vendor security list), as well as
	organizations that track vulnerabilities and security incidents,
	such as CERT. Frequently vulnerabilities may extend beyond the
	scope of the FreeBSD implementation, and (perhaps less frequently)
	may have broad implications for the global networking community.
	Under such circumstances, the Security Officer may wish to
	disclose vulnerability information to these other organizations:
	if you do not wish the Security Officer to do this, please
	indicate so explicitly in any submissions.</p>

	<p>Submitters should be careful to explicitly document any special
	information handling requirements.</p>

	<p>If the submitter of a vulnerability is interested in a
	coordinated disclosure process with the submitter and/or other
	vendors, this should be indicated explicitly in any submissions.
	In the absence of explicit requests, the FreeBSD Security Officer
	will select a disclosure schedule that reflects both a desire for
	timely disclosure and appropriate testing of any solutions.
	Submitters should be aware that if the vulnerability is being
	actively discussed in public forums (such as bugtraq), and
	actively exploited, the Security Officer may choose not to follow
	a proposed disclosure timeline in order to provide maximum
	protection for the user community.</p>

	<p>Submissions may be protected using PGP. If desired, responses
	will also be protected using PGP.</p>

	<a name="sup"></a>
	<h2>Supported FreeBSD Releases</h2>

	<p>The FreeBSD Security Officer provides security advisories for
	several branches of FreeBSD development. These are the
	<em>-STABLE Branches</em> and the <em>Security Branches</em>.
	(Advisories are not issued for the <em>-CURRENT Branch</em>.)</p>

	<ul>

	<li><p>The -STABLE branch tags have
	names like <tt>RELENG_7</tt>. The corresponding builds have
	names like <tt>FreeBSD 7.0-STABLE</tt>.</p></li>

	<li><p>Each FreeBSD Release has an associated Security Branch.
	The Security Branch tags have names like <tt>RELENG_7_0</tt>.
	The corresponding builds have names like <tt>FreeBSD
	7.0-RELEASE-p1</tt>.</p></li>
	</ul>

	<p>Issues affecting the FreeBSD Ports Collection are covered in <a
	href="http://vuxml.FreeBSD.org/">the FreeBSD VuXML
	document</a>.</p>

	<p>Each branch is supported by the Security Officer for a limited
	time only, and is designated as one of `<em>Early adopter</em>',
	`<em>Normal</em>', or `<em>Extended</em>'. The designation is
	used as a guideline for determining the lifetime of the branch as
	follows.</p>

	<dl>
	<dt>Early adopter</dt>
	<dd>Releases which are published from the -CURRENT branch will be
	supported by the Security Officer for a minimum of 6 months after
	the release.</dd>
	<dt>Normal</dt>
	<dd>Releases which are published from a -STABLE branch will be
	supported by the Security Officer for a minimum of 12 months after the
	release, and for sufficient additional time (if needed) to ensure
	that there is a newer release for at least 3 months before the
	older Normal release expires.
	</dd>
	<dt>Extended</dt>
	<dd>Selected releases (normally every second release plus the last
	release from each -STABLE branch) will be supported by the
	Security Officer for a minimum of 24 months after the release,
	and for sufficient additional time (if needed) to ensure that
	there is a newer Extended release for at least 3 months before the
	older Extended release expires.
	</dd>
	</dl>

	<a name="supported-branches"></a>

	<p>The current designation and estimated lifetimes of the currently
	supported branches are given below. The <em>Estimated EoL
	(end-of-life)</em> column gives the earliest date on which that
	branch is likely to be dropped. Please note that these dates may
	be extended into the future, but only extenuating circumstances
	would lead to a branch's support being dropped earlier than the
	date listed.</p>

	<!--
	Please also update head/en_US.ISO8859-1/htdocs/releng/index.xml
	when updating this list of supported branches.
	-->
	<table class="tblbasic">
	<tr>
	<th>Branch</th>
	<th>Release</th>
	<th>Type</th>
	<th>Release Date</th>
	<th>Estimated EoL</th>
	</tr>
	<tr>
	- <td>RELENG_7</td>
	- <td>n/a</td>
	- <td>n/a</td>
	- <td>n/a</td>
	- <td>February 28, 2013</td>
	- </tr>
	- <tr>
	- <td>RELENG_7_4</td>
	- <td>7.4-RELEASE</td>
	- <td>Extended</td>
	- <td>February 24, 2011</td>
	- <td>February 28, 2013</td>
	- </tr>
	- <tr>
	<td>RELENG_8</td>
	<td>n/a</td>
	<td>n/a</td>
	<td>n/a</td>
	<td>last release + 2 years</td>
	</tr>
	<tr>
	<td>RELENG_8_3</td>
	<td>8.3-RELEASE</td>
	<td>Extended</td>
	<td>April 18, 2012</td>
	<td>April 30, 2014</td>
	</tr>
	<tr>
	<td>RELENG_9</td>
	<td>n/a</td>
	<td>n/a</td>
	<td>n/a</td>
	<td>last release + 2 years</td>
	</tr>
	<tr>
	- <td>RELENG_9_0</td>
	- <td>9.0-RELEASE</td>
	- <td>Normal</td>
	- <td>January 10, 2012</td>
	- <td>March 31, 2013</td>
	- </tr>
	- <tr>
	<td>RELENG_9_1</td>
	<td>9.1-RELEASE</td>
	<td>Extended</td>
	<td>December 30, 2012</td>
	<td>December 31, 2014</td>
	</tr>
	</table>

	<p>Older releases are not maintained and users are strongly
	encouraged to upgrade to one of the supported releases mentioned
	above.</p>

	<p>Advisories are sent to the following FreeBSD mailing lists:</p>
	<ul>
	<li>FreeBSD-security-notifications@FreeBSD.org</li>
	<li>FreeBSD-security@FreeBSD.org</li>
	<li>FreeBSD-announce@FreeBSD.org</li>
	</ul>

	<p>The list of released advisories can be found on the <a
	href="advisories.html">FreeBSD Security Advisories</a> page.</p>

	<p>Advisories are always signed using the FreeBSD Security Officer
	<a href="so_public_key.asc">PGP
	key</a> and are archived, along with their associated patches, at
	the <a href="http://security.FreeBSD.org/">http://security.FreeBSD.org/</a>
	web server in the <a
	href="http://security.FreeBSD.org/advisories/">advisories</a> and <a
	href="http://security.FreeBSD.org/patches/">patches</a>
	subdirectories.</p>

	<a name="unsup"></a>
	<h2>Unsupported FreeBSD Releases</h2>

	<p>The following releases are no longer supported but are listed
	here for reference purposes.</p>
	<table class="tblbasic">
	<tr>
	<th>Branch</th>
	<th>Release</th>
	<th>Type</th>
	<th>Release Date</th>
	<th>EoL</th>
	</tr>
	<tr>
	<td>RELENG_4</td>
	<td>n/a</td>
	<td>n/a</td>
	<td>n/a</td>
	<td>January 31, 2007</td>
	</tr>
	<tr>
	<td>RELENG_4_11</td>
	<td>4.11-RELEASE</td>
	<td>Extended</td>
	<td>January 25, 2005</td>
	<td>January 31, 2007</td>
	</tr>
	<tr>
	<td>RELENG_5</td>
	<td>n/a</td>
	<td>n/a</td>
	<td>n/a</td>
	<td>May 31, 2008</td>
	</tr>
	<tr>
	<td>RELENG_5_3</td>
	<td>5.3-RELEASE</td>
	<td>Extended</td>
	<td>November 6, 2004</td>
	<td>October 31, 2006</td>
	</tr>
	<tr>
	<td>RELENG_5_4</td>
	<td>5.4-RELEASE</td>
	<td>Normal</td>
	<td>May 9, 2005</td>
	<td>October 31, 2006</td>
	</tr>
	<tr>
	<td>RELENG_5_5</td>
	<td>5.5-RELEASE</td>
	<td>Extended</td>
	<td>May 25, 2006</td>
	<td>May 31, 2008</td>
	</tr>
	<tr>
	<td>RELENG_6</td>
	<td>n/a</td>
	<td>n/a</td>
	<td>n/a</td>
	<td>November 30, 2010</td>
	</tr>
	<tr>
	<td>RELENG_6_0</td>
	<td>6.0-RELEASE</td>
	<td>Normal</td>
	<td>November 4, 2005</td>
	<td>January 31, 2007</td>
	</tr>
	<tr>
	<td>RELENG_6_1</td>
	<td>6.1-RELEASE</td>
	<td>Extended</td>
	<td>May 9, 2006</td>
	<td>May 31, 2008</td>
	</tr>
	<tr>
	<td>RELENG_6_2</td>
	<td>6.2-RELEASE</td>
	<td>Normal</td>
	<td>January 15, 2007</td>
	<td>May 31, 2008</td>
	</tr>
	<tr>
	<td>RELENG_6_3</td>
	<td>6.3-RELEASE</td>
	<td>Extended</td>
	<td>January 18, 2008</td>
	<td>January 31, 2010</td>
	</tr>
	<tr>
	<td>RELENG_6_4</td>
	<td>6.4-RELEASE</td>
	<td>Extended</td>
	<td>November 28, 2008</td>
	<td>November 30, 2010</td>
	</tr>
	<tr>
	+ <td>RELENG_7</td>
	+ <td>n/a</td>
	+ <td>n/a</td>
	+ <td>n/a</td>
	+ <td>February 28, 2013</td>
	+ </tr>
	+ <tr>
	<td>RELENG_7_0</td>
	<td>7.0-RELEASE</td>
	<td>Normal</td>
	<td>February 27, 2008</td>
	<td>April 30, 2009</td>
	</tr>
	<tr>
	<td>RELENG_7_1</td>
	<td>7.1-RELEASE</td>
	<td>Extended</td>
	<td>January 4, 2009</td>
	<td>February 28, 2011</td>
	</tr>
	<tr>
	<td>RELENG_7_2</td>
	<td>7.2-RELEASE</td>
	<td>Normal</td>
	<td>May 4, 2009</td>
	<td>June 30, 2010</td>
	</tr>
	<tr>
	<td>RELENG_7_3</td>
	<td>7.3-RELEASE</td>
	<td>Extended</td>
	<td>March 23, 2010</td>
	<td>March 31, 2012</td>
	</tr>
	<tr>
	+ <td>RELENG_7_4</td>
	+ <td>7.4-RELEASE</td>
	+ <td>Extended</td>
	+ <td>February 24, 2011</td>
	+ <td>February 28, 2013</td>
	+ </tr>
	+ <tr>
	<td>RELENG_8_0</td>
	<td>8.0-RELEASE</td>
	<td>Normal</td>
	<td>November 25, 2009</td>
	<td>November 30, 2010</td>
	</tr>
	<tr>
	<td>RELENG_8_1</td>
	<td>8.1-RELEASE</td>
	<td>Extended</td>
	<td>July 23, 2010</td>
	<td>July 31, 2012</td>
	</tr>
	<tr>
	<td>RELENG_8_2</td>
	<td>8.2-RELEASE</td>
	<td>Normal</td>
	<td>February 24, 2011</td>
	<td>July 31, 2012</td>
	+ </tr>
	+ <tr>
	+ <td>RELENG_9_0</td>
	+ <td>9.0-RELEASE</td>
	+ <td>Normal</td>
	+ <td>January 10, 2012</td>
	+ <td>March 31, 2013</td>
	</tr>
	</table>

	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/htdocs/where.xml
	===================================================================
	--- projects/entities/en_US.ISO8859-1/htdocs/where.xml (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/htdocs/where.xml (revision 41355)
	@@ -1,251 +1,253 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
	"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
	<!ENTITY title "Getting FreeBSD">
	<!ENTITY url.rel "ftp://ftp.FreeBSD.org/pub/FreeBSD/releases">
	]>

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<title>&title;</title>

	<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
	</head>

	<body class="navinclude.download">

	<a name="releases"></a>

	<h2><a href="&base;/releases/index.html">Release
	Information</a></h2>

	<p>Detailed descriptions of past, present, and future releases.
	Look here first to determine what the latest version of FreeBSD
	is.</p>

	<a name="install"></a>

	<h2><a href="&base;/doc/en_US.ISO8859-1/books/handbook/install.html">Installing
	FreeBSD</a></h2>

	<p>There are many options for installing FreeBSD, including
	installation from CD-ROM, DVD, floppy disk, an MS-DOS® partition,
	magnetic tape, anonymous FTP, and NFS. Please read through the
	<a href="&base;/doc/en_US.ISO8859-1/books/handbook/install.html">installation
	guide</a> before downloading the entire FreeBSD distribution.</p>

	<a name="distribution"></a>

	<h2>Buying FreeBSD</h2>

	<p>FreeBSD can be acquired on CD-ROM or DVD from <a
	href="http://www.freebsdmall.com/">FreeBSD Mall</a>, or
	one of the other <a
	href="&base;/doc/en_US.ISO8859-1/books/handbook/mirrors.html">CD-ROM
	and DVD Publishers</a>.</p>

	<a name="download"></a>

	<h2>Download FreeBSD</h2>

	<p>If you plan on getting FreeBSD via FTP or HTTP, please check
	the listing of <a
	href="&base;/doc/en_US.ISO8859-1/books/handbook/mirrors-ftp.html"><strong>mirror
	sites</strong></a> in the handbook to see if there is a site
	closer to you.</p>

	<table class="tblbasic">
	<thead>
	<tr style="text-align: center;">
	<td colspan="2">Version & Platform</td>
	<td>Distribution</td>
	<td title="ISO9660 CD image"><a href="&base;/doc/en_US.ISO8859-1/books/handbook/install-diff-media.html#INSTALL-CDROM">ISO</a></td>
	<td>Release<br/>Notes</td>
	<td>Hardware<br/>Notes</td>
	<td>Installation<br/>Notes</td>
	<td>Errata</td>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td colspan="2">FreeBSD &rel.current;-RELEASE</td>
	<td colspan="2"></td>
	<td rowspan="5"><a href="&base;/releases/&rel.current;R/relnotes.html">[View]</a></td>
	<td rowspan="5"><a href="&base;/releases/&rel.current;R/hardware.html">[View]</a></td>
	<td rowspan="5"><a href="&base;/releases/&rel.current;R/installation.html">[View]</a></td>
	<td rowspan="5"><a href="&base;/releases/&rel.current;R/errata.html">[View]</a></td>
	</tr>
	<tr>
	<td></td>
	- <td>amd64</td>
	+ <td>amd64<br/>(x86-64, x64)</td>
	<td><a href="&url.rel;/amd64/amd64/&rel.current;-RELEASE">[Distribution]</a></td>
	<td><a href="&url.rel;/amd64/amd64/ISO-IMAGES/&rel.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>i386</td>
	<td><a href="&url.rel;/i386/i386/&rel.current;-RELEASE">[Distribution]</a></td>
	<td><a href="&url.rel;/i386/i386/ISO-IMAGES/&rel.current;/">[ISO]</a></td>
	</tr>
	<!--
	<tr>
	<td></td>
	<td>ia64</td>
	<td><a href="&url.rel;/ia64/ia64/&rel.current;-RELEASE">[Distribution]</a></td>
	<td><a href="&url.rel;/ia64/ia64/ISO-IMAGES/&rel.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>powerpc</td>
	<td><a href="&url.rel;/powerpc/powerpc/&rel.current;-RELEASE">[Distribution]</a></td>
	<td><a href="&url.rel;/powerpc/powerpc/ISO-IMAGES/&rel.current;/">[ISO]</a></td>
	</tr>
	-->
	<tr>
	<td></td>
	<td>powerpc64</td>
	<td><a href="&url.rel;/powerpc/powerpc64/&rel.current;-RELEASE">[Distribution]</a></td>
	<td><a href="&url.rel;/powerpc/powerpc64/ISO-IMAGES/&rel.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>sparc64</td>
	<td><a href="&url.rel;/sparc64/sparc64/&rel.current;-RELEASE">[Distribution]</a></td>
	<td><a href="&url.rel;/sparc64/sparc64/ISO-IMAGES/&rel.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td colspan="2">FreeBSD &rel2.current;-RELEASE</td>
	<td colspan="2"></td>
	<td rowspan="5"><a href="&base;/releases/&rel2.current;R/relnotes.html">[View]</a></td>
	<td rowspan="5"><a href="&base;/releases/&rel2.current;R/hardware.html">[View]</a></td>
	<td rowspan="5"><a href="&base;/doc/en_US.ISO8859-1/books/handbook/install.html">[View]</a></td>
	<td rowspan="5"><a href="&base;/releases/&rel2.current;R/errata.html">[View]</a></td>
	</tr>
	<tr>
	<td></td>
	- <td>amd64</td>
	+ <td>amd64<br/>(x86-64, x64)</td>
	<td><a href="&url.rel;/amd64/&rel2.current;-RELEASE">[Distribution]</a></td>
	<td><a href="&url.rel;/amd64/ISO-IMAGES/&rel2.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>i386</td>
	<td><a href="&url.rel;/i386/&rel2.current;-RELEASE">[Distribution]</a></td>
	<td><a href="&url.rel;/i386/ISO-IMAGES/&rel2.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>pc98</td>
	<td><a href="&url.rel;/pc98/&rel2.current;-RELEASE">[Distribution]</a></td>
	<td><a href="&url.rel;/pc98/ISO-IMAGES/&rel2.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>sparc64</td>
	<td><a href="&url.rel;/sparc64/&rel2.current;-RELEASE">[Distribution]</a></td>
	<td><a href="&url.rel;/sparc64/ISO-IMAGES/&rel2.current;/">[ISO]</a></td>
	</tr>
	+ <!--
	<tr>
	<td colspan="2">FreeBSD &rel3.current;-RELEASE</td>
	<td colspan="2"></td>
	<td rowspan="7"><a href="&base;/releases/&rel3.current;R/relnotes.html">[View]</a></td>
	<td rowspan="7"><a href="&base;/releases/&rel3.current;R/hardware.html">[View]</a></td>
	<td rowspan="7"><a href="&base;/doc/en_US.ISO8859-1/books/handbook/install.html">[View]</a></td>
	<td rowspan="7"><a href="&base;/releases/&rel3.current;R/errata.html">[View]</a></td>
	</tr>
	<tr>
	<td></td>
	- <td>amd64</td>
	- <!--<td><a href="&url.rel;/amd64/&rel3.current;-RELEASE">[Distribution]</a></td>-->
	+ <td>amd64<br/>(x86-64, x64)</td>
	+ <td><a href="&url.rel;/amd64/&rel3.current;-RELEASE">[Distribution]</a></td>
	<td colspan="2" align="right"><a href="&url.rel;/amd64/ISO-IMAGES/&rel3.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>i386</td>
	- <!--<td><a href="&url.rel;/i386/&rel3.current;-RELEASE">[Distribution]</a></td>-->
	+ <td><a href="&url.rel;/i386/&rel3.current;-RELEASE">[Distribution]</a></td>
	<td colspan="2" align="right"><a href="&url.rel;/i386/ISO-IMAGES/&rel3.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>pc98</td>
	- <!--<td><a href="&url.rel;/pc98/&rel3.current;-RELEASE">[Distribution]</a></td>-->
	+ <td><a href="&url.rel;/pc98/&rel3.current;-RELEASE">[Distribution]</a></td>
	<td colspan="2" align="right"><a href="&url.rel;/pc98/ISO-IMAGES/&rel3.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>sparc64</td>
	- <!--<td><a href="&url.rel;/sparc64/&rel3.current;-RELEASE">[Distribution]</a></td>-->
	+ <td><a href="&url.rel;/sparc64/&rel3.current;-RELEASE">[Distribution]</a></td>
	<td colspan="2" align="right"><a href="&url.rel;/sparc64/ISO-IMAGES/&rel3.current;/">[ISO]</a></td>
	</tr>
	+ -->
	</tbody>
	</table>

	<p><em>Note:</em> If you are in doubt of which platform /
	architecture to get, you probably need <em>i386</em> if you have
	an older computer, and <em>amd64</em> if you have a newer
	computer.</p>

	&beta.desc;

	<p>If you are interested in a purely experimental
	<strong>snapshot</strong> release of FreeBSD-CURRENT (AKA
	&rel.head;-CURRENT), aimed at developers and bleeding-edge
	testers only, then please see the <a
	href="&base;/snapshots/">&os; Snapshot Releases</a> page. For
	more information about past, present and future releases in
	general, please visit the <a
	href="&base;/releases/index.html">release information
	page</a>.</p>

	<a name="derived"></a>
	<h2>FreeBSD-derived Operating System Distributions</h2>

	<p>FreeBSD is widely used as a building block for other commercial
	and open-source operating systems. The projects below are
	widely used and of particular interest to FreeBSD users.</p>

	<ul>
	<li><p><a href="http://www.freenas.org">FreeNAS</a> is an open
	source storage platform based on FreeBSD and supports sharing
	across Windows, Apple, and UNIX-like systems.</p></li>

	<li><p><a href="http://www.pcbsd.org">PC-BSD</a> is a FreeBSD
	derivative with a graphical installer and impressive desktop
	tools aimed at ease of use for the casual computer
	user.</p></li>

	<li><p><a href="http://www.pfsense.org">pfSense</a> is a free,
	open source customized distribution of FreeBSD tailored for
	use as a firewall and router.</p></li>
	</ul>

	<a name="apps"></a>

	<h2>Applications and Utility Software</h2>

	<h3>The Ports Collection</h3>

	<p>The FreeBSD Ports Collection is a diverse collection of utility
	and application software that has been ported to FreeBSD.</p>

	<ul>
	<li><a href="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/">FreeBSD
	Ports Collection</a></li>

	<li><a href="&base;/ports/index.html">Web interface to the Ports
	Collection</a></li>

	<li><a href="http://www.freshports.org/">FreshPorts - a more
	advanced web interface to the Ports Collection</a></li>
	</ul>

	<p>For information about how <em>you</em> can contribute
	<em>your</em> favorite piece of software to the Ports Collection,
	have a look at <em><a
	href="&base;/doc/en_US.ISO8859-1/books/porters-handbook/index.html">The
	Porter's Handbook</a></em> and the article <em><a
	href="&base;/doc/en_US.ISO8859-1/articles/contributing/index.html">Contributing
	to FreeBSD</a></em>.</p>

	</body>
	</html>
	Index: projects/entities/en_US.ISO8859-1/share/xml/release.l10n.ent
	===================================================================
	--- projects/entities/en_US.ISO8859-1/share/xml/release.l10n.ent (revision 41354)
	+++ projects/entities/en_US.ISO8859-1/share/xml/release.l10n.ent (revision 41355)
	@@ -1,130 +1,140 @@
	<?xml version="1.0" encoding="iso-8859-1"?>
	+<!-- $FreeBSD$ -->
	+
	<![%beta2.testing;[
	<!ENTITY beta.plural 's'>
	]]>
	<!ENTITY beta.plural ''>

	<![%beta2.testing;[
	<!ENTITY beta.second '
	<table xmlns="http://www.w3.org/1999/xhtml" class="tblbasic">
	<thead>
	<tr style="text-align: center;">
	<td colspan="2">Version & Platform</td>
	<td>Distribution</td>
	<td title="ISO9660 CD image"><a href="&base;/doc/en_US.ISO8859-1/books/handbook/install-diff-media.html#INSTALL-CDROM">ISO</a></td>
	<td>TODO List</td>
	</tr>
	</thead>
	<tbody>

	<tr>
	<td colspan="2">FreeBSD &betarel2.current;-&betarel2.vers;</td>
	<td colspan="2"></td>

	<td><a href="&base;/releases/&betarel2.current;R/todo.html">[View]</a></td>

	<td rowspan="7"><a href="http://wiki.freebsd.org/Releng/7.4TODO">[View]</a></td>
	</tr>
	<tr>
	<td></td>
	- <td>amd64</td>
	+ <td>amd64<br/>(x86-64, x64)</td>
	<td><a href="&url.rel;/amd64/amd64/&betarel2.current;-&betarel2.vers;">[Distribution]</a></td>
	<td><a href="&url.rel;/amd64/amd64/ISO-IMAGES/&betarel2.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>i386</td>
	<td><a href="&url.rel;/i386/i386/&betarel2.current;-&betarel2.vers;">[Distribution]</a></td>
	<td><a href="&url.rel;/i386/i386/ISO-IMAGES/&betarel2.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>ia64</td>
	<td><a href="&url.rel;/ia64/ia64/&betarel2.current;-&betarel2.vers;">[Distribution]</a></td>
	<td><a href="&url.rel;/ia64/ia64/ISO-IMAGES/&betarel2.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>powerpc</td>
	<td><a href="&url.rel;/powerpc/powerpc/&betarel2.current;-&betarel2.vers;">[Distribution]</a></td>
	<td><a href="&url.rel;/powerpc/powerpc/ISO-IMAGES/&betarel2.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>powerpc64</td>
	<td><a href="&url.rel;/powerpc/powerpc64/&betarel2.current;-&betarel2.vers;">[Distribution]</a></td>
	<td><a href="&url.rel;/powerpc/powerpc64/ISO-IMAGES/&betarel2.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>sparc64</td>
	<td><a href="&url.rel;/sparc64/sparc64/&betarel2.current;-&betarel2.vers;">[Distribution]</a></td>
	<td><a href="&url.rel;/sparc64/sparc64/ISO-IMAGES/&betarel2.current;/">[ISO]</a></td>
	</tr>
	</tbody>
	</table>
	'>
	]]>
	<!ENTITY beta.second ''>


	<![%beta.testing;[
	<!ENTITY beta.desc '
	<div xmlns="http://www.w3.org/1999/xhtml">
	<a name="helptest"></a>
	<h2>Help With The Next FreeBSD Release&beta.plural;</h2>

	<p>Our developers and release engineers are working on the
	the next release&beta.plural; of FreeBSD; if you wish to help with testing,
	please download the latest build&beta.plural;. Please note that these images
	are, by their very nature, intended for testing and should not
	be used in production environments.</p>

	<table class="tblbasic">
	<thead>
	<tr style="text-align: center;">
	<td colspan="2">Version & Platform</td>
	<td>Distribution</td>
	<td title="ISO9660 CD image"><a href="&base;/doc/en_US.ISO8859-1/books/handbook/install-diff-media.html#INSTALL-CDROM">ISO</a></td>
	- <td>Status page</td>
	+ <!--<td>Status page</td>-->
	</tr>
	</thead>
	<tbody>
	<tr>
	<td colspan="2">FreeBSD &betarel.current;-&betarel.vers;</td>
	<td colspan="2"></td>
	- <td rowspan="7"><a href="http://wiki.freebsd.org/Releng/&betarel.current;TODO">[View]</a></td>
	+ <!--<td rowspan="7"><a href="http://wiki.freebsd.org/Releng/&betarel.current;TODO">[View]</a></td>-->
	</tr>
	<tr>
	<td></td>
	- <td>amd64</td>
	- <td><a href="&url.rel;/amd64/amd64/&betarel.current;-&betarel.vers;">[Distribution]</a></td>
	- <td><a href="&url.rel;/amd64/amd64/ISO-IMAGES/&betarel.current;/">[ISO]</a></td>
	+ <td>amd64<br/>(x86-64, x64)</td>
	+ <td><a href="&url.rel;/amd64/&betarel.current;-&betarel.vers;">[Distribution]</a></td>
	+ <td><a href="&url.rel;/amd64/ISO-IMAGES/&betarel.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>i386</td>
	- <td><a href="&url.rel;/i386/i386/&betarel.current;-&betarel.vers;">[Distribution]</a></td>
	- <td><a href="&url.rel;/i386/i386/ISO-IMAGES/&betarel.current;/">[ISO]</a></td>
	+ <td><a href="&url.rel;/i386/&betarel.current;-&betarel.vers;">[Distribution]</a></td>
	+ <td><a href="&url.rel;/i386/ISO-IMAGES/&betarel.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	+ <td>pc98</td>
	+ <td><a href="&url.rel;/pc98/&betarel.current;-&betarel.vers;">[Distribution]</a></td>
	+ <td><a href="&url.rel;/pc98/ISO-IMAGES/&betarel.current;/">[ISO]</a></td>
	+ </tr>
	+ <!--
	+ <tr>
	+ <td></td>
	<td>sparc64</td>
	- <td><a href="&url.rel;/sparc64/sparc64/&betarel.current;-&betarel.vers;">[Distribution]</a></td>
	- <td><a href="&url.rel;/sparc64/sparc64/ISO-IMAGES/&betarel.current;/">[ISO]</a></td>
	+ <td><a href="&url.rel;/sparc64/&betarel.current;-&betarel.vers;">[Distribution]</a></td>
	+ <td><a href="&url.rel;/sparc64/ISO-IMAGES/&betarel.current;/">[ISO]</a></td>
	</tr>
	<tr>
	<td></td>
	<td>powerpc64</td>
	- <td><a href="&url.rel;/powerpc/powerpc64/&betarel.current;-&betarel.vers;">[Distribution]</a></td>
	- <td><a href="&url.rel;/powerpc/powerpc64/ISO-IMAGES/&betarel.current;/">[ISO]</a></td>
	+ <td><a href="&url.rel;/powerpc/&betarel.current;-&betarel.vers;">[Distribution]</a></td>
	+ <td><a href="&url.rel;/powerpc/ISO-IMAGES/&betarel.current;/">[ISO]</a></td>
	</tr>
	+ -->
	</tbody>
	</table>

	&beta.second;
	</div>
	'>
	]]>

	<!ENTITY beta.desc ''>

	Property changes on: projects/entities/en_US.ISO8859-1/share/xml/release.l10n.ent
	___________________________________________________________________
	Deleted: fbsd:nokeywords
	## -1 +0,0 ##
	-on
	\ No newline at end of property
	Added: svn:keywords
	## -0,0 +1 ##
	+FreeBSD=%H
	\ No newline at end of property
	Index: projects/entities/en_US.ISO8859-1
	===================================================================
	--- projects/entities/en_US.ISO8859-1 (revision 41354)
	+++ projects/entities/en_US.ISO8859-1 (revision 41355)

	Property changes on: projects/entities/en_US.ISO8859-1
	___________________________________________________________________
	Modified: svn:mergeinfo
	## -0,0 +0,1 ##
	Merged /head/en_US.ISO8859-1:r40992-41353

File Metadata

Mime Type: application/octet-stream
Expires: Tue, Oct 14, 3:32 PM (1 d, 23 h)
Storage Engine: chunks
Storage Format: Chunks
Storage Handle: a3adgcEVdzkV
Default Alt Text: (5 MB)

Offset	End	Complete
0	4194304	Yes
4194304	5334566	Yes

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions