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>
26 <holder role="mailto:doc@FreeBSD.org">The &os; Documentation
30 <legalnotice xml:id="trademarks" role="trademarks">
39 <para>This document gives a brief introduction to &os;
40 &release.current;. It includes some information on how to
41 obtain &os;, a listing of various ways to contact the &os;
42 Project, and pointers to some other sources of
47 <sect1 xml:id="intro">
48 <title>Introduction</title>
50 <para>This distribution is a &release.type; of &os;
51 &release.current;, the latest point along the &release.branch;
55 <title>About &os;</title>
57 <para>&os; is an operating system based on 4.4 BSD Lite for
58 AMD64 and Intel EM64T based PC hardware (&arch.amd64;), Intel,
59 AMD, Cyrix or NexGen <quote>x86</quote> based PC hardware
60 (&arch.i386;), Intel Itanium Processor based computers
61 (&arch.ia64;), NEC PC-9801/9821 series PCs and compatibles
62 (&arch.pc98;), and &ultrasparc; machines (&arch.sparc64;).
63 Versions for the &arm; (&arch.arm;), &mips; (&arch.mips;), and
64 &powerpc; (&arch.powerpc;) architectures are currently under
65 development as well. &os; works with a wide variety of
66 peripherals and configurations and can be used for everything
67 from software development to games to Internet Service
70 <para>This release of &os; contains everything you need to run
71 such a system, including full source code for the kernel and
72 all utilities in the base distribution. With the source
73 distribution installed, you can literally recompile the entire
74 system from scratch with one command, making it ideal for
75 students, researchers, or users who simply want to see how it
78 <para>A large collection of third-party ported software (the
79 <quote>Ports Collection</quote>) is also provided to make it
80 easy to obtain and install all your favorite traditional
81 &unix; utilities for &os;. Each <quote>port</quote> consists
82 of a set of scripts to retrieve, configure, build, and install
83 a piece of software, with a single command. Over
84 &os.numports; ports, from editors to programming languages to
85 graphical applications, make &os; a powerful and comprehensive
86 operating environment that extends far beyond what's provided
87 by many commercial versions of &unix;. Most ports are also
88 available as pre-compiled <quote>packages</quote>, which can
89 be quickly installed from the installation program.</para>
93 <title>Target Audience</title>
95 <para releasetype="current">This &release.type; is aimed
96 primarily at early adopters and various other users who want
97 to get involved with the ongoing development of &os;. While
98 the &os; development team tries its best to ensure that each
99 &release.type; works as advertised, &release.branch; is very
100 much a work-in-progress.</para>
102 <para releasetype="current">The basic requirements for using
103 this &release.type; are technical proficiency with &os; and an
104 understanding of the ongoing development process of &os;
105 &release.branch; (as discussed on the &a.stable;).</para>
107 <para releasetype="current">For those more interested in doing
108 business with &os; than in experimenting with new &os;
109 technology, formal releases (such as &release.prev.stable;)
110 are frequently more appropriate. Releases undergo a period of
111 testing and quality assurance checking to ensure high
112 reliability and dependability.</para>
114 <para releasetype="snapshot">This &release.type; is aimed
115 primarily at early adopters and various other users who want
116 to get involved with the ongoing development of &os;. While
117 the &os; development team tries its best to ensure that each
118 &release.type; works as advertised, &release.branch; is very
119 much a work-in-progress.</para>
121 <para releasetype="snapshot">The basic requirements for using
122 this &release.type; are technical proficiency with &os; and an
123 understanding of the ongoing development process of &os;
124 &release.branch; (as discussed on the &a.stable;).</para>
126 <para releasetype="snapshot">For those more interested in doing
127 business with &os; than in experimenting with new &os;
128 technology, formal releases (such as &release.prev.stable;)
129 are frequently more appropriate. Releases undergo a period of
130 testing and quality assurance checking to ensure high
131 reliability and dependability.</para>
133 <para releasetype="release">This &release.type; of &os; is
134 suitable for all users. It has undergone a period of testing
135 and quality assurance checking to ensure the highest
136 reliability and dependability.</para>
140 <sect1 xml:id="obtain">
141 <title>Obtaining &os;</title>
143 <para>&os; may be obtained in a variety of ways. This section
144 focuses on those ways that are primarily useful for obtaining a
145 complete &os; distribution, rather than updating an existing
149 <title>CDROM and DVD</title>
151 <para>&os; -RELEASE distributions may be ordered on CDROM or DVD
152 from several publishers. This is frequently the most
153 convenient way to obtain &os; for new installations, as it
154 provides a convenient way to quickly reinstall the system if
155 necessary. Some distributions include some of the optional,
156 precompiled <quote>packages</quote> from the &os; Ports
157 Collection, or other extra material.</para>
159 <para>A list of the CDROM and DVD publishers known to the
160 project are listed in the <link
161 xlink:href="&url.books.handbook;/mirrors.html"><quote>Obtaining
162 &os;</quote></link> appendix to the Handbook.</para>
168 <para>You can use FTP to retrieve &os; and any or all of its
169 optional packages from <uri
170 xlink:href="ftp://ftp.FreeBSD.org/">ftp://ftp.FreeBSD.org/</uri>,
171 which is the official &os; release site, or any of its
172 <quote>mirrors</quote>.</para>
174 <para>Lists of locations that mirror &os; can be found in the
175 <link xlink:href="&url.books.handbook;/mirrors-ftp.html">FTP
176 Sites</link> section of the Handbook.
177 Finding a close (in networking terms) mirror from which to
178 download the distribution is highly recommended.</para>
180 <para>Additional mirror sites are always welcome. Contact
181 <email>freebsd-admin@FreeBSD.org</email> for more details on
182 becoming an official mirror site. You can also find useful
183 information for mirror sites at the <link
184 xlink:href="&url.articles.hubs;/">Mirroring &os;</link>
187 <para>Mirrors generally contain the ISO images generally used to
188 create a CDROM of a &os; release. They usually also contain
189 floppy disk images (for applicable platforms), as well as the
190 files necessary to do an installation over the network.
191 Finally mirrors sites usually contain a set of packages for
192 the most current release.</para>
196 <sect1 xml:id="contacting">
197 <title>Contacting the &os; Project</title>
200 <title>Email and Mailing Lists</title>
202 <para>For any questions or general technical support issues,
203 please send mail to the &a.questions;.</para>
205 <para>If tracking the &release.branch; development efforts, you
206 <emphasis>must</emphasis> join the &a.stable;, in order to
207 keep abreast of recent developments and changes that may
208 affect the way you use and maintain the system.</para>
210 <para>Being a largely-volunteer effort, the &os; Project is
211 always happy to have extra hands willing to help—there
212 are already far more desired enhancements than there is time
213 to implement them. To contact the developers on technical
214 matters, or with offers of help, please send mail to the
217 <para>Please note that these mailing lists can experience
218 <emphasis>significant</emphasis> amounts of traffic. If you
219 have slow or expensive mail access, or are only interested in
220 keeping up with major &os; events, you may find it
221 preferable to subscribe instead to the &a.announce;.</para>
223 <para>All of the mailing lists can be freely joined by anyone
224 wishing to do so. Visit the <link
225 xlink:href="&url.base;/mailman/listinfo"> &os; Mailman Info
226 Page</link>. This will give you more information on joining
227 the various lists, accessing archives, etc. There are
228 a number of mailing lists targeted at special interest groups
229 not mentioned here; more information can be obtained either
230 from the Mailman pages or the <link
231 xlink:href="&url.base;/support.html#mailing-list">mailing
232 lists section</link> of the &os; Web site.</para>
235 <para>Do <emphasis>not</emphasis> send email to the lists
236 asking to be subscribed. Use the Mailman interface
242 <title>Submitting Problem Reports</title>
244 <para>Suggestions, bug reports and contributions of code are
245 always valued—please do not hesitate to report any
246 problems you may find. Bug reports with attached fixes are of
247 course even more welcome.</para>
249 <para>The preferred method to submit bug reports from a machine
250 with Internet connectivity is to use the
251 <application>Bugzilla</application> bug tracker.
252 <quote>Problem Reports</quote> (PRs) submitted in this way
253 will be filed and their progress tracked; the &os; developers
254 will do their best to respond to all reported bugs as soon as
256 xlink:href="https://bugs.FreeBSD.org/search/">A list of all
257 active PRs</link> is available on the &os; Web site; this
258 list is useful to see what potential problems other users have
261 <para>Note that &man.send-pr.1; is deprecated.</para>
263 <para>For more information, <link
264 xlink:href="&url.articles.problem-reports;/"><quote>Writing
265 &os; Problem Reports</quote></link>, available on the &os;
266 Web site, has a number of helpful hints on writing and
267 submitting effective problem reports.</para>
271 <sect1 xml:id="seealso">
272 <title>Further Reading</title>
274 <para>There are many sources of information about &os;; some are
275 included with this distribution, while others are available
276 on-line or in print versions.</para>
278 <sect2 xml:id="release-docs">
279 <title>Release Documentation</title>
281 <para>A number of other files provide more specific information
282 about this &release.type; distribution. These files are
283 provided in various formats. Most distributions will include
284 both ASCII text (<filename>.TXT</filename>) and HTML
285 (<filename>.HTM</filename>) renditions. Some distributions
286 may also include other formats such as Portable Document
287 Format (<filename>.PDF</filename>).</para>
291 <para><filename>README.TXT</filename>: This file, which
292 gives some general information about &os; as well as
293 some cursory notes about obtaining a
298 <para><filename>RELNOTES.TXT</filename>: The release
299 notes, showing what's new and different in &os;
300 &release.current; compared to the previous release (&os;
301 &release.prev;).</para>
305 <para><filename>HARDWARE.TXT</filename>: The hardware
306 compatibility list, showing devices with which &os; has
307 been tested and is known to work.</para>
311 <para><filename>ERRATA.TXT</filename>: Release errata.
312 Late-breaking, post-release information can be found in
313 this file, which is principally applicable to releases
314 (as opposed to snapshots). It is important to consult
315 this file before installing a release of &os;, as it
316 contains the latest information on problems which have
317 been found and fixed since the release was
322 <para>On platforms that support &man.bsdinstall.8; (currently
323 &arch.amd64;, &arch.i386;, &arch.ia64;, &arch.pc98;, and
324 &arch.sparc64;), these documents are generally available via
325 the Documentation menu during installation. Once the system
326 is installed, you can revisit this menu by re-running the
327 &man.bsdinstall.8; utility.</para>
330 <para>It is extremely important to read the errata for any
331 given release before installing it, to learn about any
332 <quote>late-breaking news</quote> or post-release problems.
333 The errata file accompanying each release (most likely right
334 next to this file) is already out of date by definition, but
335 other copies are kept updated on the Internet and should be
336 consulted as the <quote>current errata</quote> for this
337 release. These other copies of the errata are located at
339 xlink:href="&url.base;/releases/">&url.base;/releases/</uri>
340 (as well as any sites which keep up-to-date mirrors of this
346 <title>Manual Pages</title>
348 <para>As with almost all &unix; like operating systems, &os;
349 comes with a set of on-line manual pages, accessed through the
350 &man.man.1; command or through the <link
351 xlink:href="http://www.FreeBSD.org/cgi/man.cgi">hypertext
352 manual pages gateway</link> on the &os; Web site. In
353 general, the manual pages provide information on the different
354 commands and APIs available to the &os; user.</para>
356 <para>In some cases, manual pages are written to give
357 information on particular topics. Notable examples of such
358 manual pages are &man.tuning.7; (a guide to performance
359 tuning), &man.security.7; (an introduction to &os; security),
360 and &man.style.9; (a style guide to kernel coding).</para>
364 <title>Books and Articles</title>
366 <para>Two highly-useful collections of &os;-related information,
367 maintained by the &os; Project, are the &os; Handbook and &os;
368 FAQ (Frequently Asked Questions document). On-line versions
370 xlink:href="&url.books.handbook;/">Handbook</link> and <link
371 xlink:href="&url.books.faq;/">FAQ</link> are always
372 available from the <link
373 xlink:href="&url.base;/docs.html">&os; Documentation
374 page</link> or its mirrors. If you install the
375 <filename>doc</filename> distribution set, you can use a Web
376 browser to read the Handbook and FAQ locally. In particular,
377 note that the Handbook contains a step-by-step guide to
378 installing &os;.</para>
380 <para>A number of on-line books and articles, also maintained by
381 the &os; Project, cover more-specialized, &os;-related topics.
382 This material spans a wide range of topics, from effective use
383 of the mailing lists, to dual-booting &os; with other
384 operating systems, to guidelines for new committers. Like the
385 Handbook and FAQ, these documents are available from the &os;
386 Documentation Page or in the <filename>doc</filename>
387 distribution set.</para>
389 <para>A listing of other books and documents about &os; can be
391 xlink:href="&url.books.handbook;/bibliography.html">bibliography</link>
392 of the &os; Handbook. Because of &os;'s strong &unix;
393 heritage, many other articles and books written for &unix;
394 systems are applicable as well, some of which are also listed
395 in the bibliography.</para>
399 <sect1 xml:id="acknowledgements">
400 <title>Acknowledgments</title>
402 <para>&os; represents the cumulative work of many hundreds, if not
403 thousands, of individuals from around the world who have worked
404 countless hours to bring about this &release.type;. For
405 a complete list of &os; developers and contributors, please see
407 xlink:href="&url.articles.contributors;/"><quote>Contributors
408 to &os;</quote></link> on the &os; Web site or any of its
411 <para>Special thanks also go to the many thousands of &os; users
412 and testers all over the world, without whom this &release.type;
413 simply would not have been possible.</para>