1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
3 "../../../share/xml/freebsd50.dtd" [
4 <!ENTITY % release PUBLIC "-//FreeBSD//ENTITIES Release Specification//EN" "release.ent">
12 sgml-always-quote-attributes: t
15 <article xmlns="http://docbook.org/ns/docbook"
16 xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
18 <title>&os; &release.current; README</title>
20 <author><orgname>The &os; Project</orgname></author>
22 <pubdate>$FreeBSD$</pubdate>
40 <holder role="mailto:doc@FreeBSD.org">The &os; Documentation
44 <legalnotice xml:id="trademarks" role="trademarks">
53 <para>This document gives a brief introduction to &os;
54 &release.current;. It includes some information on how to
55 obtain &os;, a listing of various ways to contact the &os;
56 Project, and pointers to some other sources of
61 <sect1 xml:id="intro">
62 <title>Introduction</title>
64 <para>This distribution is a &release.type; of &os;
65 &release.current;, the latest point along the &release.branch;
69 <title>About &os;</title>
71 <para>&os; is an operating system based on 4.4 BSD Lite for
72 AMD64 and Intel EM64T based PC hardware (&arch.amd64;), Intel,
73 AMD, Cyrix or NexGen <quote>x86</quote> based PC hardware
74 (&arch.i386;), Intel Itanium Processor based computers
75 (&arch.ia64;), NEC PC-9801/9821 series PCs and compatibles
76 (&arch.pc98;), and &ultrasparc; machines (&arch.sparc64;).
77 Versions for the &arm; (&arch.arm;), &mips; (&arch.mips;), and
78 &powerpc; (&arch.powerpc;) architectures are currently under
79 development as well. &os; works with a wide variety of
80 peripherals and configurations and can be used for everything
81 from software development to games to Internet Service
84 <para>This release of &os; contains everything you need to run
85 such a system, including full source code for the kernel and
86 all utilities in the base distribution. With the source
87 distribution installed, you can literally recompile the entire
88 system from scratch with one command, making it ideal for
89 students, researchers, or users who simply want to see how it
92 <para>A large collection of third-party ported software (the
93 <quote>Ports Collection</quote>) is also provided to make it
94 easy to obtain and install all your favorite traditional
95 &unix; utilities for &os;. Each <quote>port</quote> consists
96 of a set of scripts to retrieve, configure, build, and install
97 a piece of software, with a single command. Over
98 &os.numports; ports, from editors to programming languages to
99 graphical applications, make &os; a powerful and comprehensive
100 operating environment that extends far beyond what's provided
101 by many commercial versions of &unix;. Most ports are also
102 available as pre-compiled <quote>packages</quote>, which can
103 be quickly installed from the installation program.</para>
107 <title>Target Audience</title>
109 <para releasetype="current">This &release.type; is aimed
110 primarily at early adopters and various other users who want
111 to get involved with the ongoing development of &os;. While
112 the &os; development team tries its best to ensure that each
113 &release.type; works as advertised, &release.branch; is very
114 much a work-in-progress.</para>
116 <para releasetype="current">The basic requirements for using
117 this &release.type; are technical proficiency with &os; and an
118 understanding of the ongoing development process of &os;
119 &release.branch; (as discussed on the &a.stable;).</para>
121 <para releasetype="current">For those more interested in doing
122 business with &os; than in experimenting with new &os;
123 technology, formal releases (such as &release.prev.stable;)
124 are frequently more appropriate. Releases undergo a period of
125 testing and quality assurance checking to ensure high
126 reliability and dependability.</para>
128 <para releasetype="snapshot">This &release.type; is aimed
129 primarily at early adopters and various other users who want
130 to get involved with the ongoing development of &os;. While
131 the &os; development team tries its best to ensure that each
132 &release.type; works as advertised, &release.branch; is very
133 much a work-in-progress.</para>
135 <para releasetype="snapshot">The basic requirements for using
136 this &release.type; are technical proficiency with &os; and an
137 understanding of the ongoing development process of &os;
138 &release.branch; (as discussed on the &a.stable;).</para>
140 <para releasetype="snapshot">For those more interested in doing
141 business with &os; than in experimenting with new &os;
142 technology, formal releases (such as &release.prev.stable;)
143 are frequently more appropriate. Releases undergo a period of
144 testing and quality assurance checking to ensure high
145 reliability and dependability.</para>
147 <para releasetype="release">This &release.type; of &os; is
148 suitable for all users. It has undergone a period of testing
149 and quality assurance checking to ensure the highest
150 reliability and dependability.</para>
154 <sect1 xml:id="obtain">
155 <title>Obtaining &os;</title>
157 <para>&os; may be obtained in a variety of ways. This section
158 focuses on those ways that are primarily useful for obtaining a
159 complete &os; distribution, rather than updating an existing
163 <title>CDROM and DVD</title>
165 <para>&os; -RELEASE distributions may be ordered on CDROM or DVD
166 from several publishers. This is frequently the most
167 convenient way to obtain &os; for new installations, as it
168 provides a convenient way to quickly reinstall the system if
169 necessary. Some distributions include some of the optional,
170 precompiled <quote>packages</quote> from the &os; Ports
171 Collection, or other extra material.</para>
173 <para>A list of the CDROM and DVD publishers known to the
174 project are listed in the <link
175 xlink:href="&url.books.handbook;/mirrors.html"><quote>Obtaining
176 &os;</quote></link> appendix to the Handbook.</para>
182 <para>You can use FTP to retrieve &os; and any or all of its
183 optional packages from <uri
184 xlink:href="ftp://ftp.FreeBSD.org/">ftp://ftp.FreeBSD.org/</uri>,
185 which is the official &os; release site, or any of its
186 <quote>mirrors</quote>.</para>
188 <para>Lists of locations that mirror &os; can be found in the
189 <link xlink:href="&url.books.handbook;/mirrors-ftp.html">FTP
190 Sites</link> section of the Handbook.
191 Finding a close (in networking terms) mirror from which to
192 download the distribution is highly recommended.</para>
194 <para>Additional mirror sites are always welcome. Contact
195 <email>freebsd-admin@FreeBSD.org</email> for more details on
196 becoming an official mirror site. You can also find useful
197 information for mirror sites at the <link
198 xlink:href="&url.articles.hubs;/">Mirroring &os;</link>
201 <para>Mirrors generally contain the ISO images generally used to
202 create a CDROM of a &os; release. They usually also contain
203 floppy disk images (for applicable platforms), as well as the
204 files necessary to do an installation over the network.
205 Finally mirrors sites usually contain a set of packages for
206 the most current release.</para>
210 <sect1 xml:id="contacting">
211 <title>Contacting the &os; Project</title>
214 <title>Email and Mailing Lists</title>
216 <para>For any questions or general technical support issues,
217 please send mail to the &a.questions;.</para>
219 <para>If tracking the &release.branch; development efforts, you
220 <emphasis>must</emphasis> join the &a.stable;, in order to
221 keep abreast of recent developments and changes that may
222 affect the way you use and maintain the system.</para>
224 <para>Being a largely-volunteer effort, the &os; Project is
225 always happy to have extra hands willing to help—there
226 are already far more desired enhancements than there is time
227 to implement them. To contact the developers on technical
228 matters, or with offers of help, please send mail to the
231 <para>Please note that these mailing lists can experience
232 <emphasis>significant</emphasis> amounts of traffic. If you
233 have slow or expensive mail access, or are only interested in
234 keeping up with major &os; events, you may find it
235 preferable to subscribe instead to the &a.announce;.</para>
237 <para>All of the mailing lists can be freely joined by anyone
238 wishing to do so. Visit the <link
239 xlink:href="&url.base;/mailman/listinfo"> &os; Mailman Info
240 Page</link>. This will give you more information on joining
241 the various lists, accessing archives, etc. There are
242 a number of mailing lists targeted at special interest groups
243 not mentioned here; more information can be obtained either
244 from the Mailman pages or the <link
245 xlink:href="&url.base;/support.html#mailing-list">mailing
246 lists section</link> of the &os; Web site.</para>
249 <para>Do <emphasis>not</emphasis> send email to the lists
250 asking to be subscribed. Use the Mailman interface
256 <title>Submitting Problem Reports</title>
258 <para>Suggestions, bug reports and contributions of code are
259 always valued—please do not hesitate to report any
260 problems you may find. Bug reports with attached fixes are of
261 course even more welcome.</para>
263 <para>The preferred method to submit bug reports from a machine
264 with Internet connectivity is to use the
265 <application>Bugzilla</application> bug tracker.
266 <quote>Problem Reports</quote> (PRs) submitted in this way
267 will be filed and their progress tracked; the &os; developers
268 will do their best to respond to all reported bugs as soon as
270 xlink:href="https://bugs.FreeBSD.org/search/">A list of all
271 active PRs</link> is available on the &os; Web site; this
272 list is useful to see what potential problems other users have
275 <para>Note that &man.send-pr.1; is deprecated.</para>
277 <para>For more information, <link
278 xlink:href="&url.articles.problem-reports;/"><quote>Writing
279 &os; Problem Reports</quote></link>, available on the &os;
280 Web site, has a number of helpful hints on writing and
281 submitting effective problem reports.</para>
285 <sect1 xml:id="seealso">
286 <title>Further Reading</title>
288 <para>There are many sources of information about &os;; some are
289 included with this distribution, while others are available
290 on-line or in print versions.</para>
292 <sect2 xml:id="release-docs">
293 <title>Release Documentation</title>
295 <para>A number of other files provide more specific information
296 about this &release.type; distribution. These files are
297 provided in various formats. Most distributions will include
298 both ASCII text (<filename>.TXT</filename>) and HTML
299 (<filename>.HTM</filename>) renditions. Some distributions
300 may also include other formats such as Portable Document
301 Format (<filename>.PDF</filename>).</para>
305 <para><filename>README.TXT</filename>: This file, which
306 gives some general information about &os; as well as
307 some cursory notes about obtaining a
312 <para><filename>RELNOTES.TXT</filename>: The release
313 notes, showing what's new and different in &os;
314 &release.current; compared to the previous release (&os;
315 &release.prev;).</para>
319 <para><filename>HARDWARE.TXT</filename>: The hardware
320 compatibility list, showing devices with which &os; has
321 been tested and is known to work.</para>
325 <para><filename>ERRATA.TXT</filename>: Release errata.
326 Late-breaking, post-release information can be found in
327 this file, which is principally applicable to releases
328 (as opposed to snapshots). It is important to consult
329 this file before installing a release of &os;, as it
330 contains the latest information on problems which have
331 been found and fixed since the release was
336 <para>On platforms that support &man.bsdinstall.8; (currently
337 &arch.amd64;, &arch.i386;, &arch.ia64;, &arch.pc98;, and
338 &arch.sparc64;), these documents are generally available via
339 the Documentation menu during installation. Once the system
340 is installed, you can revisit this menu by re-running the
341 &man.bsdinstall.8; utility.</para>
344 <para>It is extremely important to read the errata for any
345 given release before installing it, to learn about any
346 <quote>late-breaking news</quote> or post-release problems.
347 The errata file accompanying each release (most likely right
348 next to this file) is already out of date by definition, but
349 other copies are kept updated on the Internet and should be
350 consulted as the <quote>current errata</quote> for this
351 release. These other copies of the errata are located at
353 xlink:href="&url.base;/releases/">&url.base;/releases/</uri>
354 (as well as any sites which keep up-to-date mirrors of this
360 <title>Manual Pages</title>
362 <para>As with almost all &unix; like operating systems, &os;
363 comes with a set of on-line manual pages, accessed through the
364 &man.man.1; command or through the <link
365 xlink:href="http://www.FreeBSD.org/cgi/man.cgi">hypertext
366 manual pages gateway</link> on the &os; Web site. In
367 general, the manual pages provide information on the different
368 commands and APIs available to the &os; user.</para>
370 <para>In some cases, manual pages are written to give
371 information on particular topics. Notable examples of such
372 manual pages are &man.tuning.7; (a guide to performance
373 tuning), &man.security.7; (an introduction to &os; security),
374 and &man.style.9; (a style guide to kernel coding).</para>
378 <title>Books and Articles</title>
380 <para>Two highly-useful collections of &os;-related information,
381 maintained by the &os; Project, are the &os; Handbook and &os;
382 FAQ (Frequently Asked Questions document). On-line versions
384 xlink:href="&url.books.handbook;/">Handbook</link> and <link
385 xlink:href="&url.books.faq;/">FAQ</link> are always
386 available from the <link
387 xlink:href="&url.base;/docs.html">&os; Documentation
388 page</link> or its mirrors. If you install the
389 <filename>doc</filename> distribution set, you can use a Web
390 browser to read the Handbook and FAQ locally. In particular,
391 note that the Handbook contains a step-by-step guide to
392 installing &os;.</para>
394 <para>A number of on-line books and articles, also maintained by
395 the &os; Project, cover more-specialized, &os;-related topics.
396 This material spans a wide range of topics, from effective use
397 of the mailing lists, to dual-booting &os; with other
398 operating systems, to guidelines for new committers. Like the
399 Handbook and FAQ, these documents are available from the &os;
400 Documentation Page or in the <filename>doc</filename>
401 distribution set.</para>
403 <para>A listing of other books and documents about &os; can be
405 xlink:href="&url.books.handbook;/bibliography.html">bibliography</link>
406 of the &os; Handbook. Because of &os;'s strong &unix;
407 heritage, many other articles and books written for &unix;
408 systems are applicable as well, some of which are also listed
409 in the bibliography.</para>
413 <sect1 xml:id="acknowledgements">
414 <title>Acknowledgments</title>
416 <para>&os; represents the cumulative work of many hundreds, if not
417 thousands, of individuals from around the world who have worked
418 countless hours to bring about this &release.type;. For
419 a complete list of &os; developers and contributors, please see
421 xlink:href="&url.articles.contributors;/"><quote>Contributors
422 to &os;</quote></link> on the &os; Web site or any of its
425 <para>Special thanks also go to the many thousands of &os; users
426 and testers all over the world, without whom this &release.type;
427 simply would not have been possible.</para>