diff --git a/documentation/content/en/articles/building-products/_index.adoc b/documentation/content/en/articles/building-products/_index.adoc --- a/documentation/content/en/articles/building-products/_index.adoc +++ b/documentation/content/en/articles/building-products/_index.adoc @@ -118,26 +118,26 @@ Here are a few ways organizations have used FreeBSD: * As an upstream source for tested code for libraries and utilities. -+ ++ By being "downstream" of the project, organizations leverage the new features, bug fixes and testing that the upstream code receives. * As an embedded OS (for example, for an OEM router and firewall device). In this model, organizations use a customized FreeBSD kernel and application program set along with a proprietary management layer for their device. OEMs benefit from new hardware support being added by the FreeBSD project upstream, and from the testing that the base system receives. -+ ++ FreeBSD ships with a self-hosting development environment that allows easy creation of such configurations. * As a Unix compatible environment for the management functions of high-end storage and networking devices, running on a separate processor "blade". -+ ++ FreeBSD provides the tools for creating dedicated OS and application program images. Its implementation of a BSD unix API is mature and tested. FreeBSD can also provide a stable cross-development environment for the other components of the high-end device. * As a vehicle to get widespread testing and support from a worldwide team of developers for non-critical "intellectual property". -+ ++ In this model, organizations contribute useful infrastructural frameworks to the FreeBSD project (for example, see man:netgraph[3]). The widespread exposure that the code gets helps to quickly identify performance issues and bugs. The involvement of top-notch developers also leads to useful extensions to the infrastructure that the contributing organization also benefits from. * As a development environment supporting cross-development for embedded OSes like http://www.rtems.com/[RTEMS] and http://ecos.sourceware.org/[eCOS]. -+ ++ There are many full-fledged development environments in the {numports}-strong collection of applications ported and packaged with FreeBSD. * As a way to support a Unix-like API in an otherwise proprietary OS, increasing its palatability for application developers. -+ ++ Here parts of FreeBSD's kernel and application programs are "ported" to run alongside other tasks in the proprietary OS. The availability of a stable and well tested Unix(TM) API implementation can reduce the effort needed to port popular applications to the proprietary OS. As FreeBSD ships with high-quality documentation for its internals and has effective vulnerability management and release engineering processes, the costs of keeping up-to-date are kept low. @@ -154,12 +154,12 @@ * Libraries for many programming tasks: archivers, FTP and HTTP support, thread support, in addition to a full POSIX(TM) like programming environment. * Security features: Mandatory Access Control (man:mac[9]), jails (man:jail[2]), ACLs, and in-kernel cryptographic device support. * Networking features: firewall-ing, QoS management, high-performance TCP/IP networking with support for many extensions. -+ ++ FreeBSD's in-kernel Netgraph (man:netgraph[4]) framework allows kernel networking modules to be connected together in flexible ways. * Support for storage technologies: Fibre Channel, SCSI, software and hardware RAID, ATA and SATA. -+ ++ FreeBSD supports a number of filesystems, and its native UFS2 filesystem supports soft updates, snapshots and very large filesystem sizes (16TB per filesystem) <>. -+ ++ FreeBSD's in-kernel GEOM (man:geom[4]) framework allows kernel storage modules to be composed in flexible ways. * Over {numports} ported applications, both commercial and open-source, managed via the FreeBSD ports collection. diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -183,7 +183,7 @@ <.> A three year key lifespan is short enough to obsolete keys weakened by advancing computer power, but long enough to reduce key management problems. <.> Use your real name here, preferably matching that shown on government-issued ID to make it easier for others to verify your identity. Text that may help others identify you can be entered in the `Comment` section. -+ ++ After the email address is entered, a passphrase is requested. Methods of creating a secure passphrase are contentious. Rather than suggest a single way, here are some links to sites that describe various methods: http://world.std.com/~reinhold/diceware.html[], http://www.iusmentis.com/security/passphrasefaq/[], http://xkcd.com/936/[], http://en.wikipedia.org/wiki/Passphrase[]. @@ -2307,22 +2307,22 @@ *Procedure 1. Steps for New Committers* . Add an Author Entity -+ ++ [.filename]#doc/shared/authors.adoc# - Add an author entity. Later steps depend on this entity, and missing this step will cause the [.filename]#doc/# build to fail. This is a relatively easy task, but remains a good first test of version control skills. . Update the List of Developers and Contributors -+ ++ [.filename]#doc/documentation/content/en/articles/contributors/contrib-committers.adoc# - Add an entry, which will then appear in the "Developers" section of the link:{contributors}#staff-committers[Contributors List]. Entries are sorted by last name. -+ ++ [.filename]#doc/documentation/content/en/articles/contributors/contrib-additional.adoc# - _Remove_ the entry. Entries are sorted by first name. . Add a News Item -+ ++ [.filename]#doc/website/data/en/news/news.toml# - Add an entry. Look for the other entries that announce new committers and follow the format. Use the date from the commit bit approval email from mailto:core@FreeBSD.org[core@FreeBSD.org]. . Add a PGP Key -+ ++ `{des}` has written a shell script ([.filename]#doc/documentation/tools/addkey.sh#) to make this easier. See the https://cgit.freebsd.org/doc/plain/documentation/static/pgpkeys/README[README] file for more information. -+ ++ Use [.filename]#doc/documentation/tools/checkkey.sh# to verify that keys meet minimal best-practices standards. -+ ++ After adding and checking a key, add both updated files to source control and then commit them. Entries in this file are sorted by last name. + [NOTE] @@ -2330,24 +2330,24 @@ It is very important to have a current PGP/GnuPG key in the repository. The key may be required for positive identification of a committer. For example, the `{admins}` might need it for account recovery. A complete keyring of `FreeBSD.org` users is available for download from link:https://www.FreeBSD.org/doc/pgpkeyring.txt[https://www.FreeBSD.org/doc/pgpkeyring.txt]. ====== . Update Mentor and Mentee Information -+ ++ [.filename]#src/share/misc/committers-.dot# - Add an entry to the current committers section, where _repository_ is `doc`, `ports`, or `src`, depending on the commit privileges granted. -+ ++ Add an entry for each additional mentor/mentee relationship in the bottom section. . Generate a Kerberos Password -+ ++ See <> to generate or set a Kerberos for use with other FreeBSD services like the bug tracking database. . Optional: Enable Wiki Account -+ ++ https://wiki.freebsd.org[FreeBSD Wiki] Account - A wiki account allows sharing projects and ideas. Those who do not yet have an account can follow instructions on the https://wiki.freebsd.org/AboutWiki[AboutWiki Page] to obtain one. Contact mailto:wiki-admin@FreeBSD.org[wiki-admin@FreeBSD.org] if you need help with your Wiki account. . Optional: Update Wiki Information -+ ++ Wiki Information - After gaining access to the wiki, some people add entries to the https://wiki.freebsd.org/HowWeGotHere[How We Got Here], https://wiki.freebsd.org/IRC/Nicknames[IRC Nicks], and https://wiki.freebsd.org/Community/Dogs[Dogs of FreeBSD] pages. . Optional: Update Ports with Personal Information -+ ++ [.filename]#ports/astro/xearth/files/freebsd.committers.markers# and [.filename]#src/usr.bin/calendar/calendars/calendar.freebsd# - Some people add entries for themselves to these files to show where they are located or the date of their birthday. . Optional: Prevent Duplicate Mailings -+ ++ Subscribers to {dev-commits-doc-all}, {dev-commits-ports-all} or {dev-commits-src-all} might wish to unsubscribe to avoid receiving duplicate copies of commit messages and followups. ==== @@ -2364,7 +2364,7 @@ ====== If your e-mail system uses SPF with strict rules, you should whitelist `mx2.FreeBSD.org` from SPF checks. ====== -+ ++ 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. To have these checks turned off for your email, create a file named [.filename]#~/.spam_lover# on `freefall.FreeBSD.org`. + [NOTE] @@ -2509,7 +2509,7 @@ * Ping the patch. If it is urgent, provide reasons why it is important to you to get this patch landed and ping it every couple of days. If it is not urgent, the common courtesy ping rate is one week. Remember that you are asking for valuable time from other professional developers. * Ask for help on mailing lists, IRC, etc. Others may be able to either help you directly, or suggest a reviewer. * Split your patch into multiple smaller patches that build on each other. The smaller your patch, the higher the probability that somebody will take a quick look at it. -+ ++ When making large changes, it is helpful to keep this in mind from the beginning of the effort as breaking large changes into smaller ones is often difficult after the fact. Developers should participate in code reviews as both reviewers and reviewees. @@ -3168,23 +3168,23 @@ [[respect]] . Respect other committers. -+ ++ 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 _treat_ other committers with respect at all times, on public forums and in private email. -+ ++ 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. -+ ++ 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 persons 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 "energy economics", 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. -+ ++ 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. . Respect other contributors. -+ ++ You were not always a committer. At one time you were a contributor. Remember that at all times. @@ -3196,40 +3196,40 @@ 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. -+ ++ Consider the points raised under <> and apply them also to contributors. . Discuss any significant change _before_ committing. -+ ++ The repository is not where changes are initially submitted for correctness or argued over, that happens first in the mailing lists or by use of the Phabricator service. The commit will only happen once something resembling consensus has been reached. This does not mean that permission is required before correcting every obvious syntax error or manual page misspelling, just that it is good 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 _surprised_ by those changes. The very best way of making sure that things are on the right track is to have code reviewed by one or more other committers. -+ ++ When in doubt, ask for review! . Respect existing maintainers if listed. -+ ++ Many parts of FreeBSD are not "owned" in the sense that any specific individual will jump up and yell if you commit a change to "their" area, but it still pays to check first. One convention we use is to put a maintainer line in the [.filename]#Makefile# for any package or subtree which is being actively maintained by one or more people; see link:{developers-handbook}#policies[Source Tree Guidelines and Policies] 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 "maintainer-ship" of something is not clear, look at the repository logs for the files in question and see if someone has been working recently or predominantly in that area. . 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. -+ ++ 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 _very_ 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. . Changes go to FreeBSD-CURRENT before FreeBSD-STABLE unless specifically permitted by the release engineer or unless they are not applicable to FreeBSD-CURRENT. Any non-trivial or non-urgent change which is applicable should also be allowed to sit in FreeBSD-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 FreeBSD-STABLE branch as outlined in rule #5. -+ ++ This is another "do not argue about it" 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 FreeBSD-STABLE branch. The management of FreeBSD-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 FreeBSD-STABLE and different rules apply there than in FreeBSD-CURRENT. There is also really no point in having FreeBSD-CURRENT be a testing ground if changes are merged over to FreeBSD-STABLE immediately. Changes need a chance to be tested by the FreeBSD-CURRENT developers, so allow some time to elapse before merging unless the FreeBSD-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. -+ ++ Changes to the security branches (for example, `releng/9.3`) must be approved by a member of the `{security-officer}`, or in some cases, by a member of the `{re}`. . Do not fight in public with other committers; it looks bad. -+ ++ 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. @@ -3240,16 +3240,16 @@ 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 third party to resolve the dispute. All parties involved must then agree to be bound by the decision reached by this third party. . Respect all code freezes and read the `committers` and `developers` mailing list on a timely basis so you know when a code freeze is in effect. -+ ++ 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. . When in doubt on any procedure, ask first! -+ ++ 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 "how in the heck do I do this?" We already know you are an intelligent person; otherwise, you would not be a committer. . Test your changes before committing them. -+ ++ 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. @@ -3258,18 +3258,18 @@ Please refer to the https://www.FreeBSD.org/internal/[FreeBSD Internal Page] 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. . Do not commit to contributed software without _explicit_ approval from the respective maintainers. -+ ++ Contributed software is anything under the [.filename]#src/contrib#, [.filename]#src/crypto#, or [.filename]#src/sys/contrib# trees. -+ ++ The trees mentioned above are for contributed software usually imported onto a vendor branch. Committing something there may cause unnecessary headaches when importing newer versions of the software. As a general consider sending patches upstream to the vendor. Patches may be committed to FreeBSD first with permission of the maintainer. -+ ++ Reasons for modifying upstream software range from wanting strict control over a tightly coupled dependency to lack of portability in the canonical repository's distribution of their code. Regardless of the reason, effort to minimize the maintenance burden of fork is helpful to fellow maintainers. Avoid committing trivial or cosmetic changes to files since it makes every merge thereafter more difficult: such patches need to be manually re-verified every import. -+ ++ If a particular piece of software lacks a maintainer, you are encouraged to take up ownership. If you are unsure of the current maintainership email {freebsd-arch} and ask. @@ -3315,42 +3315,42 @@ === Privacy and Confidentiality . Most FreeBSD business is done in public. -+ ++ FreeBSD is an _open_ project. Which means that not only can anyone use the source code, but that most of the development process is open to public scrutiny. . Certain sensitive matters must remain private or held under embargo. -+ ++ There unfortunately cannot be complete transparency. As a FreeBSD developer you will have a certain degree of privileged access to information. Consequently you are expected to respect certain requirements for confidentiality. Sometimes the need for confidentiality comes from external collaborators or has a specific time limit. Mostly though, it is a matter of not releasing private communications. . The Security Officer has sole control over the release of security advisories. -+ ++ Where there are security problems that affect many different operating systems, FreeBSD frequently depends on early access to be able to prepare advisories for coordinated release. Unless FreeBSD developers can be trusted to maintain security, such early access will not be made available. The Security Officer is responsible for controlling pre-release access to information about vulnerabilities, and for timing the release of all advisories. He may request help under condition of confidentiality from any developer with relevant knowledge to prepare security fixes. . Communications with Core are kept confidential for as long as necessary. -+ ++ Communications to core will initially be treated as confidential. Eventually however, most of Core's business will be summarized into the monthly or quarterly core reports. Care will be taken to avoid publicising any sensitive details. Records of some particularly sensitive subjects may not be reported on at all and will be retained only in Core's private archives. . Non-disclosure Agreements may be required for access to certain commercially sensitive data. -+ ++ Access to certain commercially sensitive data may only be available under a Non-Disclosure Agreement. The FreeBSD Foundation legal staff must be consulted before any binding agreements are entered into. . Private communications must not be made public without permission. -+ ++ Beyond the specific requirements above there is a general expectation not to publish private communications between developers without the consent of all parties involved. Ask permission before forwarding a message onto a public mailing list, or posting it to a forum or website that can be accessed by other than the original correspondents. . Communications on project-only or restricted access channels must be kept private. -+ ++ Similarly to personal communications, certain internal communications channels, including FreeBSD Committer only mailing lists and restricted access IRC channels are considered private communications. Permission is required to publish material from these sources. . Core may approve publication. -+ ++ Where it is impractical to obtain permission due to the number of correspondents or where permission to publish is unreasonably withheld, Core may approve release of such private matters that merit more general publication. [[archs]] diff --git a/documentation/content/en/articles/contributing/_index.adoc b/documentation/content/en/articles/contributing/_index.adoc --- a/documentation/content/en/articles/contributing/_index.adoc +++ b/documentation/content/en/articles/contributing/_index.adoc @@ -336,20 +336,20 @@ [.procedure] ==== . Watch for updates -+ ++ Monitor the upstream vendor for new versions, updates and security fixes for the software. Announcement mailing lists or news web pages are useful for doing this. Sometimes users will contact you and ask when your port will be updated. If you are busy with other things or for any reason just cannot update it at the moment, ask if they will help you by submitting an update. -+ ++ You may also receive automated email from the `FreeBSD Ports Version Check` informing you that a newer version of your port's distfile is available. More information about that system (including how to stop future emails) will be provided in the message. . Incorporate changes -+ ++ When they become available, incorporate the changes into the port. You need to be able to generate a patch between the original port and your updated port. . Review and test -+ ++ Thoroughly review and test your changes: ** Build, install and test your port on as many platforms and architectures as you can. It is common for a port to work on one branch or platform and fail on another. @@ -359,7 +359,7 @@ ** Consider whether changes to your port might cause any other ports to break. If this is the case, coordinate the changes with the maintainers of those ports. This is especially important if your update changes the shared library version; in this case, at the very least, the dependent ports will need to get a `PORTREVISION` bump so that they will automatically be upgraded by automated tools such as portmaster or man:portupgrade[1]. . Submit changes -+ ++ Send your update by submitting a PR with an explanation of the changes and a patch containing the differences between the original port and the updated one. Please refer to link:{problem-reports}[Writing FreeBSD Problem Reports] for information on how to write a really good PR. + @@ -370,15 +370,15 @@ The Porter's Handbook section on link:{porters-handbook}#port-upgrading[Upgrading] has more information. ====== . Wait -+ ++ At some stage a committer will deal with your PR. It may take minutes, or it may take weeks - so please be patient. . Give feedback -+ ++ If a committer finds a problem with your changes, they will most likely refer it back to you. A prompt response will help get your PR committed faster, and is better for maintaining a thread of conversation when trying to resolve any problems. . And Finally -+ ++ Your changes will be committed and your port will have been updated. The PR will then be closed by the committer. That's it! ==== @@ -405,10 +405,10 @@ [.procedure] ==== . Watch for build failures -+ ++ Check your mail for mail from `pkg-fallout@FreeBSD.org` and the http://portscout.FreeBSD.org[distfiles scanner] to see if any of the port which are failing to build are out of date. . Collect information -+ ++ Once you are aware of a problem, collect information to help you fix it. Build errors reported by `pkg-fallout` are accompanied by logs which will show you where the build failed. If the failure was reported to you by a user, ask them to send you information which may help in diagnosing the problem, such as: @@ -421,14 +421,14 @@ ** When their ports tree and [.filename]#INDEX# was last updated . Investigate and find a solution -+ ++ Unfortunately there is no straightforward process to follow to do this. Remember, though: if you are stuck, ask for help! The {freebsd-ports} is a good place to start, and the upstream developers are often very helpful. . Submit changes -+ ++ Just as with updating a port, you should now incorporate changes, review and test, submit your changes in a PR, and provide feedback if required. . Send patches to upstream authors -+ ++ In some cases, you will have to make patches to the port to make it run on FreeBSD. Some (but not all) upstream authors will accept such patches back into their code for the next release. If so, this may even help their users on other BSD-based systems as well and perhaps save duplicated effort. @@ -447,18 +447,18 @@ [.procedure] ==== . Respond to bug reports -+ ++ Bugs may be reported to you through email via the https://bugs.FreeBSD.org/search/[Problem Report database]. Bugs may also be reported directly to you by users. -+ ++ You should respond to PRs and other reports within 14 days, but please try not to take that long. Try to respond as soon as possible, even if it is just to say you need some more time before you can work on the PR. -+ ++ If you have not responded after 14 days, any committer may commit from a PR that you have not responded to via a `maintainer-timeout`. . Collect information -+ ++ If the person reporting the bug has not also provided a fix, you need to collect the information that will allow you to generate one. -+ ++ If the bug is reproducible, you can collect most of the required information yourself. If not, ask the person who reported the bug to collect the information for you, such as: @@ -469,18 +469,18 @@ ** Stack traces . Eliminate incorrect reports -+ ++ Some bug reports may be incorrect. For example, the user may have simply misused the program; or their installed packages may be out of date and require updating. Sometimes a reported bug is not specific to FreeBSD. In this case report the bug to the upstream developers. If the bug is within your capabilities to fix, you can also patch the port so that the fix is applied before the next upstream release. . Find a solution -+ ++ As with build errors, you will need to sort out a fix to the problem. Again, remember to ask if you are stuck! . Submit or approve changes -+ ++ Just as with updating a port, you should now incorporate changes, review and test, and submit your changes in a PR (or send a follow-up if a PR already exists for the problem). If another user has submitted changes in the PR, you can also send a follow-up saying whether or not you approve the changes. ==== diff --git a/documentation/content/en/articles/contributors/_index.adoc b/documentation/content/en/articles/contributors/_index.adoc --- a/documentation/content/en/articles/contributors/_index.adoc +++ b/documentation/content/en/articles/contributors/_index.adoc @@ -62,7 +62,7 @@ ** Ulf Zimmermann mailto:ulf@Alameda.net[ulf@Alameda.net] of http://www.Alameda.net/[Alameda Networks] donated _128MB of memory_, a _4 Gb disk drive and the case._ * _Direct funding:_ -+ ++ The following individuals and businesses have generously contributed direct funding to the project: ** Annelise Anderson mailto:ANDRSN@HOOVER.STANFORD.EDU[ANDRSN@HOOVER.STANFORD.EDU] @@ -88,7 +88,7 @@ ** Chris Silva mailto:ras@interaccess.com[ras@interaccess.com] * _Hardware contributors:_ -+ ++ The following individuals and businesses have generously contributed hardware for testing and device driver development/support: ** 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. diff --git a/documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc b/documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc --- a/documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc +++ b/documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc @@ -1,60 +1,60 @@ * Bruce D. Evans (1991 - 2019; RIP 2019) -+ ++ Bruce was a programming giant who made FreeBSD his home. -+ ++ Back before FreeBSD and Linux there was Minix, a toy "unix" written by Andy Tannenbaum, released in 1987, sold with complete sources on three floppy disks, for $99. -+ ++ Bruce ported Minix to the i386 around 1989. -+ ++ Linus Torvalds used Minix/386 to develop his own kernel, and Bruce was the first person he thanked in the release-announcement. -+ ++ When Bill Jolitz released 386BSD 0.1 in 1992, Bruce was listed as a contributor. -+ ++ Bruce co-founded the FreeBSD project, and served on core.0, but he was never partisan, and over the years many other projects have benefitted from his patches, advice and wisdom. -+ ++ Code reviews from Bruce came in three flavours, "mild", "brucified" and "brucifiction", but they were never personal: It was always only about the code, the mistakes, the sloppy thinking, the missing historical context, the ambiguous standards - and the style(9) transgressions. -+ ++ As Bruce gave more code reviews than anybody else in the history of the FreeBSD project, the commit logs hide the true scale of his impact until you pay attention to "Submitted by", "Reviewed by" and "Pointed out by". -+ ++ Being hard of hearing, Bruce did not attend conferences. -+ ++ The notable exception was the 1999 BSDcon in California, where his core team colleagues greeted him with "We're not worthy!" in Wayne's World fashion. -+ ++ Twenty years later we're still not. * Kurt Lidl (2015 - 2019; RIP 2019) -+ ++ Kurt first got involved with BSD while it was still a project at the University of California at Berkeley. Shortly after personalized license plates became available in Maryland, he got "BSDWZRD". -+ ++ He began contributing to FreeBSD shortly after the conception of the project. He became a FreeBSD source committer in October 2015. -+ ++ Kurt's most well known FreeBSD project was man:blacklistd[8] which blocks and releases ports on demand to avoid DoS abuse. He has also made many other bug fixes and enhancements to DTrace, boot loaders, and other bits and pieces of the FreeBSD infrastructure. -+ ++ Earlier work included the game XTank, an author on RFC 2516 https://tools.ietf.org/html/rfc2516["A Method for Transmitting PPP Over Ethernet (PPPoE)"], and the USENIX paper https://www.usenix.org/conference/usenix-winter-1994-technical-conference/drinking-firehose-multicast-usenet-news["Drinking from the Firehose: Multicast USENET News"]. * Frank Durda IV (1995 - 2003; RIP 2018) -+ ++ Frank had been around the project since the very early days, contributing code to the 1.x line before becoming a committer. * Andrey A. Chernov (1993 - 2017; RIP 2017) -+ ++ Andrey contributions to FreeBSD can not be overstated. Having been involved for a long there is hardly an area which he did not touch. * Jürgen Lock (2006 - 2015; RIP 2015) -+ ++ Jürgen made a number of contributions to FreeBSD, including work on libvirt, the graphics stack, and QEMU. Jürgen's contributions and helpfulness were appreciated by people around the world. That work continues to improve the lives of thousands every day. * {alexbl} (2006 - 2011; RIP 2012) -+ ++ http://www.legacy.com/obituaries/sfgate/obituary.aspx?pid=159801494[Alexander] was best known as a major contributor to FreeBSD's Python ports and a founding member of {python} as well as his work on XMMS2. * {jb} (1997 - 2009; RIP 2009) -+ ++ http://hub.opensolaris.org/bin/view/Community+Group+ogb/In+Memoriam[John] made major contributions to FreeBSD, the best known of which is the import of the man:dtrace[1] code. John's unique sense of humor and plain-spokenness either ruffled feathers or made him quick friends. At the end of his life, he had moved to a rural area and was attempting to live with as minimal impact to the planet as possible, while at the same time still working in the high-tech area. * {jmz} (1994 - 2009; RIP 2009) -+ ++ http://www.obs-besancon.fr/article.php3?id_article=323[Jean-Marc] was an astrophysicist who made important contributions to the modeling of the atmospheres of both planets and comets at http://www.obs-besancon.fr/[l'Observatoire de Besançon] in Besançon, France. While there, he participated in the conception and construction of the Vega tricanal spectrometer that studied Halley's Comet. He had also been a long-time contributor to FreeBSD. * {itojun} (1997 - 2001; RIP 2008) -+ ++ Known to everyone as http://astralblue.livejournal.com/350702.html[itojun], Jun-ichiro Hagino was a core researcher at the http://www.kame.net/[KAME Project], which aimed to provide IPv6 and IPsec technology in freely redistributable form. Much of this code was incorporated into FreeBSD. Without his efforts, the state of IPv6 on the Internet would be much different. * {cg} (1999 - 2005; RIP 2005) -+ ++ http://www.dbsi.org/cam/[Cameron] was a unique individual who contributed to the project despite serious physical disabilities. He was responsible for a complete rewrite of our sound system during the late 1990s. Many of those who corresponded with him had no idea of his limited mobility, due to his cheerful spirit and willingness to help others. * {alane} (2002 - 2003; RIP 2003) -+ ++ http://freebsd.kde.org/memoriam/alane.php[Alan] was a major contributor to the KDE on FreeBSD group. In addition, he maintained many other difficult and time-consuming ports such as autoconf, CUPS, and python. Alan's path was not an easy one but his passion for FreeBSD, and dedication to programming excellence, won him many friends. diff --git a/documentation/content/en/articles/explaining-bsd/_index.adoc b/documentation/content/en/articles/explaining-bsd/_index.adoc --- a/documentation/content/en/articles/explaining-bsd/_index.adoc +++ b/documentation/content/en/articles/explaining-bsd/_index.adoc @@ -42,13 +42,13 @@ * The BSD kernel, which handles process scheduling, memory management, symmetric multi-processing (SMP), device drivers, etc. * The C library, the base API for the system. -+ ++ __The BSD C library is based on code from Berkeley, not the GNU project.__ * Utilities such as shells, file utilities, compilers and linkers. -+ ++ __Some of the utilities are derived from the GNU project, others are not.__ * The X Window system, which handles graphical display. -+ ++ The X Window system used in most versions of BSD is maintained by the http://www.X.org/[X.Org project]. FreeBSD allows the user to choose from a variety of desktop environments, such as Gnome, KDE, or Xfce; and lightweight window managers like Openbox, Fluxbox, or Awesome. * Many other programs and utilities. @@ -96,7 +96,7 @@ . The BSD developers are often more interested in polishing their code than marketing it. . Much of Linux's popularity is due to factors external to the Linux projects, such as the press, and to companies formed to provide Linux services. Until recently, the open source BSDs had no such proponents. . In 1992, AT&T sued http://www.bsdi.com/[BSDI], the vendor of BSD/386, alleging that the product contained AT&T-copyrighted code. The case was settled out of court in 1994, but the spectre of the litigation continues to haunt people. In March 2000 an article published on the web claimed that the court case had been "recently settled". -+ ++ One detail that the lawsuit did clarify is the naming: in the 1980s, BSD was known as "BSD UNIX(R)". With the elimination of the last vestige of AT&T code from BSD, it also lost the right to the name UNIX(R). Thus you will see references in book titles to "the 4.3BSD UNIX(R) operating system" and "the 4.4BSD operating system". @@ -126,7 +126,7 @@ * _Contributors_ write code or documentation. They are not permitted to commit (add code) directly to the source tree. In order for their code to be included in the system, it must be reviewed and checked in by a registered developer, known as a __committer__. * _Committers_ are developers with write access to the source tree. In order to become a committer, an individual must show ability in the area in which they are active. -+ ++ It is at the individual committer's discretion whether they should obtain authority before committing changes to the source tree. In general, an experienced committer may make changes which are obviously correct without obtaining consensus. For example, a documentation project committer may correct typographical or grammatical errors without review. diff --git a/documentation/content/en/articles/fonts/_index.adoc b/documentation/content/en/articles/fonts/_index.adoc --- a/documentation/content/en/articles/fonts/_index.adoc +++ b/documentation/content/en/articles/fonts/_index.adoc @@ -495,12 +495,12 @@ .... % gs -dNODISPLAY -q -- ttf2pf.ps TTF_name PS_font_name AFM_name .... -+ ++ Where, _TTF_name_ is your TrueType font file, _PS_font_name_ is the file name for [.filename]#.pfa#, _AFM_name_ is the name you wish for [.filename]#.afm#. If you do not specify output file names for the [.filename]#.pfa# or [.filename]#.afm# files, then default names will be generated from the TrueType font file name. -+ ++ This also produces a [.filename]#.pfa#, the ascii PostScript font metrics file ([.filename]#.pfb# is for the binary form). This will not be needed, but could (I think) be useful for a fontserver. -+ ++ For example, to convert the 30f9 Barcode font using the default file names, use the following command: + [source,shell] @@ -511,7 +511,7 @@ This software comes with NO WARRANTY: see the file PUBLIC for details. Converting 3of9.ttf to 3of9.pfa and 3of9.afm. .... -+ ++ If you want the converted fonts to be stored in [.filename]#A.pfa# and [.filename]#B.afm#, then use this command: + [source,shell] @@ -524,7 +524,7 @@ .... . Create the groff PostScript file: -+ ++ Change directories to [.filename]#/usr/share/groff_font/devps# so as to make the following command easier to execute. You will probably need root privileges for this. (Or, if you are paranoid about working there, make sure you reference the files [.filename]#DESC#, [.filename]#text.enc# and [.filename]#generate/textmap# as being in this directory.) @@ -533,7 +533,7 @@ .... % afmtodit -d DESC -e text.enc file.afm generate/textmap PS_font_name .... -+ ++ Where, [.filename]#file.afm# is the _AFM_name_ created by `ttf2pf.ps` above, and _PS_font_name_ is the font name used from that command, as well as the name that man:groff[1] will use for references to this font. For example, assuming you used the first `tiff2pf.ps` above, then the 3of9 Barcode font can be created using the command: + @@ -541,9 +541,9 @@ .... % afmtodit -d DESC -e text.enc 3of9.afm generate/textmap 3of9 .... -+ ++ Ensure that the resulting _PS_font_name_ file (e.g., [.filename]#3of9# in the example above) is located in the directory [.filename]#/usr/share/groff_font/devps# by copying or moving it there. -+ ++ Note that if [.filename]#ttf2pf.ps# assigns a font name using the one it finds in the TrueType font file and you want to use a different name, you must edit the [.filename]#.afm# prior to running `afmtodit`. This name must also match the one used in the Fontmap file if you wish to pipe man:groff[1] into man:gs[1]. diff --git a/documentation/content/en/articles/freebsd-questions/_index.adoc b/documentation/content/en/articles/freebsd-questions/_index.adoc --- a/documentation/content/en/articles/freebsd-questions/_index.adoc +++ b/documentation/content/en/articles/freebsd-questions/_index.adoc @@ -165,10 +165,10 @@ * 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. * 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. "FreeBSD problem" or "Help" 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. * 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. -+ ++ 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. -+ ++ A lot of badly formatted messages come from http://www.lemis.com/email.html[bad mailers or badly configured mailers]. The following mailers are known to send out badly formatted messages without you finding out about them: @@ -176,7 +176,7 @@ ** exmh ** Microsoft(R) Exchange ** Microsoft(R) Outlook(R) -+ ++ Try not to use MIME: a lot of people use mailers which do not get on very well with MIME. * 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. * 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. @@ -184,7 +184,7 @@ ** 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. ** With any problem which _could_ 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? -+ ++ 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. ** If you get error messages, do not say "I get error messages", say (for example) "I get the error message 'No route to host'". ** If your system panics, do not say "My system panicked", say (for example) "my system panicked with the message 'free vnode isn't'". @@ -197,7 +197,7 @@ .... % dmesg > /tmp/dmesg.out .... -+ ++ This redirects the information to the file [.filename]#/tmp/dmesg.out#. * 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. @@ -249,7 +249,7 @@ . A lot of the points on submitting questions also apply to answering questions. Read them. . 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. -+ ++ 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. . Do you have something to contribute beyond what has already been said? In general, "Yeah, me too" answers do not help much, although there are exceptions, like when somebody is describing a problem they are having, and they do not know whether it is their fault or whether there is something wrong with the hardware or software. If you do send a "me too" answer, you should also include any further relevant information. @@ -261,9 +261,9 @@ . 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. . Most mailers change the subject line on a reply by prepending a text such as "Re: ". If your mailer does not do it automatically, you should do it manually. . If the submitter did not abide by format conventions (lines too long, inappropriate subject line) _please_ fix it. In the case of an incorrect subject line (such as "HELP!!??"), change the subject line to (say) "Re: Difficulties with sync PPP (was: HELP!!??)". That way other people trying to follow the thread will have less difficulty following it. -+ ++ 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. -+ ++ 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. diff --git a/documentation/content/en/articles/freebsd-releng/_index.adoc b/documentation/content/en/articles/freebsd-releng/_index.adoc --- a/documentation/content/en/articles/freebsd-releng/_index.adoc +++ b/documentation/content/en/articles/freebsd-releng/_index.adoc @@ -631,10 +631,10 @@ There are two paths of file sourcing: * [.filename]#builds-12.conf# - [.filename]#main.conf# -+ ++ This controls [.filename]#thermite.sh# behavior * [.filename]#12-amd64-GENERIC-snap.conf# - [.filename]#defaults-12.conf# - [.filename]#main.conf# -+ ++ This controls [.filename]#release/release.sh# behavior within the build [NOTE] @@ -745,7 +745,7 @@ Staging FreeBSD snapshots and releases is a two part process: * Creating the directory structure to match the hierarchy on `ftp-master` -+ ++ If `EVERYTHINGISFINE` is defined in the build configuration files, [.filename]#main.conf# in the case of the build scripts referenced above, this happens automatically in the after the build is complete, creating the directory structure in [.filename]#${DESTDIR}/R/ftp-stage# with a path structure matching what is expected on `ftp-master`. This is equivalent to running the following in the directly: + @@ -753,10 +753,10 @@ .... # make -C /usr/src/release -f Makefile.mirrors EVERYTHINGISFINE=1 ftp-stage .... -+ ++ After each architecture is built, [.filename]#thermite.sh# will rsync the [.filename]#${DESTDIR}/R/ftp-stage# from the build to [.filename]#/snap/ftp/snapshots# or [.filename]#/snap/ftp/releases# on the build host, respectively. * Copying the files to a staging directory on `ftp-master` before moving the files into [.filename]#pub/# to begin propagation to the Project mirrors -+ ++ Once all builds have finished, [.filename]#/snap/ftp/snapshots#, or [.filename]#/snap/ftp/releases# for a release, is polled by `ftp-master` using rsync to [.filename]#/archive/tmp/snapshots# or [.filename]#/archive/tmp/releases#, respectively. + [NOTE] diff --git a/documentation/content/en/articles/mailing-list-faq/_index.adoc b/documentation/content/en/articles/mailing-list-faq/_index.adoc --- a/documentation/content/en/articles/mailing-list-faq/_index.adoc +++ b/documentation/content/en/articles/mailing-list-faq/_index.adoc @@ -129,7 +129,7 @@ * Please respect the fact that bandwidth is not infinite. Not everyone reads email through high-speed connections, so if your posting involves something like the content of [.filename]#config.log# or an extensive stack trace, please consider putting that information up on a website somewhere and just provide a URL to it. Remember, too, that these postings will be archived indefinitely, so huge postings will simply inflate the size of the archives long after their purpose has expired. * Format your message so that it is legible, and PLEASE DO NOT SHOUT!!!!!. Do not underestimate the effect that a poorly formatted mail message has, and not just on the FreeBSD mailing lists. Your mail message is all that people see of you, and if it is poorly formatted, badly spelled, full of errors, and/or has lots of exclamation points, it will give people a poor impression of you. * Please use an appropriate human language for a particular mailing list. Many non-English mailing lists are link:https://www.FreeBSD.org/community/mailinglists/[available]. -+ ++ For the ones that are not, we do appreciate that many people do not speak English as their first language, and we try to make allowances for that. It is considered particularly poor form to criticize non-native speakers for spelling or grammatical errors. FreeBSD has an excellent track record in this regard; please, help us to uphold that tradition. @@ -138,7 +138,7 @@ ** exmh ** Microsoft(R) Exchange ** Microsoft(R) Outlook(R) -+ ++ Try not to use MIME: a lot of people use mailers which do not get on very well with MIME. * 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 on these mailing lists 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 that they missed it and not bother to look. * 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#. Do not try to copy this information by typing it in again; not only it is a real pain, but 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 `dmesg`, redirect the output to a file and include that. For example, @@ -147,14 +147,14 @@ .... % dmesg > /tmp/dmesg.out .... -+ ++ This redirects the information to the file [.filename]#/tmp/dmesg.out#. * When using cut-and-paste, please be aware that some such operations badly mangle their messages. This is of particular concern when posting contents of [.filename]#Makefiles#, where `tab` is a significant character. This is a very common, and very annoying, problem with submissions to the link:https://www.FreeBSD.org/support/[Problem Reports database]. [.filename]#Makefiles# with tabs changed to either spaces, or the annoying `=3B` escape sequence, create a great deal of aggravation for committers. === What are the special etiquette consideration when replying to an existing posting on the mailing lists? * Please 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. -+ ++ This is especially important for postings of the type "yes, I see this too", where the initial posting was dozens or hundreds of lines. * Use some technique to identify which text came from the original message, and which text you add. A common convention is to prepend "`>`" to the original message. Leaving white space after the "`>`" and leaving empty lines between your text and the original text both make the result more readable. * Please ensure that the attributions of the text you are quoting is correct. People can become offended if you attribute words to them that they themselves did not write. @@ -162,7 +162,7 @@ + ** A: Because it reverses the logical flow of conversation. ** Q: Why is top posting frowned upon? -+ ++ (Thanks to Randy Bush for the joke.) [[recurring]] diff --git a/documentation/content/en/articles/nanobsd/_index.adoc b/documentation/content/en/articles/nanobsd/_index.adoc --- a/documentation/content/en/articles/nanobsd/_index.adoc +++ b/documentation/content/en/articles/nanobsd/_index.adoc @@ -390,7 +390,7 @@ ==== . Build a new NanoBSD image, as usual. . Upload the new image into an unused partition of a running NanoBSD appliance. -+ ++ The most important difference of this step from the initial NanoBSD installation is that now instead of using [.filename]#\_.disk.full# (which contains an image of the entire disk), the [.filename]#_.disk.image# image is installed (which contains an image of a single system partition). . Reboot, and start the system from the newly installed partition. . If all goes well, the upgrade is finished. diff --git a/documentation/content/en/articles/problem-reports/_index.adoc b/documentation/content/en/articles/problem-reports/_index.adoc --- a/documentation/content/en/articles/problem-reports/_index.adoc +++ b/documentation/content/en/articles/problem-reports/_index.adoc @@ -108,10 +108,10 @@ * Optionally, the entire web-use your favorite search engine to locate any references to the problem. You may even get hits from archived mailing lists or newsgroups you did not know of or had not thought to search through. * Next, the searchable https://bugs.freebsd.org/bugzilla/query.cgi[FreeBSD PR database] (Bugzilla). Unless the problem is recent or obscure, there is a fair chance it has already been reported. * Most importantly, attempt to see if existing documentation in the source base addresses your problem. -+ ++ For the base FreeBSD code, you should carefully study the contents of [.filename]#/usr/src/UPDATING# on your system or the latest version at https://cgit.freebsd.org/src/tree/UPDATING[https://cgit.freebsd.org/src/tree/UPDATING]. (This is vital information if you are upgrading from one version to another-especially if you are upgrading to the FreeBSD-CURRENT branch). -+ ++ However, if the problem is in something that was installed as a part of the FreeBSD Ports Collection, you should refer to [.filename]#/usr/ports/UPDATING# (for individual ports) or [.filename]#/usr/ports/CHANGES# (for changes that affect the entire Ports Collection). https://cgit.freebsd.org/ports/tree/UPDATING[https://cgit.freebsd.org/ports/tree/UPDATING] and https://cgit.freebsd.org/ports/tree/CHANGES[https://cgit.freebsd.org/ports/tree/CHANGES] are also available via cgit. @@ -196,12 +196,12 @@ * _Summary:_ Fill this out with a short and accurate description of the problem. The synopsis is used as the subject of the problem report email, and is used in problem report listings and summaries; problem reports with obscure synopses tend to get ignored. * _Severity:_ One of `Affects only me`, `Affects some people` or `Affects many people`. Do not overreact; refrain from labeling your problem `Affects many people` unless it really does. FreeBSD developers will not necessarily work on your problem faster if you inflate its importance since there are so many other people who have done exactly that. * _Category:_ Choose an appropriate category. -+ ++ The first thing you need to do is to decide what part of the system your problem lies in. Remember, FreeBSD is a complete operating system, which installs both a kernel, the standard libraries, many peripheral drivers, and a large number of utilities (the "base system"). However, there are thousands of additional applications in the Ports Collection. You'll first need to decide if the problem is in the base system or something installed via the Ports Collection. -+ ++ Here is a description of the major categories: ** If a problem is with the kernel, the libraries (such as standard C library `libc`), or a peripheral driver in the base system, in general you will use the `kern` category. (There are a few exceptions; see below). In general these are things that are described in section 2, 3, or 4 of the manual pages. @@ -213,7 +213,7 @@ ==== if you are having a problem with something from a port named `www/_someportname_`, this nevertheless goes in the `ports` category. ==== -+ ++ There are a few more specialized categories. ** If the problem would otherwise be filed in `kern` but has to do with the USB subsystem, the correct choice is `usb`. diff --git a/documentation/content/en/articles/serial-uart/_index.adoc b/documentation/content/en/articles/serial-uart/_index.adoc --- a/documentation/content/en/articles/serial-uart/_index.adoc +++ b/documentation/content/en/articles/serial-uart/_index.adoc @@ -897,7 +897,7 @@ device sio15 at isa? port 0x170 flags 0x1005 device sio16 at isa? port 0x178 flags 0x1005 irq 3 .... -+ ++ The flags entry _must_ be changed from this example unless you are using the exact same sio assignments. Flags are set according to 0x``__MYY__`` where _M_ indicates the minor number of the master port (the last port on a Boca 16) and _YY_ indicates if FIFO is enabled or disabled(enabled), IRQ sharing is used(yes) and if there is an AST/4 compatible IRQ control register(no). In this example, @@ -947,7 +947,7 @@ sio16 at 0x178-0x17f irq 3 flags 0x1005 on isa sio16: type 16550A (multiport master) .... -+ ++ If the messages go by too fast to see, + [source,shell] @@ -956,7 +956,7 @@ .... will show you the boot messages. . Next, appropriate entries in [.filename]#/dev# for the devices must be made using the [.filename]#/dev/MAKEDEV# script. This step can be omitted if you are running FreeBSD 5.X with a kernel that has man:devfs[5] support compiled in. -+ ++ If you do need to create the [.filename]#/dev# entries, run the following as `root`: + [source,shell] @@ -969,7 +969,7 @@ # ./MAKEDEV ttyg # ./MAKEDEV cuag .... -+ ++ If you do not want or need call-out devices for some reason, you can dispense with making the [.filename]#cua*# devices. . If you want a quick and sloppy way to make sure the devices are working, you can simply plug a modem into each port and (as root) + diff --git a/documentation/content/en/articles/solid-state/_index.adoc b/documentation/content/en/articles/solid-state/_index.adoc --- a/documentation/content/en/articles/solid-state/_index.adoc +++ b/documentation/content/en/articles/solid-state/_index.adoc @@ -135,7 +135,7 @@ [.procedure] ==== . Partitioning Your Flash Media Device -+ ++ After booting with the kern and mfsroot floppies, choose `custom` from the installation menu. In the custom installation menu, choose `partition`. In the partition menu, you should delete all existing partitions using kbd:[d]. @@ -146,7 +146,7 @@ Now press kbd:[q] to quit the partition menu. You will be shown the boot manager menu once more - repeat the choice you made earlier. . Creating Filesystems on Your Flash Memory Device -+ ++ Exit the custom installation menu, and from the main installation menu choose the `fixit` option. After entering the fixit environment, enter the following command: + @@ -154,7 +154,7 @@ .... # disklabel -e /dev/ad0c .... -+ ++ At this point you will have entered the vi editor under the auspices of the disklabel command. Next, you need to add an `a:` line at the end of the file. This `a:` line should look like: + @@ -162,7 +162,7 @@ .... a: 123456 0 4.2BSD 0 0 .... -+ ++ Where _123456_ is a number that is exactly the same as the number in the existing `c:` entry for size. Basically you are duplicating the existing `c:` line as an `a:` line, making sure that fstype is `4.2BSD`. Save the file and exit. @@ -174,14 +174,14 @@ .... . Placing Your Filesystem on the Flash Media -+ ++ Mount the newly prepared flash media: + [source,shell] .... # mount /dev/ad0a /flash .... -+ ++ Bring this machine up on the network so we may transfer our tar file and explode it onto our flash media filesystem. One example of how to do this is: + @@ -190,7 +190,7 @@ # ifconfig xl0 192.168.0.10 netmask 255.255.255.0 # route add default 192.168.0.1 .... -+ ++ Now that the machine is on the network, transfer your tar file. You may be faced with a bit of a dilemma at this point - if your flash memory part is 128 megabytes, for instance, and your tar file is larger than 64 megabytes, you cannot have your tar file on the flash media at the same time as you explode it - you will run out of space. One solution to this problem, if you are using FTP, is to untar the file while it is transferred over FTP. @@ -200,14 +200,14 @@ .... ftp> get tarfile.tar "| tar xvf -" .... -+ ++ If your tarfile is gzipped, you can accomplish this as well: + [source,shell] .... ftp> get tarfile.tar "| zcat | tar xvf -" .... -+ ++ After the contents of your tarred filesystem are on your flash memory filesystem, you can unmount the flash memory and reboot: + [source,shell] @@ -216,7 +216,7 @@ # umount /flash # exit .... -+ ++ Assuming that you configured your filesystem correctly when it was built on the normal hard disk (with your filesystems mounted read-only, and with the necessary options compiled into the kernel) you should now be successfully booting your FreeBSD embedded system. ==== diff --git a/documentation/content/en/articles/vinum/_index.adoc b/documentation/content/en/articles/vinum/_index.adoc --- a/documentation/content/en/articles/vinum/_index.adoc +++ b/documentation/content/en/articles/vinum/_index.adoc @@ -576,7 +576,7 @@ .... # gvinum l -rv root .... -+ ++ [.filename]#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 by `bsdlabel`. . Run this command for each device that participates in the root volume: @@ -585,18 +585,18 @@ .... # bsdlabel -e devname .... -+ ++ _devname_ must be either the name of the disk, like [.filename]#da0# for disks without a slice table, or the name of the slice, like [.filename]#ad0s1#. -+ ++ If there is already an `a` partition on the device from a pre-[.filename]#vinum# 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 "Fixit" media, or in a two-step process where, in a mirror, the disk that is not been currently booted is manipulated first. -+ ++ The offset of the [.filename]#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 `offset` value for the new `a` partition. The `size` value for this partition can be taken verbatim from the calculation above. The `fstype` should be `4.2BSD`. The `fsize`, `bsize`, and `cpg` values should be chosen to match the actual file system, though they are fairly unimportant within this context. -+ ++ That way, a new `a` partition will be established that overlaps the [.filename]#vinum# partition on this device. `bsdlabel` will only allow for this overlap if the [.filename]#vinum# partition has properly been marked using the `vinum` fstype. . A faked `a` 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: diff --git a/documentation/content/en/books/arch-handbook/isa/_index.adoc b/documentation/content/en/books/arch-handbook/isa/_index.adoc --- a/documentation/content/en/books/arch-handbook/isa/_index.adoc +++ b/documentation/content/en/books/arch-handbook/isa/_index.adoc @@ -243,7 +243,7 @@ The functions to manipulate resources are: * `int bus_set_resource(device_t dev, int type, int rid, u_long start, u_long count)` -+ ++ Set a range for a resource. Returns 0 if successful, error code otherwise. Normally, this function will return an error only if one of `type`, `rid`, `start` or `count` has a value that falls out of the permitted range. ** dev - driver's device @@ -252,16 +252,16 @@ ** start, count - resource range * `int bus_get_resource(device_t dev, int type, int rid, u_long *startp, u_long *countp)` -+ ++ Get the range of resource. Returns 0 if successful, error code if the resource is not defined yet. * `u_long bus_get_resource_start(device_t dev, int type, int rid) u_long bus_get_resource_count (device_t dev, int type, int rid)` -+ ++ Convenience functions to get only the start or count. Return 0 in case of error, so if the resource start has 0 among the legitimate values it would be impossible to tell if the value is 0 or an error occurred. Luckily, no ISA resources for add-on drivers may have a start value equal to 0. * `void bus_delete_resource(device_t dev, int type, int rid)` -+ ++ Delete a resource, make it undefined. * `struct resource * bus_alloc_resource(device_t dev, int type, int *rid, u_long start, u_long end, u_long count, u_int flags)` -+ ++ Allocate a resource as a range of count values not allocated by anyone else, somewhere between start and end. Alas, alignment is not supported. If the resource was not set yet it is automatically created. The special values of start 0 and end ~0 (all ones) means that the fixed values previously set by `bus_set_resource()` must be used instead: start and count as themselves and end=(start+count), in this case if the resource was not defined before then an error is returned. Although rid is passed by reference it is not set anywhere by the resource allocation code of the ISA bus. (The other buses may use a different approach and modify it). Flags are a bitmap, the flags interesting for the caller are: @@ -277,7 +277,7 @@ * `int bus_setup_intr(device_t dev, struct resource *r, int flags, driver_intr_t *handler, void *arg, void **cookiep) int bus_teardown_intr(device_t dev, struct resource *r, void *cookie)` * Associate or de-associate the interrupt handler with a device. Return 0 on success, error code otherwise. * r - the activated resource handler describing the IRQ -+ ++ flags - the interrupt priority level, one of: ** `INTR_TYPE_TTY` - terminals and other likewise character-type devices. To mask them use `spltty()`. @@ -328,7 +328,7 @@ The functions working on the DMA memory are: * `int bus_dma_tag_create(bus_dma_tag_t parent, bus_size_t alignment, bus_size_t boundary, bus_addr_t lowaddr, bus_addr_t highaddr, bus_dma_filter_t *filter, void *filterarg, bus_size_t maxsize, int nsegments, bus_size_t maxsegsz, int flags, bus_dma_tag_t *dmat)` -+ ++ Create a new tag. Returns 0 on success, the error code otherwise. ** _parent_ - parent tag, or NULL to create a top-level tag. @@ -339,9 +339,9 @@ *** For `bus_dmamem_alloc()` all the addresses from 0 to lowaddr-1 are considered permitted, the higher ones are forbidden. *** For `bus_dmamap_create()` all the addresses outside the inclusive range [lowaddr; highaddr] are considered accessible. The addresses of pages inside the range are passed to the filter function which decides if they are accessible. If no filter function is supplied then all the range is considered unaccessible. *** For the ISA devices the normal values (with no filter function) are: -+ ++ lowaddr = BUS_SPACE_MAXADDR_24BIT -+ ++ highaddr = BUS_SPACE_MAXADDR ** _filter, filterarg_ - the filter function and its argument. If NULL is passed for filter then the whole range [lowaddr, highaddr] is considered unaccessible when doing `bus_dmamap_create()`. Otherwise the physical address of each attempted page in range [lowaddr; highaddr] is passed to the filter function which decides if it is accessible. The prototype of the filter function is: `int filterfunc(void *arg, bus_addr_t paddr)`. It must return 0 if the page is accessible, non-zero otherwise. @@ -356,12 +356,12 @@ ** _dmat_ - pointer to the storage for the new tag to be returned. * `int bus_dma_tag_destroy(bus_dma_tag_t dmat)` -+ ++ Destroy a tag. Returns 0 on success, the error code otherwise. -+ ++ dmat - the tag to be destroyed. * `int bus_dmamem_alloc(bus_dma_tag_t dmat, void** vaddr, int flags, bus_dmamap_t *mapp)` -+ ++ Allocate an area of contiguous memory described by the tag. The size of memory to be allocated is tag's maxsize. Returns 0 on success, the error code otherwise. The result still has to be loaded by `bus_dmamap_load()` before being used to get the physical address of the memory. ** _dmat_ - the tag @@ -373,7 +373,7 @@ ** _mapp_ - pointer to the storage for the new map to be returned. * `void bus_dmamem_free(bus_dma_tag_t dmat, void *vaddr, bus_dmamap_t map)` -+ ++ Free the memory allocated by `bus_dmamem_alloc()`. At present, freeing of the memory allocated with ISA restrictions is not implemented. Due to this the recommended model of use is to keep and re-use the allocated areas for as long as possible. Do not lightly free some area and then shortly allocate it again. That does not mean that `bus_dmamem_free()` should not be used at all: hopefully it will be properly implemented soon. ** _dmat_ - the tag @@ -381,7 +381,7 @@ ** _map_ - the map of the memory (as returned from `bus_dmamem_alloc()`) * `int bus_dmamap_create(bus_dma_tag_t dmat, int flags, bus_dmamap_t *mapp)` -+ ++ Create a map for the tag, to be used in `bus_dmamap_load()` later. Returns 0 on success, the error code otherwise. ** _dmat_ - the tag @@ -389,14 +389,14 @@ ** _mapp_ - pointer to the storage for the new map to be returned * `int bus_dmamap_destroy(bus_dma_tag_t dmat, bus_dmamap_t map)` -+ ++ Destroy a map. Returns 0 on success, the error code otherwise. ** dmat - the tag to which the map is associated ** map - the map to be destroyed * `int bus_dmamap_load(bus_dma_tag_t dmat, bus_dmamap_t map, void *buf, bus_size_t buflen, bus_dmamap_callback_t *callback, void *callback_arg, int flags)` -+ ++ Load a buffer into the map (the map must be previously created by `bus_dmamap_create()` or `bus_dmamem_alloc()`). All the pages of the buffer are checked for conformance to the tag requirements and for those not conformant the bounce pages are allocated. An array of physical segment descriptors is built and passed to the callback routine. This callback routine is then expected to handle it in some way. The number of bounce buffers in the system is limited, so if the bounce buffers are needed but not immediately available the request will be queued and the callback will be called when the bounce buffers will become available. Returns 0 if the callback was executed immediately or `EINPROGRESS` if the request was queued for future execution. In the latter case the synchronization with queued callback routine is the responsibility of the driver. + ** _dmat_ - the tag @@ -404,28 +404,28 @@ ** _buf_ - kernel virtual address of the buffer ** _buflen_ - length of the buffer ** _callback_, `callback_arg` - the callback function and its argument -+ ++ The prototype of callback function is: `void callback(void *arg, bus_dma_segment_t *seg, int nseg, int error)` + ** _arg_ - the same as callback_arg passed to `bus_dmamap_load()` ** _seg_ - array of the segment descriptors ** _nseg_ - number of descriptors in array ** _error_ - indication of the segment number overflow: if it is set to `EFBIG` then the buffer did not fit into the maximal number of segments permitted by the tag. In this case only the permitted number of descriptors will be in the array. Handling of this situation is up to the driver: depending on the desired semantics it can either consider this an error or split the buffer in two and handle the second part separately -+ ++ Each entry in the segments array contains the fields: + ** _ds_addr_ - physical bus address of the segment ** _ds_len_ - length of the segment + * `void bus_dmamap_unload(bus_dma_tag_t dmat, bus_dmamap_t map)` -+ ++ unload the map. + ** _dmat_ - tag ** _map_ - loaded map + * `void bus_dmamap_sync (bus_dma_tag_t dmat, bus_dmamap_t map, bus_dmasync_op_t op)` -+ ++ Synchronise a loaded buffer with its bounce pages before and after physical transfer to or from device. This is the function that does all the necessary copying of data between the original buffer and its mapped version. The buffers must be synchronized both before and after doing the transfer. + ** _dmat_ - tag @@ -554,20 +554,20 @@ For the simpler devices things get more complicated. The functions used are: * `int isa_dma_acquire(int chanel_number)` -+ ++ Reserve a DMA channel. Returns 0 on success or EBUSY if the channel was already reserved by this or a different driver. Most of the ISA devices are not able to share DMA channels anyway, so normally this function is called when attaching a device. This reservation was made redundant by the modern interface of bus resources but still must be used in addition to the latter. If not used then later, other DMA routines will panic. * `int isa_dma_release(int chanel_number)` -+ ++ Release a previously reserved DMA channel. No transfers must be in progress when the channel is released (in addition the device must not try to initiate transfer after the channel is released). * `void isa_dmainit(int chan, u_int bouncebufsize)` -+ ++ Allocate a bounce buffer for use with the specified channel. The requested size of the buffer can not exceed 64KB. This bounce buffer will be automatically used later if a transfer buffer happens to be not physically contiguous or outside of the memory accessible by the ISA bus or crossing the 64KB boundary. If the transfers will be always done from buffers which conform to these conditions (such as those allocated by `bus_dmamem_alloc()` with proper limitations) then `isa_dmainit()` does not have to be called. But it is quite convenient to transfer arbitrary data using the DMA controller. The bounce buffer will automatically care of the scatter-gather issues. + ** _chan_ - channel number ** _bouncebufsize_ - size of the bounce buffer in bytes + * `void isa_dmastart(int flags, caddr_t addr, u_int nbytes, int chan)` -+ ++ Prepare to start a DMA transfer. This function must be called to set up the DMA controller before actually starting transfer on the device. It checks that the buffer is contiguous and falls into the ISA memory range, if not then the bounce buffer is automatically used. If bounce buffer is required but not set up by `isa_dmainit()` or too small for the requested transfer size then the system will panic. In case of a write request with bounce buffer the data will be automatically copied to the bounce buffer. * flags - a bitmask determining the type of operation to be done. The direction bits B_READ and B_WRITE are mutually exclusive. + @@ -579,13 +579,13 @@ * nbytes - length of the buffer. Must be less or equal to 64KB. Length of 0 is not allowed: the DMA controller will understand it as 64KB while the kernel code will understand it as 0 and that would cause unpredictable effects. For channels number 4 and higher the length must be even because these channels transfer 2 bytes at a time. In case of an odd length the last byte will not be transferred. * chan - channel number * `void isa_dmadone(int flags, caddr_t addr, int nbytes, int chan)` -+ ++ Synchronize the memory after device reports that transfer is done. If that was a read operation with a bounce buffer then the data will be copied from the bounce buffer to the original buffer. Arguments are the same as for `isa_dmastart()`. Flag B_RAW is permitted but it does not affect `isa_dmadone()` in any way. * `int isa_dmastatus(int channel_number)` -+ ++ Returns the number of bytes left in the current transfer to be transferred. In case the flag B_READ was set in `isa_dmastart()` the number returned will never be equal to zero. At the end of transfer it will be automatically reset back to the length of buffer. The normal use is to check the number of bytes left after the device signals that the transfer is completed. If the number of bytes is not 0 then something probably went wrong with that transfer. * `int isa_dmastop(int channel_number)` -+ ++ Aborts the current transfer and returns the number of bytes left untransferred. [[isa-driver-probe]] diff --git a/documentation/content/en/books/arch-handbook/jail/_index.adoc b/documentation/content/en/books/arch-handbook/jail/_index.adoc --- a/documentation/content/en/books/arch-handbook/jail/_index.adoc +++ b/documentation/content/en/books/arch-handbook/jail/_index.adoc @@ -343,7 +343,7 @@ * `semctl(semid, semnum, cmd, ...)`: `semctl` does the specified `cmd` on the semaphore queue indicated by `semid`. * `semget(key, nsems, flag)`: `semget` creates an array of semaphores, corresponding to `key`. -+ ++ `key and flag take on the same meaning as they do in msgget.` * `semop(semid, array, nops)`: `semop` performs a group of operations indicated by `array`, to the set of semaphores identified by `semid`. diff --git a/documentation/content/en/books/arch-handbook/scsi/_index.adoc b/documentation/content/en/books/arch-handbook/scsi/_index.adoc --- a/documentation/content/en/books/arch-handbook/scsi/_index.adoc +++ b/documentation/content/en/books/arch-handbook/scsi/_index.adoc @@ -270,7 +270,7 @@ The most common initiator mode requests are: * _XPT_SCSI_IO_ - execute an I/O transaction -+ ++ The instance "struct ccb_scsiio csio" of the union ccb is used to transfer the arguments. They are: ** _cdb_io_ - pointer to the SCSI command buffer or the buffer itself @@ -285,9 +285,9 @@ *** CAM_TAG_ACTION_NONE - do not use tags for this transaction *** MSG_SIMPLE_Q_TAG, MSG_HEAD_OF_Q_TAG, MSG_ORDERED_Q_TAG - value equal to the appropriate tag message (see /sys/cam/scsi/scsi_message.h); this gives only the tag type, the SIM driver must assign the tag value itself -+ ++ The general logic of handling this request is the following: -+ ++ The first thing to do is to check for possible races, to make sure that the command did not get aborted when it was sitting in the queue: + [.programlisting] @@ -299,7 +299,7 @@ return; } .... -+ ++ Also we check that the device is supported at all by our controller: + [.programlisting] @@ -316,7 +316,7 @@ return; } .... -+ ++ Then allocate whatever data structures (such as card-dependent hardware control block) we need to process this request. If we can not then freeze the SIM queue and remember that we have a pending operation, return the CCB back and ask CAM to re-queue it. Later when the resources become available the SIM queue must be unfrozen by returning a ccb with the `CAM_SIMQ_RELEASE` bit set in its status. Otherwise, if all went well, link the CCB with the hardware control block (HCB) and mark it as queued. + [.programlisting] @@ -334,7 +334,7 @@ hcb->ccb = ccb; ccb_h->ccb_hcb = (void *)hcb; ccb_h->status |= CAM_SIM_QUEUED; .... -+ ++ Extract the target data from CCB into the hardware control block. Check if we are asked to assign a tag and if yes then generate an unique tag and build the SCSI tag messages. The SIM driver is also responsible for negotiations with the devices to set the maximal mutually supported bus width, synchronous rate and offset. + [.programlisting] @@ -346,9 +346,9 @@ if( !target_negotiated(hcb) ) generate_negotiation_messages(hcb); .... -+ ++ Then set up the SCSI command. The command storage may be specified in the CCB in many interesting ways, specified by the CCB flags. The command buffer can be contained in CCB or pointed to, in the latter case the pointer may be physical or virtual. Since the hardware commonly needs physical address we always convert the address to the physical one, typically using the busdma API. -+ ++ In case if a physical address is requested it is OK to return the CCB with the status `CAM_REQ_INVALID`, the current drivers do that. If necessary a physical address can be also converted or mapped back to a virtual address but with big pain, so we do not do that. + [.programlisting] @@ -368,7 +368,7 @@ } hcb->cmdlen = csio->cdb_len; .... -+ ++ Now it is time to set up the data. Again, the data storage may be specified in the CCB in many interesting ways, specified by the CCB flags. First we get the direction of the data transfer. The simplest case is if there is no data to transfer: + [.programlisting] @@ -378,7 +378,7 @@ if (dir == CAM_DIR_NONE) goto end_data; .... -+ ++ Then we check if the data is in one chunk or in a scatter-gather list, and the addresses are physical or virtual. The SCSI controller may be able to handle only a limited number of chunks of limited length. If the request hits this limitation we return an error. We use a special function to return the CCB to handle in one place the HCB resource shortages. The functions to add chunks are driver-dependent, and here we leave them without detailed implementation. See description of the SCSI command (CDB) handling for the details on the address-translation issues. If some variation is too difficult or impossible to implement with a particular card it is OK to return the status `CAM_REQ_INVALID`. Actually, it seems like the scatter-gather ability is not used anywhere in the CAM code now. But at least the case for a single non-scattered virtual buffer must be implemented, it is actively used by CAM. + [.programlisting] @@ -432,7 +432,7 @@ } end_data: .... -+ ++ If disconnection is disabled for this CCB we pass this information to the hcb: + [.programlisting] @@ -440,9 +440,9 @@ if(ccb_h->flags & CAM_DIS_DISCONNECT) hcb_disable_disconnect(hcb); .... -+ ++ If the controller is able to run REQUEST SENSE command all by itself then the value of the flag CAM_DIS_AUTOSENSE should also be passed to it, to prevent automatic REQUEST SENSE if the CAM subsystem does not want it. -+ ++ The only thing left is to set up the timeout, pass our hcb to the hardware and return, the rest will be done by the interrupt handler (or timeout handler). + [.programlisting] @@ -452,7 +452,7 @@ put_hcb_into_hardware_queue(hcb); return; .... -+ ++ And here is a possible implementation of the function returning CCB: + [.programlisting] @@ -479,16 +479,16 @@ .... * _XPT_RESET_DEV_ - send the SCSI "BUS DEVICE RESET" message to a device -+ ++ There is no data transferred in CCB except the header and the most interesting argument of it is target_id. Depending on the controller hardware a hardware control block just like for the XPT_SCSI_IO request may be constructed (see XPT_SCSI_IO request description) and sent to the controller or the SCSI controller may be immediately programmed to send this RESET message to the device or this request may be just not supported (and return the status `CAM_REQ_INVALID`). Also on completion of the request all the disconnected transactions for this target must be aborted (probably in the interrupt routine). -+ ++ Also all the current negotiations for the target are lost on reset, so they might be cleaned too. Or they clearing may be deferred, because anyway the target would request re-negotiation on the next transaction. * _XPT_RESET_BUS_ - send the RESET signal to the SCSI bus -+ ++ No arguments are passed in the CCB, the only interesting argument is the SCSI bus indicated by the struct sim pointer. -+ ++ A minimalistic implementation would forget the SCSI negotiations for all the devices on the bus and return the status CAM_REQ_CMP. -+ ++ The proper implementation would in addition actually reset the SCSI bus (possible also reset the SCSI controller) and mark all the CCBs being processed, both those in the hardware queue and those being disconnected, as done with the status CAM_SCSI_BUS_RESET. Like: + [.programlisting] @@ -542,16 +542,16 @@ xpt_async(AC_BUS_RESET, softc->wpath, NULL); return; .... -+ ++ Implementing the SCSI bus reset as a function may be a good idea because it would be re-used by the timeout function as a last resort if the things go wrong. * _XPT_ABORT_ - abort the specified CCB -+ ++ The arguments are transferred in the instance "struct ccb_abort cab" of the union ccb. The only argument field in it is: -+ ++ _abort_ccb_ - pointer to the CCB to be aborted -+ ++ If the abort is not supported just return the status CAM_UA_ABORT. This is also the easy way to minimally implement this call, return CAM_UA_ABORT in any case. -+ ++ The hard way is to implement this request honestly. First check that abort applies to a SCSI transaction: + [.programlisting] @@ -566,7 +566,7 @@ } .... -+ ++ Then it is necessary to find this CCB in our queue. This can be done by walking the list of all our hardware control blocks in search for one associated with this CCB: + [.programlisting] @@ -595,7 +595,7 @@ hcb=found_hcb; .... -+ ++ Now we look at the current processing status of the HCB. It may be either sitting in the queue waiting to be sent to the SCSI bus, being transferred right now, or disconnected and waiting for the result of the command, or actually completed by hardware but not yet marked as done by software. To make sure that we do not get in any races with hardware we mark the HCB as being aborted, so that if this HCB is about to be sent to the SCSI bus the SCSI controller will see this flag and skip it. + [.programlisting] @@ -619,7 +619,7 @@ free_hcb_and_ccb_done(hcb, abort_ccb, CAM_REQ_ABORTED); break; .... -+ ++ If the CCB is being transferred right now we would like to signal to the SCSI controller in some hardware-dependent way that we want to abort the current transfer. The SCSI controller would set the SCSI ATTENTION signal and when the target responds to it send an ABORT message. We also reset the timeout to make sure that the target is not sleeping forever. If the command would not get aborted in some reasonable time like 10 seconds the timeout routine would go ahead and reset the whole SCSI bus. Since the command will be aborted in some reasonable time we can just return the abort request now as successfully completed, and mark the aborted CCB as aborted (but not mark it as done yet). + [.programlisting] @@ -640,7 +640,7 @@ break; .... -+ ++ If the CCB is in the list of disconnected then set it up as an abort request and re-queue it at the front of hardware queue. Reset the timeout and report the abort request to be completed. + [.programlisting] @@ -657,9 +657,9 @@ xpt_done(ccb); return; .... -+ ++ That is all for the ABORT request, although there is one more issue. As the ABORT message cleans all the ongoing transactions on a LUN we have to mark all the other active transactions on this LUN as aborted. That should be done in the interrupt routine, after the transaction gets aborted. -+ ++ Implementing the CCB abort as a function may be quite a good idea, this function can be re-used if an I/O transaction times out. The only difference would be that the timed out transaction would return the status CAM_CMD_TIMEOUT for the timed out request. Then the case XPT_ABORT would be small, like that: + [.programlisting] @@ -683,7 +683,7 @@ .... * _XPT_SET_TRAN_SETTINGS_ - explicitly set values of SCSI transfer settings -+ ++ The arguments are transferred in the instance "struct ccb_trans_setting cts" of the union ccb: ** _valid_ - a bitmask showing which settings should be updated: @@ -701,19 +701,19 @@ *** _CCB_TRANS_CURRENT_SETTINGS_ - change the current negotiations *** _CCB_TRANS_USER_SETTINGS_ - remember the desired user values sync_period, sync_offset - self-explanatory, if sync_offset==0 then the asynchronous mode is requested bus_width - bus width, in bits (not bytes) -+ ++ Two sets of negotiated parameters are supported, the user settings and the current settings. The user settings are not really used much in the SIM drivers, this is mostly just a piece of memory where the upper levels can store (and later recall) its ideas about the parameters. Setting the user parameters does not cause re-negotiation of the transfer rates. But when the SCSI controller does a negotiation it must never set the values higher than the user parameters, so it is essentially the top boundary. -+ ++ The current settings are, as the name says, current. Changing them means that the parameters must be re-negotiated on the next transfer. Again, these "new current settings" are not supposed to be forced on the device, just they are used as the initial step of negotiations. Also they must be limited by actual capabilities of the SCSI controller: for example, if the SCSI controller has 8-bit bus and the request asks to set 16-bit wide transfers this parameter must be silently truncated to 8-bit transfers before sending it to the device. -+ ++ One caveat is that the bus width and synchronous parameters are per target while the disconnection and tag enabling parameters are per lun. -+ ++ The recommended implementation is to keep 3 sets of negotiated (bus width and synchronous transfer) parameters: ** _user_ - the user set, as above ** _current_ - those actually in effect ** _goal_ - those requested by setting of the "current" parameters -+ ++ The code looks like: + [.programlisting] @@ -766,7 +766,7 @@ xpt_done(ccb); return; .... -+ ++ Then when the next I/O request will be processed it will check if it has to re-negotiate, for example by calling the function target_negotiated(hcb). It can be implemented like this: + [.programlisting] @@ -785,15 +785,15 @@ return 1; /* TRUE */ } .... -+ ++ After the values are re-negotiated the resulting values must be assigned to both current and goal parameters, so for future I/O transactions the current and goal parameters would be the same and `target_negotiated()` would return TRUE. When the card is initialized (in `xxx_attach()`) the current negotiation values must be initialized to narrow asynchronous mode, the goal and current values must be initialized to the maximal values supported by controller. -+ ++ _XPT_GET_TRAN_SETTINGS_ - get values of SCSI transfer settings -+ ++ This operations is the reverse of XPT_SET_TRAN_SETTINGS. Fill up the CCB instance "struct ccb_trans_setting cts" with data as requested by the flags CCB_TRANS_CURRENT_SETTINGS or CCB_TRANS_USER_SETTINGS (if both are set then the existing drivers return the current settings). Set all the bits in the valid field. -+ ++ _XPT_CALC_GEOMETRY_ - calculate logical (BIOS) geometry of the disk -+ ++ The arguments are transferred in the instance "struct ccb_calc_geometry ccg" of the union ccb: ** _block_size_ - input, block (A.K.A sector) size in bytes @@ -801,7 +801,7 @@ ** _cylinders_ - output, logical cylinders ** _heads_ - output, logical heads ** _secs_per_track_ - output, logical sectors per track -+ ++ If the returned geometry differs much enough from what the SCSI controller BIOS thinks and a disk on this SCSI controller is used as bootable the system may not be able to boot. The typical calculation example taken from the aic7xxx driver is: + [.programlisting] @@ -829,7 +829,7 @@ xpt_done(ccb); return; .... -+ ++ This gives the general idea, the exact calculation depends on the quirks of the particular BIOS. If BIOS provides no way set the "extended translation" flag in EEPROM this flag should normally be assumed equal to 1. Other popular geometries are: + [.programlisting] @@ -837,10 +837,10 @@ 128 heads, 63 sectors - Symbios controllers 16 heads, 63 sectors - old controllers .... -+ ++ Some system BIOSes and SCSI BIOSes fight with each other with variable success, for example a combination of Symbios 875/895 SCSI and Phoenix BIOS can give geometry 128/63 after power up and 255/63 after a hard reset or soft reboot. * _XPT_PATH_INQ_ - path inquiry, in other words get the SIM driver and SCSI controller (also known as HBA - Host Bus Adapter) properties -+ ++ The properties are returned in the instance "struct ccb_pathinq cpi" of the union ccb: ** version_num - the SIM driver version number, now all drivers use 1 @@ -871,14 +871,14 @@ ** sim_vid - SIM driver's vendor id, a zero-terminated string of maximal length SIM_IDLEN including the terminating zero ** hba_vid - SCSI controller's vendor id, a zero-terminated string of maximal length HBA_IDLEN including the terminating zero ** dev_name - device driver name, a zero-terminated string of maximal length DEV_IDLEN including the terminating zero, equal to cam_sim_name(sim) -+ ++ The recommended way of setting the string fields is using strncpy, like: + [.programlisting] .... strncpy(cpi->dev_name, cam_sim_name(sim), DEV_IDLEN); .... -+ ++ After setting the values set the status to CAM_REQ_CMP and mark the CCB as done. [[scsi-polling]] diff --git a/documentation/content/en/books/arch-handbook/sound/_index.adoc b/documentation/content/en/books/arch-handbook/sound/_index.adoc --- a/documentation/content/en/books/arch-handbook/sound/_index.adoc +++ b/documentation/content/en/books/arch-handbook/sound/_index.adoc @@ -78,7 +78,7 @@ DRIVER_MODULE(snd_xxxpci, pci, xxx_driver, pcm_devclass, 0, 0); MODULE_DEPEND(snd_xxxpci, snd_pcm, PCM_MINVER, PCM_PREFVER,PCM_MAXVER); .... -+ ++ Most sound drivers need to store additional private information about their device. A private data structure is usually allocated in the attach routine. Its address is passed to [.filename]#pcm# by the calls to `pcm_register()` and `mixer_init()`. [.filename]#pcm# later passes back this address as a parameter in calls to the sound driver interfaces. * The sound driver attach routine should declare its MIXER or AC97 interface to [.filename]#pcm# by calling `mixer_init()`. For a MIXER interface, this causes in turn a call to <>. * The sound driver attach routine declares its general CHANNEL configuration to [.filename]#pcm# by calling `pcm_register(dev, sc, nplay, nrec)`, where `sc` is the address for the device data structure, used in further calls from [.filename]#pcm#, and `nplay` and `nrec` are the number of play and record channels. diff --git a/documentation/content/en/books/developers-handbook/ipv6/_index.adoc b/documentation/content/en/books/developers-handbook/ipv6/_index.adoc --- a/documentation/content/en/books/developers-handbook/ipv6/_index.adoc +++ b/documentation/content/en/books/developers-handbook/ipv6/_index.adoc @@ -328,7 +328,7 @@ . If the source address is explicitly specified by the user (e.g., via the advanced API), the specified address is used. . If there is an address assigned to the outgoing interface (which is usually determined by looking up the routing table) that has the same scope as the destination address, the address is used. -+ ++ This is the most typical case. . If there is no address that satisfies the above condition, choose a global address assigned to one of the interfaces on the sending node. . If there is no address that satisfies the above condition, and destination address is site local scope, choose a site local address assigned to one of the interfaces on the sending node. @@ -568,7 +568,7 @@ * By default, AF_INET6 socket will grab IPv4 connections in certain condition, and can initiate connection to IPv4 destination embedded in IPv4 mapped IPv6 address. * You can disable it on entire system with sysctl like below. -+ ++ `sysctl net.inet6.ip6.mapped_addr=0` ====== Listening Side diff --git a/documentation/content/en/books/developers-handbook/policies/_index.adoc b/documentation/content/en/books/developers-handbook/policies/_index.adoc --- a/documentation/content/en/books/developers-handbook/policies/_index.adoc +++ b/documentation/content/en/books/developers-handbook/policies/_index.adoc @@ -96,10 +96,10 @@ [.procedure] . *Preparing the Tree* -+ ++ If this is your first import after the switch to SVN, you will have to flatten and clean up the vendor tree, and bootstrap merge history in the main tree. If not, you can safely omit this step. -+ ++ During the conversion from CVS to SVN, vendor branches were imported with the same layout as the main tree. For example, the foo vendor sources ended up in [.filename]#vendor/foo/dist/contrib/foo#, but it is pointless and rather inconvenient. What we really want is to have the vendor source directly in [.filename]#vendor/foo/dist#, like this: @@ -113,7 +113,7 @@ % svn propdel -R svn:mergeinfo % svn commit .... -+ ++ Note that, the `propdel` bit is necessary because starting with 1.5, Subversion will automatically add `svn:mergeinfo` to any directory you copy or move. In this case, you will not need this information, since you are not going to merge anything from the tree you deleted. + @@ -123,7 +123,7 @@ The procedure is exactly the same. If you do this, put off the commit until the end. ==== -+ ++ Check the [.filename]#dist# tree and perform any cleanup that is deemed to be necessary. You may want to disable keyword expansion, as it makes no sense on unmodified vendor code. In some cases, it can be even be harmful. @@ -133,7 +133,7 @@ % svn propdel svn:keywords -R . % svn commit .... -+ ++ Bootstrapping of `svn:mergeinfo` on the target directory (in the main tree) to the revision that corresponds to the last change was made to the vendor tree prior to importing new sources is also needed: + [source,bash] @@ -142,14 +142,14 @@ % svn merge --record-only ^/vendor/foo/dist@12345678 . % svn commit .... -+ ++ With some shells, the `^` in the above command may need to be escaped with a backslash. . *Importing New Sources* -+ ++ Prepare a full, clean tree of the vendor sources. With SVN, we can keep a full distribution in the vendor tree without bloating the main tree. Import everything but merge only what is needed. -+ ++ Note that you will need to add any files that were added since the last vendor import, and remove any that were removed. To facilitate this, you should prepare sorted lists of the contents of the vendor tree and of the sources you are about to import: + @@ -160,21 +160,21 @@ % cd ../foo-9.9 % find . -type f | cut -c 3- | sort > ../new .... -+ ++ With these two files, the following command will list removed files (files only in [.filename]#old#): + [source,bash] .... % comm -23 ../old ../new .... -+ ++ While the command below will list added files (files only in [.filename]#new#): + [source,bash] .... % comm -13 ../old ../new .... -+ ++ Let us put this together: + [source,bash] @@ -192,7 +192,7 @@ You will have to add the directories, and run it again. Conversely, if any directories were removed, you will have to remove them manually. ==== -+ ++ Check properties on any new files: ** All text files should have `svn:eol-style` set to `native`. @@ -204,7 +204,7 @@ ==== You are ready to commit, but you should first check the output of `svn stat` and `svn diff` to make sure everything is in order. ==== -+ ++ Once you have committed the new vendor release, you should tag it for future reference. The best and quickest way is to do it directly in the repository: + @@ -212,7 +212,7 @@ .... % svn copy ^/vendor/foo/dist svn_base/vendor/foo/9.9 .... -+ ++ To get the new tag, you can update your working copy of [.filename]#vendor/foo#. + [NOTE] @@ -221,7 +221,7 @@ ==== . *Merging to __-HEAD__* -+ ++ After you have prepared your import, it is time to merge. Option `--accept=postpone` tells SVN not to handle merge conflicts yet, because they will be taken care of manually: + @@ -231,14 +231,14 @@ % svn update % svn merge --accept=postpone ^/vendor/foo/dist .... -+ ++ Resolve any conflicts, and make sure that any files that were added or removed in the vendor tree have been properly added or removed in the main tree. It is always a good idea to check differences against the vendor branch: + [source,bash] .... % svn diff --no-diff-deleted --old=^/vendor/foo/dist --new=. .... -+ ++ `--no-diff-deleted` tells SVN not to check files that are in the vendor tree but not in the main tree. + [NOTE] @@ -247,10 +247,10 @@ If a file that previously had local modifications no longer does, just remove any left-over cruft, such as FreeBSD version tags, so it no longer shows up in diffs against the vendor tree. ==== -+ ++ If any changes are required for the world to build with the new sources, make them now - and test until you are satisfied that everything build and runs correctly. . *Commit* -+ ++ Now, you are ready to commit. Make sure you get everything in one go. Ideally, you would have done all steps in a clean tree, in which case you can just commit from the top of that tree. diff --git a/documentation/content/en/books/developers-handbook/testing/_index.adoc b/documentation/content/en/books/developers-handbook/testing/_index.adoc --- a/documentation/content/en/books/developers-handbook/testing/_index.adoc +++ b/documentation/content/en/books/developers-handbook/testing/_index.adoc @@ -56,14 +56,14 @@ * Remove all non-essential device drivers from the kernel. For instance if USB is not needed for the test, do not put USB in the kernel. Drivers which attach often have timeouts ticking away. * Unconfigure hardware that are not in use. Detach disks with man:atacontrol[8] and man:camcontrol[8] if the disks are not used for the test. * Do not configure the network unless it is being tested, or wait until after the test has been performed to ship the results off to another computer. -+ ++ If the system must be connected to a public network, watch out for spikes of broadcast traffic. Even though it is hardly noticeable, it will take up CPU cycles. Multicast has similar caveats. * Put each file system on its own disk. This minimizes jitter from head-seek optimizations. * Minimize output to serial or VGA consoles. Running output into files gives less jitter. (Serial consoles easily become a bottleneck.) Do not touch keyboard while the test is running, even kbd:[space] or kbd:[back-space] shows up in the numbers. * Make sure the test is long enough, but not too long. If the test is too short, timestamping is a problem. If it is too long temperature changes and drift will affect the frequency of the quartz crystals in the computer. Rule of thumb: more than a minute, less than an hour. * Try to keep the temperature as stable as possible around the machine. This affects both quartz crystals and disk drive algorithms. To get real stable clock, consider stabilized clock injection. E.g., get a OCXO + PLL, inject output into clock circuits instead of motherboard xtal. Contact {phk} for more information about this. * Run the test at least 3 times but it is better to run more than 20 times both for "before" and "after" code. Try to interleave if possible (i.e.: do not run 20 times before then 20 times after), this makes it possible to spot environmental effects. Do not interleave 1:1, but 3:3, this makes it possible to spot interaction effects. -+ ++ A good pattern is: `bababa{bbbaaa}*`. This gives hint after the first 1+1 runs (so it is possible to stop the test if it goes entirely the wrong way), a standard deviation after the first 3+3 (gives a good indication if it is going to be worth a long run) and trending and interaction numbers later on. * Use man:ministat[1] to see if the numbers are significant. Consider buying "Cartoon guide to statistics" ISBN: 0062731025, highly recommended, if you have forgotten or never learned about standard deviation and Student's T. diff --git a/documentation/content/en/books/developers-handbook/tools/_index.adoc b/documentation/content/en/books/developers-handbook/tools/_index.adoc --- a/documentation/content/en/books/developers-handbook/tools/_index.adoc +++ b/documentation/content/en/books/developers-handbook/tools/_index.adoc @@ -452,7 +452,7 @@ char *foo; strcpy(foo, "bang!"); .... -+ ++ 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. * Trying to access past the end of an array, eg @@ -470,7 +470,7 @@ char *foo = "My string"; strcpy(foo, "bang!"); .... -+ ++ UNIX(R) compilers often put string literals like `"My string"` into read-only areas of memory. * Doing naughty things with `malloc()` and `free()`, eg + @@ -479,7 +479,7 @@ char bar[80]; free(bar); .... -+ ++ or + [.programlisting] @@ -1339,7 +1339,7 @@ .... % emacsclient filename .... -+ ++ and then you can edit the file in your Emacs!footnote:[Many Emacs users set their EDITOR environment to emacsclient so this happens every time they need to edit a file.] .A Sample [.filename]#.emacs# diff --git a/documentation/content/en/books/developers-handbook/x86/_index.adoc b/documentation/content/en/books/developers-handbook/x86/_index.adoc --- a/documentation/content/en/books/developers-handbook/x86/_index.adoc +++ b/documentation/content/en/books/developers-handbook/x86/_index.adoc @@ -3046,7 +3046,7 @@ * If the counter grows above 18, we stop appending to the buffer. We continue reading the digits and sending them to the output. * If, or rather _when_, the next input character is not a digit, we are done inputting for now. -+ ++ Incidentally, we can simply discard the non-digit, unless it is a `#`, which we must return to the input stream. It starts a comment, so we must see it after we are done producing output and start looking for more input. diff --git a/documentation/content/en/books/faq/_index.adoc b/documentation/content/en/books/faq/_index.adoc --- a/documentation/content/en/books/faq/_index.adoc +++ b/documentation/content/en/books/faq/_index.adoc @@ -335,9 +335,9 @@ * The compression and packaging scheme. .. Where the format is `html-split`, the files are bundled up using man:tar[1]. The resulting [.filename]#.tar# is then compressed using the compression schemes detailed in the next point. .. All the other formats generate one file. For example, [.filename]#article.pdf#, [.filename]#book.html#, and so on. -+ ++ These files are then compressed using either the `zip` or `bz2` compression schemes. man:tar[1] can be used to uncompress these files. -+ ++ So the PDF version of the Handbook, compressed using `bzip2` will be stored in a file called [.filename]#book.pdf.bz2# in the [.filename]#handbook/# directory. After choosing the format and compression mechanism, download the compressed files, uncompress them, and then copy the appropriate documents into place. @@ -684,7 +684,7 @@ . The hard disks might be overheating: Check that the fans are still working, as the disk and other hardware might be overheating. . 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, ensure that the hardware is running at what it is specified to run at, at least while trying to solve this problem. If it is not, clock it back to the default settings.) -+ ++ Regarding overclocking, it is far cheaper to have a slow system than a fried system that needs replacing! Also the community is not sympathetic to problems on overclocked systems. . Dodgy memory: if multiple memory SIMMS/DIMMS are installed, pull them all out and try running the machine with each SIMM or DIMM individually to narrow the problem down to either the problematic DIMM/SIMM or perhaps even a combination. . Over-optimistic motherboard settings: the BIOS settings, and some motherboard jumpers, provide options to set various timings. The defaults are often sufficient, but sometimes setting the wait states on RAM too low, or setting the "RAM Speed: Turbo" option will cause strange behavior. A possible idea is to set to BIOS defaults, after noting the current settings first. @@ -1412,7 +1412,7 @@ .... options QUOTA .... -+ ++ Refer to the link:{handbook}#quotas/[Handbook entry on quotas] for full details. . Do not turn on quotas on [.filename]#/#. . Put the quota file on the file system that the quotas are to be enforced on: @@ -2088,18 +2088,18 @@ "Sandbox" is a security term. It can mean two things: * 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. -+ ++ The process is only able to run inside the walls. Since nothing the process does in regards to executing code is supposed to be able to breach the walls, a detailed audit of its code is not needed in order to be able to say certain things about its security. -+ ++ 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. -+ ++ Take the `ntalk` service, for example (see man:inetd[8]). This service used to run as user ID `root`. Now it runs as user ID `tty`. The `tty` user is a sandbox designed to make it more difficult for someone who has successfully hacked into the system via `ntalk` from being able to hack beyond that user ID. * 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. -+ ++ 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 so that [.filename]#/# for that process is this directory, not the real [.filename]#/# of the system). -+ ++ 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. -+ ++ 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. UNIX(R) implements two core sandboxes. One is at the process level, and one is at the userid level. @@ -2532,14 +2532,14 @@ .... % nm -n kernel.that.caused.the.panic | grep f0xxxxxx .... -+ ++ where `f0xxxxxx` 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: + [source,shell] .... % nm -n kernel.that.caused.the.panic | grep f0xxxxx .... -+ ++ If that does not yield any results, chop off another digit. Repeat until there is 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. ==== diff --git a/documentation/content/en/books/fdp-primer/overview/_index.adoc b/documentation/content/en/books/fdp-primer/overview/_index.adoc --- a/documentation/content/en/books/fdp-primer/overview/_index.adoc +++ b/documentation/content/en/books/fdp-primer/overview/_index.adoc @@ -72,7 +72,7 @@ .... + . Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input. -+ ++ Review the output and edit the file to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved. + @@ -90,7 +90,7 @@ % cd ~/doc % git diff > bsdinstall.diff.txt .... -+ ++ Give the diff file a descriptive name. In the example above, changes have been made to the [.filename]#bsdinstall# portion of the Handbook. . Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. If using the web form, enter a Summary of _[patch] short description of problem_. Select the Component `Documentation`. In the Description field, enter a short description of the changes and any important details about them. Use the btn:[Add an attachment] button to attach the diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system. diff --git a/documentation/content/en/books/fdp-primer/po-translations/_index.adoc b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc --- a/documentation/content/en/books/fdp-primer/po-translations/_index.adoc +++ b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc @@ -106,7 +106,7 @@ .... + . Use a PO editor to enter translations in the PO file. There are several different editors available. [.filename]#poedit# from package:editors/poedit[] is shown here. -+ ++ [source,shell] .... % poedit documentation/content/es/articles/leap-seconds/_index.po @@ -133,7 +133,7 @@ --localized-charset "UTF-8" \ --keep 0 .... -+ ++ The name of the generated document matches the name of the English original, usually [.filename]#_index.adoc#. + . Check the generated file by rendering it to HTML and viewing it with a web browser: @@ -276,7 +276,7 @@ % cd porters-handbook % cp -R ~/doc/documentation/content/en/books/porters-handbook/* . .... -+ ++ Now the document structure is ready for the translator to begin translating with `po4a` command. ====== ==== diff --git a/documentation/content/en/books/handbook/advanced-networking/_index.adoc b/documentation/content/en/books/handbook/advanced-networking/_index.adoc --- a/documentation/content/en/books/handbook/advanced-networking/_index.adoc +++ b/documentation/content/en/books/handbook/advanced-networking/_index.adoc @@ -378,16 +378,16 @@ .... % ifconfig | grep -B3 -i wireless .... -+ ++ On FreeBSD 11 or higher, use this command instead: + [source,shell] .... % sysctl net.wlan.devices .... -+ ++ If a wireless adapter is not listed, an additional kernel module might be required, or it might be a model not supported by FreeBSD. -+ ++ This example shows the Atheros `ath0` wireless adapter. . Add an entry for this network to [.filename]#/etc/wpa_supplicant.conf#. If the file does not exist, create it. Replace _myssid_ and _mypsk_ with the SSID and PSK provided by the network administrator. + @@ -1391,7 +1391,7 @@ * If the access point is not listed when scanning, check that the configuration has not limited the wireless device to a limited set of channels. * If the device cannot associate with an access point, verify that the configuration matches the settings on the access point. This includes the authentication scheme and any security protocols. Simplify the configuration as much as possible. If using a security protocol such as WPA or WEP, configure the access point for open authentication and no security to see if traffic will pass. -+ ++ Debugging support is provided by man:wpa_supplicant[8]. Try running this utility manually with `-dd` and look at the system logs. * Once the system can associate with the access point, diagnose the network configuration using tools like man:ping[8]. * There are many lower-level debugging tools. Debugging messages can be enabled in the 802.11 protocol support layer using man:wlandebug[8]. For example, to enable console messages related to scanning for access points and the 802.11 protocol handshakes required to arrange communication: @@ -1401,7 +1401,7 @@ # wlandebug -i wlan0 +scan+auth+debug+assoc net.wlan.0.debug: 0 => 0xc80000 .... -+ ++ Many useful statistics are maintained by the 802.11 layer and `wlanstats`, found in [.filename]#/usr/src/tools/tools/net80211#, will dump this information. These statistics should display all errors identified by the 802.11 layer. However, some errors are identified in the device drivers that lie below the 802.11 layer so they may not show up. @@ -2638,7 +2638,7 @@ # Device Mountpoint FSType Options Dump Pass myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro 0 0 .... -+ ++ Replace _myhost.example.com_ with the hostname or IP address of the NFS server. In this example, the root file system is mounted read-only in order to prevent NFS clients from potentially deleting the contents of the root file system. . Set the root password in the PXE environment for client machines which are PXE booting : @@ -2752,7 +2752,7 @@ tftp> get FreeBSD/install/boot/pxeboot Received 264951 bytes in 0.1 seconds .... -+ ++ The `BUGS` sections in man:tftpd[8] and man:tftp[1] document some limitations with TFTP. . Make sure that the root file system can be mounted via NFS. To test this example configuration: + diff --git a/documentation/content/en/books/handbook/bibliography/_index.adoc b/documentation/content/en/books/handbook/bibliography/_index.adoc --- a/documentation/content/en/books/handbook/bibliography/_index.adoc +++ b/documentation/content/en/books/handbook/bibliography/_index.adoc @@ -67,7 +67,7 @@ == Users' Guides * Ohio State University has written a http://www.cs.duke.edu/csl/docs/unix_course/[UNIX Introductory Course] which is available online in HTML and PostScript format. -+ ++ An Italian https://www.FreeBSD.org/doc/it_IT.ISO8859-15/books/unix-introduction/[translation] of this document is available as part of the FreeBSD Italian Documentation Project. * http://www.jp.FreeBSD.org/[Jpman Project, Japan FreeBSD Users Group]. FreeBSD User's Reference Manual (Japanese translation). http://www.pc.mycom.co.jp/[Mainichi Communications Inc.], 1998. ISBN4-8399-0088-4 P3800E. * http://www.ed.ac.uk/[Edinburgh University] has written an http://www.ed.ac.uk/information-services/help-consultancy/is-skills/catalogue/program-op-sys-catalogue/unix1[Online Guide] for newcomers to the UNIX environment. @@ -100,7 +100,7 @@ * Leffler, Samuel J., Marshall Kirk McKusick, Michael J Karels and John Quarterman _The Design and Implementation of the 4.3BSD UNIX Operating System_. Reading, Mass. : Addison-Wesley, 1989. ISBN 0-201-06196-1 * Leffler, Samuel J., Marshall Kirk McKusick, _The Design and Implementation of the 4.3BSD UNIX Operating System: Answer Book_. Reading, Mass. : Addison-Wesley, 1991. ISBN 0-201-54629-9 * McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and John Quarterman. _The Design and Implementation of the 4.4BSD Operating System_. Reading, Mass. : Addison-Wesley, 1996. ISBN 0-201-54979-4 -+ ++ (Chapter 2 of this book is available link:{design-44bsd}[online] as part of the FreeBSD Documentation Project.) * Marshall Kirk McKusick, George V. Neville-Neil _The Design and Implementation of the FreeBSD Operating System_. Boston, Mass. : Addison-Wesley, 2004. ISBN 0-201-70245-2 * Marshall Kirk McKusick, George V. Neville-Neil, Robert N. M. Watson _The Design and Implementation of the FreeBSD Operating System, 2nd Ed._. Westford, Mass. : Pearson Education, Inc., 2014. ISBN 0-321-96897-2 diff --git a/documentation/content/en/books/handbook/bsdinstall/_index.adoc b/documentation/content/en/books/handbook/bsdinstall/_index.adoc --- a/documentation/content/en/books/handbook/bsdinstall/_index.adoc +++ b/documentation/content/en/books/handbook/bsdinstall/_index.adoc @@ -131,28 +131,28 @@ [.procedure] . *Back Up Important Data* -+ ++ Before installing any operating system, _always_ backup all important data first. Do not store the backup on the system being installed. Instead, save the data to a removable disk such as a USB drive, another system on the network, or an online backup service. Test the backup before starting the installation to make sure it contains all of the needed files. Once the installer formats the system's disk, all data stored on that disk will be lost. . *Decide Where to Install FreeBSD* -+ ++ If FreeBSD will be the only operating system installed, this step can be skipped. But if FreeBSD will share the disk with another operating system, decide which disk or partition will be used for FreeBSD. -+ ++ In the i386 and amd64 architectures, disks can be divided into multiple partitions using one of two partitioning schemes. A traditional _Master Boot Record_ (MBR) holds a partition table defining up to four _primary partitions_. For historical reasons, FreeBSD calls these primary partition _slices_. One of these primary partitions can be made into an _extended partition_ containing multiple _logical partitions_. The _GUID Partition Table_ (GPT) is a newer and simpler method of partitioning a disk. Common GPT implementations allow up to 128 partitions per disk, eliminating the need for logical partitions. -+ ++ The FreeBSD boot loader requires either a primary or GPT partition. If all of the primary or GPT partitions are already in use, one must be freed for FreeBSD. To create a partition without deleting existing data, use a partition resizing tool to shrink an existing partition and create a new partition using the freed space. -+ ++ A variety of free and commercial partition resizing tools are listed at http://en.wikipedia.org/wiki/List_of_disk_partitioning_software[http://en.wikipedia.org/wiki/List_of_disk_partitioning_software]. GParted Live (http://gparted.sourceforge.net/livecd.php[http://gparted.sourceforge.net/livecd.php]) is a free live CD which includes the GParted partition editor. GParted is also included with many other Linux live CD distributions. @@ -162,14 +162,14 @@ When used properly, disk shrinking utilities can safely create space for creating a new partition. Since the possibility of selecting the wrong partition exists, always backup any important data and verify the integrity of the backup before modifying disk partitions. ==== -+ ++ Disk partitions containing different operating systems make it possible to install multiple operating systems on one computer. An alternative is to use virtualization (crossref:virtualization[virtualization,Virtualization]) which allows multiple operating systems to run at the same time without modifying any disk partitions. . *Collect Network Information* -+ ++ Some FreeBSD installation methods require a network connection in order to download the installation files. After any installation, the installer will offer to setup the system's network interfaces. -+ ++ If the network has a DHCP server, it can be used to provide automatic network configuration. If DHCP is not available, the following network information for the system must be obtained from the local network administrator or Internet service provider: + @@ -188,7 +188,7 @@ On very rare occasions those bugs affect the installation process. As these problems are discovered and fixed, they are noted in the FreeBSD Errata (link:https://www.FreeBSD.org/releases/{rel121-current}R/errata/[https://www.freebsd.org/releases/{rel121-current}R/errata/]) on the FreeBSD web site. Check the errata before installing to make sure that there are no problems that might affect the installation. -+ ++ Information and errata for all the releases can be found on the release information section of the FreeBSD web site (link:https://www.FreeBSD.org/releases/[https://www.freebsd.org/releases/]). [[bsdinstall-installation-media]] diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc --- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc +++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc @@ -552,14 +552,14 @@ To track FreeBSD-CURRENT: . Join the {freebsd-current} and the {dev-commits-src-main} lists. This is _essential_ in order to see the comments that people are making about the current state of the system and to receive important bulletins about the current state of FreeBSD-CURRENT. -+ ++ The {dev-commits-src-main} list records the commit log entry for each change as it is made, along with any pertinent information on possible side effects. -+ ++ To join these lists, go to {mailman-lists}, click on the list to subscribe to, and follow the instructions. In order to track changes to the whole source tree, not just the changes to FreeBSD-CURRENT, subscribe to the {dev-commits-src-all}. . Synchronize with the FreeBSD-CURRENT sources. Typically, `git` is used to check out the -CURRENT code from the `main` branch of the FreeBSD Git repository (see crossref:mirrors[git,“Using Git”] for details). . Due to the size of the repository, some users choose to only synchronize the sections of source that interest them or which they are contributing patches to. However, users that plan to compile the operating system from source must download _all_ of FreeBSD-CURRENT, not just selected portions. -+ ++ Before compiling FreeBSD-CURRENT, read [.filename]#/usr/src/Makefile# very carefully and follow the instructions in <>. Read the {freebsd-current} and [.filename]#/usr/src/UPDATING# to stay up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release. . Be active! FreeBSD-CURRENT users are encouraged to submit their suggestions for enhancements or bug fixes. Suggestions with accompanying code are always welcome. @@ -583,15 +583,15 @@ To track FreeBSD-STABLE: . Join the {freebsd-stable} in order to stay informed of build dependencies that may appear in FreeBSD-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. -+ ++ Join the relevant git list for the branch being tracked. For example, users tracking the {betarel-current-major}-STABLE branch should join the {dev-commits-src-branches}. This list records the commit log entry for each change as it is made, along with any pertinent information on possible side effects. -+ ++ To join these lists, go to {mailman-lists}, click on the list to subscribe to, and follow the instructions. In order to track changes for the whole source tree, subscribe to {dev-commits-src-all}. . To install a new FreeBSD-STABLE system, install the most recent FreeBSD-STABLE release from the crossref:mirrors[mirrors,FreeBSD mirror sites] or use a monthly snapshot built from FreeBSD-STABLE. Refer to link:https://www.FreeBSD.org/snapshots/[www.freebsd.org/snapshots] for more information about snapshots. -+ ++ To compile or upgrade to an existing FreeBSD system to FreeBSD-STABLE, use `git` to check out the source for the desired branch. Branch names, such as `stable/9`, are listed at link:https://www.FreeBSD.org/releng/[www.freebsd.org/releng]. . Before compiling or upgrading to FreeBSD-STABLE , read [.filename]#/usr/src/Makefile# carefully and follow the instructions in <>. Read the {freebsd-stable} and [.filename]#/usr/src/UPDATING# to keep up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release. diff --git a/documentation/content/en/books/handbook/disks/_index.adoc b/documentation/content/en/books/handbook/disks/_index.adoc --- a/documentation/content/en/books/handbook/disks/_index.adoc +++ b/documentation/content/en/books/handbook/disks/_index.adoc @@ -780,7 +780,7 @@ .... % cdda2wav -vall -B -Owav .... -+ ++ A device name does not need to be specified if there is only one CD device on the system. Refer to the `cdda2wav` manual page for instructions on how to specify a device and to learn more about the other options available for this command. . Use `cdrecord` to write the [.filename]#.wav# files: @@ -789,7 +789,7 @@ .... % cdrecord -v dev=2,0 -dao -useinfo *.wav .... -+ ++ Make sure that _2,0_ is set appropriately, as described in <>. [[creating-dvds]] @@ -1824,7 +1824,7 @@ [.procedure] .Procedure: Encrypting a Partition with gbde . Add the New Hard Drive -+ ++ Install the new drive to the system as explained in <>. For the purposes of this example, a new hard drive partition has been added as [.filename]#/dev/ad4s1c# and [.filename]#/dev/ad0s1*# represents the existing standard FreeBSD partitions. + @@ -1842,12 +1842,12 @@ .... # mkdir /etc/gbde .... -+ ++ The gbde lock file contains information that gbde requires to access encrypted partitions. Without access to the lock file, gbde 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. . Initialize the `gbde` Partition -+ ++ A gbde partition must be initialized before it can be used. This initialization needs to be performed only once. This command will open the default editor, in order to set various configuration options in a template. @@ -1866,12 +1866,12 @@ sector_size = 2048 [...] .... -+ ++ Once the edit is saved, the user will be asked twice to type the passphrase used to secure the data. The passphrase must be the same both times. The ability of gbde 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 http://world.std.com/\~reinhold/diceware.html[http://world.std.com/~reinhold/diceware.htm]. -+ ++ This initialization creates a lock file for the gbde partition. In this example, it is stored as [.filename]#/etc/gbde/ad4s1c.lock#. Lock files must end in ".lock" in order to be correctly detected by the [.filename]#/etc/rc.d/gbde# start up script. @@ -1888,7 +1888,7 @@ .... # gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c.lock .... -+ ++ 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]#/dev# as [.filename]#/dev/device_name.bde#: + @@ -1901,7 +1901,7 @@ .... . Create a File System on the Encrypted Device -+ ++ Once the encrypted device has been attached to the kernel, a file system can be created on the device. This example creates a UFS file system with soft updates enabled. Be sure to specify the partition which has a [.filename]#*.bde# extension: @@ -1912,7 +1912,7 @@ .... . Mount the Encrypted Partition -+ ++ Create a mount point and mount the encrypted file system: + [source,shell] @@ -1922,7 +1922,7 @@ .... . Verify That the Encrypted File System is Available -+ ++ The encrypted file system should now be visible and available for use: + [source,shell] @@ -1989,21 +1989,21 @@ [.procedure] .Procedure: Encrypting a Partition with `geli` . Load `geli` Support -+ ++ Support for `geli` is available as a loadable kernel module. To configure the system to automatically load the module at boot time, add the following line to [.filename]#/boot/loader.conf#: + [.programlisting] .... geom_eli_load="YES" .... -+ ++ To load the kernel module now: + [source,shell] .... # kldload geom_eli .... -+ ++ For a custom kernel, ensure the kernel configuration file contains these lines: + [.programlisting] @@ -2013,7 +2013,7 @@ .... . Generate the Master Key -+ ++ The following commands generate a master key that all data will be encrypted with. This key can never be changed. Rather than using it directly, it is encrypted with one or more user keys. @@ -2028,9 +2028,9 @@ Enter new passphrase: Reenter new passphrase: .... -+ ++ 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. -+ ++ If the key file is given as "-", standard input will be used. For example, this command generates three key files: + @@ -2040,7 +2040,7 @@ .... . Attach the Provider with the Generated Key -+ ++ To attach the provider, specify the key file, the name of the disk, and the passphrase: + [source,shell] @@ -2048,7 +2048,7 @@ # geli attach -k /root/da2.key /dev/da2 Enter passphrase: .... -+ ++ This creates a new device with an [.filename]#.eli# extension: + [source,shell] @@ -2058,7 +2058,7 @@ .... . Create the New File System -+ ++ Next, format the device with the UFS file system and mount it on an existing mount point: + [source,shell] @@ -2067,7 +2067,7 @@ # newfs /dev/da2.eli # mount /dev/da2.eli /private .... -+ ++ The encrypted file system should now be available for use: + [source,shell] diff --git a/documentation/content/en/books/handbook/firewalls/_index.adoc b/documentation/content/en/books/handbook/firewalls/_index.adoc --- a/documentation/content/en/books/handbook/firewalls/_index.adoc +++ b/documentation/content/en/books/handbook/firewalls/_index.adoc @@ -813,7 +813,7 @@ .... fdescfs /dev/fd fdescfs rw 0 0 .... -+ ++ Then, mount the filesystem: + [.programlisting] @@ -832,14 +832,14 @@ rdr pass on $ext_if inet proto tcp from ! to \ { $ext_if, $localnet } port smtp -> 127.0.0.1 port 8025 .... -+ ++ The two tables `` and `` are essential. SMTP traffic from an address listed in `` but not in `` is redirected to the spamd daemon listening at port 8025. . The next step is to configure spamd in [.filename]#/usr/local/etc/spamd.conf# and to add some [.filename]#rc.conf# parameters. -+ ++ The installation of package:mail/spamd[] includes a sample configuration file ([.filename]#/usr/local/etc/spamd.conf.sample#) and a man page for [.filename]#spamd.conf#. Refer to these for additional configuration options beyond those shown in this example. -+ ++ One of the first lines in the configuration file that does not begin with a `#` comment sign contains the block which defines the `all` list, which specifies the lists to use: + [.programlisting] @@ -847,10 +847,10 @@ all:\ :traplist:whitelist: .... -+ ++ This entry adds the desired blacklists, separated by colons (`:`). To use a whitelist to subtract addresses from a blacklist, add the name of the whitelist _immediately_ after the name of that blacklist. For example: `:blacklist:whitelist:`. -+ ++ This is followed by the specified blacklist's definition: + [.programlisting] @@ -861,12 +861,12 @@ :method=http:\ :file=www.openbsd.org/spamd/traplist.gz .... -+ ++ where the first line is the name of the blacklist and the second line specifies the list type. The `msg` field contains the message to display to blacklisted senders during the SMTP dialogue. The `method` field specifies how spamd-setup fetches the list data; supported methods are `http`, `ftp`, from a `file` in a mounted file system, and via `exec` of an external program. Finally, the `file` field specifies the name of the file spamd expects to receive. -+ ++ The definition of the specified whitelist is similar, but omits the `msg` field since a message is not needed: + [.programlisting] @@ -884,7 +884,7 @@ Using all the blacklists in the sample [.filename]#spamd.conf# will blacklist large blocks of the Internet. Administrators need to edit the file to create an optimal configuration which uses applicable data sources and, when necessary, uses custom lists. ==== -+ ++ Next, add this entry to [.filename]#/etc/rc.conf#. Additional flags are described in the man page specified by the comment: + @@ -892,7 +892,7 @@ .... spamd_flags="-v" # use "" and see spamd-setup(8) for flags .... -+ ++ When finished, reload the ruleset, start spamd by typing `service obspamd start`, and complete the configuration using `spamd-setup`. Finally, create a man:cron[8] job which calls `spamd-setup` to update the tables at reasonable intervals. **** @@ -918,7 +918,7 @@ .... spamd_grey="YES" # use spamd greylisting if YES .... -+ ++ Refer to the spamd man page for descriptions of additional related parameters. . To complete the greylisting setup: + diff --git a/documentation/content/en/books/handbook/geom/_index.adoc b/documentation/content/en/books/handbook/geom/_index.adoc --- a/documentation/content/en/books/handbook/geom/_index.adoc +++ b/documentation/content/en/books/handbook/geom/_index.adoc @@ -125,7 +125,7 @@ .... # newfs -U /dev/stripe/st0a .... -+ ++ Many numbers will glide across the screen, and after a few seconds, the process will be complete. The volume has been created and is ready to be mounted. . To manually mount the created disk stripe: @@ -725,7 +725,7 @@ .... # graid3 load .... -+ ++ or: + [source,shell] @@ -759,7 +759,7 @@ # gpart add -t freebsd-ufs /dev/raid3/gr0 # newfs -j /dev/raid3/gr0p1 .... -+ ++ Many numbers will glide across the screen, and after a bit of time, the process will be complete. The volume has been created and is ready to be mounted: + @@ -767,7 +767,7 @@ .... # mount /dev/raid3/gr0p1 /multimedia/ .... -+ ++ The RAID3 array is now ready to use. Additional configuration is needed to retain this setup across system reboots. @@ -994,7 +994,7 @@ OK set kern.geom.raid.enable=0 OK boot .... -+ ++ The system will boot with man:graid[8] disabled. . Back up all data on the affected drive. . As a workaround, man:graid[8] array detection can be disabled by adding @@ -1003,9 +1003,9 @@ .... kern.geom.raid.enable=0 .... -+ ++ to [.filename]#/boot/loader.conf#. -+ ++ To permanently remove the man:graid[8] metadata from the affected drive, boot a FreeBSD installation CD-ROM or memory stick, and select `Shell`. Use `status` to find the name of the array, typically `raid/r0`: + @@ -1016,17 +1016,17 @@ raid/r0 OPTIMAL ada0 (ACTIVE (ACTIVE)) ada1 (ACTIVE (ACTIVE)) .... -+ ++ Delete the volume by name: + [source,shell] .... # graid delete raid/r0 .... -+ ++ If there is more than one volume shown, repeat the process for each volume. After the last array has been deleted, the volume will be destroyed. -+ ++ Reboot and verify data, restoring from backup if necessary. After the metadata has been removed, the `kern.geom.raid.enable=0` entry in [.filename]#/boot/loader.conf# can also be removed. diff --git a/documentation/content/en/books/handbook/jails/_index.adoc b/documentation/content/en/books/handbook/jails/_index.adoc --- a/documentation/content/en/books/handbook/jails/_index.adoc +++ b/documentation/content/en/books/handbook/jails/_index.adoc @@ -229,14 +229,14 @@ } .... -+ ++ Configure jails to start at boot time in [.filename]#rc.conf#: + [.programlisting] .... jail_enable="YES" # Set to NO to disable starting of any jails .... -+ ++ The default startup of jails configured in man:jail.conf[5], will run the [.filename]#/etc/rc# script of the jail, which assumes the jail is a complete virtual system. For service jails, the default startup command of the jail should be changed, by setting the `exec.start` option appropriately. + @@ -461,7 +461,7 @@ .... WRKDIRPREFIX?= /s/portbuild .... -+ ++ This makes it possible to compile FreeBSD ports inside each jail. Remember that the ports directory is part of the read-only system. The custom path for `WRKDIRPREFIX` allows builds to be done in the read-write portion of every jail. @@ -484,7 +484,7 @@ /home/js/mail /home/j/mail/s nullfs rw 0 0 /home/js/www /home/j/www/s nullfs rw 0 0 .... -+ ++ To prevent fsck from checking nullfs mounts during boot and dump from backing up the read-only nullfs mounts of the jails, the last two columns are both set to `0`. . Configure the jails in [.filename]#/etc/rc.conf#: + @@ -506,7 +506,7 @@ jail_www_rootdir="/usr/home/j/www" jail_www_devfs_enable="YES" .... -+ ++ The `jail__name__rootdir` variable is set to [.filename]#/usr/home# instead of [.filename]#/home# because the physical path of [.filename]#/home# on a default FreeBSD installation is [.filename]#/usr/home#. The `jail__name__rootdir` variable must _not_ be set to a path which includes a symbolic link, otherwise the jails will refuse to start. . Create the required mount points for the read-only file system of each jail: @@ -574,7 +574,7 @@ # cpdup /usr/src usr/src # mkdir s .... -+ ++ The `installworld` creates a few unnecessary directories, which should be removed: + [source,shell] @@ -661,7 +661,7 @@ .... cloned_interfaces="lo1" .... -+ ++ The second loopback interface `lo1` will be created when the system starts. It can also be created manually without a restart: + @@ -670,12 +670,12 @@ # service netif cloneup Created clone interfaces: lo1. .... -+ ++ Jails can be allowed to use aliases of this secondary loopback interface without interfering with the host. -+ ++ Inside a jail, access to the loopback address `127.0.0.1` is redirected to the first IP address assigned to the jail. To make the jail loopback correspond with the new `lo1` interface, that interface must be specified first in the list of interfaces and IP addresses given when creating a new jail. -+ ++ Give each jail a unique loopback address in the `127.0.0.0/8` netblock. . Install package:sysutils/ezjail[]: + @@ -714,7 +714,7 @@ [.procedure] . To Populate the Jail with FreeBSD-RELEASE -+ ++ For a basejail based on the FreeBSD RELEASE matching that of the host computer, use `install`. For example, on a host computer running FreeBSD 10-STABLE, the latest RELEASE version of FreeBSD -10 will be installed in the jail): + @@ -724,9 +724,9 @@ .... . To Populate the Jail with `installworld` -+ ++ The basejail can be installed from binaries created by `buildworld` on the host with `ezjail-admin update`. -+ ++ In this example, FreeBSD 10-STABLE has been built from source. The jail directories are created. Then `installworld` is executed, installing the host's [.filename]#/usr/obj# into the basejail. @@ -735,7 +735,7 @@ .... # ezjail-admin update -i -p .... -+ ++ The host's [.filename]#/usr/src# is used by default. A different source directory on the host can be specified with `-s` and a path, or set with `ezjail_sourcetree` in [.filename]#/usr/local/etc/ezjail.conf#. @@ -817,7 +817,7 @@ [.procedure] . Set the `root` Password -+ ++ Connect to the jail and set the `root` user's password: + [source,shell] @@ -830,18 +830,18 @@ .... . Time Zone Configuration -+ ++ The jail's time zone can be set with man:tzsetup[8]. To avoid spurious error messages, the man:adjkerntz[8] entry in [.filename]#/etc/crontab# can be commented or removed. This job attempts to update the computer's hardware clock with time zone changes, but jails are not allowed to access that hardware. . DNS Servers -+ ++ Enter domain name server lines in [.filename]#/etc/resolv.conf# so DNS works in the jail. . Edit [.filename]#/etc/hosts# -+ ++ Change the address and add the jail name to the `localhost` entries in [.filename]#/etc/hosts#. . Configure [.filename]#/etc/rc.conf# -+ ++ Enter configuration settings in [.filename]#/etc/rc.conf#. This is much like configuring a full computer. The host name and IP address are not set here. diff --git a/documentation/content/en/books/handbook/mail/_index.adoc b/documentation/content/en/books/handbook/mail/_index.adoc --- a/documentation/content/en/books/handbook/mail/_index.adoc +++ b/documentation/content/en/books/handbook/mail/_index.adoc @@ -728,14 +728,14 @@ .... saslauthd_enable="YES" .... -+ ++ Finally, start the saslauthd daemon: + [source,shell] .... # service saslauthd start .... -+ ++ This daemon serves as a broker for Sendmail to authenticate against the FreeBSD man:passwd[5] database. This saves the trouble of creating a new set of usernames and passwords for each user that needs to use SMTP authentication, and keeps the login and mail password the same. . Next, edit [.filename]#/etc/make.conf# and add the following lines: @@ -745,7 +745,7 @@ SENDMAIL_CFLAGS=-I/usr/local/include/sasl -DSASL SENDMAIL_LDADD=/usr/local/lib/libsasl2.so .... -+ ++ These lines provide Sendmail the proper configuration options for linking to package:cyrus-sasl2[] at compile time. Make sure that package:cyrus-sasl2[] has been installed before recompiling Sendmail. . Recompile Sendmail by executing the following commands: @@ -759,7 +759,7 @@ # cd /usr/src/usr.sbin/sendmail # make cleandir && make obj && make && make install .... -+ ++ This compile should not have any problems if [.filename]#/usr/src# has not changed extensively and the shared libraries it needs are available. . After Sendmail has been compiled and reinstalled, edit [.filename]#/etc/mail/freebsd.mc# or the local [.filename]#.mc#. Many administrators choose to use the output from man:hostname[1] as the name of [.filename]#.mc# for uniqueness. Add these lines: + @@ -769,7 +769,7 @@ TRUST_AUTH_MECH(`GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl .... -+ ++ These options configure the different methods available to Sendmail for authenticating users. To use a method other than pwcheck, refer to the Sendmail documentation. . Finally, run man:make[1] while in [.filename]#/etc/mail#. That will run the new [.filename]#.mc# and create a [.filename]#.cf# named either [.filename]#freebsd.cf# or the name used for the local [.filename]#.mc#. Then, run `make install restart`, which will copy the file to [.filename]#sendmail.cf#, and properly restart Sendmail. For more information about this process, refer to [.filename]#/etc/mail/Makefile#. diff --git a/documentation/content/en/books/handbook/network-servers/_index.adoc b/documentation/content/en/books/handbook/network-servers/_index.adoc --- a/documentation/content/en/books/handbook/network-servers/_index.adoc +++ b/documentation/content/en/books/handbook/network-servers/_index.adoc @@ -568,16 +568,16 @@ There are three types of hosts in an NIS environment: * NIS master server -+ ++ This server acts as a central repository for host configuration information and maintains the authoritative copy of the files used by all of the NIS clients. The [.filename]#passwd#, [.filename]#group#, and other various files used by NIS clients are stored on the master server. While it is possible for one machine to be an NIS master server for more than one NIS domain, this type of configuration will not be covered in this chapter as it assumes a relatively small-scale NIS environment. * NIS slave servers -+ ++ NIS slave servers maintain copies of the NIS master's data files in order to provide redundancy. Slave servers also help to balance the load of the master server as NIS clients always attach to the NIS server which responds first. * NIS clients -+ ++ NIS clients authenticate against the NIS server during log on. Information in many files can be shared using NIS. @@ -884,7 +884,7 @@ .... +::::::::: .... -+ ++ This line configures the client to provide anyone with a valid account in the NIS server's password maps an account on the client. There are many ways to configure the NIS client by modifying this line. One method is described in <>. @@ -1767,19 +1767,19 @@ The DHCP client uses the following files: * [.filename]#/etc/dhclient.conf# -+ ++ The configuration file used by `dhclient`. Typically, this file contains only comments as the defaults are suitable for most clients. This configuration file is described in man:dhclient.conf[5]. * [.filename]#/sbin/dhclient# -+ ++ More information about the command itself can be found in man:dhclient[8]. * [.filename]#/sbin/dhclient-script# -+ ++ The FreeBSD-specific DHCP client configuration script. It is described in man:dhclient-script[8], but should not need any user modification to function properly. * [.filename]#/var/db/dhclient.leases.interface# -+ ++ The DHCP client keeps a database of valid leases in this file, which is written as a log and is described in man:dhclient.leases[5]. @@ -1853,18 +1853,18 @@ Note that the manual pages are installed with the server software. * [.filename]#/usr/local/sbin/dhcpd# -+ ++ More information about the dhcpd server can be found in dhcpd(8). * [.filename]#/usr/local/etc/dhcpd.conf# -+ ++ The server configuration file needs to contain all the information that should be provided to clients, along with information regarding the operation of the server. This configuration file is described in dhcpd.conf(5). * [.filename]#/var/db/dhcpd.leases# -+ ++ The DHCP server keeps a database of leases it has issued in this file, which is written as a log. Refer to dhcpd.leases(5), which gives a slightly longer description. * [.filename]#/usr/local/sbin/dhcrelay# -+ ++ This daemon is used in advanced environments where one DHCP server forwards a request from a client to another DHCP server on a separate network. If this functionality is required, install the package:net/isc-dhcp43-relay[] package or port. The installation includes dhcrelay(8) which provides more detail. diff --git a/documentation/content/en/books/handbook/ports/_index.adoc b/documentation/content/en/books/handbook/ports/_index.adoc --- a/documentation/content/en/books/handbook/ports/_index.adoc +++ b/documentation/content/en/books/handbook/ports/_index.adoc @@ -99,7 +99,7 @@ .Port Benefits * 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. * Some applications have compile-time options relating to which features are installed. For example, Apache can be configured with a wide variety of different built-in options. -+ ++ In some cases, multiple packages will exist for the same application to specify certain settings. For example, Ghostscript is available as a [.filename]#ghostscript# package and a [.filename]#ghostscript-nox11# package, depending on whether or not Xorg is installed. Creating multiple packages rapidly becomes impossible if an application has more than one or two different compile-time options. * The licensing conditions of some software forbid binary distribution. Such software must be distributed as source code which must be compiled by the end-user. * Some people do not trust binary distributions or prefer to read through source code in order to look for potential problems. @@ -141,7 +141,7 @@ subversion16-1.6.23_4 subversion17-1.7.16_2 .... -+ ++ Package names include the version number and, in the case of ports based on python, the version number of the version of python the package was built with. Some ports also have multiple versions available. In the case of Subversion, there are different versions available, as well as different compile options. @@ -164,7 +164,7 @@ devel/subversion-book devel/subversion-static .... -+ ++ Searching by shell globs, regular expressions, exact match, by description, or any other field in the repository database is also supported by `pkg search`. After installing package:ports-mgmt/pkg[] or package:ports-mgmt/pkg-devel[], see man:pkg-search[8] for more details. * If the Ports Collection is already installed, there are several methods to query the local version of the ports tree. To find out which category a port is in, type `whereis _file_`, where _file_ is the program to be installed: @@ -174,7 +174,7 @@ # whereis lsof lsof: /usr/ports/sysutils/lsof .... -+ ++ Alternately, an man:echo[1] statement can be used: + [source,shell] @@ -182,7 +182,7 @@ # echo /usr/ports/*/*lsof* /usr/ports/sysutils/lsof .... -+ ++ Note that this will also return any matched files downloaded into the [.filename]#/usr/ports/distfiles# directory. * Another way to find software is by using the Ports Collection's built-in search mechanism. To use the search feature, cd to [.filename]#/usr/ports# then run `make search name=program-name` where _program-name_ is the name of the software. For example, to search for `lsof`: + @@ -205,9 +205,9 @@ If a message indicates that the [.filename]#INDEX# is required, run `make fetchindex` to download the current index file. With the [.filename]#INDEX# present, `make search` will be able to perform the requested search. ==== -+ ++ The "Path:" line indicates where to find the port. -+ ++ To receive less information, use the `quicksearch` feature: + [source,shell] @@ -218,10 +218,10 @@ Path: /usr/ports/sysutils/lsof Info: Lists information about open files (similar to fstat(1)) .... -+ ++ For more in-depth searching, use `make search key=_string_` or `make quicksearch key=_string_`, where _string_ is some text to search for. The text can be in comments, descriptions, or dependencies in order to find ports which relate to a particular subject when the name of the program is unknown. -+ ++ When using `search` or `quicksearch`, the search string is case-insensitive. Searching for "LSOF" will yield the same results as searching for "lsof". @@ -716,7 +716,7 @@ # cd /usr/ports/devel/git # make install clean .... -+ ++ If the ports tree is not available, or pkg is being used to manage packages, Git can be installed as a package: + [source,shell] @@ -1325,7 +1325,7 @@ In particular, ports maintained by mailto:ports@FreeBSD.org[ports@FreeBSD.org] are not maintained by a specific individual. Instead, any fixes and support come from the general community who subscribe to that mailing list. More volunteers are always needed! ==== -+ ++ If there is no response to the email, use Bugzilla to submit a bug report using the instructions in link:{problem-reports}[Writing FreeBSD Problem Reports]. . Fix it! The link:{porters-handbook}[Porter's Handbook] includes detailed information on the ports infrastructure so that you can fix the occasional broken port or even submit your own! . Install the package instead of the port using the instructions in <>. diff --git a/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc b/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc --- a/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc +++ b/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc @@ -83,7 +83,7 @@ * The IP address of the default gateway. If this information is unknown, the ISP will automatically provide the correct value during connection setup. When configuring PPP on FreeBSD, this address is referred to as `HISADDR`. * The subnet mask. If the ISP has not provided one, `255.255.255.255` will be used in the man:ppp[8] configuration file. * -+ ++ If the ISP has assigned a static IP address and hostname, it should be input into the configuration file. Otherwise, this information will be automatically provided during connection setup. The rest of this section demonstrates how to configure FreeBSD for common PPP connection scenarios. diff --git a/documentation/content/en/books/handbook/printing/_index.adoc b/documentation/content/en/books/handbook/printing/_index.adoc --- a/documentation/content/en/books/handbook/printing/_index.adoc +++ b/documentation/content/en/books/handbook/printing/_index.adoc @@ -101,7 +101,7 @@ .... lpd_enable="YES" .... -+ ++ Start the service: + [source,shell] @@ -121,7 +121,7 @@ ==== If both lines do not start at the left border, but "stairstep" instead, see <>. ==== -+ ++ Text files can now be printed with `lpr`. Give the filename on the command line, or pipe output directly into `lpr`. + diff --git a/documentation/content/en/books/handbook/serialcomms/_index.adoc b/documentation/content/en/books/handbook/serialcomms/_index.adoc --- a/documentation/content/en/books/handbook/serialcomms/_index.adoc +++ b/documentation/content/en/books/handbook/serialcomms/_index.adoc @@ -1005,16 +1005,16 @@ [.procedure] .Procedure: Configuring a Serial Console . Prepare a serial cable. -+ ++ Use either a null-modem cable or a standard serial cable and a null-modem adapter. See <> for a discussion on serial cables. . Unplug the keyboard. -+ ++ Many 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 will refuse to boot until the keyboard is plugged in. -+ ++ If the computer complains about the error, but boots anyway, no further configuration is needed. -+ ++ If the computer refuses to boot without a keyboard attached, configure the BIOS so that it ignores this error. Consult the motherboard's manual for details on how to do this. + @@ -1025,7 +1025,7 @@ If that option is not present in the BIOS, look for an "Halt on Error" option instead. Setting this to "All but Keyboard" or to "No Errors" will have the same effect. ==== -+ ++ If the system has a PS/2(R) mouse, unplug it as well. PS/2(R) 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. + @@ -1041,7 +1041,7 @@ . Plug a dumb terminal, an old computer with a modem program, or the serial port on another UNIX(R) box into the serial port. . Add the appropriate `hint.sio.*` entries to [.filename]#/boot/device.hints# for the serial port. Some multi-port cards also require kernel configuration options. Refer to man:sio[4] for the required options and device hints for each supported serial port. . Create [.filename]#boot.config# in the root directory of the `a` partition on the boot drive. -+ ++ 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: @@ -1069,15 +1069,15 @@ Keyboards on some laptops may not be properly found because of this limitation. If this is the case, do not use `-P`. ==== -+ ++ Use either `-P` to select the console automatically or `-h` to activate the serial console. Refer to man:boot[8] and man:boot.config[5] for more details. -+ ++ The options, except for `-P`, 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 `-h`. This means that if `-D` is specified but `-h` is not specified in [.filename]#/boot.config#, 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. . Boot the machine. -+ ++ When FreeBSD starts, the boot blocks echo the contents of [.filename]#/boot.config# to the console. For example: + [source,shell] @@ -1085,7 +1085,7 @@ /boot.config: -P Keyboard: no .... -+ ++ The second line appears only if `-P` is in [.filename]#/boot.config# 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#: + @@ -1113,10 +1113,10 @@ |`-P`, keyboard absent |serial console |=== -+ ++ 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. -+ ++ Press any key, other than kbd:[Enter], at the console to interrupt the boot process. The boot blocks will then prompt for further action: + @@ -1126,10 +1126,10 @@ Default: 0:ad(0,a)/boot/loader boot: .... -+ ++ Verify that the above message appears on either the serial or internal console, or both, according to the options in [.filename]#/boot.config#. If the message appears in the correct console, press kbd:[Enter] to continue the boot process. -+ ++ If there is no prompt on the serial terminal, something is wrong with the settings. Enter `-h` then kbd:[Enter] or kbd:[Return] 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. @@ -1176,7 +1176,7 @@ # make # make install .... -+ ++ If the serial console is configured in some other way than by booting with `-h`, or if the serial console used by the kernel is different from the one used by the boot blocks, add the following option, with the desired speed, to a custom kernel configuration file and compile a new kernel: + [.programlisting] diff --git a/documentation/content/en/books/handbook/virtualization/_index.adoc b/documentation/content/en/books/handbook/virtualization/_index.adoc --- a/documentation/content/en/books/handbook/virtualization/_index.adoc +++ b/documentation/content/en/books/handbook/virtualization/_index.adoc @@ -131,7 +131,7 @@ [.procedure] . Set Boot Loader Variables -+ ++ The most important step is to reduce the `kern.hz` tunable to reduce the CPU utilization of FreeBSD under the Parallels environment. This is accomplished by adding the following line to [.filename]#/boot/loader.conf#: + @@ -139,15 +139,15 @@ .... kern.hz=100 .... -+ ++ Without this setting, an idle FreeBSD Parallels guest will use roughly 15% of the CPU of a single processor iMac(R). After this change the usage will be closer to 5%. . Create a New Kernel Configuration File -+ ++ All of the SCSI, FireWire, and USB device drivers can be removed from a custom kernel configuration file. Parallels 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. . Configure Networking -+ ++ The most basic networking setup uses DHCP to connect the virtual machine to the same local area network as the host Mac(R). This can be accomplished by adding `ifconfig_ed0="DHCP"` to [.filename]#/etc/rc.conf#. More advanced networking setups are described in crossref:advanced-networking[advanced-networking,Advanced Networking]. @@ -222,7 +222,7 @@ [.procedure] . Set Boot Loader Variables -+ ++ The most important step is to reduce the `kern.hz` tunable to reduce the CPU utilization of FreeBSD under the Virtual PC environment. This is accomplished by adding the following line to [.filename]#/boot/loader.conf#: + @@ -230,15 +230,15 @@ .... kern.hz=100 .... -+ ++ Without this setting, an idle FreeBSD Virtual PC guest OS will use roughly 40% of the CPU of a single processor computer. After this change, the usage will be closer to 3%. . Create a New Kernel Configuration File -+ ++ All of the SCSI, FireWire, and USB device drivers can be removed from a custom kernel configuration file. Virtual PC 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. . Configure Networking -+ ++ The most basic networking setup uses DHCP to connect the virtual machine to the same local area network as the Microsoft(R) Windows(R) host. This can be accomplished by adding `ifconfig_de0="DHCP"` to [.filename]#/etc/rc.conf#. More advanced networking setups are described in crossref:advanced-networking[advanced-networking,Advanced Networking]. @@ -320,7 +320,7 @@ [.procedure] . Set Boot Loader Variables -+ ++ The most important step is to reduce the `kern.hz` tunable to reduce the CPU utilization of FreeBSD under the VMware Fusion environment. This is accomplished by adding the following line to [.filename]#/boot/loader.conf#: + @@ -328,15 +328,15 @@ .... kern.hz=100 .... -+ ++ Without this setting, an idle FreeBSD VMware Fusion guest will use roughly 15% of the CPU of a single processor iMac(R). After this change, the usage will be closer to 5%. . Create a New Kernel Configuration File -+ ++ All of the FireWire, and USB device drivers can be removed from a custom kernel configuration file. VMware Fusion provides a virtual network adapter used by the man:em[4] driver, so all network devices except for man:em[4] can be removed from the kernel. . Configure Networking -+ ++ The most basic networking setup uses DHCP to connect the virtual machine to the same local area network as the host Mac(R). This can be accomplished by adding `ifconfig_em0="DHCP"` to [.filename]#/etc/rc.conf#. More advanced networking setups are described in crossref:advanced-networking[advanced-networking,Advanced Networking]. diff --git a/documentation/content/en/books/handbook/zfs/_index.adoc b/documentation/content/en/books/handbook/zfs/_index.adoc --- a/documentation/content/en/books/handbook/zfs/_index.adoc +++ b/documentation/content/en/books/handbook/zfs/_index.adoc @@ -2639,16 +2639,16 @@ * [[zfs-advanced-tuning-arc_min]] `_vfs.zfs.arc_min_` - Minimum size of the <>. The default is one half of `vfs.zfs.arc_meta_limit`. Adjust this value to prevent other applications from pressuring out the entire <>. This value can be adjusted at runtime with man:sysctl[8] and can be set in [.filename]#/boot/loader.conf# or [.filename]#/etc/sysctl.conf#. * [[zfs-advanced-tuning-vdev-cache-size]] `_vfs.zfs.vdev.cache.size_` - A preallocated amount of memory reserved as a cache for each device in the pool. The total amount of memory used will be this value multiplied by the number of devices. This value can only be adjusted at boot time, and is set in [.filename]#/boot/loader.conf#. * [[zfs-advanced-tuning-min-auto-ashift]] `_vfs.zfs.min_auto_ashift_` - Minimum `ashift` (sector size) that will be used automatically at pool creation time. The value is a power of two. The default value of `9` represents `2^9 = 512`, a sector size of 512 bytes. To avoid _write amplification_ and get the best performance, set this value to the largest sector size used by a device in the pool. -+ ++ Many drives have 4 KB sectors. Using the default `ashift` of `9` with these drives results in write amplification on these devices. Data that could be contained in a single 4 KB write must instead be written in eight 512-byte writes. ZFS tries to read the native sector size from all devices when creating a pool, but many drives with 4 KB sectors report that their sectors are 512 bytes for compatibility. Setting `vfs.zfs.min_auto_ashift` to `12` (`2^12 = 4096`) before creating a pool forces ZFS to use 4 KB blocks for best performance on these drives. -+ ++ Forcing 4 KB blocks is also useful on pools where disk upgrades are planned. Future disks are likely to use 4 KB sectors, and `ashift` values cannot be changed after a pool is created. -+ ++ In some specific cases, the smaller 512-byte block size might be preferable. When used with 512-byte disks for databases, or as storage for virtual machines, less data is transferred during small random reads. This can provide better performance, especially when using a smaller ZFS record size. @@ -2752,11 +2752,11 @@ ==== * [[zfs-term-vdev-raidz]] _RAID-Z_ - ZFS implements RAID-Z, a variation on standard RAID-5 that offers better distribution of parity and eliminates the "RAID-5 write hole" in which the data and parity information become inconsistent after an unexpected restart. ZFS supports three levels of RAID-Z which provide varying levels of redundancy in exchange for decreasing levels of usable storage. The types are named RAID-Z1 through RAID-Z3 based on the number of parity devices in the array and the number of disks which can fail while the pool remains operational. -+ ++ In a RAID-Z1 configuration with four disks, each 1 TB, usable storage is 3 TB and the pool will still be able to operate in degraded mode with one faulted disk. If an additional disk goes offline before the faulted disk is replaced and resilvered, all data in the pool can be lost. -+ ++ In a RAID-Z3 configuration with eight disks of 1 TB, the volume will provide 5 TB of usable space and still be able to operate with three faulted disks. Sun(TM) recommends no more than nine disks in a single vdev. If the configuration has more disks, it is recommended to divide them into separate vdevs and the pool data will be striped across them. -+ ++ A configuration of two RAID-Z2 vdevs consisting of 8 disks each would create something similar to a RAID-60 array. A RAID-Z group's storage capacity is approximately the size of the smallest disk multiplied by the number of non-parity disks. Four 1 TB disks in RAID-Z1 has an effective size of approximately 3 TB, and an array of eight 1 TB disks in RAID-Z3 will yield 5 TB of usable space. * [[zfs-term-vdev-spare]] _Spare_ - ZFS has a special pseudo-vdev type for keeping track of available hot spares. Note that installed hot spares are not deployed automatically; they must manually be configured to replace the failed device using `zfs replace`. * [[zfs-term-vdev-log]] _Log_ - ZFS Log Devices, also known as ZFS Intent Log (<>) move the intent log from the regular pool devices to a dedicated device, typically an SSD. Having a dedicated log device can significantly improve the performance of applications with a high volume of synchronous writes, especially databases. Log devices can be mirrored, but RAID-Z is not supported. If multiple log devices are used, writes will be load balanced across them. diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc --- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc +++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc @@ -2039,15 +2039,15 @@ Okay, so the previous example did not reflect the new port's needs? In this section we will explain in detail how the fine grained fetching mechanism `MASTER_SITES:n` works and how it can be used. . Elements can be postfixed with `:__n__` where _n_ is `[^:,]+`, that is, _n_ could conceptually be any alphanumeric string but we will limit it to `[a-zA-Z_][0-9a-zA-Z_]+` for now. -+ ++ Moreover, string matching is case sensitive; that is, `n` is different from `N`. -+ ++ However, these words cannot be used for postfixing purposes since they yield special meaning: `default`, `all` and `ALL` (they are used internally in item <>). Furthermore, `DEFAULT` is a special purpose word (check item <>). . Elements postfixed with `:n` belong to the group `n`, `:m` belong to group `m` and so forth. + [[porting-master-sites-n-DEFAULT-group]] . Elements without a postfix are groupless, they all belong to the special group `DEFAULT`. Any elements postfixed with `DEFAULT`, is just being redundant unless an element belongs to both `DEFAULT` and other groups at the same time (check item <>). -+ ++ These examples are equivalent but the first one is preferred: + [.programlisting] @@ -2064,9 +2064,9 @@ + [[porting-master-sites-n-comma-operator]] . When an element belongs to several groups at the same time, use the comma operator (`,`). -+ ++ 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, `:m,n,o` marks an element that belongs to group `m`, `n` and `o`. -+ ++ All these examples are equivalent but the last one is preferred: + [.programlisting] @@ -2183,7 +2183,7 @@ ==== . How do I group one of the special macros from [.filename]#bsd.sites.mk#, for example, SourceForge (`SF`)? -+ ++ This has been simplified as much as possible. See <>. + [[ports-master-sites-n-example-detailed-use-master-site-sourceforge]] @@ -2200,7 +2200,7 @@ [.filename]#something.tar.gz# will be fetched from all sites within SourceForge. ==== . How do I use this with `PATCH*`? -+ ++ All examples were done with `MASTER*` but they work exactly the same for `PATCH*` ones as can be seen in <>. + [[ports-master-sites-n-example-detailed-use-patch-sites]] @@ -2228,7 +2228,7 @@ ** `do-fetch`: deploys the new grouping postfixed `DISTFILES` and `PATCHFILES` with their matching group elements within both `MASTER_SITES` and `PATCH_SITES` which use matching group elements within both `MASTER_SITE_SUBDIR` and `PATCH_SITE_SUBDIR`. Check <>. ** `fetch-list`: works like old `fetch-list` with the exception that it groups just like `do-fetch`. ** `master-sites` and `patch-sites`: (incompatible with older versions) only return the elements of group `DEFAULT`; in fact, they execute targets `master-sites-default` and `patch-sites-default` respectively. -+ ++ Furthermore, using target either `master-sites-all` or `patch-sites-all` is preferred to directly checking either `MASTER_SITES` or `PATCH_SITES`. Also, directly checking is not guaranteed to work in any future versions. Check item <> for more information on these new port targets. . New port targets diff --git a/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc b/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc --- a/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc +++ b/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc @@ -270,9 +270,9 @@ === Variables * `BROKEN` is reserved for ports that currently do not compile, install, deinstall, or run correctly. Use it for ports where the problem is believed to be temporary. -+ ++ 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.) -+ ++ For instance, use `BROKEN` when a port: ** does not compile @@ -361,7 +361,7 @@ .... NOT_FOR_ARCHS= ia64 sparc64 .... -+ ++ A custom `IGNORE` message can be set using `ONLY_FOR_ARCHS_REASON` and `NOT_FOR_ARCHS_REASON`. Per architecture entries are possible with `ONLY_FOR_ARCHS_REASON_ARCH` and `NOT_FOR_ARCHS_REASON_ARCH`. [[dads-arch-i386]] @@ -371,7 +371,7 @@ === Cluster-Specific Considerations * Some ports attempt to tune themselves to the exact machine they are being built on by specifying `-march=native` to the compiler. This should be avoided: either list it under an off-by-default option, or delete it entirely. -+ ++ Otherwise, the default package produced by the build cluster might not run on every single machine of that `ARCH`. [[dads-deprecated]] diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc --- a/documentation/content/en/books/porters-handbook/special/_index.adoc +++ b/documentation/content/en/books/porters-handbook/special/_index.adoc @@ -4247,7 +4247,7 @@ .... # service name stop .... -+ ++ will probably not work properly. See man:service[8] for more information. . Have all occurrences of [.filename]#/usr/local# been replaced with `%%PREFIX%%`? . Do the default variable assignments come after `load_rc_config`?