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