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