diff options
Diffstat (limited to 'documentation/content/en/articles')
77 files changed, 55176 insertions, 1777 deletions
diff --git a/documentation/content/en/articles/_index.po b/documentation/content/en/articles/_index.po new file mode 100644 index 0000000000..42a0aa133d --- /dev/null +++ b/documentation/content/en/articles/_index.po @@ -0,0 +1,29 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2022-01-08 11:34-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: Title = +#: documentation/content/en/articles/_index.adoc:1 +#: documentation/content/en/articles/_index.adoc:6 +#, no-wrap +msgid "Articles" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/_index.adoc:8 +msgid "{{< list-articles-directories >}}" +msgstr "" diff --git a/documentation/content/en/articles/bsdl-gpl/_index.po b/documentation/content/en/articles/bsdl-gpl/_index.po new file mode 100644 index 0000000000..54a98693aa --- /dev/null +++ b/documentation/content/en/articles/bsdl-gpl/_index.po @@ -0,0 +1,780 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2022-02-01 09:21-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: Title = +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:1 +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:11 +#, no-wrap +msgid "Why you should use a BSD style license for your Open Source Project" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:43 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:47 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:52 +msgid "" +"This document makes a case for using a BSD style license for software and " +"data; specifically it recommends using a BSD style license in place of the " +"GPL. It can also be read as a BSD versus GPL Open Source License " +"introduction and summary." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:54 +#, no-wrap +msgid "Very Brief Open Source History" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:60 +msgid "" +"Long before the term \"Open Source\" was used, software was developed by " +"loose associations of programmers and freely exchanged. Starting in the " +"early 1950's, organizations such as http://www.share.org[SHARE] and http://" +"www.decus.org[DECUS] developed much of the software that computer hardware " +"companies bundled with their hardware offerings. At that time computer " +"companies were in the hardware business; anything that reduced software cost " +"and made more programs available made the hardware companies more " +"competitive." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:67 +msgid "" +"This model changed in the 1960's. In 1965 ADR developed the first licensed " +"software product independent of a hardware company. ADR was competing " +"against a free IBM package originally developed by IBM customers. ADR " +"patented their software in 1968. To stop sharing of their program, they " +"provided it under an equipment lease in which payment was spread over the " +"lifetime of the product. ADR thus retained ownership and could control " +"resale and reuse." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:70 +msgid "" +"In 1969 the US Department of Justice charged IBM with destroying businesses " +"by bundling free software with IBM hardware. As a result of this suit, IBM " +"unbundled its software; that is, software became independent products " +"separate from hardware." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:75 +msgid "" +"In 1968 Informatics introduced the first commercial killer-app and rapidly " +"established the concept of the software product, the software company, and " +"very high rates of return. Informatics developed the perpetual license " +"which is now standard throughout the computer industry, wherein ownership is " +"never transferred to the customer." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:77 +#, no-wrap +msgid "Unix from a BSD Licensing Perspective" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:83 +msgid "" +"AT&T, who owned the original Unix implementation, was a publicly regulated " +"monopoly tied up in anti-trust court; it was legally unable to sell a " +"product into the software market. It was, however, able to provide it to " +"academic institutions for the price of media." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:89 +msgid "" +"Universities rapidly adopted Unix after an OS conference publicized its " +"availability. It was extremely helpful that Unix ran on the PDP-11, a very " +"affordable 16-bit computer, and was coded in a high-level language that was " +"demonstrably good for systems programming. The DEC PDP-11 had, in effect, " +"an open hardware interface designed to make it easy for customers to write " +"their own OS, which was common. As DEC founder Ken Olsen famously " +"proclaimed, \"software comes from heaven when you have good hardware\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:95 +msgid "" +"Unix author Ken Thompson returned to his alma mater, University of " +"California Berkeley (UCB), in 1975 and taught the kernel line-by-line. This " +"ultimately resulted in an evolving system known as BSD (Berkeley Standard " +"Distribution). UCB converted Unix to 32-bits, added virtual memory, and " +"implemented the version of the TCP/IP stack upon which the Internet was " +"essentially built. UCB made BSD available for the cost of media, under what " +"became known as \"the BSD license\". A customer purchased Unix from AT&T " +"and then ordered a BSD tape from UCB." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:99 +msgid "" +"In the mid-1980s a government anti-trust case against AT&T ended with the " +"break-up of AT&T. AT&T still owned Unix and was now able to sell it. AT&T " +"embarked on an aggressive licensing effort and most commercial Unixes of the " +"day became AT&T-derived." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:105 +msgid "" +"In the early 1990's AT&T sued UCB over license violations related to BSD. " +"UCB discovered that AT&T had incorporated, without acknowledgment or " +"payment, many improvements due to BSD into AT&T's products, and a lengthy " +"court case, primarily between AT&T and UCB, ensued. During this period some " +"UCB programmers embarked on a project to rewrite any AT&T code associated " +"with BSD. This project resulted in a system called BSD 4.4-lite (lite " +"because it was not a complete system; it lacked 6 key AT&T files)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:109 +msgid "" +"A lengthy series of articles published slightly later in Dr. Dobbs magazine " +"described a BSD-derived 386 PC version of Unix, with BSD-licensed " +"replacement files for the 6 missing 4.4 lite files. This system, named " +"386BSD, was due to ex-UCB programmer William Jolitz. It became the original " +"basis of all the PC BSDs in use today." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:112 +msgid "" +"In the mid 1990s, Novell purchased AT&T's Unix rights and a (then secret) " +"agreement was reached to terminate the lawsuit. UCB soon terminated its " +"support for BSD." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:114 +#, no-wrap +msgid "The Current State of FreeBSD and BSD Licenses" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:120 +msgid "" +"The so-called http://www.opensource.org/licenses/bsd-license.php[new BSD " +"license] applied to FreeBSD within the last few years is effectively a " +"statement that you can do anything with the program or its source, but you " +"do not have any warranty and none of the authors has any liability " +"(basically, you cannot sue anybody). This new BSD license is intended to " +"encourage product commercialization. Any BSD code can be sold or included " +"in proprietary products without any restrictions on the availability of your " +"code or your future behavior." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:123 +msgid "" +"Do not confuse the new BSD license with \"public domain\". While an item in " +"the public domain is also free for all to use, it has no owner." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:125 +#, no-wrap +msgid "The origins of the GPL" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:129 +msgid "" +"While the future of Unix had been so muddled in the late 1980s and early " +"1990s, the GPL, another development with important licensing considerations, " +"reached fruition." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:138 +msgid "" +"Richard Stallman, the developer of Emacs, was a member of the staff at MIT " +"when his lab switched from home-grown to proprietary systems. Stallman " +"became upset when he found that he could not legally add minor improvements " +"to the system. (Many of Stallman's co-workers had left to form two " +"companies based on software developed at MIT and licensed by MIT; there " +"appears to have been disagreement over access to the source code for this " +"software). Stallman devised an alternative to the commercial software " +"license and called it the GPL, or \"GNU Public License\". He also started a " +"non-profit foundation, the http://www.fsf.org[Free Software Foundation] " +"(FSF), which intended to develop an entire operating system, including all " +"associated software, that would not be subject to proprietary licensing. " +"This system was called GNU, for \"GNU is Not Unix\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:143 +msgid "" +"The GPL was designed to be the antithesis of the standard proprietary " +"license. To this end, any modifications that were made to a GPL program " +"were required to be given back to the GPL community (by requiring that the " +"source of the program be available to the user) and any program that used or " +"linked to GPL code was required to be under the GPL. The GPL was intended " +"to keep software from becoming proprietary. As the last paragraph of the " +"GPL states:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:145 +msgid "" +"\"This General Public License does not permit incorporating your program " +"into proprietary programs.\"<<one>>" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:147 +msgid "" +"The http://www.opensource.org/licenses/gpl-license.php[GPL] is a complex " +"license so here are some rules of thumb when using the GPL:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:149 +msgid "" +"you can charge as much as you want for distributing, supporting, or " +"documenting the software, but you cannot sell the software itself." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:150 +msgid "" +"the rule-of-thumb states that if GPL source is required for a program to " +"compile, the program must be under the GPL. Linking statically to a GPL " +"library requires a program to be under the GPL." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:151 +msgid "" +"the GPL requires that any patents associated with GPLed software must be " +"licensed for everyone's free use." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:152 +msgid "" +"simply aggregating software together, as when multiple programs are put on " +"one disk, does not count as including GPLed programs in non-GPLed programs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:153 +msgid "" +"output of a program does not count as a derivative work. This enables the " +"gcc compiler to be used in commercial environments without legal problems." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:154 +msgid "" +"since the Linux kernel is under the GPL, any code statically linked with the " +"Linux kernel must be GPLed. This requirement can be circumvented by " +"dynamically linking loadable kernel modules. This permits companies to " +"distribute binary drivers, but often has the disadvantage that they will " +"only work for particular versions of the Linux kernel." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:157 +msgid "" +"Due in part to its complexity, in many parts of the world today the " +"legalities of the GPL are being ignored in regard to Linux and related " +"software. The long-term ramifications of this are unclear." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:159 +#, no-wrap +msgid "The origins of Linux and the LGPL" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:164 +msgid "" +"While the commercial Unix wars raged, the Linux kernel was developed as a PC " +"Unix clone. Linus Torvalds credits the existence of the GNU C compiler and " +"the associated GNU tools for the existence of Linux. He put the Linux " +"kernel under the GPL." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:173 +msgid "" +"Remember that the GPL requires anything that statically links to any code " +"under the GPL also be placed under the GPL. The source for this code must " +"thus be made available to the user of the program. Dynamic linking, " +"however, is not considered a violation of the GPL. Pressure to put " +"proprietary applications on Linux became overwhelming. Such applications " +"often must link with system libraries. This resulted in a modified version " +"of the GPL called the http://www.opensource.org/licenses/lgpl-license." +"php[LGPL] (\"Library\", since renamed to \"Lesser\", GPL). The LGPL allows " +"proprietary code to be linked to the GNU C library, glibc. You do not have " +"to release the source code which has been dynamically linked to an LGPLed " +"library." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:177 +msgid "" +"If you statically link an application with glibc, such as is often required " +"in embedded systems, you cannot keep your application proprietary, that is, " +"the source must be released. Both the GPL and LGPL require any " +"modifications to the code directly under the license to be released." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:179 +#, no-wrap +msgid "Open Source licenses and the Orphaning Problem" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:184 +msgid "" +"One of the serious problems associated with proprietary software is known as " +"\"orphaning\". This occurs when a single business failure or change in a " +"product strategy causes a huge pyramid of dependent systems and companies to " +"fail for reasons beyond their control. Decades of experience have shown " +"that the momentary size or success of a software supplier is no guarantee " +"that their software will remain available, as current market conditions and " +"strategies can change rapidly." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:186 +msgid "" +"The GPL attempts to prevent orphaning by severing the link to proprietary " +"intellectual property." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:191 +msgid "" +"A BSD license gives a small company the equivalent of software-in-escrow " +"without any legal complications or costs. If a BSD-licensed program becomes " +"orphaned, a company can simply take over, in a proprietary manner, the " +"program on which they are dependent. An even better situation occurs when a " +"BSD code-base is maintained by a small informal consortium, since the " +"development process is not dependent on the survival of a single company or " +"product line. The survivability of the development team when they are " +"mentally in the zone is much more important than simple physical " +"availability of the source code." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:193 +#, no-wrap +msgid "What a license cannot do" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:197 +msgid "" +"No license can guarantee future software availability. Although a copyright " +"holder can traditionally change the terms of a copyright at anytime, the " +"presumption in the BSD community is that such an attempt simply causes the " +"source to fork." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:203 +msgid "" +"The GPL explicitly disallows revoking the license. It has occurred, " +"however, that a company (Mattel) purchased a GPL copyright (cphack), revoked " +"the entire copyright, went to court, and prevailed <<two>>. That is, they " +"legally revoked the entire distribution and all derivative works based on " +"the copyright. Whether this could happen with a larger and more dispersed " +"distribution is an open question; there is also some confusion regarding " +"whether the software was really under the GPL." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:208 +msgid "" +"In another example, Red Hat purchased Cygnus, an engineering company that " +"had taken over development of the FSF compiler tools. Cygnus was able to do " +"so because they had developed a business model in which they sold support " +"for GNU software. This enabled them to employ some 50 engineers and drive " +"the direction of the programs by contributing the preponderance of " +"modifications. As Donald Rosenberg states \"projects using licenses like " +"the GPL...live under constant threat of having someone take over the project " +"by producing a better version of the code and doing it faster than the " +"original owners.\" <<three>>" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:210 +#, no-wrap +msgid "GPL Advantages and Disadvantages" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:214 +msgid "" +"A common reason to use the GPL is when modifying or extending the gcc " +"compiler. This is particularly apt when working with one-off specialty CPUs " +"in environments where all software costs are likely to be considered " +"overhead, with minimal expectations that others will use the resulting " +"compiler." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:217 +msgid "" +"The GPL is also attractive to small companies selling CDs in an environment " +"where \"buy-low, sell-high\" may still give the end-user a very inexpensive " +"product. It is also attractive to companies that expect to survive by " +"providing various forms of technical support, including documentation, for " +"the GPLed intellectual property world." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:220 +msgid "" +"A less publicized and unintended use of the GPL is that it is very favorable " +"to large companies that want to undercut software companies. In other " +"words, the GPL is well suited for use as a marketing weapon, potentially " +"reducing overall economic benefit and contributing to monopolistic behavior." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:223 +msgid "" +"The GPL can present a real problem for those wishing to commercialize and " +"profit from software. For example, the GPL adds to the difficulty a " +"graduate student will have in directly forming a company to commercialize " +"his research results, or the difficulty a student will have in joining a " +"company on the assumption that a promising research project will be " +"commercialized." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:228 +msgid "" +"For those who must work with statically-linked implementations of multiple " +"software standards, the GPL is often a poor license, because it precludes " +"using proprietary implementations of the standards. The GPL thus minimizes " +"the number of programs that can be built using a GPLed standard. The GPL " +"was intended to not provide a mechanism to develop a standard on which one " +"engineers proprietary products. (This does not apply to Linux applications " +"because they do not statically link, rather they use a trap-based API.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:232 +msgid "" +"The GPL attempts to make programmers contribute to an evolving suite of " +"programs, then to compete in the distribution and support of this suite. " +"This situation is unrealistic for many required core system standards, which " +"may be applied in widely varying environments which require commercial " +"customization or integration with legacy standards under existing (non-GPL) " +"licenses. Real-time systems are often statically linked, so the GPL and " +"LGPL are definitely considered potential problems by many embedded systems " +"companies." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:235 +msgid "" +"The GPL is an attempt to keep efforts, regardless of demand, at the research " +"and development stages. This maximizes the benefits to researchers and " +"developers, at an unknown cost to those who would benefit from wider " +"distribution." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:239 +msgid "" +"The GPL was designed to keep research results from transitioning to " +"proprietary products. This step is often assumed to be the last step in the " +"traditional technology transfer pipeline and it is usually difficult enough " +"under the best of circumstances; the GPL was intended to make it impossible." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:241 +#, no-wrap +msgid "BSD Advantages" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:244 +msgid "" +"A BSD style license is a good choice for long duration research or other " +"projects that need a development environment that:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:246 +msgid "has near zero cost" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:247 +msgid "will evolve over a long period of time" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:248 +msgid "" +"permits anyone to retain the option of commercializing final results with " +"minimal legal issues." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:250 +msgid "" +"This final consideration may often be the dominant one, as it was when the " +"Apache project decided upon its license:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:254 +msgid "" +"\"This type of license is ideal for promoting the use of a reference body of " +"code that implements a protocol for common service. This is another reason " +"why we choose it for the Apache group - many of us wanted to see HTTP " +"survive and become a true multiparty standard, and would not have minded in " +"the slightest if Microsoft or Netscape choose to incorporate our HTTP engine " +"or any other component of our code into their products, if it helped further " +"the goal of keeping HTTP common... All this means that, strategically " +"speaking, the project needs to maintain sufficient momentum, and that " +"participants realize greater value by contributing their code to the " +"project, even code that would have had value if kept proprietary.\"" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:258 +msgid "" +"Developers tend to find the BSD license attractive as it keeps legal issues " +"out of the way and lets them do whatever they want with the code. In " +"contrast, those who expect primarily to use a system rather than program it, " +"or expect others to evolve the code, or who do not expect to make a living " +"from their work associated with the system (such as government employees), " +"find the GPL attractive, because it forces code developed by others to be " +"given to them and keeps their employer from retaining copyright and thus " +"potentially \"burying\" or orphaning the software. If you want to force " +"your competitors to help you, the GPL is attractive." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:265 +msgid "" +"A BSD license is not simply a gift. The question \"why should we help our " +"competitors or let them steal our work?\" comes up often in relation to a " +"BSD license. Under a BSD license, if one company came to dominate a product " +"niche that others considered strategic, the other companies can, with " +"minimal effort, form a mini-consortium aimed at reestablishing parity by " +"contributing to a competitive BSD variant that increases market competition " +"and fairness. This permits each company to believe that it will be able to " +"profit from some advantage it can provide, while also contributing to " +"economic flexibility and efficiency. The more rapidly and easily the " +"cooperating members can do this, the more successful they will be. A BSD " +"license is essentially a minimally complicated license that enables such " +"behavior." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:268 +msgid "" +"A key effect of the GPL, making a complete and competitive Open Source " +"system widely available at cost of media, is a reasonable goal. A BSD style " +"license, in conjunction with ad-hoc-consortiums of individuals, can achieve " +"this goal without destroying the economic assumptions built around the " +"deployment-end of the technology transfer pipeline." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:270 +#, no-wrap +msgid "Specific Recommendations for using a BSD license" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:275 +msgid "" +"The BSD license is preferable for transferring research results in a way " +"that will widely be deployed and most benefit an economy. As such, research " +"funding agencies, such as the NSF, ONR and DARPA, should encourage in the " +"earliest phases of funded research projects, the adoption of BSD style " +"licenses for software, data, results, and open hardware. They should also " +"encourage formation of standards based around implemented Open Source " +"systems and ongoing Open Source projects." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:277 +msgid "" +"Government policy should minimize the costs and difficulties in moving from " +"research to deployment. When possible, grants should require results to be " +"available under a commercialization friendly BSD style license." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:278 +msgid "" +"In many cases, the long-term results of a BSD style license more accurately " +"reflect the goals proclaimed in the research charter of universities than " +"what occurs when results are copyrighted or patented and subject to " +"proprietary university licensing. Anecdotal evidence exists that " +"universities are financially better rewarded in the long run by releasing " +"research results and then appealing to donations from commercially " +"successful alumni." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:279 +msgid "" +"Companies have long recognized that the creation of de facto standards is a " +"key marketing technique. The BSD license serves this role well, if a company " +"really has a unique advantage in evolving the system. The license is legally " +"attractive to the widest audience while the company's expertise ensures " +"their control. There are times when the GPL may be the appropriate vehicle " +"for an attempt to create such a standard, especially when attempting to " +"undermine or co-opt others. The GPL, however, penalizes the evolution of " +"that standard, because it promotes a suite rather than a commercially " +"applicable standard. Use of such a suite constantly raises commercialization " +"and legal issues. It may not be possible to mix standards when some are " +"under the GPL and others are not. A true technical standard should not " +"mandate exclusion of other standards for non-technical reasons." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:280 +msgid "" +"Companies interested in promoting an evolving standard, which can become the " +"core of other companies' commercial products, should be wary of the GPL. " +"Regardless of the license used, the resulting software will usually devolve " +"to whoever actually makes the majority of the engineering changes and most " +"understands the state of the system. The GPL simply adds more legal friction " +"to the result." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:281 +msgid "" +"Large companies, in which Open Source code is developed, should be aware " +"that programmers appreciate Open Source because it leaves the software " +"available to the employee when they change employers. Some companies " +"encourage this behavior as an employment perk, especially when the software " +"involved is not directly strategic. It is, in effect, a front-loaded " +"retirement benefit with potential lost opportunity costs but no direct " +"costs. Encouraging employees to work for peer acclaim outside the company is " +"a cheap portable benefit a company can sometimes provide with near zero " +"downside." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:282 +msgid "" +"Small companies with software projects vulnerable to orphaning should " +"attempt to use the BSD license when possible. Companies of all sizes should " +"consider forming such Open Source projects when it is to their mutual " +"advantage to maintain the minimal legal and organization overheads " +"associated with a true BSD-style Open Source project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:283 +msgid "" +"Non-profits should participate in Open Source projects when possible. To " +"minimize software engineering problems, such as mixing code under different " +"licenses, BSD-style licenses should be encouraged. Being leery of the GPL " +"should particularly be the case with non-profits that interact with the " +"developing world. In some locales where application of law becomes a costly " +"exercise, the simplicity of the new BSD license, as compared to the GPL, may " +"be of considerable advantage." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:285 +#, no-wrap +msgid "Conclusion" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:290 +msgid "" +"In contrast to the GPL, which is designed to prevent the proprietary " +"commercialization of Open Source code, the BSD license places minimal " +"restrictions on future behavior. This allows BSD code to remain Open Source " +"or become integrated into commercial solutions, as a project's or company's " +"needs change. In other words, the BSD license does not become a legal time-" +"bomb at any point in the development process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:292 +msgid "" +"In addition, since the BSD license does not come with the legal complexity " +"of the GPL or LGPL licenses, it allows developers and companies to spend " +"their time creating and promoting good code rather than worrying if that " +"code violates licensing." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:295 +#, no-wrap +msgid "Bibliographical References" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:298 +msgid "[[[one,1]]] http://www.gnu.org/licenses/gpl.html" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:300 +msgid "" +"[[[two,2]]] http://archives.cnn.com/2000/TECH/computing/03/28/cyberpatrol." +"mirrors/" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:302 +msgid "" +"[[[three,3]]] Open Source: the Unauthorized White Papers, Donald K. " +"Rosenberg, IDG Books, 2000. Quotes are from page 114, \"Effects of the GNU " +"GPL\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:304 +msgid "" +"[[[four,4]]] In the \"What License to Use?\" section of http://www.oreilly." +"com/catalog/opensources/book/brian.html" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:305 +msgid "" +"This whitepaper is a condensation of an original work available at http://" +"alumni.cse.ucsc.edu/~brucem/open_source_license.htm" +msgstr "" diff --git a/documentation/content/en/articles/building-products/_index.adoc b/documentation/content/en/articles/building-products/_index.adoc index 038feb9c07..4ace1173e8 100644 --- a/documentation/content/en/articles/building-products/_index.adoc +++ b/documentation/content/en/articles/building-products/_index.adoc @@ -62,7 +62,8 @@ toc::[] FreeBSD today is well-known as a high-performance server operating system. It is deployed on millions of web servers and internet-facing hosts worldwide. FreeBSD code also forms an integral part of many products, ranging from appliances such as network routers, firewalls, and storage devices, to personal computers. -Portions of FreeBSD have also been used in commercial shrink-wrapped software (see <<freebsd-intro>>). +Portions of FreeBSD have also been used in commercial shrink-wrapped software +(see crossref:building-products[freebsd-intro, FreeBSD as a set of building blocks]). In this article we look at the link:https://www.FreeBSD.org/[FreeBSD project] as a software engineering resource-as a collection of building blocks and processes which you can use to build products. @@ -95,21 +96,24 @@ After reading this article you should have: The rest of the article is structured as follows: -* <<freebsd-intro>> introduces the FreeBSD project, explores its organizational structure, key technologies and release engineering processes. -* <<freebsd-collaboration>> describes ways to collaborate with the FreeBSD project. It examines common pitfalls encountered by corporates working with voluntary projects like FreeBSD. -* <<conclusion>> concludes. +* crossref:building-products[freebsd-intro, FreeBSD as a set of building blocks] introduces the FreeBSD project, explores its organizational structure, key technologies and release engineering processes. +* crossref:building-products[freebsd-collaboration, Collaborating with FreeBSD] describes ways to collaborate with the FreeBSD project. It examines common pitfalls encountered by corporates working with voluntary projects like FreeBSD. +* crossref:building-products[conclusion, Conclusion] concludes. [[freebsd-intro]] == FreeBSD as a set of building blocks FreeBSD makes an excellent foundation on which to build products: -* FreeBSD source code is distributed under a liberal BSD license facilitating its adoption in commercial products <<Mon2005>> with minimum hassle. +* FreeBSD source code is distributed under a liberal BSD license facilitating + its adoption in commercial products crossref:building-products[Mon2005,"Why you should use a BSD style license for your Open Source Project"] with minimum hassle. * The FreeBSD project has excellent engineering practices that can be leveraged. * The project offers exceptional transparency into its workings, allowing organizations using its code to plan effectively for the future. -* The culture of the FreeBSD project, carried over from the Computer Science Research Group at The University of California, Berkeley <<McKu1999-1>>, fosters high-quality work. Some features in FreeBSD define the state of the art. +* The culture of the FreeBSD project, carried over from the Computer Science + Research Group at The University of California, Berkeley + crossref:building-products[McKu1999-1,"Twenty Years of Berkeley Unix: From AT&T-Owned to Freely Redistributable"], fosters high-quality work. Some features in FreeBSD define the state of the art. -<<GoldGab2005>> examines the business reasons for using open-source in greater detail. +crossref:building-products[GoldGab2005,"Innovation Happens Elsewhere: Open Source as Business Strategy"] examines the business reasons for using open-source in greater detail. For organizations, the benefits of using FreeBSD components in their products include a shorter time to market, lower development costs and lower development risks. === Building with FreeBSD @@ -157,7 +161,9 @@ A selection of these are listed below: 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) <<McKu1999>>. +FreeBSD supports a number of filesystems, and its native UFS2 filesystem +supports soft updates, snapshots and very large filesystem sizes (16TB per + filesystem) crossref:building-products[McKu1999,"Soft Updates: A Technique for Eliminating Most Synchronous Writes in the Fast 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. @@ -179,14 +185,17 @@ Conflict resolution is performed by a nine member "Core Team" that is elected fr FreeBSD does not have "corporate" committers. Individual committers are required to take responsibility for the changes they introduce to the code. -The extref:{committers-guide}[FreeBSD Committer's guide] <<ComGuide>> documents the rules and responsibilities for committers. +The extref:{committers-guide}[FreeBSD Committer's guide] +crossref:building-products[ComGuide,"Committer's Guide"] documents the rules and responsibilities for committers. -FreeBSD's project model is examined in detail in <<Nik2005>>. +FreeBSD's project model is examined in detail in +crossref:building-products[Nik2005,"A project model for the FreeBSD Project"]. === FreeBSD Release Engineering Processes FreeBSD's release engineering processes play a major role in ensuring that its released versions are of a high quality. -At any point of time, FreeBSD's volunteers support multiple code lines (<<fig-freebsd-branches, FreeBSD Release Branches>>): +At any point of time, FreeBSD's volunteers support multiple code lines +(crossref:building-products[fig-freebsd-branches, FreeBSD Release Branches]): * New features and disruptive code enters on the development branch, also known as the _-CURRENT_ branch. * _-STABLE_ branches are code lines that are branched from HEAD at regular intervals. Only tested code is allowed onto a -STABLE branch. New features are allowed once they have been tested and stabilized in the -CURRENT branch. @@ -204,7 +213,8 @@ The list of extref:{committers-guide}[supported architectures, archs] is part of The release engineering team publishes a link:https://www.FreeBSD.org/releng/[road map] for future releases of FreeBSD on the project's web site. The dates laid down in the road map are not deadlines; FreeBSD is released when its code and documentation are ready. -FreeBSD's release engineering processes are described in <<RelEngDoc>>. +FreeBSD's release engineering processes are described in +crossref:building-products[RelEngDoc,"FreeBSD Release Engineering"]. [[freebsd-collaboration]] == Collaborating with FreeBSD @@ -217,7 +227,8 @@ Using open-source code is best viewed not as a one-off activity, but as an __ong The best projects to collaborate with are the ones that are __live__; i.e., with an active community, clear goals and a transparent working style. * FreeBSD has an active developer community around it. At the time of writing there are many thousands of contributors from every populated continent in the world and over 300 individuals with write access to the project's source repositories. -* The goals of the FreeBSD project are <<Hub1994>>: +* The goals of the FreeBSD project are + crossref:building-products[Hub1994,"Contributing to the FreeBSD Project"]: ** To develop a high-quality operating system for popular computer hardware, and, ** To make our work available to all under a liberal license. @@ -232,18 +243,24 @@ To be able to work effectively with the FreeBSD project, you need to understand Volunteer driven projects operate under different rules than for-profit corporates. A common mistake that companies make when venturing into the open-source world is that of underplaying these differences. -*Motivation.* Most contributions to FreeBSD are done voluntarily without monetary rewards entering the picture. The factors that motivate individuals are complex, ranging from altruism, to an interest in solving the kinds of problems that FreeBSD attempts to solve. In this environment, "elegance is never optional"<<Nor1993>>. +*Motivation.* Most contributions to FreeBSD are done voluntarily without +monetary rewards entering the picture. The factors that motivate individuals are +complex, ranging from altruism, to an interest in solving the kinds of problems +that FreeBSD attempts to solve. In this environment, "elegance is never +optional"crossref:building-products[Nor1993,"Tutorial on Good Lisp Programming Style"]. *The Long Term View.* FreeBSD traces its roots back nearly twenty years to the work of the Computer Science Research Group at the University of California Berkeley.footnote:[FreeBSD's source repository contains a history of the project since its inception, and there are CDROMs available that contain earlier code from the CSRG.] A number of the original CSRG developers remain associated with the project. -The project values long-term perspectives <<Nor2001>>. A frequent acronym encountered in the project is DTRT, which stands for "Do The Right Thing". +The project values long-term perspectives crossref:building-products[Nor2001,"Teach Yourself Programming in Ten Years"]. A frequent acronym encountered in the project is DTRT, which stands for "Do The Right Thing". *Development Processes.* Computer programs are tools for communication: at one level programmers communicate their intentions using a precise notation to a tool (a compiler) that translates their instructions to executable code. At another level, the same notation is used for communication of intent between two programmers. Formal specifications and design documents are seldom used in the project. -Clear and well-written code and well-written change logs (<<fig-change-log, A sample change log entry>>) are used in their place. -FreeBSD development happens by "rough consensus and running code"<<Carp1996>>. +Clear and well-written code and well-written change logs +(crossref:building-products[fig-change-log, A sample change log entry]) are used in their place. +FreeBSD development happens by "rough consensus and running +code"crossref:building-products[Carp1996,"The Architectural Principles of the Internet"]. [.programlisting] .... @@ -281,7 +298,8 @@ For example: + *Track FreeBSD source code.* The project makes it easy to mirror its SVN repository using extref:{committers-guide}[svnsync, svn-advanced-use-setting-up-svnsync]. Having the complete history of the source is useful when debugging complex problems and offers valuable insight into the intentions of the original developers. Use a capable source control system that allows you to easily merge changes between the upstream FreeBSD code base and your own in-house code. + -<<fig-svn-blame, An annotated source listing generated using `svn blame`>> shows a portion of an annotated listing of the file referenced by the change log in <<fig-change-log, A sample change log entry>>. +crossref:building-products[fig-svn-blame, An annotated source listing generated using `svn blame`] shows a portion of an annotated listing of the file +referenced by the change log in crossref:building-products[fig-change-log, A sample change log entry]. The ancestry of each line of the source is clearly visible. Annotated listings showing the history of every file that is part of FreeBSD are https://svnweb.freebsd.org/[available on the web]. + @@ -325,7 +343,8 @@ The FreeBSD project maintains a link:https://www.FreeBSD.org/commercial/consult_ The http://www.bsdcertification.org/[BSD Certification Group] offers certification for all the major BSD derived OSes. + For less critical needs, you can ask for help on the link:https://lists.freebsd.org/[project mailing lists]. -A useful guide to follow when asking for help is given in <<Ray2004>>. +A useful guide to follow when asking for help is given in +crossref:building-products[Ray2004,"How to ask questions the smart way"]. Publicize your involvement:: You are not required to publicize your use of FreeBSD, but doing so helps both your effort as well as that of the project. + diff --git a/documentation/content/en/articles/building-products/_index.po b/documentation/content/en/articles/building-products/_index.po new file mode 100644 index 0000000000..262121f36f --- /dev/null +++ b/documentation/content/en/articles/building-products/_index.po @@ -0,0 +1,1126 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-12-29 08:30-0500\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/building-products/_index.adoc:1 +#, no-wrap +msgid "How FreeBSD can help you build a better product" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/building-products/_index.adoc:1 +#: documentation/content/en/articles/building-products/_index.adoc:13 +#, no-wrap +msgid "Building Products with FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:46 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:50 +msgid "" +"The FreeBSD project is a worldwide, volunteer based, and collaborative " +"project, which develops a portable and high-quality operating system. The " +"FreeBSD project distributes the source code for its product under a liberal " +"license, with the intention of encouraging the use of its code. " +"Collaborating with the FreeBSD project can help organizations reduce their " +"time to market, reduce engineering costs and improve their product quality." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:54 +msgid "" +"This article examines the issues in using FreeBSD code in appliances and " +"software products. It highlights the characteristics of FreeBSD that make " +"it an excellent substrate for product development. The article concludes by " +"suggesting a few \"best practices\" for organizations collaborating with the " +"FreeBSD project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:56 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/building-products/_index.adoc:60 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:67 +msgid "" +"FreeBSD today is well-known as a high-performance server operating system. " +"It is deployed on millions of web servers and internet-facing hosts " +"worldwide. FreeBSD code also forms an integral part of many products, " +"ranging from appliances such as network routers, firewalls, and storage " +"devices, to personal computers. Portions of FreeBSD have also been used in " +"commercial shrink-wrapped software (see crossref:building-products[freebsd-" +"intro, FreeBSD as a set of building blocks])." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:69 +msgid "" +"In this article we look at the link:https://www.FreeBSD.org/[FreeBSD " +"project] as a software engineering resource-as a collection of building " +"blocks and processes which you can use to build products." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:72 +msgid "" +"While FreeBSD's source is distributed freely to the public, to fully enjoy " +"the benefits of the project's work, organizations need to _collaborate_ with " +"the project. In subsequent sections of this article we discuss effective " +"means of collaboration with the project and the pitfalls that need to be " +"avoided while doing so." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:75 +#, no-wrap +msgid "" +"*Caveat Reader.* The author believes that the characteristics of the FreeBSD Project listed in this article were substantially true at the time the article was conceived and written (2005).\n" +"However, the reader should keep in mind that the practices and processes used by open-source communities can change over time, and that the information in this article should therefore be taken as indicative rather than normative.\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:76 +#, no-wrap +msgid "Target Audience" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:79 +msgid "" +"This document would be of interest to the following broad groups of people:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:81 +msgid "" +"Decision makers in product companies looking at ways to improve their " +"product quality, reduce their time to market and lower engineering costs in " +"the long term." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:82 +msgid "" +"Technology consultants looking for best-practices in leveraging \"open-" +"source\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:83 +msgid "" +"Industry observers interested in understanding the dynamics of open-source " +"projects." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:84 +msgid "" +"Software developers seeking to use FreeBSD and looking for ways to " +"contribute back." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:85 +#, no-wrap +msgid "Article Goals" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:88 +msgid "After reading this article you should have:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:90 +msgid "" +"An understanding of the goals of the FreeBSD Project and its organizational " +"structure." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:91 +msgid "" +"An understanding of its development model and release engineering processes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:92 +msgid "" +"An understanding of how conventional corporate software development " +"processes differ from that used in the FreeBSD project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:93 +msgid "" +"Awareness of the communication channels used by the project and the level of " +"transparency you can expect." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:94 +msgid "" +"Awareness of optimal ways of working with the project-how best to reduce " +"engineering costs, improve time to market, manage security vulnerabilities, " +"and preserve future compatibility with your product as the FreeBSD project " +"evolves." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:95 +#, no-wrap +msgid "Article Structure" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:98 +msgid "The rest of the article is structured as follows:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:100 +msgid "" +"crossref:building-products[freebsd-intro, FreeBSD as a set of building " +"blocks] introduces the FreeBSD project, explores its organizational " +"structure, key technologies and release engineering processes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:101 +msgid "" +"crossref:building-products[freebsd-collaboration, Collaborating with " +"FreeBSD] describes ways to collaborate with the FreeBSD project. It examines " +"common pitfalls encountered by corporates working with voluntary projects " +"like FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:102 +msgid "crossref:building-products[conclusion, Conclusion] concludes." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/building-products/_index.adoc:104 +#, no-wrap +msgid "FreeBSD as a set of building blocks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:107 +msgid "FreeBSD makes an excellent foundation on which to build products:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:110 +msgid "" +"FreeBSD source code is distributed under a liberal BSD license facilitating " +"its adoption in commercial products crossref:building-products[Mon2005,\"Why " +"you should use a BSD style license for your Open Source Project\"] with " +"minimum hassle." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:111 +msgid "" +"The FreeBSD project has excellent engineering practices that can be " +"leveraged." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:112 +msgid "" +"The project offers exceptional transparency into its workings, allowing " +"organizations using its code to plan effectively for the future." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:115 +msgid "" +"The culture of the FreeBSD project, carried over from the Computer Science " +"Research Group at The University of California, Berkeley crossref:building-" +"products[McKu1999-1,\"Twenty Years of Berkeley Unix: From AT&T-Owned to " +"Freely Redistributable\"], fosters high-quality work. Some features in " +"FreeBSD define the state of the art." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:118 +msgid "" +"crossref:building-products[GoldGab2005,\"Innovation Happens Elsewhere: Open " +"Source as Business Strategy\"] examines the business reasons for using open-" +"source in greater detail. For organizations, the benefits of using FreeBSD " +"components in their products include a shorter time to market, lower " +"development costs and lower development risks." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:119 +#, no-wrap +msgid "Building with FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:122 +msgid "Here are a few ways organizations have used FreeBSD:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:124 +msgid "As an upstream source for tested code for libraries and utilities." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:126 +msgid "" +"By being \"downstream\" of the project, organizations leverage the new " +"features, bug fixes and testing that the upstream code receives." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:127 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:129 +msgid "" +"FreeBSD ships with a self-hosting development environment that allows easy " +"creation of such configurations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:130 +msgid "" +"As a Unix compatible environment for the management functions of high-end " +"storage and networking devices, running on a separate processor \"blade\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:134 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:135 +msgid "" +"As a vehicle to get widespread testing and support from a worldwide team of " +"developers for non-critical \"intellectual property\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:139 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:140 +msgid "" +"As a development environment supporting cross-development for embedded OSes " +"like http://www.rtems.com/[RTEMS] and http://ecos.sourceware.org/[eCOS]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:142 +msgid "" +"There are many full-fledged development environments in the {numports}-" +"strong collection of applications ported and packaged with FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:143 +msgid "" +"As a way to support a Unix-like API in an otherwise proprietary OS, " +"increasing its palatability for application developers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:147 +msgid "" +"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." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:149 +#, no-wrap +msgid "Technologies" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:153 +msgid "" +"There are a large number of technologies supported by the FreeBSD project. " +"A selection of these are listed below:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:155 +msgid "" +"A complete system that can cross-host itself for link:https://www.FreeBSD." +"org/platforms/[many architectures:]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:156 +msgid "" +"A modular symmetric multiprocessing capable kernel, with loadable kernel " +"modules and a flexible and easy to use configuration system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:157 +msgid "" +"Support for emulation of Linux(TM) and SVR4 binaries at near machine speeds. " +"Support for binary Windows(TM) (NDIS) network drivers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:158 +msgid "" +"Libraries for many programming tasks: archivers, FTP and HTTP support, " +"thread support, in addition to a full POSIX(TM) like programming environment." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:159 +msgid "" +"Security features: Mandatory Access Control (man:mac[9]), jails (man:" +"jail[2]), ACLs, and in-kernel cryptographic device support." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:160 +msgid "" +"Networking features: firewall-ing, QoS management, high-performance TCP/IP " +"networking with support for many extensions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:162 +msgid "" +"FreeBSD's in-kernel Netgraph (man:netgraph[4]) framework allows kernel " +"networking modules to be connected together in flexible ways." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:163 +msgid "" +"Support for storage technologies: Fibre Channel, SCSI, software and hardware " +"RAID, ATA and SATA." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:167 +#, no-wrap +msgid "" +"FreeBSD supports a number of filesystems, and its native UFS2 filesystem\n" +"supports soft updates, snapshots and very large filesystem sizes (16TB per\n" +"\t\tfilesystem) crossref:building-products[McKu1999,\"Soft Updates: A Technique for Eliminating Most Synchronous Writes in the Fast Filesystem\"].\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:169 +msgid "" +"FreeBSD's in-kernel GEOM (man:geom[4]) framework allows kernel storage " +"modules to be composed in flexible ways." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:170 +msgid "" +"Over {numports} ported applications, both commercial and open-source, " +"managed via the FreeBSD ports collection." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:171 +#, no-wrap +msgid "Organizational Structure" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:174 +msgid "FreeBSD's organizational structure is non-hierarchical." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:176 +msgid "" +"There are essentially two kinds of contributors to FreeBSD, general users of " +"FreeBSD, and developers with write access (known as _committers_ in the " +"jargon) to the source base." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:180 +msgid "" +"There are many thousands of contributors in the first group; the vast " +"majority of contributions to FreeBSD come from individuals in this group. " +"Commit rights (write access) to the repository are granted to individuals " +"who contribute consistently to the project. Commit rights come with " +"additional responsibilities, and new committers are assigned mentors to help " +"them learn the ropes." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/building-products/_index.adoc:181 +#, no-wrap +msgid "FreeBSD Organization" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/building-products/_index.adoc:182 +#, no-wrap +msgid "freebsd-organization.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:185 +msgid "" +"Conflict resolution is performed by a nine member \"Core Team\" that is " +"elected from the group of committers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:190 +msgid "" +"FreeBSD does not have \"corporate\" committers. Individual committers are " +"required to take responsibility for the changes they introduce to the code. " +"The extref:{committers-guide}[FreeBSD Committer's guide] crossref:building-" +"products[ComGuide,\"Committer's Guide\"] documents the rules and " +"responsibilities for committers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:193 +msgid "" +"FreeBSD's project model is examined in detail in crossref:building-" +"products[Nik2005,\"A project model for the FreeBSD Project\"]." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:194 +#, no-wrap +msgid "FreeBSD Release Engineering Processes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:199 +msgid "" +"FreeBSD's release engineering processes play a major role in ensuring that " +"its released versions are of a high quality. At any point of time, " +"FreeBSD's volunteers support multiple code lines (crossref:building-" +"products[fig-freebsd-branches, FreeBSD Release Branches]):" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:201 +msgid "" +"New features and disruptive code enters on the development branch, also " +"known as the _-CURRENT_ branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:202 +msgid "" +"_-STABLE_ branches are code lines that are branched from HEAD at regular " +"intervals. Only tested code is allowed onto a -STABLE branch. New features " +"are allowed once they have been tested and stabilized in the -CURRENT branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:203 +msgid "" +"_-RELEASE_ branches are maintained by the FreeBSD security team. Only bug " +"fixes for critical issues are permitted onto -RELEASE branches." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/building-products/_index.adoc:205 +#, no-wrap +msgid "FreeBSD Release Branches" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/building-products/_index.adoc:206 +#, no-wrap +msgid "freebsd-branches.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:209 +msgid "" +"Code lines are kept alive for as long as there is user and developer " +"interest in them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:212 +msgid "" +"Machine architectures are grouped into \"tiers\"; _Tier 1_ architectures are " +"fully supported by the project's release engineering and security teams, " +"_Tier 2_ architectures are supported on a best effort basis, and " +"experimental architectures comprise _Tier 3_. The list of extref:" +"{committers-guide}[supported architectures, archs] is part of the FreeBSD " +"documentation collection." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:215 +msgid "" +"The release engineering team publishes a link:https://www.FreeBSD.org/releng/" +"[road map] for future releases of FreeBSD on the project's web site. The " +"dates laid down in the road map are not deadlines; FreeBSD is released when " +"its code and documentation are ready." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:218 +msgid "" +"FreeBSD's release engineering processes are described in crossref:building-" +"products[RelEngDoc,\"FreeBSD Release Engineering\"]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/building-products/_index.adoc:220 +#, no-wrap +msgid "Collaborating with FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:223 +msgid "" +"Open-source projects like FreeBSD offer finished code of a very high quality." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:228 +msgid "" +"While access to quality source code can reduce the cost of initial " +"development, in the long-term the costs of managing change begin to " +"dominate. As computing environments change over the years and new security " +"vulnerabilities are discovered, your product too needs to change and adapt. " +"Using open-source code is best viewed not as a one-off activity, but as an " +"__ongoing process__. The best projects to collaborate with are the ones " +"that are __live__; i.e., with an active community, clear goals and a " +"transparent working style." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:230 +msgid "" +"FreeBSD has an active developer community around it. At the time of writing " +"there are many thousands of contributors from every populated continent in " +"the world and over 300 individuals with write access to the project's source " +"repositories." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:232 +msgid "" +"The goals of the FreeBSD project are crossref:building-products[Hub1994," +"\"Contributing to the FreeBSD Project\"]:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:234 +msgid "" +"To develop a high-quality operating system for popular computer hardware, " +"and," +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:235 +msgid "To make our work available to all under a liberal license." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:237 +msgid "" +"FreeBSD enjoys an open and transparent working culture. Nearly all " +"discussion in the project happens by email, on link:https://lists.freebsd." +"org/[public mailing lists] that are also archived for posterity. The " +"project's policies are link:https://www.FreeBSD.org/internal/policies/" +"[documented] and maintained under revision control. Participation in the " +"project is open to all." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:239 +#, no-wrap +msgid "Understanding FreeBSD culture" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:242 +msgid "" +"To be able to work effectively with the FreeBSD project, you need to " +"understand the project's culture." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:245 +msgid "" +"Volunteer driven projects operate under different rules than for-profit " +"corporates. A common mistake that companies make when venturing into the " +"open-source world is that of underplaying these differences." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:251 +#, no-wrap +msgid "" +"*Motivation.* Most contributions to FreeBSD are done voluntarily without\n" +"monetary rewards entering the picture. The factors that motivate individuals are\n" +"complex, ranging from altruism, to an interest in solving the kinds of problems\n" +"that FreeBSD attempts to solve. In this environment, \"elegance is never\n" +"optional\"crossref:building-products[Nor1993,\"Tutorial on Good Lisp Programming Style\"].\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:253 +#, no-wrap +msgid "*The Long Term View.* FreeBSD traces its roots back nearly twenty years to the work of the Computer Science Research Group at the University of California Berkeley.footnote:[FreeBSD's source repository contains a history of the project since its inception, and there are CDROMs available that contain earlier code from the CSRG.] A number of the original CSRG developers remain associated with the project.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:255 +msgid "" +"The project values long-term perspectives crossref:building-products[Nor2001," +"\"Teach Yourself Programming in Ten Years\"]. A frequent acronym encountered " +"in the project is DTRT, which stands for \"Do The Right Thing\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:258 +#, no-wrap +msgid "" +"*Development Processes.* Computer programs are tools for communication: at one level programmers communicate their intentions using a precise notation to a tool (a compiler) that translates their instructions to executable code.\n" +"At another level, the same notation is used for communication of intent between two programmers.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:264 +msgid "" +"Formal specifications and design documents are seldom used in the project. " +"Clear and well-written code and well-written change logs (crossref:building-" +"products[fig-change-log, A sample change log entry]) are used in their " +"place. FreeBSD development happens by \"rough consensus and running " +"code\"crossref:building-products[Carp1996,\"The Architectural Principles of " +"the Internet\"]." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/building-products/_index.adoc:270 +#, no-wrap +msgid "" +"r151864 | bde | 2005-10-29 09:34:50 -0700 (Sat, 29 Oct 2005) | 13 lines\n" +"Changed paths:\n" +" M /head/lib/msun/src/e_rem_pio2f.c\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/building-products/_index.adoc:280 +#, no-wrap +msgid "" +"Use double precision to simplify and optimize arg reduction for small\n" +"and medium size args too: instead of conditionally subtracting a float\n" +"17+24, 17+17+24 or 17+17+17+24 bit approximation to pi/2, always\n" +"subtract a double 33+53 bit one. The float version is now closer to\n" +"the double version than to old versions of itself -- it uses the same\n" +"33+53 bit approximation as the simplest cases in the double version,\n" +"and where the float version had to switch to the slow general case at\n" +"|x| == 2^7*pi/2, it now switches at |x| == 2^19*pi/2 the same as the\n" +"double version.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/building-products/_index.adoc:283 +#, no-wrap +msgid "" +"This speeds up arg reduction by a factor of 2 for |x| between 3*pi/4 and\n" +"2^7*pi/4, and by a factor of 7 for |x| between 2^7*pi/4 and 2^19*pi/4.\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/building-products/_index.adoc:284 +#, no-wrap +msgid "A sample change log entry [[fig-change-log]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:287 +msgid "" +"Communication between programmers is enhanced by the use of a common coding " +"standard man:style[9]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:290 +#, no-wrap +msgid "" +"*Communication Channels.* FreeBSD's contributors are spread across the world.\n" +"Email (and to a lesser extent, IRC) is the preferred means of communication in the project.\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:291 +#, no-wrap +msgid "Best Practices for collaborating with the FreeBSD project" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:294 +msgid "" +"We now look at a few best practices for making the best use of FreeBSD in " +"product development." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/building-products/_index.adoc:295 +#, no-wrap +msgid "Plan for the long term" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:298 +msgid "" +"Setup processes that help in tracking the development of FreeBSD. For " +"example:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:300 +#, no-wrap +msgid "*Track FreeBSD source code.* The project makes it easy to mirror its SVN repository using extref:{committers-guide}[svnsync, svn-advanced-use-setting-up-svnsync]. Having the complete history of the source is useful when debugging complex problems and offers valuable insight into the intentions of the original developers. Use a capable source control system that allows you to easily merge changes between the upstream FreeBSD code base and your own in-house code.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:305 +msgid "" +"crossref:building-products[fig-svn-blame, An annotated source listing " +"generated using `svn blame`] shows a portion of an annotated listing of the " +"file referenced by the change log in crossref:building-products[fig-change-" +"log, A sample change log entry]. The ancestry of each line of the source is " +"clearly visible. Annotated listings showing the history of every file that " +"is part of FreeBSD are https://svnweb.freebsd.org/[available on the web]." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/building-products/_index.adoc:309 +#, no-wrap +msgid "#REV #WHO #DATE #TEXT\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/building-products/_index.adoc:323 +#, no-wrap +msgid "" +"176410 bde 2008-02-19 07:42:46 -0800 (Tue, 19 Feb 2008) #include <sys/cdefs.h>\n" +"176410 bde 2008-02-19 07:42:46 -0800 (Tue, 19 Feb 2008) __FBSDID(\"$FreeBSD$\");\n" +" 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) \n" +" 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) /* __ieee754_rem_pio2f(x,y)\n" +" 8870 rgrimes 1995-05-29 22:51:47 -0700 (Mon, 29 May 1995) *\n" +"176552 bde 2008-02-25 05:33:20 -0800 (Mon, 25 Feb 2008) * return the remainder of x rem pi/2 in *y\n" +"176552 bde 2008-02-25 05:33:20 -0800 (Mon, 25 Feb 2008) * use double precision for everything except passing x\n" +"152535 bde 2005-11-16 18:20:04 -0800 (Wed, 16 Nov 2005) * use __kernel_rem_pio2() for large x\n" +" 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) */\n" +" 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) \n" +"176465 bde 2008-02-22 07:55:14 -0800 (Fri, 22 Feb 2008) #include <float.h>\n" +"176465 bde 2008-02-22 07:55:14 -0800 (Fri, 22 Feb 2008) \n" +" 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) #include \"math.h\"\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/building-products/_index.adoc:324 +#, no-wrap +msgid "An annotated source listing generated using `svn blame` [[fig-svn-blame]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:327 +#, no-wrap +msgid "*Use a gatekeeper.* Appoint a _gatekeeper_ to monitor FreeBSD development, to keep an eye out for changes that could potentially impact your products.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:330 +#, no-wrap +msgid "" +"*Report bugs upstream.* If you notice bug in the FreeBSD code that you are using, file a https://www.FreeBSD.org/support/bugreports/[bug report].\n" +"This step helps ensure that you do not have to fix the bug the next time you take a code drop from upstream.\n" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/building-products/_index.adoc:330 +#, no-wrap +msgid "Leverage FreeBSD's release engineering efforts" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:333 +msgid "" +"Use code from a -STABLE development branch of FreeBSD. These development " +"branches are formally supported by FreeBSD's release engineering and " +"security teams and comprise of tested code." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/building-products/_index.adoc:334 +#, no-wrap +msgid "Donate code to reduce costs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:338 +msgid "" +"A major proportion of the costs associated with developing products is that " +"of doing maintenance. By donating non-critical code to the project, you " +"benefit by having your code see much wider exposure than it would otherwise " +"get. This in turn leads to more bugs and security vulnerabilities being " +"flushed out and performance anomalies being identified and fixed." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/building-products/_index.adoc:339 +#, no-wrap +msgid "Get support effectively" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:344 +msgid "" +"For products with tight deadlines, it is recommended that you hire or enter " +"into a consulting agreement with a developer or firm with FreeBSD " +"experience. The {freebsd-jobs} is a useful communication channel to find " +"talent. The FreeBSD project maintains a link:https://www.FreeBSD.org/" +"commercial/consult_bycat/[gallery of consultants and consulting firms] " +"undertaking FreeBSD work. The http://www.bsdcertification.org/[BSD " +"Certification Group] offers certification for all the major BSD derived OSes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:348 +msgid "" +"For less critical needs, you can ask for help on the link:https://lists." +"freebsd.org/[project mailing lists]. A useful guide to follow when asking " +"for help is given in crossref:building-products[Ray2004,\"How to ask " +"questions the smart way\"]." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/building-products/_index.adoc:348 +#, no-wrap +msgid "Publicize your involvement" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:350 +msgid "" +"You are not required to publicize your use of FreeBSD, but doing so helps " +"both your effort as well as that of the project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:354 +msgid "" +"Letting the FreeBSD community know that your company uses FreeBSD helps " +"improve your chances of attracting high quality talent. A large roster of " +"support for FreeBSD also means more mind share for it among developers. " +"This in turn yields a healthier foundation for your future." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/building-products/_index.adoc:354 +#, no-wrap +msgid "Support FreeBSD developers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:360 +msgid "" +"Sometimes the most direct way to get a desired feature into FreeBSD is to " +"support a developer who is already looking at a related problem. Help can " +"range from hardware donations to direct financial assistance. In some " +"countries, donations to the FreeBSD project enjoy tax benefits. The project " +"has a dedicated link:https://www.FreeBSD.org/donations/[donations liaison] " +"to assist donors. The project also maintains a web page where developers " +"link:https://www.FreeBSD.org/donations/wantlist/[list their needs]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:362 +msgid "" +"As a policy the FreeBSD project extref:{contributors}[acknowledges] all " +"contributions received on its web site." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/building-products/_index.adoc:364 +#, no-wrap +msgid "Conclusion" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:368 +msgid "" +"The FreeBSD project's goals are to create and give away the source code for " +"a high-quality operating system. By working with the FreeBSD project you " +"can reduce development costs and improve your time to market in a number of " +"product development scenarios." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:372 +msgid "" +"We examined the characteristics of the FreeBSD project that make it an " +"excellent choice for being part of an organization's product strategy. We " +"then looked at the prevailing culture of the project and examined effective " +"ways of interacting with its developers. The article concluded with a list " +"of best-practices that could help organizations collaborating with the " +"project." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/building-products/_index.adoc:376 +#, no-wrap +msgid "Bibliography" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:379 +msgid "" +"[[Carp1996]] [Carp1996] http://www.ietf.org/rfc/rfc1958.txt[The " +"Architectural Principles of the Internet] B. Carpenter. The Internet " +"Architecture Board.The Internet Architecture Board. Copyright(R) 1996." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:381 +msgid "" +"[[ComGuide]] [ComGuide] extref:{committers-guide}[Committer's Guide] The " +"FreeBSD Project. Copyright(R) 2005." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:383 +msgid "" +"[[GoldGab2005]] [GoldGab2005] http://dreamsongs.com/IHE/IHE.html[Innovation " +"Happens Elsewhere: Open Source as Business Strategy] Ron Goldman. Richard " +"Gabriel. Copyright(R) 2005. Morgan-Kaufmann." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:385 +msgid "" +"[[Hub1994]] [Hub1994] extref:{contributing}[Contributing to the FreeBSD " +"Project] Jordan Hubbard. Copyright(R) 1994-2005. The FreeBSD Project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:387 +msgid "" +"[[McKu1999]] [McKu1999] http://www.usenix.org/publications/library/" +"proceedings/usenix99/mckusick.html[Soft Updates: A Technique for Eliminating " +"Most Synchronous Writes in the Fast Filesystem] Kirk McKusick. Gregory " +"Ganger. Copyright(R) 1999." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:389 +msgid "" +"[[McKu1999-1]] [McKu1999-1] http://www.oreilly.com/catalog/opensources/book/" +"kirkmck.html[Twenty Years of Berkeley Unix: From AT&T-Owned to Freely " +"Redistributable] Marshall Kirk McKusick. http://www.oreilly.com/catalog/" +"opensources/book/toc.html[Open Sources: Voices from the Open Source " +"Revolution] O'Reilly Inc.. Copyright(R) 1993." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:391 +msgid "" +"[[Mon2005]] [Mon2005] extref:{bsdl-gpl}[Why you should use a BSD style " +"license for your Open Source Project] Bruce Montague. The FreeBSD Project. " +"Copyright(R) 2005." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:393 +msgid "" +"[[Nik2005]] [Nik2005] extref:{dev-model}[A project model for the FreeBSD " +"Project] Niklas Saers. Copyright(R) 2005. The FreeBSD Project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:395 +msgid "" +"[[Nor1993]] [Nor1993] http://www.norvig.com/luv-slides.ps[Tutorial on Good " +"Lisp Programming Style] Peter Norvig. Kent Pitman. Copyright(R) 1993." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:397 +msgid "" +"[[Nor2001]] [Nor2001] http://www.norvig.com/21-days.html[Teach Yourself " +"Programming in Ten Years] Peter Norvig. Copyright(R) 2001." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:399 +msgid "" +"[[Ray2004]] [Ray2004] http://www.catb.org/~esr/faqs/smart-questions.html[How " +"to ask questions the smart way] Eric Steven Raymond. Copyright(R) 2004." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:400 +msgid "" +"[[RelEngDoc]] [RelEngDoc] extref:{releng}[FreeBSD Release Engineering] " +"Murray Stokely. Copyright(R) 2001. The FreeBSD Project." +msgstr "" diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index 557630327b..1a61f5f7e4 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -2,9 +2,9 @@ title: Committer's Guide authors: - author: The FreeBSD Documentation Project -copyright: 1999-2021 The FreeBSD Documentation Project +copyright: 1999-2022 The FreeBSD Documentation Project description: Introductory information for FreeBSD committers -trademarks: ["freebsd", "coverity", "ibm", "intel", "general"] +trademarks: ["freebsd", "coverity", "git", "github", "gitlab", "ibm", "intel", "general"] weight: 25 tags: ["FreeBSD Committer's Guide", "Guide", "Community"] --- @@ -48,8 +48,8 @@ All new committers should read this document before they start, and existing com Almost all FreeBSD developers have commit rights to one or more repositories. However, a few developers do not, and some of the information here applies to them as well. -(For instance, some people only have rights to work with the Problem Report database). -Please see <<non-committers>> for more information. +(For instance, some people only have rights to work with the Problem Report database.) +Please see crossref:committers-guide[non-committers, Issues Specific to Developers Who Are Not Committers] for more information. This document may also be of interest to members of the FreeBSD community who want to learn more about how the project works. @@ -74,22 +74,22 @@ toc::[] |`ref*.FreeBSD.org`, `universe*.freeBSD.org` (see also link:https://www.FreeBSD.org/internal/machines/[FreeBSD Project Hosts]) |_SMTP Host_ -|`smtp.FreeBSD.org:587` (see also <<smtp-setup>>). +|`smtp.FreeBSD.org:587` (see also crossref:committers-guide[smtp-setup, SMTP Access Setup]). |`_src/_` Git Repository -|`ssh://git@gitrepo.FreeBSD.org/src.git` (see also <<git-getting-started-base-layout>>). +|`ssh://git@gitrepo.FreeBSD.org/src.git` |`_doc/_` Git Repository -|`ssh://git@gitrepo.FreeBSD.org/doc.git` (see also <<git-getting-started-doc-layout>>). +|`ssh://git@gitrepo.FreeBSD.org/doc.git` |`_ports/_` Git Repository -|`ssh://git@gitrepo.FreeBSD.org/ports.git` (see also <<git-getting-started-ports-layout>>). +|`ssh://git@gitrepo.FreeBSD.org/ports.git` |_Internal Mailing Lists_ -|developers (technically called all-developers), doc-developers, doc-committers, ports-developers, ports-committers, src-developers, src-committers. (Each project repository has its own -developers and -committers mailing lists. Archives for these lists can be found in the files [.filename]#/local/mail/repository-name-developers-archive# and [.filename]#/local/mail/repository-name-committers-archive# on the `FreeBSD.org` cluster.) +|developers (technically called all-developers), doc-developers, doc-committers, ports-developers, ports-committers, src-developers, src-committers. (Each project repository has its own -developers and -committers mailing lists. Archives for these lists can be found in the files [.filename]#/local/mail/repository-name-developers-archive# and [.filename]#/local/mail/repository-name-committers-archive# on `freefall.FreeBSD.org`.) |_Core Team monthly reports_ -|[.filename]#/home/core/public/monthly-reports# on the `FreeBSD.org` cluster. +|[.filename]#/home/core/public/reports# on the `FreeBSD.org` cluster. |_Ports Management Team monthly reports_ |[.filename]#/home/portmgr/public/monthly-reports# on the `FreeBSD.org` cluster. @@ -98,7 +98,8 @@ toc::[] |`stable/n` (`n`-STABLE), `main` (-CURRENT) |=== -man:ssh[1] is required to connect to the project hosts. For more information, see <<ssh.guide>>. +man:ssh[1] is required to connect to the project hosts. For more information, + see crossref:committers-guide[ssh.guide, SSH Quick-Start Guide]. Useful links: @@ -111,7 +112,7 @@ Useful links: Cryptographic keys conforming to the OpenPGP (__Pretty Good Privacy__) standard are used by the FreeBSD project to authenticate committers. Messages carrying important information like public SSH keys can be signed with the OpenPGP key to prove that they are really from the committer. -See http://www.nostarch.com/pgp_ml.htm[PGP & GPG: Email for the Practical Paranoid by Michael Lucas] and http://en.wikipedia.org/wiki/Pretty_Good_Privacy[] for more information. +See https://nostarch.com/releases/pgp_release.pdf[PGP & GPG: Email for the Practical Paranoid by Michael Lucas] and https://en.wikipedia.org/wiki/Pretty_Good_Privacy[] for more information. [[pgpkeys-creating]] === Creating a Key @@ -124,18 +125,14 @@ For those who do not yet have an OpenPGP key, or need a new key to meet FreeBSD [[pgpkeys-create-steps]] [.procedure] ==== -. Install [.filename]#security/gnupg#. Enter these lines in [.filename]#~/.gnupg/gpg.conf# to set minimum acceptable defaults: +. Install [.filename]#security/gnupg#. Enter these lines in [.filename]#~/.gnupg/gpg.conf# to set minimum acceptable defaults for signing and new key preferences (see the link:https://www.gnupg.org/documentation/manuals/gnupg/GPG-Options.html[GnuPG options documentation] for more details): + [.programlisting] .... -fixed-list-mode -keyid-format 0xlong +# Sorted list of preferred algorithms for signing (strongest to weakest). personal-digest-preferences SHA512 SHA384 SHA256 SHA224 -default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed -verify-options show-uid-validity -list-options show-uid-validity -sig-notation issuer-fpr@notations.openpgp.fifthhorseman.net=%g -cert-digest-algo SHA512 +# Default preferences for new keys +default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 CAMELLIA256 AES192 CAMELLIA192 AES CAMELLIA128 CAST5 BZIP2 ZLIB ZIP Uncompressed .... . Generate a key: + @@ -177,7 +174,7 @@ Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o You need a Passphrase to protect your secret key. .... -<.> 2048-bit keys with a three-year expiration provide adequate protection at present (2013-12). http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits[] describes the situation in more detail. +<.> 2048-bit keys with a three-year expiration provide adequate protection at present (2022-10). <.> A three year key lifespan is short enough to obsolete keys weakened by advancing computer power, but long enough to reduce key management problems. @@ -185,13 +182,13 @@ You need a Passphrase to protect your secret key. + 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[]. +Rather than suggest a single way, here are some links to sites that describe various methods: https://world.std.com/~reinhold/diceware.html[], https://www.iusmentis.com/security/passphrasefaq/[], https://xkcd.com/936/[], https://en.wikipedia.org/wiki/Passphrase[]. ==== Protect the private key and passphrase. If either the private key or passphrase may have been compromised or disclosed, immediately notify mailto:accounts@FreeBSD.org[accounts@FreeBSD.org] and revoke the key. -Committing the new key is shown in <<commit-steps, Steps for New Committers>>. +Committing the new key is shown in crossref:committers-guide[commit-steps, Steps for New Committers]. [[kerberos-ldap]] == Kerberos and LDAP web Password for FreeBSD Cluster @@ -201,7 +198,6 @@ The Kerberos password also serves as the LDAP web password, since LDAP is proxyi Some of the services which require this include: * https://bugs.freebsd.org/bugzilla[Bugzilla] -* https://ci.freebsd.org[Jenkins] To create a new Kerberos account in the FreeBSD cluster, or to reset a Kerberos password for an existing account using a random password generator: @@ -245,7 +241,7 @@ Additional areas of authority may be added at a later date: when this occurs, th |__Tree Components__ |src -|core@ +|srcmgr@ |src/ |doc @@ -266,10 +262,10 @@ Committers are encouraged to seek review for their work as part of the normal de === Policy for Committer Activity in Other Trees * All committers may modify [.filename]#src/share/misc/committers-*.dot#, [.filename]#src/usr.bin/calendar/calendars/calendar.freebsd#, and [.filename]#ports/astro/xearth/files#. -* doc committers may commit documentation changes to [.filename]#src# files, such as man pages, READMEs, fortune databases, calendar files, and comment fixes without approval from a src committer, subject to the normal care and tending of commits. +* doc committers may commit documentation changes to [.filename]#src# files, such as manual pages, READMEs, fortune databases, calendar files, and comment fixes without approval from a src committer, subject to the normal care and tending of commits. * Any committer may make changes to any other tree with an "Approved by" from a non-mentored committer with the appropriate bit. Mentored committers can provide a "Reviewed by" but not an "Approved by". -* Committers can acquire an additional bit by the usual process of finding a mentor who will propose them to core, doceng, or portmgr, as appropriate. When approved, they will be added to 'access' and the normal mentoring period will ensue, which will involve a continuing of "Approved by" for some period. +* Committers can acquire an additional bit by the usual process of finding a mentor who will propose them to srcmgr, doceng, or portmgr, as appropriate. When approved, they will be added to 'access' and the normal mentoring period will ensue, which will involve a continuing of "Approved by" for some period. [[doc-blanket-approval]] ==== Documentation Implicit (Blanket) Approval @@ -327,7 +323,7 @@ This primer is less ambitiously scoped than the old Subversion Primer, but shoul If you want to download FreeBSD, compile it from sources, and generally keep up to date that way, this primer is for you. It covers getting the sources, updating the sources, bisecting and touches briefly on how to cope with a few local changes. It covers the basics, and tries to give good pointers to more in-depth treatment for when the reader finds the basics insufficient. -Other sections of this guide cover more advanced topics related to contributing to the project. +Other sections of this guide cover more advanced topics related to contributing to the project. The goal of this section is to highlight those bits of Git needed to track sources. They assume a basic understanding of Git. @@ -338,8 +334,14 @@ There are many primers for Git on the web, but the https://git-scm.com/book/en/v This section describes the read-write access for committers to push the commits from developers or contributors. +[[git-mini-daily-use]] ===== Daily use +[NOTE] +==== +In the examples below, replace `${repo}` with the name of the desired FreeBSD repository: `doc`, `ports`, or `src`. +==== + * Clone the repository: + [source,shell] @@ -385,14 +387,31 @@ freebsd https://git.freebsd.org/${repo}.git (fetch) freebsd git@gitrepo.freebsd.org:${repo}.git (push) .... + -Again, note that `gitrepo.freebsd.org` will be canonicalized to `repo.freebsd.org` in the future. +Again, note that `gitrepo.freebsd.org` has been canonicalized to `repo.freebsd.org`. * Install commit message template hook: + +For doc repository: ++ +[source,shell] +.... +% cd .git/hooks +% ln -s ../../.hooks/prepare-commit-msg +.... ++ +For ports repository: ++ [source,shell] .... -% fetch https://cgit.freebsd.org/src/plain/tools/tools/git/hooks/prepare-commit-msg -o .git/hooks -% chmod 755 .git/hooks/prepare-commit-msg +% git config --add core.hooksPath .hooks +.... ++ +For src repository: ++ +[source,shell] +.... +% cd .git/hooks +% ln -s ../../tools/tools/git/hooks/prepare-commit-msg .... [[admin-branch]] @@ -416,22 +435,15 @@ git worktree add -b admin ../${repo}-admin internal/admin .... For browsing `internal/admin` branch on web: -https://cgit.freebsd.org/${repo}/log/?h=internal/admin +`https://cgit.freebsd.org/${repo}/log/?h=internal/admin` -For pushing, either specify the full refspec: +For pushing, specify the full refspec: [source,shell] .... git push freebsd HEAD:refs/internal/admin .... -Or set `push.default` to `freebsd` which will make `git push` to push the current branch back to its upstream by default, which is more suitable for our workflow: - -[source,shell] -.... -git config push.default freebsd -.... - ==== Keeping Current With The FreeBSD src Tree [[keeping_current]] First step: cloning a tree. @@ -440,16 +452,27 @@ There are two ways to download. Most people will want to do a deep clone of the repository. However, there are times when you may wish to do a shallow clone. -===== Branch names -The branch names in the new Git repository are similar to the old names. -For the stable branches, they are stable/X where X is the major release (like 11 or 12). -The main branch in the new repository is 'main'. -The main branch in the old GitHub mirror was 'master', but is now 'main'. -Both reflect the defaults of Git at the time they were created. -The 'main' branch is the default branch if you omit the '-b branch' or '--branch branch' options below. +===== Branch Names +FreeBSD-CURRENT uses the `main` branch. + +`main` is the default branch. + +For FreeBSD-STABLE, branch names include `stable/12` and `stable/13`. + +For FreeBSD-RELEASE, release engineering branch names include `releng/12.4` and `releng/13.2`. + +https://www.freebsd.org/releng/[] shows: + +* `main` and `stable/⋯` branches open +* `releng/⋯` branches, each of which is frozen when a release is tagged. + +Examples: + +* tag https://cgit.freebsd.org/src/tag/?h=release/13.1.0[release/13.1.0] on the https://cgit.freebsd.org/src/log/?h=releng/13.1[releng/13.1] branch +* tag https://cgit.freebsd.org/src/tag/?h=release/13.2.0[release/13.2.0] on the https://cgit.freebsd.org/src/log/?h=releng/13.2[releng/13.2] branch. ===== Repositories -Please see the <<admin,Administrative Details>> for the latest information on where to get FreeBSD sources. +Please see the crossref:committers-guide[admin,Administrative Details] for the latest information on where to get FreeBSD sources. $URL below can be obtained from that page. Note: The project doesn't use submodules as they are a poor fit for our workflows and development model. @@ -461,12 +484,12 @@ It is the easiest to do. It also allows you to use Git's worktree feature to have all your active branches checked out into separate directories but with only one copy of the repository. [source,shell] .... -% git clone -o freebsd $URL -b branch [dir] +% git clone -o freebsd $URL -b branch [<directory>] .... -is how you make a deep clone. -'branch' should be one of the branches listed in the previous section. -It is optional if it is the main branch. -'dir' is an optional directory to place it in (the default will be the name of the repo you are cloning (src, doc, etc)). +-- will create a deep clone. +`branch` should be one of the branches listed in the previous section. +If no `branch` is given: the default (`main`) will be used. +If no `<directory>` is given: the name of the new directory will match the name of the repo ([.filename]#doc#, [.filename]#ports# or [.filename]#src#). You will want a deep clone if you are interested in the history, plan on making local changes, or plan on working on more than one branch. It is the easiest to keep up to date as well. @@ -487,7 +510,7 @@ However, see below for a significant limitation of this approach. This clones the repository, but only has the most recent version in the repository. The rest of the history is not downloaded. -Should you change your mind later, you can do 'git fetch --unshallow' to get the old history. +Should you change your mind later, you can do `git fetch --unshallow` to get the old history. [WARNING] ==== @@ -509,7 +532,7 @@ e.g.: .... so that won't be covered in depth here. -If you want to build a custom kernel, extref:{handbook}[the kernel config section, kernelconfig] of the FreeBSD Handbook recommends creating a file MYKERNEL under sys/${ARCH}/conf with your changes against GENERIC. +If you want to build a custom kernel, extref:{handbook}kernelconfig[the kernel config section, kernelconfig] of the FreeBSD Handbook recommends creating a file MYKERNEL under sys/${ARCH}/conf with your changes against GENERIC. To have MYKERNEL disregarded by Git, it can be added to .git/info/exclude. ===== Updating @@ -522,15 +545,15 @@ This pulls in all the revisions since your last update. .... will update the tree. In Git, a 'fast forward' merge is one that only needs to set a new branch pointer and doesn't need to re-create the commits. -By always doing a 'fast forward' merge/pull, you'll ensure that you have an exact copy of the FreeBSD tree. +By always doing a fast forward merge/pull, you'll ensure that you have an exact copy of the FreeBSD tree. This will be important if you want to maintain local patches. See below for how to manage local changes. -The simplest is to use --autostash on the 'git pull' command, but more sophisticated options are available. +The simplest is to use `--autostash` on the `git pull` command, but more sophisticated options are available. ==== Selecting a Specific Version -In Git, the 'git checkout' checks out both branches and specific versions. +In Git, `git checkout` checks out both branches and specific versions. Git's versions are the long hashes rather than a sequential number. When you checkout a specific version, just specify the hash you want on the command line (the git log command can help you decide which hash you might want): @@ -564,29 +587,29 @@ Sometimes, things go wrong. The last version worked, but the one you just updated to does not. A developer may ask you to bisect the problem to track down which commit caused the regression. -Git makes bisecting changes easy with a powerful 'git bisect' command. +Git makes bisecting changes easy with a powerful `git bisect` command. Here's a brief outline of how to use it. For more information, you can view https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination or https://git-scm.com/docs/git-bisect for more details. The man git-bisect page is good at describing what can go wrong, what to do when versions won't build, when you want to use terms other than 'good' and 'bad', etc, none of which will be covered here. `git bisect start --first-parent` will start the bisection process. Next, you need to tell a range to go through. -'git bisect good XXXXXX' will tell it the working version and 'git bisect bad XXXXX' will tell it the bad version. +`git bisect good XXXXXX` will tell it the working version and `git bisect bad XXXXX` will tell it the bad version. The bad version will almost always be HEAD (a special tag for what you have checked out). The good version will be the last one you checked out. The `--first-parent` argument is necessary so that subsequent `git bisect` commands do not try to check out a vendor branch which lacks the full FreeBSD source tree. [TIP] ==== -If you want to know the last version you checked out, you should use 'git reflog': +If you want to know the last version you checked out, you should use `git reflog`: [source,shell] .... 5ef0bd68b515 (HEAD -> main, freebsd/main, freebsd/HEAD) HEAD@{0}: pull --ff-only: Fast-forward a8163e165c5b (upstream/main) HEAD@{1}: checkout: moving from b6fb97efb682994f59b21fe4efb3fcfc0e5b9eeb to main ... .... -shows me moving the working tree to the main branch (a816...) and then updating from upstream (to 5ef0...). -In this case, bad would be HEAD (or 5rf0bd68) and good would be a8163e165. +shows me moving the working tree to the `main` branch (a816...) and then updating from upstream (to 5ef0...). +In this case, bad would be HEAD (or 5ef0bd68b515) and good would be a8163e165c5b. As you can see from the output, HEAD@{1} also often works, but isn't foolproof if you have done other things to your Git tree after updating, but before you discover the need to bisect. ==== @@ -602,11 +625,11 @@ Bisecting: 1722 revisions left to test after this (roughly 11 steps) .... You would then build/install that version. -If it's good you'd type 'git bisect good' otherwise 'git bisect bad'. -If the version doesn't compile, type 'git bisect skip'. +If it's good you'd type `git bisect good` otherwise `git bisect bad`. +If the version doesn't compile, type `git bisect skip`. You will get a similar message to the above after each step. When you are done, report the bad version to the developer (or fix the bug yourself and send a patch). -'git bisect reset' will end the process and return you back to where you started (usually tip of main). +`git bisect reset` will end the process and return you back to where you started (usually tip of `main`). Again, the git-bisect manual (linked above) is a good resource for when things go wrong or for unusual cases. [[git-gpg-signing]] @@ -625,10 +648,10 @@ You can do this by setting a few configuration variables: [source,shell] .... -% git config --add user.signingKey=LONG-KEY-ID -% git config --add commit.gpgSign=true -% git config --add tag.gpgSign=true -% git config --add push.gpgSign=if-asked +% git config --add user.signingKey LONG-KEY-ID +% git config --add commit.gpgSign true +% git config --add tag.gpgSign true +% git config --add push.gpgSign if-asked .... // push.gpgSign should probably be set to `yes` once we enable it, or be set with --global, so that it is enabled for all repositories. @@ -649,7 +672,7 @@ For example, to encrypt for the subkey `DEADBEEF`, use `DEADBEEF!`. Commit signatures can be verified by running either `git verify-commit <commit hash>`, or `git log --show-signature`. -Tag signatures can be verified with `git verity-tag <tag name>`, or `git tag -v <tag name>`. +Tag signatures can be verified with `git verify-tag <tag name>`, or `git tag -v <tag name>`. //// Commented out for now until we decide what to do. @@ -664,12 +687,13 @@ The ports tree operates the same way. The branch names are different and the repositories are in different locations. The cgit repository web interface for use with web browsers is at https://cgit.FreeBSD.org/ports/ . -The production Git repository is at https://git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or anongit@git.FreeBSD.org:ports.git). +The production Git repository is at https://git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or `anongit@git.FreeBSD.org:ports.git`). -There is also a mirror on GitHub, see extref:{handbook}/mirrors[External mirrors, mirrors] for an overview. -The 'current' branch is 'main' . -The quarterly branches are named 'yyyyQn' for year 'yyyy' and quarter 'n'. +There is also a mirror on GitHub, see extref:{handbook}mirrors[External mirrors, mirrors] for an overview. +The _latest_ branch is `main`. +The _quarterly_ branches are named `yyyyQn` for year 'yyyy' and quarter 'n'. +[[port-commit-message-formats]] ===== Commit message formats A hook is available in the ports repository to help you write up your commit messages in https://cgit.freebsd.org/ports/tree/.hooks/prepare-commit-msg[.hooks/prepare-commit-message]. @@ -699,7 +723,7 @@ Another blank line should be added if there are any metadata fields, so that the ==== Managing Local Changes This section addresses tracking local changes. -If you have no local changes, you can stop reading now (it is the last section and OK to skip). +If you have no local changes you can skip this section. One item that is important for all of them: all changes are local until pushed. Unlike Subversion, Git uses a distributed model. @@ -708,16 +732,16 @@ However, if you have local changes, you can use the same tool to manage them as All changes that you have not pushed are local and can easily be modified (git rebase, discussed below does this). ===== Keeping local changes -The simplest way to keep local changes (especially trivial ones) is to use 'git stash'. -In its simplest form, you use 'git stash' to record the changes (which pushes them onto the stash stack). +The simplest way to keep local changes (especially trivial ones) is to use `git stash`. +In its simplest form, you use `git stash` to record the changes (which pushes them onto the stash stack). Most people use this to save changes before updating the tree as described above. -They then use 'git stash apply' to re-apply them to the tree. -The stash is a stack of changes that can be examined with 'git stash list'. +They then use `git stash apply` to re-apply them to the tree. +The stash is a stack of changes that can be examined with `git stash list`. The git-stash man page (https://git-scm.com/docs/git-stash) has all the details. This method is suitable when you have tiny tweaks to the tree. When you have anything non trivial, you'll likely be better off keeping a local branch and rebasing. -Stashing is also integrated with the 'git pull' command: just add '--autostash' to the command line. +Stashing is also integrated with the `git pull` command: just add `--autostash` to the command line. ===== Keeping a local branch [[keeping_a_local_branch]] @@ -728,7 +752,7 @@ Git also allows one to merge, along with the same problems. That's one way to manage the branch, but it's the least flexible. In addition to merging, Git supports the concept of 'rebasing' which avoids these issues. -The 'git rebase' command replays all the commits of a branch at a newer location on the parent branch. +The `git rebase` command replays all the commits of a branch at a newer location on the parent branch. We will cover the most common scenarios that arise using it. ====== Create a branch @@ -765,9 +789,10 @@ The commit will pop you into an editor to describe what you've done. Once you enter that, you have your own **local** branch in the Git repo. Build and install it like you normally would, following the directions in the handbook. Git differs from other version control systems in that you have to tell it explicitly which files to commit. -I have opted to do it on the commit command line, but you can also do it with 'git add' which many of the more in depth tutorials cover. +I have opted to do it on the commit command line, but you can also do it with `git add` which many of the more in depth tutorials cover. ====== Time to update + When it is time to bring in a new version, it is almost the same as w/o the branches. You would update like you would above, but there is one extra command before you update, and one after. The following assumes you are starting with an unmodified tree. @@ -791,7 +816,7 @@ That is OK. Do not panic. Instead, handle them the same as any other merge conflicts. To keep it simple, I will just describe a common issue that may arise. -A pointer to a more complete treatment can be found at the end of this section. +A pointer to a complete treatment can be found at the end of this section. Let's say the includes changes upstream in a radical shift to terminfo as well as a name change for the option. When you updated, you might see something like this: @@ -807,19 +832,22 @@ To abort and get back to the state before "git rebase", run "git rebase --abort" Could not apply 646e0f9cda11... no color ls .... which looks scary. + If you bring up an editor, you will see it is a typical 3-way merge conflict resolution that you may be familiar with from other source code systems (the rest of ls.c has been omitted): [source,shell] .... -<<<<<<< HEAD -#ifdef COLORLS_NEW -#include <terminfo.h> -======= -#undef COLORLS -#ifdef COLORLS -#include <termcap.h> ->>>>>>> 646e0f9cda11... no color ls + <<<<<<< HEAD + #ifdef COLORLS_NEW + #include <terminfo.h> + ======= + #undef COLORLS + #ifdef COLORLS + #include <termcap.h> + >>>>>>> 646e0f9cda11... no color ls .... + The new code is first, and your code is second. + The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then delete the old changes: [source,shell] .... @@ -828,6 +856,7 @@ The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then de #include <terminfo.h> .... save the file. + The rebase was interrupted, so you have to complete it: [source,shell] .... @@ -842,7 +871,7 @@ If the commit message is still accurate, just exit the editor. If you get stuck during the rebase, do not panic. git rebase --abort will take you back to a clean slate. It is important, though, to start with an unmodified tree. -An aside: The above mentioned 'git reflog' comes in handy here, as it will have a list of all the (intermediate) commits that you can view or inspect or cherry-pick. +An aside: The above mentioned `git reflog` comes in handy here, as it will have a list of all the (intermediate) commits that you can view or inspect or cherry-pick. For more on this topic, https://www.freecodecamp.org/news/the-ultimate-guide-to-git-merge-and-git-rebase/ provides a rather extensive treatment. It is a good resource for issues that arise occasionally but are too obscure for this guide. @@ -858,7 +887,7 @@ If you have a deep clone, the following will suffice: If you have a local branch, though, there are one or two caveats. First, rebase will rewrite history, so you will likely want to do something to save it. Second, jumping branches tends to cause more conflicts. -If we pretend the example above was relative to stable/12, then to move to main, I'd suggest the following: +If we pretend the example above was relative to stable/12, then to move to `main`, I'd suggest the following: [source,shell] .... % git checkout no-color-ls @@ -868,50 +897,9 @@ If we pretend the example above was relative to stable/12, then to move to main, What the above does is checkout no-color-ls. Then create a new name for it (no-color-ls-stable-12) in case you need to get back to it. -Then you rebase onto the main branch. +Then you rebase onto the `main` branch. This will find all the commits to the current no-color-ls branch (back to where it meets up with the stable/12 branch) and then it will -replay them onto the main branch creating a new no-color-ls branch there (which is why I had you create a place holder name). - -===== Migrating from an existing Git clone -If you have work based on a previous Git conversion or a locally running git-svn conversion, migrating to new repository can encounter problems because Git has no knowledge about the connection between the two. - -When you have only a few local changes, the easiest way would be to cherry-pick those changes to the new base: -[source,shell] -.... -% git checkout main -% git cherry-pick old_branch..your_branch -.... -Or alternatively, do the same thing with rebase: -[source,shell] -.... -% git rebase --onto main master your_branch -.... - -If you do have a lot of changes, you would probably want to perform a merge instead. -The idea is to create a merge point that consolidates the history of the old_branch, and the new FreeBSD repository (main). - -You can find out by looking up the same commit that are found on both parents: -[source,shell] -.... -% git show old_branch -.... -You will see a commit message, now search for that in the new branch: -[source,shell] -.... -% git log --grep="commit message on old_branch" freebsd/main -.... -You would help locate the commit hash on the new main branch, create a helper branch (in the example we call it 'stage') from that hash: -[source,shell] -.... -% git checkout -b stage _hash_found_from_git_log_ -.... -Then perform a merge of the old branch: -[source,shell] -.... -% git merge -s ours -m "Mark old branch as merged" old_branch -.... -With that, it's possible to merge your work branch or the main branch in any order without problem. -Eventually, when you are ready to commit your work back to main, you can perform a rebase to main, or do a squash commit by combining everything into one commit. +replay them onto the `main` branch creating a new no-color-ls branch there (which is why I had you create a place holder name). [[mfc-with-git]] === MFC (Merge From Current) Procedures @@ -994,9 +982,9 @@ Once the MFC is complete, you can delete the temporary branch: ==== MFC a vendor import -Vendor imports are the only thing in the tree that creates a merge commit in the main line. +Vendor imports are the only thing in the tree that creates a merge commit in the `main` branch. Cherry picking merge commits into stable/XX presents an additional difficulty because there are two parents for a merge commit. -Generally, you'll want the first parent's diff since that's the diff to mainline (though there may be some exceptions). +Generally, you'll want the first parent's diff since that's the diff to `main` (though there may be some exceptions). [source,shell] .... @@ -1005,9 +993,9 @@ Generally, you'll want the first parent's diff since that's the diff to mainline is typically what you want. This will tell cherry-pick to apply the correct diff. -There are some, hopefully, rare cases where it's possible that the mainline was merged backwards by the conversion script. -Should that be the case (and we've not found any yet), you'd change the above to '-m 2' to pickup the proper parent. -Just do +There are some, hopefully, rare cases where it's possible that the `main` branch was merged backwards by the conversion script. +Should that be the case (and we've not found any yet), you'd change the above to `-m 2` to pickup the proper parent. +Just do: [source,shell] .... % git cherry-pick --abort @@ -1024,7 +1012,7 @@ then the easiest way is to use `git reset --hard` like so: % git reset --hard freebsd/stable/12 .... though if you have some revs you want to keep, and others you don't, -using 'git rebase -i' is better. +using `git rebase -i` is better. ==== Considerations when MFCing @@ -1036,7 +1024,7 @@ When committing source commits to stable and releng branches, we have the follow With Subversion, we used the following practices to achieve these goals: -* Using 'MFC' and 'MFS' tags to mark commits that merged changes from another branch. +* Using `MFC` and `MFS` tags to mark commits that merged changes from another branch. * Squashing fixup commits into the main commit when merging a change. * Recording mergeinfo so that `svn mergeinfo --show-revs` worked. @@ -1051,17 +1039,8 @@ Instead, when this document refers to "merge commits", it means a commit origina Git provides some built-in support for this via the `git cherry` and `git log --cherry` commands. These commands compare the raw diffs of commits (but not other metadata such as log messages) to determine if two commits are identical. -This works well when each commit from head is landed as a single commit to a stable branch, but it falls over if multiple commits from main are squashed together as a single commit to a stable branch. - -There are a few options for resolving this: - -1. We could ban squashing of commits and instead require that committers stage all of the fixup / follow-up commits to stable into a single push. -This would still achieve the goal of stability in stable and releng branches since pushes are atomic and users doing a simple pull will never end up with a tree that has the main commit without the fixup(s). -`git bisect` is also able to cope with this model via `git bisect skip`. - -2. We could adopt a consistent style for describing MFCs and write our own tooling to wrap around `git cherry` to determine the list of eligible commits. -A simple approach here might be to use the syntax from `git cherry-pick -x`, but require that a squashed commit list all of the hashes (one line per hash) at the end of the commit message. -Developers could do this by using `git cherry-pick -x` of each individual commit into a branch and then use `git rebase` to squash the commits down into a single commit, but collecting the `-x` annotations at the end of the landed commit log. +This works well when each commit from `main` is landed as a single commit to a stable branch, but it falls over if multiple commits from `main` are squashed together as a single commit to a stable branch. +The project makes extensive use of `git cherry-pick -x` with all lines preserved to work around these difficulties and is working on automated tooling to take advantage of this. ==== Commit message standards ===== Marking MFCs @@ -1080,7 +1059,7 @@ Should it include the metadata from the original commit unchanged, or should it Historical practice has varied, though some of the variance is by field. For example, MFCs that are relevant to a PR generally include the PR field in the MFC so that MFC commits are included in the bug tracker's audit trail. Other fields are less clear. -For example, Phabricator shows the diff of the last commit tagged to a review, so including Phabricator URLs replaces the `main` commit with the landed commits. +For example, Phabricator shows the diff of the last commit tagged to a review, so including Phabricator URLs replaces the main commit with the landed commits. The list of reviewers is also not clear. If a reviewer has approved a change to `main`, does that mean they have approved the MFC commit? Is that true if it's identical code only, or with merely trivial rework? It's clearly not true for more extensive reworks. Even for identical code what if the commit doesn't conflict but introduces an ABI change? A reviewer may have ok'd a commit for `main` due to the ABI breakage but may not approve of merging the same commit as-is. @@ -1091,268 +1070,13 @@ This new metadata will have to be added via `git commit --amend` or similar afte We may also want to reserve some metadata fields in MFC commits such as Phabricator URLs for use by re@ in the future. Preserving existing metadata provides a very simple workflow. -Developers can just use `git cherry-pick -x` without having to edit the log message. +Developers use `git cherry-pick -x` without having to edit the log message. If instead we choose to adjust metadata in MFCs, developers will have to edit log messages explicitly via the use of `git cherry-pick --edit` or `git commit --amend`. However, as compared to svn, at least the existing commit message can be pre-populated and metadata fields can be added or removed without having to re-enter the entire commit message. The bottom line is that developers will likely need to curate their commit message for MFCs that are non-trivial. -==== Examples - -===== Merging a Single Subversion Commit - -This walks through the process of merging a commit to stable/12 that was originally committed to head in Subversion. -In this case, the original commit is r368685. - -The first step is to map the Subversion commit to a Git hash. -Once you have fetched refs/notes/commits, you can pass the revision number to `git log --grep`: - -[source,shell] -.... -% git log main --grep 368685 -commit ce8395ecfda2c8e332a2adf9a9432c2e7f35ea81 -Author: John Baldwin <jhb@FreeBSD.org> -Date: Wed Dec 16 00:11:30 2020 +0000 - - Use the 't' modifier to print a ptrdiff_t. - - Reviewed by: imp - Obtained from: CheriBSD - Sponsored by: DARPA - Differential Revision: https://reviews.freebsd.org/D27576 - -Notes: - svn path=/head/; revision=368685 -.... - -Next, MFC the commit to a `stable/12` checkout: - -[source,shell] -.... -git checkout stable/12 -git cherry-pick -x ce8395ecfda2c8e332a2adf9a9432c2e7f35ea81 --edit -.... - -Git will invoke the editor. -Use this to remove the metadata that only applied to the original commit (Phabricator URL and Reviewed by). -After the editor saves the updated log message, Git completes the commit: - -[source,shell] -.... -[stable/12 3e3a548c4874] Use the 't' modifier to print a ptrdiff_t. - Date: Wed Dec 16 00:11:30 2020 +0000 - 1 file changed, 1 insertion(+), 1 deletion(-) -.... - -The contents of the MFCd commit can be examined via `git show`: - -[source,shell] -.... -% git show -commit 3e3a548c487450825679e4bd63d8d1a67fd8bd2d (HEAD -> stable/12) -Author: John Baldwin <jhb@FreeBSD.org> -Date: Wed Dec 16 00:11:30 2020 +0000 - - Use the 't' modifier to print a ptrdiff_t. - - Obtained from: CheriBSD - Sponsored by: DARPA - - (cherry picked from commit ce8395ecfda2c8e332a2adf9a9432c2e7f35ea81) - -diff --git a/sys/compat/linuxkpi/common/include/linux/printk.h b/sys/compat/linuxkpi/common/include/linux/printk.h -index 31802bdd2c99..e6510e9e9834 100644 ---- a/sys/compat/linuxkpi/common/include/linux/printk.h -+++ b/sys/compat/linuxkpi/common/include/linux/printk.h -@@ -68,7 +68,7 @@ print_hex_dump(const char *level, const char *prefix_str, - printf("[%p] ", buf); - break; - case DUMP_PREFIX_OFFSET: -- printf("[%p] ", (const char *)((const char *)buf - -+ printf("[%#tx] ", ((const char *)buf - - (const char *)buf_old)); - break; - default: -.... - -The MFC commit can now be published via `git push` - -[source,shell] -.... -% git push freebsd -Enumerating objects: 17, done. -Counting objects: 100% (17/17), done. -Delta compression using up to 4 threads -Compressing objects: 100% (7/7), done. -Writing objects: 100% (9/9), 817 bytes | 204.00 KiB/s, done. -Total 9 (delta 5), reused 1 (delta 1), pack-reused 0 -To gitrepo-dev.FreeBSD.org:src.git - 525bd9c9dda7..3e3a548c4874 stable/12 -> stable/12 -.... - -===== Merging a Single Subversion Commit with a Conflict - -This example is similar to the previous example except that the commit in question encounters a merge conflict. -In this case, the original commit is r368314. - -As above, the first step is to map the Subversion commit to a Git hash: - -[source,shell] -.... -% git log main --grep 368314 -commit 99963f5343a017e934e4d8ea2371a86789a46ff9 -Author: John Baldwin <jhb@FreeBSD.org> -Date: Thu Dec 3 22:01:13 2020 +0000 - - Don't transmit mbufs that aren't yet ready on TOE sockets. - - This includes mbufs waiting for data from sendfile() I/O requests, or - mbufs awaiting encryption for KTLS. - - Reviewed by: np - MFC after: 2 weeks - Sponsored by: Chelsio Communications - Differential Revision: https://reviews.freebsd.org/D27469 - -Notes: - svn path=/head/; revision=368314 -.... - -Next, MFC the commit to a `stable/12` checkout: - -[source,shell] -.... -% git checkout stable/12 -% git cherry-pick -x 99963f5343a017e934e4d8ea2371a86789a46ff9 --edit -Auto-merging sys/dev/cxgbe/tom/t4_cpl_io.c -CONFLICT (content): Merge conflict in sys/dev/cxgbe/tom/t4_cpl_io.c -warning: inexact rename detection was skipped due to too many files. -warning: you may want to set your merge.renamelimit variable to at least 7123 and retry the command. -error: could not apply 99963f5343a0... Don't transmit mbufs that aren't yet ready on TOE sockets. -hint: after resolving the conflicts, mark the corrected paths -hint: with 'git add <paths>' or 'git rm <paths>' -hint: and commit the result with 'git commit' -.... - -In this case, the commit encountered a merge conflict in sys/dev/cxge/tom/t4_cpl_io.c as kernel TLS is not present in stable/12. -Note that Git does not invoke an editor to adjust the commit message due to the conflict. -`git status` confirms that this file has merge conflicts: - -[source,shell] -.... -% git status -On branch stable/12 -Your branch is up to date with 'upstream/stable/12'. - -You are currently cherry-picking commit 99963f5343a0. - (fix conflicts and run "git cherry-pick --continue") - (use "git cherry-pick --skip" to skip this patch) - (use "git cherry-pick --abort" to cancel the cherry-pick operation) - -Unmerged paths: - (use "git add <file>..." to mark resolution) - both modified: sys/dev/cxgbe/tom/t4_cpl_io.c - -no changes added to commit (use "git add" and/or "git commit -a") -.... - -After editing the file to resolve the conflict, `git status` shows the conflict as resolved: - -[source,shell] -.... -% git status -On branch stable/12 -Your branch is up to date with 'upstream/stable/12'. - -You are currently cherry-picking commit 99963f5343a0. - (all conflicts fixed: run "git cherry-pick --continue") - (use "git cherry-pick --skip" to skip this patch) - (use "git cherry-pick --abort" to cancel the cherry-pick operation) - -Changes to be committed: - modified: sys/dev/cxgbe/tom/t4_cpl_io.c -.... - -The cherry-pick can now be completed: - -[source,shell] -.... -% git cherry-pick --continue -.... - -Since there was a merge conflict, Git invokes the editor to adjust the commit message. -Trim the metadata fields from the commit log from the original commit to head and save the updated log message. - -The contents of the MFC commit can be examined via `git show`: - -[source,shell] -.... -% git show -commit 525bd9c9dda7e7c7efad2d4570c7fd8e1a8ffabc (HEAD -> stable/12) -Author: John Baldwin <jhb@FreeBSD.org> -Date: Thu Dec 3 22:01:13 2020 +0000 - - Don't transmit mbufs that aren't yet ready on TOE sockets. - - This includes mbufs waiting for data from sendfile() I/O requests, or - mbufs awaiting encryption for KTLS. - - Sponsored by: Chelsio Communications - - (cherry picked from commit 99963f5343a017e934e4d8ea2371a86789a46ff9) - -diff --git a/sys/dev/cxgbe/tom/t4_cpl_io.c b/sys/dev/cxgbe/tom/t4_cpl_io.c -index 8e8c2b8639e6..43861f10b689 100644 ---- a/sys/dev/cxgbe/tom/t4_cpl_io.c -+++ b/sys/dev/cxgbe/tom/t4_cpl_io.c -@@ -746,6 +746,8 @@ t4_push_frames(struct adapter *sc, struct toepcb *toep, int drop) - for (m = sndptr; m != NULL; m = m->m_next) { - int n; - -+ if ((m->m_flags & M_NOTAVAIL) != 0) -+ break; - if (IS_AIOTX_MBUF(m)) - n = sglist_count_vmpages(aiotx_mbuf_pages(m), - aiotx_mbuf_pgoff(m), m->m_len); -@@ -821,8 +823,9 @@ t4_push_frames(struct adapter *sc, struct toepcb *toep, int drop) - - /* nothing to send */ - if (plen == 0) { -- KASSERT(m == NULL, -- ("%s: nothing to send, but m != NULL", __func__)); -+ KASSERT(m == NULL || (m->m_flags & M_NOTAVAIL) != 0, -+ ("%s: nothing to send, but m != NULL is ready", -+ __func__)); - break; - } - -@@ -910,7 +913,7 @@ t4_push_frames(struct adapter *sc, struct toepcb *toep, int drop) - toep->txsd_avail--; - - t4_l2t_send(sc, wr, toep->l2te); -- } while (m != NULL); -+ } while (m != NULL && (m->m_flags & M_NOTAVAIL) == 0); - - /* Send a FIN if requested, but only if there's no more data to send */ - if (m == NULL && toep->flags & TPF_SEND_FIN) -.... - -The MFC commit can now be published via `git push` - -[source,shell] -.... -git push freebsd -Enumerating objects: 13, done. -Counting objects: 100% (13/13), done. -Delta compression using up to 4 threads -Compressing objects: 100% (7/7), done. -Writing objects: 100% (7/7), 819 bytes | 117.00 KiB/s, done. -Total 7 (delta 6), reused 0 (delta 0), pack-reused 0 -To gitrepo.FreeBSD.org:src.git - f4d0bc6aa6b9..525bd9c9dda7 stable/12 -> stable/12 -.... - [[vendor-import-git]] === Vendor Imports with Git @@ -1406,8 +1130,24 @@ package:net/rsync[] is commonly installed, so I'll use that. % git tag -a vendor/NetBSD/mtree/20201211 .... -Note: I run the `git diff` and `git status` commands to make sure nothing weird was present. -Also I used `-m` to illustrate, but you should compose a proper message in an editor (using a commit message template). +It is critical to verify that the source code you are importing comes from a +trustworthy source. Many open-source projects use cryptographic signatures to +sign code changes, git tags, and/or source code tarballs. Always verify these +signatures, and use isolation mechanisms like jails, chroot, in combination with +a dedicated, non-privileged user account that is different from the one you +regularly use (see the Updating the FreeBSD source tree section below for +more details), until you are confident that the source code you are importing +looks safe. Following the upstream development and occasionally reviewing the +upstream code changes can greatly help in improving code quality and benefit +everyone involved. It is also a good idea to examine the git diff results +before importing them into the vendor area. + +Always run the `git diff` and `git status` commands and examine the results +carefully. When in doubt, it is useful to do a `git annotate` on the vendor +branch or the upstream git repository to see who and why a change was made. + +In the example above we used `-m` to illustrate, but you should compose a +proper message in an editor (using a commit message template). It is also important to create an annotated tag using `git tag -a`, otherwise the push will be rejected. Only annotated tags are allowed to be pushed. @@ -1430,6 +1170,12 @@ At this point you can push the import to `vendor` into our repo. Now you need to update the mtree in FreeBSD. The sources live in `contrib/mtree` since it is upstream software. +From time to time, we may have to make changes to the contributed code to +better satisfy FreeBSD's needs. Whenever possible, please try to contribute +the local changes back to the upstream projects, this helps them to better +support FreeBSD, and also saves your time for future conflict resolutions +when importing updates. + [source,shell] .... % cd ../src @@ -1437,9 +1183,35 @@ The sources live in `contrib/mtree` since it is upstream software. .... This would generate a subtree merge commit of `contrib/mtree` against the local `vendor/NetBSD/mtree` branch. +Examine the diff from the merge result and the contents of the +upstream branch. If the merge reduced our local changes to more +trivial difference like blank line or indenting changes, try amending +the local changes to reduce diff against upstream, or try to +contribute the remaining changes back to the upstream project. If there were conflicts, you would need to fix them before committing. Include details about the changes being merged in the merge commit message. +Some open-source software includes a `configure` script that generates files +used to define how the code is built; usually, these generated files like +`config.h` should be updated as part of the import process. When doing +this, always keep in mind that these scripts are executable code running +under the current user's credentials. This process should always be run +in an isolated environment, ideally inside a jail that does not have +network access, and with an unprivileged account; or, at minimum, a +dedicated account that is different from the user account you normally +use for everyday purposes or for pushing to the FreeBSD source +code repository. This minimizes the risk of encountering bugs that can +cause data loss or, in worse cases, maliciously planted code. Using an +isolated jail also prevents the configure scripts from detecting locally +installed software packages, which may lead to unexpected results. + +When testing your changes, run them in a chroot or jailed environment, +or even within a virtual machine first, especially for kernel or library +modifications. This approach helps prevent adverse interactions with +your working environment. It can be particularly beneficial for +changes to libraries that many base system components use, +among others. + ==== Rebasing your change against latest FreeBSD source tree Because the current policy recommends against using merges, if the upstream FreeBSD `main` moved forward before you get a chance to push, you would have to redo the merge. @@ -1447,56 +1219,85 @@ Because the current policy recommends against using merges, if the upstream Free Regular `git rebase` or `git pull --rebase` doesn't know how to rebase a merge commit **as a merge commit**, so instead of that you would have to recreate the commit. -The easiest way to do this would be to create a side branch with the **contents** of the merged tree: +The following steps should be taken to easily recreate the merge commit as if `git rebase --merge-commits` worked properly: -[source,shell] -.... -% cd ../src -% git fetch freebsd -% git checkout -b merge_result -% git merge freebsd/main -.... - -Typically, there would be no merge conflicts here (because developers tend to work on different components). -In the worst case scenario, you would still have to resolve merge conflicts, if there was any, but this should be really rare. +* cd to the top of the repo +* Create a side branch `XXX` with the **contents** of the merged tree. +* Update this side branch `XXX` to be merged and up-to-date with FreeBSD's `main` branch. +** In the worst case scenario, you would still have to resolve merge conflicts, if there was any, but this should be really rare. +** Resolve conflicts, and collapse multiple commits down to 1 if need be (without conflicts, there's no collapse needed) +* checkout `main` +* create a branch `YYY` (allows for easier unwinding if things go wrong) +* Re-do the subtree merge +* Instead of resolving any conflicts from the subtree merge, checkout the contents of XXX on top of it. +** The trailing `.` is important, as is being at the top level of the repo. +** Rather than switching branches to XXX, it splats the contents of XXX on top of the repo +* Commit the results with the prior commit message (the example assumes there's only one merge on the XXX branch). +* Make sure the branches are the same. +* Do whatever review you need, including having others check it out if you think that's needed. +* Push the commit, if you 'lost the race' again, just redo these steps again (see below for a recipe) +* Delete the branches once the commit is upstream. They are throw-a-way. -Now, checkout `freebsd/main` again as `new_merge`, and redo the merge: +The commands one would use, following the above example of mtree, would be like so (the `#` starts a comment to help link commands to descriptions above): [source,shell] .... -% git checkout -b new_merge freebsd/main -% git subtree merge -P contrib/mtree vendor/NetBSD/mtree +% cd ../src # CD to top of tree +% git checkout -b XXX # create new throw-away XXX branch for merge +% git fetch freebsd # Get changes from upstream from upstream +% git merge freebsd/main # Merge the changes and resolve conflicts +% git checkout -b YYY freebsd/main # Create new throw-away YYY branch for redo +% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree merge +% git checkout XXX . # XXX branch has the conflict resolution +% git commit -c XXX~1 # -c reuses the commit message from commit before rebase +% git diff XXX YYY # Should be empty +% git show YYY # Should only have changes you want, and be a merge commit from vendor branch .... -Instead of resolving the conflicts, perform this instead: - +Note: if things go wrong with the commit, you can reset the `YYY` branch by reissuing the checkout command that created it with -B to start over: [source,shell] .... -% git checkout merge_result . +% git checkout -B YYY freebsd/main # Create new throw-away YYY branch if starting over is just going to be easier .... -Which will overwrite the files with conflicts with the version found in `merge_result`. +==== Pushing the changes -Examine the tree against `merge_result` to make sure that you haven't missed deleted files: +Once you think you have a set of changes that are good, you can push it to a fork off GitHub or GitLab for others to review. +One nice thing about Git is that it allows you to publish rough drafts of your work for others to review. +While Phabricator is good for content review, publishing the updated vendor branch and merge commits lets others check the details as they will eventually appear in the repository. + +After review, when you are sure it is a good change, you can push it to the FreeBSD repo: [source,shell] .... -% git diff merge_result +% git push freebsd YYY:main # put the commit on upstream's 'main' branch +% git branch -D XXX # Throw away the throw-a-way branches. +% git branch -D YYY .... -==== Pushing the changes +Note: I used `XXX` and `YYY` to make it obvious they are terrible names and should not leave your machine. +If you use such names for other work, then you'll need to pick different names, or risk losing the other work. +There is nothing magic about these names. +Upstream will not allow you to push them, but never the less, please pay attention to the exact commands above. +Some commands use syntax that differs only slightly from typical uses and that different behavior is critical to this recipe working. -Once you are sure that you have a set of deltas you think is good, you can push it to a fork off GitHub or GitLab for others to review. -One nice thing about Git is that it allows you to publish rough drafts of your work for others to review. -While Phabricator is good for content review, publishing the updated vendor branch and merge commits lets others check the details as they will eventually appear in the repository. +==== How to redo things if need be -After review, when you are sure it is a good change, you can push it to the FreeBSD repo: +If you've tried to do the push in the previous section and it fails, then you should do the following to 'redo' things. +This sequence keeps the commit with the commit message always at XXX~1 to make committing easier. [source,shell] .... -% git push freebsd main +% git checkout -B XXX YYY # recreate that throw-away-branch XXX and switch to it +% git merge freebsd/main # Merge the changes and resolve conflicts +% git checkout -B YYY freebsd/main # Recreate new throw-away YYY branch for redo +% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree merge +% git checkout XXX . # XXX branch has the conflict resolution +% git commit -c XXX~1 # -c reuses the commit message from commit before rebase .... +Then go check it out as above and push as above when ready. + === Creating a new vendor branch There are a number of ways to create a new vendor branch. @@ -1539,7 +1340,8 @@ At this point, you should have a pristine copy of glorbnitz ready to commit. .... As above, I used `-m` for simplicity, but you should likely create a commit message that explains what a Glorb is and why you'd use a Nitz to get it. -Not everybody will know so, for your actual commit, you should follow the <<commit-log-message,commit log message>> section instead of emulating the brief style used here. +Not everybody will know so, for your actual commit, you should follow the +crossref:committers-guide[commit-log-message,commit log message] section instead of emulating the brief style used here. ==== Now import it into our repository @@ -1592,8 +1394,8 @@ Here 'good' means: . All the right files, and none of the wrong ones, were merged into contrib/glorbnitz. . No other changes are in the tree. -. The commit messages look <<commit-log-message,good>>. It should contain a summary of what's changed since the last merge to the FreeBSD main line and any caveats. -. UPDATING should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc. +. The commit messages look crossref:committers-guide[commit-log-message,good]. It should contain a summary of what's changed since the last merge to the FreeBSD `main` branch and any caveats. +. `RELNOTES` and `UPDATING` should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc. [NOTE] ==== @@ -1601,90 +1403,6 @@ This hasn't connected `glorbnitz` to the build yet. How so do that is specific to the software being imported and is beyond the scope of this tutorial. ==== -=== FreeBSD Src Committer Transition Guide - -This section is designed to walk people through the conversion process from Subversion to Git, written from the source committer's point of view. - -==== Migrating from a Subversion tree - -This section will cover a couple of common scenarios for migrating from using the FreeBSD Subversion repo to the FreeBSD source Git repo. -The FreeBSD Git conversion is still in beta status, so some minor things may change between this and going into production. - -The first thing to do is install Git. Any version of Git will do, though the latest one in ports / packages generally will be good. -Either build it from ports, or install it using pkg (though some folks might use `su` or `doas` instead of `sudo`): - -[source,shell] -.... -% sudo pkg install git -.... - -===== No staged changes migration - -If you have no changes pending, the migration is straightforward. -In this, you abandon the Subversion tree and clone the Git repository. -It's likely best to retain your Subversion tree, in case there's something you've forgotten about there. -First, let's clone the repository: - -[source,shell] -.... -% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/src.git freebsd-src -.... - -will create a clone of the FreeBSD src repository into a subdirectory called `freebsd-src` and include the 'notes' about the revisions. -We are currently mirroring the source repository to https://github.com/freebsd/freebsd-src.git as well. -https://github.com/freebsd/freebsd-legacy.git has the old GitHub mirror with the old hashes should you need that for your migration. -The GitHub `master` branch has been frozen. -As the default in Git has changed, we've shifted from `master` to `main`; the new repository uses `main`. -We also mirror the repository to GitLab at https://gitlab.com/FreeBSD/src.git . - -It's useful to have the old Subversion revisions available. -This data is stored using Git notes, but Git doesn't fetch those by default. -The --config and the argument above changed the default to fetch the notes. -If you've cloned the repository without this, or wish to add notes to a previously cloned repository, use the following commands: - -[source,shell] -.... -% git config --add remote.freebsd.fetch "+refs/notes/*:refs/notes/*" -% git fetch -.... - -At this point you have the src checked out into a Git tree, ready to do other things. - -===== But I have changes that I've not committed - -If you are migrating from a tree that has changes you've not yet committed to FreeBSD, you'll need to follow the steps from the previous section first, and then follow these. - -[source,shell] -.... -% cd path-to-svn-checkout-tree -% svn diff > /tmp/src.diff -% cd _mumble_/freebsd-src -% git checkout -b working -.... - -This will create a diff of your current changes. -The last command creates a branch called `working` though you can call it whatever you want. - -[source,shell] -.... -% git apply /tmp/src.diff -.... - -this will apply all your pending changes to the working tree. -This doesn't commit the change, so you'll need to make this permanent: - -[source,shell] -.... -% git add _files_ -% git commit -.... - -The last command will commit these changes to the branch. -The editor will prompt you for a commit message. -Enter one as if you were committing to FreeBSD. - -At this point, your work is preserved, and in the Git repository. - ===== Keeping current So, time passes. @@ -1693,7 +1411,7 @@ When you checkout `main` make sure that you have no diffs. It's a lot easier to commit those to a branch (or use `git stash`) before doing the following. If you are used to `git pull`, we strongly recommend using the `--ff-only` option, and further setting it as the default option. -Alternatively, `git pull --rebase` is useful if you have changes staged in the main branch. +Alternatively, `git pull --rebase` is useful if you have changes staged in the `main` branch. [source,shell] .... @@ -1722,7 +1440,7 @@ The longer form is also recommended. % git merge --ff-only freebsd/main .... -These commands reset your tree to the main branch, and then update it from where you pulled the tree from originally. +These commands reset your tree to the `main` branch, and then update it from where you pulled the tree from originally. It's important to switch to `main` before doing this so it moves forward. Now, it's time to move the changes forward: @@ -1759,9 +1477,9 @@ freefall% gen-gitconfig.sh on freefall.freebsd.org to get a recipe that you can use directly, assuming /usr/local/bin is in the PATH. -The below command merges the `working` branch into the upstream main line. +The below command merges the `working` branch into the upstream `main` branch. It's important that you curate your changes to be just like you want them in the FreeBSD source repo before doing this. -This syntax pushes the `working` branch to main, moving the `main` branch forward. +This syntax pushes the `working` branch to `main`, moving the `main` branch forward. You will only be able to do this if this results in a linear change to `main` (e.g. no merges). [source,shell] @@ -1803,7 +1521,7 @@ Note: merging vendor branch commits will not work with this technique. ===== Finding the Subversion Revision -You'll need to make sure that you've fetched the notes (see the `No staged changes migration` section above for details. +You'll need to make sure that you've fetched the notes (see the crossref:committers-guide[git-mini-daily-use, Daily use]for details). Once you have these, notes will show up in the git log command like so: [source,shell] @@ -1821,51 +1539,6 @@ If you have a specific version in mind, you can use this construct: to find the specific revision. The hex number after 'commit' is the hash you can use to refer to this commit. -==== Migrating from GitHub fork - -Note: as of this writing, https://github.com/freebsd/freebsd-src is mirroring all official branches, along with a `master` branch which is the legacy svn2git result. -The `master` branch will not be updated anymore, and the link:https://github.com/freebsd/freebsd-src/commit/de1aa3dab23c06fec962a14da3e7b4755c5880cf[last commit] contains the instructions for migrating to the new `main` branch. -We'll retain the `master` branch for a certain time, but in the future it will only be kept in the link:https://github.com/freebsd/freebsd-legacy[freebsd-legacy] repository. -In addition, link:https://github.com/freebsd/git_conv/wiki/Migrating-merge-based-project-from-legacy-git-tree[this article] has an earlier version of the last commit instructions that may be helpful. - -When migrating branches from a GitHub fork from the old GitHub mirror to the official repo, the process is straight forward. -This assumes that you have a `freebsd` upstream pointing to GitHub, adjust if necessary. -This also assumes a clean tree before starting... - -===== Add the new `freebsd` upstream repository: - -[source,shell] -.... -% git remote add freebsd https://git.freebsd.org/src.git -% git fetch freebsd -% git checkout --track freebsd/main -.... - -===== Rebase all your WIP branches. - -For each branch FOO, do the following after fetching the `freebsd` sources and creating a local `main` branch with the above checkout: - -[source,shell] -.... -% git rebase -i freebsd/master FOO --onto main -.... - -And you'll now be tracking the official repository. -You can then follow the `Keeping Current` section above to stay up to date. - -If you need to then commit work to FreeBSD, you can do so following the `Time to push changes upstream` instructions. -You'll need to do the following once to update the push URL if you are a FreeBSD committer: - -[source,shell] -.... -% git remote set-url --push freebsd ssh://git@gitrepo.freebsd.org/src.git -.... - -(note that gitrepo.freebsd.org will be change to repo.freebsd.org in the future.) - -You will also need to add `freebsd` as the location to push to. -The author recommends that your upstream GitHub repository remain the default push location so that you only push things into FreeBSD you intend to by making it explicit. - [[git-faq]] === Git FAQ @@ -1925,9 +1598,9 @@ Here's https://adventurist.me/posts/00296[a good writeup] that goes into more de ==== Developers -===== Ooops! I committed to `main` instead of a branch. +===== Ooops! I committed to `main`, instead of another branch. -**Q:** From time to time, I goof up and commit to main instead of to a branch. What do I do? +**Q:** From time to time, I goof up and mistakenly commit to the `main` branch. What do I do? **A:** First, don't panic. @@ -1939,9 +1612,9 @@ The following answer assumes you committed to `main` and want to create a branch [source,shell] .... -% git branch issue # Create the 'issue' branch -% git reset --hard freebsd/main # Reset 'main' back to the official tip -% git checkout issue # Back to where you were +% git checkout -b issue # Create the 'issue' branch +% git checkout -B main freebsd/main # Reset main to upstream +% git checkout issue # Back to where you were .... ===== Ooops! I committed something to the wrong branch! @@ -1962,13 +1635,20 @@ It also assumes that it's the last commit on wilma (hence using wilma in the `gi % git reset --hard HEAD^ # move what wilma refers to back 1 commit .... -Git experts would first rewind the wilma branch by 1 commit, switch over to fred and then use `git reflog` to see what that 1 deleted commit was and -cherry-pick it over. +If it is not the last commit, you can cherry-pick that one change from wilma onto fred, then use `git rebase -i` to remove the change from wilma. + +[source,shell] +.... +# We're on branch wilma +% git checkout fred # move to fred branch +% git cherry-pick HASH_OF_CHANGE # copy the misplaced commit +% git rebase -i main wilma # drop the cherry-picked change +.... **Q:** But what if I want to commit a few changes to `main`, but keep the rest in `wilma` for some reason? **A:** The same technique above also works if you are wanting to 'land' parts of the branch you are working on into `main` before the rest of the branch is ready (say you noticed an unrelated typo, or fixed an incidental bug). -You can cherry pick those changes into main, then push to the parent repository. +You can cherry pick those changes into `main`, then push to the parent repository. Once you've done that, cleanup couldn't be simpler: just `git rebase -i`. Git will notice you've done this and skip the common changes automatically (even if you had to change the commit message or tweak the commit slightly). There's no need to switch back to wilma to adjust it: just rebase! @@ -2045,8 +1725,8 @@ You can also stack: .... and you are ready to try again. -The 'checkout -B' with the hash combines checking out and creating a branch for it. -The -B instead of -b forces the movement of a pre-existing branch. +The `checkout -B` with the hash combines checking out and creating a branch for it. +The `-B` instead of `-b` forces the movement of a pre-existing branch. Either way works, which is what's great (and awful) about Git. One reason I tend to use `git checkout -B xxxx hash` instead of checking out the hash, and then creating / moving the branch is purely to avoid the slightly distressing message about detached heads: @@ -2073,11 +1753,13 @@ this produces the same effect, but I have to read a lot more and severed heads a ===== Ooops! I did a `git pull` and it created a merge commit, what do I do? -**Q:** I was on autopilot and did a `git pull` for my development tree and that created a merge commit on the mainline. +**Q:** I was on autopilot and did a `git pull` for my development tree and that created a merge commit on `main`. How do I recover? **A:** This can happen when you invoke the pull with your development branch checked out. +Many developers use `git pull --rebase` to avoid this situation. + Right after the pull, you will have the new merge commit checked out. Git supports a `HEAD^#` syntax to examine the parents of a merge commit: @@ -2092,9 +1774,11 @@ Then you simply reset your branch to the corresponding `HEAD^#`: [source,shell] .... -git reset --hard HEAD^2 +git reset --hard HEAD^1 .... +In addition, a `git pull --rebase` at this stage will rebase your changes to 'main' to the latest 'freebsd/main'. + **Q:** But I also need to fix my `main` branch. How do I do that? **A:** Git keeps track of the remote repository branches in a `freebsd/` namespace. @@ -2207,6 +1891,14 @@ Once you're done, `git commit` and you'll have the remainder in your tree. You can run it multiple times as well, and even over multiple files (though I find it easier to do one file at a time and use the `git rebase -i` to fold the related commits together). +===== Joining the FreeBSD GitHub oranization. + +**Q:** How do I join the FreeBSD GitHub organization? + +**A:** Please see https://wiki.freebsd.org/GitHub#Joining_the_Organisation[our GitHub Wiki Info] page for details. +Briefly, all FreeBSD committers may join. +Those who are not committers who request joining will be considered on a case by case basis. + ==== Cloning and Mirroring **Q:** I'd like to mirror the entire Git repository, how do I do that? @@ -2223,7 +1915,7 @@ However, there are two disadvantages to this if you want to use it for anything First, this is a 'bare repository' which has the repository database, but no checked out worktree. This is great for mirroring, but terrible for day to day work. -There's a number of ways around this with 'git worktree': +There's a number of ways around this with `git worktree`: [source,shell] .... @@ -2260,7 +1952,7 @@ To setup your repository to do that: git config --add remote.freebsd.fetch '+refs/*:refs/freebsd/*' .... -which will put everything in the upstream repository into your local repository's 'refs/freebsd/' namespace. +which will put everything in the upstream repository into your local repository's `refs/freebsd/` namespace. Please note, that this also grabs all the unconverted vendor branches and the number of refs associated with them is quite large. You'll need to refer to these 'refs' with their full name because they aren't in and of Git's regular namespaces. @@ -2275,18 +1967,19 @@ would look at the log for the vendor branch for zlib starting at 1.2.10. === Collaborating with others One of the keys to good software development on a project as large as FreeBSD is the ability to collaborate with others before you push your changes to the tree. -The FreeBSD project's Git repositories do not, yet, allow user-created branches to be pushed to the repository, and therefore if you wish to share your changes with others you must use another mechanism, such as a hosted GitLab or GitHub, in order to share changes in a user-generated branch. +The FreeBSD project's Git repositories do not, yet, allow user-created branches to be pushed to the repository, and therefore if you wish to share your changes with others you must use another mechanism, such as a hosted GitLab or GitHub, to share changes in a user-generated branch. -The following instructions show how to set up a user-generated branch, based on the FreeBSD main branch, and push it to GitHub. +The following instructions show how to set up a user-generated branch, based on the FreeBSD `main` branch, and push it to GitHub. -Before you begin, make sure that your local Git repo is up to date and has the correct origins set <<keeping_current,as shown above.>> +Before you begin, make sure that your local Git repo is up to date and has the +correct origins set crossref:committers-guide[keeping_current,as shown above]. [source,shell] -```` +.... % git remote -v freebsd https://git.freebsd.org/src.git (fetch) freebsd ssh://git@gitrepo.freebsd.org/src.git (push) -```` +.... The first step is to create a fork of https://github.com/freebsd/freebsd-src[FreeBSD] on GitHub following these https://docs.github.com/en/github/getting-started-with-github/fork-a-repo[guidelines]. The destination of the fork should be your own, personal, GitHub account (gvnn3 in my case). @@ -2301,7 +1994,8 @@ github git@github.com:gvnn3/freebsd-src.git (push) freebsd https://git.freebsd.org/src.git (fetch) freebsd ssh://git@gitrepo.freebsd.org/src.git (push) .... -With this in place you can create a branch <<keeping_a_local_branch,as shown above.>> +With this in place you can create a branch +crossref:committers-guide[keeping_a_local_branch,as shown above]. [source,shell] .... @@ -2367,7 +2061,8 @@ While this is not an official way to submit patches at this time, sometimes good Similar steps can be used to pull branches from other repositories and land those. When committing pull requests from others, one should take extra care to examine all the changes to ensure they are exactly as represented. -Before beginning, make sure that the local Git repo is up to date and has the correct origins set <<keeping_current,as shown above.>> +Before beginning, make sure that the local Git repo is up to date and has the +correct origins set crossref:committers-guide[keeping_current,as shown above]. In addition, make sure to have the following origins: [source,shell] .... @@ -2436,7 +2131,7 @@ It is worth noting that if your `github` origin uses `https://`, the only step y [[vcs-history]] == Version Control History -The project has moved to <<git-primer,git>>. +The project has moved to crossref:committers-guide[git-primer,git]. The FreeBSD source repository switched from CVS to Subversion on May 31st, 2008. The first real SVN commit is __r179447__. @@ -2474,7 +2169,7 @@ Those who have been given commit rights to the FreeBSD repositories must follow [[commit-steps]] [.procedure] ==== -*Procedure 1. Steps for New Committers* +*Steps for New Committers* . Add an Author Entity + @@ -2486,7 +2181,7 @@ Those who have been given commit rights to the FreeBSD repositories must follow [.filename]#doc/shared/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]. +[.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. . 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. @@ -2504,15 +2199,23 @@ It is very important to have a current PGP/GnuPG key in the repository. The key [.filename]#src/share/misc/committers-<repository>.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. +. Update git mailmap file ++ +[.filename]#src/.mailmap#, [.filename]#doc/.mailmap#, and [.filename]#ports/.mailmap# - Add an entry for commits you created prior to becoming a FreeBSD committer. ++ +Mapping to your FreeBSD address allows us to track external committers who may be ready for a commit bit more easily. +You can also use this to correct old names, mispelled names, etc in the default `git log` output. . Generate a Kerberos Password + -See <<kerberos-ldap>> to generate or set a Kerberos for use with other FreeBSD services like the bug tracking database. +See crossref:committers-guide[kerberos-ldap, Kerberos and LDAP web Password for FreeBSD Cluster] to generate or set a Kerberos account for use with other FreeBSD services like the link:https://bugs.freebsd.org/bugzilla/[bug-tracking database] (you get a bug-tracking account as part of that step). . 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. +link: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 link:https://wiki.freebsd.org/Wiki/About[Wiki/About 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. +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], https://wiki.freebsd.org/Community/Dogs[Dogs of FreeBSD], and or https://wiki.freebsd.org/Community/Cats[Cats 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. @@ -2553,7 +2256,8 @@ For those willing to send e-mail messages through the FreeBSD.org infrastructure . Point your mail client at `smtp.FreeBSD.org:587`. . Enable STARTTLS. . Ensure your `From:` address is set to `_yourusername_@FreeBSD.org`. -. For authentication, you can use your FreeBSD Kerberos username and password (see <<kerberos-ldap>>). The `_yourusername_/mail` principal is preferred, as it is only valid for authenticating to mail resources. +. For authentication, you can use your FreeBSD Kerberos username and password + (see crossref:committers-guide[kerberos-ldap, Kerberos and LDAP web Password for FreeBSD Cluster]). The `_yourusername_/mail` principal is preferred, as it is only valid for authenticating to mail resources. + [NOTE] ====== @@ -2645,6 +2349,51 @@ freebsd yourusername:yourpassword .... ==== +[[smtp-setup-local-exim]] +.Using Exim +[example] +==== + +To direct a local Exim instance to forward all mail from `_example_@FreeBSD.org` + to FreeBSD.org servers, add this to Exim [.filename]#configuration#: + +[.programlisting] +.... +Routers section: (at the top of the list): +freebsd_send: + driver = manualroute + domains = !+local_domains + transport = freebsd_smtp + route_data = ${lookup {${lc:$sender_address}} lsearch {/usr/local/etc/exim/freebsd_send}} + +Transport Section: +freebsd_smtp: + driver = smtp + tls_certificate=<local certificate> + tls_privatekey=<local certificate private key> + tls_require_ciphers = EECDH+ECDSA+AESGCM:EECDH+aRSA+AESGCM:EECDH+ECDSA+SHA384:EECDH+ECDSA+SHA256:EECDH+aRSA+SHA384:EECDH+aRSA+SHA256:EECDH+AESGCM:EECDH:EDH+AESGCM:EDH+aRSA:HIGH:!MEDIUM:!LOW:!aNULL:!eNULL:!LOW:!RC4:!MD5:!EXP:!PSK:!SRP:!DSS + dkim_domain = <local DKIM domain> + dkim_selector = <local DKIM selector> + dkim_private_key= <local DKIM private key> + dnssec_request_domains = * + hosts_require_auth = smtp.freebsd.org + +Authenticators: +freebsd_plain: + driver = plaintext + public_name = PLAIN + client_send = ^example/mail^examplePassword + client_condition = ${if eq{$host}{smtp.freebsd.org}} +.... + +Create [.filename]#/usr/local/etc/exim/freebsd_send# with the following content: + +[.programlisting] +.... +example@freebsd.org:smtp.freebsd.org::587 +.... + +==== [[mentors]] === Mentors @@ -2658,13 +2407,14 @@ Document that approval with an `Approved by:` line in the commit message. When the mentor decides that a mentee has learned the ropes and is ready to commit on their own, the mentor announces it with a commit to [.filename]#mentors#. This file is in the [.filename]#admin# orphan branch of each repository. -Detailed information on how to access these branches can be found in <<admin-branch>>. +Detailed information on how to access these branches can be found in +crossref:committers-guide[admin-branch, "admin" branch]. [[pre-commit-review]] == Pre-Commit Review Code review is one way to increase the quality of software. -The following guidelines apply to commits to the `head` (-CURRENT) branch of the `src` repository. +The following guidelines apply to commits to the `main` (-CURRENT) branch of the `src` repository. Other branches and the `ports` and `docs` trees have their own review policies, but these guidelines generally apply to commits requiring review: * All non-trivial changes should be reviewed before they are committed to the repository. @@ -2698,7 +2448,7 @@ This section contains some suggestions and traditions for how commit logs are fo === Why are commit messages important? When you commit a change in Git, Subversion, or another version control system (VCS), you're prompted to write some text describing the commit -- a commit message. -How important is this commit message? Should you spend some significant effort writing it? Does it really matter if you write simply fixed a bug? +How important is this commit message? Should you spend some significant effort writing it? Does it really matter if you write simply `fixed a bug`? Most projects have more than one developer and last for some length of time. Commit messages are a very important method of communicating with other developers, in the present and for the future. @@ -2740,15 +2490,16 @@ The subject should, by itself, allow the reader to quickly determine if the chan The subject line should be as short as possible while still retaining the required information. This is to make browsing Git log more efficient, and so that git log --oneline can display the short hash and subject on a single 80-column line. -A good rule of thumb is to stay below 63 characters, and aim for about 50 or fewer if possible. +A good rule of thumb is to stay below 67 characters, and aim for about 50 or fewer if possible. === Prefix the subject line with a component, if applicable If the change relates to a specific component the subject line may be prefixed with that component name and a colon (:). +If applicable, try to use the same prefix used in previous commits to the same files. ✓ `foo: Add -k option to keep temporary data` -Include the prefix in the 63-character limit suggested above, so that `git log --oneline` avoids wrapping. +Include the prefix in the 67-character limit suggested above, so that `git log --oneline` avoids wrapping. === Capitalize the first letter of the subject @@ -2820,6 +2571,8 @@ As well as including an informative message with each commit, some additional in This information consists of one or more lines containing the key word or phrase, a colon, tabs for formatting, and then the additional information. +For key words where multiple values make sense (e.g., `PR:` with a comma-separated list of PRs), it is permitted to use the same keyword multiple times to avoid ambiguity or improve readability. + The key words or phrases are: [.informaltable] @@ -2834,7 +2587,8 @@ The key words or phrases are: Typically used when there is no PR, for example if the issue was reported on a mailing list. -|`Submitted by:` +|`Submitted by:` + +(deprecated) |This has been deprecated with git; submitted patches should have the author set by using `git commit --author` with a full name and valid email. |`Reviewed by:` @@ -2856,6 +2610,10 @@ Reviewed by: Full Name <valid@email> (maintainer) |`Tested by:` |The name and e-mail address of the person or people that tested the change; for developers, just the username on the FreeBSD cluster. +|`Discussed with:` +|The name and e-mail address of the person or people that contributed to the patch by providing meaningful feedback; for developers, just the username on the FreeBSD cluster. +Typically used to credit those who did not explicitly review, test, or approve the change, but nevertheless contributed to the discussion surrounding the change, which led to improvements and a better understanding of its impact on the FreeBSD project. + |`Approved by:` a| @@ -2867,6 +2625,7 @@ There are several cases where approval is customary: * commits to an area of the tree covered by the LOCKS file (src) * during a release cycle * committing to a repo where you do not hold a commit bit (e.g. src committer committing to docs) +* committing to a port maintained by someone else While under mentorship, get mentor approval before the commit. Enter the mentor's username in this field, and note that they are a mentor: @@ -2886,7 +2645,8 @@ Approved by: re (username) |The name of the project (if any) from which the code was obtained. Do not use this line for the name of an individual person. |`Fixes:` -|The Git short hash and the title line of a commit that is fixed by this change as returned by `git log -n 1 --oneline GIT-COMMIT-HASH`. +|The Git short hash and the title line of a commit that is fixed by this change as returned by `git log -n 1 --pretty=format:'%h ("%s")' GIT-COMMIT-HASH`. +We include the commit title so that the referenced commit can be located even in the case that a future VCS migration invalidates hash references. |`MFC after:` |To receive an e-mail reminder to MFC at a later date, specify the number of days, weeks, or months after which an MFC is planned. @@ -2894,14 +2654,15 @@ Approved by: re (username) |`MFC to:` |If the commit should be merged to a subset of stable branches, specify the branch names. -|`MFC with:` -|If the commit should be merged together with a previous one in a single MFC commit (for example, where this commit corrects a bug in the previous change), specify the corresponding Git hash. - |`MFH:` |If the commit is to be merged into a ports quarterly branch name, specify the quarterly branch. For example `2021Q2`. |`Relnotes:` |If the change is a candidate for inclusion in the release notes for the next release from the branch, set to `yes`. +|Candidates are user-visible changes, new features, compatibility breaks, etc.. +|If you forget to set this line, or want to provide more details, add an entry to the `RELNOTES` file in the root of the src tree. +|The `RELNOTES` file is used to generate release notes for the next release. +|Do not use the `Relnotes:` line to describe the change: its only valid value is `yes`. |`Security:` |If the change is related to a security vulnerability or security exposure, include one or more references or a description of the issue. If possible, include a VuXML URL or a CVE ID. @@ -2917,6 +2678,10 @@ Approved by: re (username) It should include the entire URL to the pull request, as these often act as code reviews for the code. For example: `https://github.com/freebsd/freebsd-src/pull/745` +|`Co-authored-by:` +|The name and email address of an additional author of the commit. +GitHub has a detailed description of the Co-authored-by trailer at https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors. + |`Signed-off-by:` |ID certifies compliance with https://developercertificate.org/ @@ -3041,8 +2806,8 @@ The FreeBSD Project suggests and uses this text as the preferred license scheme: [.programlisting] .... -/*- - * SPDX-License-Identifier: BSD-2-Clause-FreeBSD +/* + * SPDX-License-Identifier: BSD-2-Clause * * Copyright (c) [year] [your name] * @@ -3077,7 +2842,7 @@ If you have code in the tree with the advertising clause, please consider removi In fact, please consider using the above license for your code. The FreeBSD project discourages completely new licenses and variations on the standard licenses. -New licenses require the approval of the {core-email} to reside in the main repository. +New licenses require the approval of {core-email} to reside in the `src` repository. The more different licenses that are used in the tree, the more problems that this causes to those wishing to utilize this code, typically from unintended consequences from a poorly worded license. Project policy dictates that code under some non-BSD licenses must be placed only in specific sections of the repository, and in some cases, compilation must be conditional or even disabled by default. @@ -3120,8 +2885,8 @@ At present, these tags are indented to help automated tools reconstruct license All _SPDX-License-Identifier_ tags in the tree should be considered to be informative. All files in the FreeBSD source tree with these tags also have a copy of the license which governs use of that file. In the event of a discrepancy, the verbatim license is controlling. -The project tries to follow the https://spdx.github.io/spdx-spec/[SPDX Specification, Version 2.2]. -How to mark source files and valid algebraic expressions are found in https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/[Appendix IV] and https://spdx.github.io/spdx-spec/appendix-V-using-SPDX-short-identifiers-in-source-files/[Appendix V]. +The project tries to follow the https://spdx.github.io/spdx-spec/v2.2.2/[SPDX Specification, Version 2.2]. +How to mark source files and valid algebraic expressions are found in https://spdx.github.io/spdx-spec/v2.2.2/SPDX-license-expressions/[Annex D] and https://spdx.github.io/spdx-spec/v2.2.2/using-SPDX-short-identifiers-in-source-files/[Annex E]. The project draws identifiers from SPDX's list of valid https://spdx.org/licenses/[short license identifiers]. The project uses only the _SPDX-License-Identifier_ tag. @@ -3130,13 +2895,19 @@ As of March 2021, approximately 25,000 out of 90,000 files in the tree have been == Developer Relations When working directly on your own code or on code which is already well established as your responsibility, then there is probably little need to check with other committers before jumping in with a commit. -Working on a bug in an area of the system which is clearly orphaned (and there are a few such areas, to our shame), the same applies. -When modifying parts of the system which are maintained, formally, or informally, consider asking for review just as a developer would have before becoming a committer. +When working on a bug in an area of the system which is clearly orphaned (and there are a few such areas, to our shame), the same applies. +When modifying parts of the system which are maintained, formally or informally, consider asking for a review just as a developer would have before becoming a committer. For ports, contact the listed `MAINTAINER` in the [.filename]#Makefile#. To determine if an area of the tree is maintained, check the MAINTAINERS file at the root of the tree. If nobody is listed, scan the revision history to see who has committed changes in the past. -An example script that lists each person who has committed to a given file along with the number of commits each person has made can be found at on `freefall` at [.filename]#~eadler/bin/whodid#. +To list the names and email addresses of all commit authors for a given file in the last 2 years and the number of commits each has authored, ordered by descending number of commits, use: + +[source,shell] +---- +% git -C /path/to/repo shortlog -sne --since="2 years" -- relative/path/to/file +---- + If queries go unanswered or the committer otherwise indicates a lack of interest in the area affected, go ahead and commit it. [IMPORTANT] @@ -3151,7 +2922,7 @@ If a commit does results in controversy erupting, it may be advisable to conside Remember, with a version control system we can always change it back. Do not impugn the intentions of others. -If they see a different solution to a problem, or even a different problem, it is probably not because they are stupid, because they have questionable parentage, or because they are trying to destroy hard work, personal image, or FreeBSD, but basically because they have a different outlook on the world. +If they see a different solution to a problem, or even a different problem, it is probably not because they are stupid, because they have questionable parentage, or because they are trying to destroy hard work, personal image, or FreeBSD, but basically because they have a different outlook on the world. Different is good. Disagree honestly. @@ -3190,8 +2961,8 @@ Once your question is answered, if no one pointed you to documentation that spel == Bugzilla The FreeBSD Project utilizes Bugzilla for tracking bugs and change requests. -Be sure that if you commit a fix or suggestion found in the PR database to close it. -It is also considered nice if you take time to close any PRs associated with your commits, if appropriate. +If you commit a fix or suggestion found in the PR database, be sure to close the PR. +It is also considered nice if you take time to close any other PRs associated with your commits. Committers with non-``FreeBSD.org`` Bugzilla accounts can have the old account merged with the `FreeBSD.org` account by following these steps: @@ -3199,7 +2970,8 @@ Committers with non-``FreeBSD.org`` Bugzilla accounts can have the old account m ==== . Log in using your old account. . Open new bug. Choose `Services` as the Product, and `Bug Tracker` as the Component. In bug description list accounts you wish to be merged. -. Log in using `FreeBSD.org` account and post comment to newly opened bug to confirm ownership. See <<kerberos-ldap>> for more details on how to generate or set a password for your `FreeBSD.org` account. +. Log in using `FreeBSD.org` account and post comment to newly opened bug to + confirm ownership. See crossref:committers-guide[kerberos-ldap, Kerberos and LDAP web Password for FreeBSD Cluster] for more details on how to generate or set a password for your `FreeBSD.org` account. . If there are more than two accounts to merge, post comments from each of them. ==== @@ -3212,14 +2984,18 @@ You can find out more about Bugzilla at: == Phabricator The FreeBSD Project utilizes https://reviews.freebsd.org[Phabricator] for code review requests. -See the https://wiki.freebsd.org/CodeReview[CodeReview] wiki page for details. +See the https://wiki.freebsd.org/Phabricator[Phabricator wiki page] for details. + +Please use the `git arc` command provided by `devel/freebsd-git-devtools` (install the port or package, then type `git help arc` for documentation) to create and update Phabricator reviews. +This will make it easier for others to review and test your patches. Committers with non-``FreeBSD.org`` Phabricator accounts can have the old account renamed to the ``FreeBSD.org`` account by following these steps: [.procedure] ==== . Change your Phabricator account email to your `FreeBSD.org` email. -. Open new bug on our bug tracker using your `FreeBSD.org` account, see <<bugzilla>> for more information. Choose `Services` as the Product, and `Code Review` as the Component. In bug description request that your Phabricator account be renamed, and provide a link to your Phabricator user. For example, `https://reviews.freebsd.org/p/bob_example.com/` +. Open new bug on our bug tracker using your `FreeBSD.org` account, see + crossref:committers-guide[bugzilla, Bugzilla] for more information. Choose `Services` as the Product, and `Code Review` as the Component. In bug description request that your Phabricator account be renamed, and provide a link to your Phabricator user. For example, `https://reviews.freebsd.org/p/bob_example.com/` ==== [IMPORTANT] @@ -3248,12 +3024,8 @@ If there is something you want merged from FreeBSD-CURRENT to FreeBSD-STABLE (wh `{so}`:: `{so-name}` is the link:https://www.FreeBSD.org/security/[FreeBSD Security Officer] and oversees the `{security-officer}`. -`{wollman}`:: -If you need advice on obscure network internals or are not sure of some potential change to the networking subsystem you have in mind, Garrett is someone to talk to. -Garrett is also very knowledgeable on the various standards applicable to FreeBSD. - {committers-name}:: -{svn-src-all}, {svn-ports-all} and {svn-doc-all} are the mailing lists that the version control system uses to send commit messages to. +{dev-src-all}, {dev-ports-all} and {dev-doc-all} are the mailing lists that the version control system uses to send commit messages to. _Never_ send email directly to these lists. Only send replies to this list when they are short and are directly related to a commit. @@ -3378,7 +3150,7 @@ 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 <<respect,Respect other committers>> and apply them also to contributors. +Consider the points raised under crossref:committers-guide[respect,Respect other committers] 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. @@ -3391,7 +3163,7 @@ 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 extref:{developers-handbook}[Source Tree Guidelines and Policies, policies] for documentation on this. +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 extref:{developers-handbook}policies[Source Tree Guidelines and Policies, 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. @@ -3431,11 +3203,12 @@ If you have not done it before, chances are good that you do not actually know t 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. +If your changes are anywhere else, make sure you can still compile userspace via `make buildworld`. If your changes are to a branch, make sure your testing occurs with a machine which is running that code. If you have a change which also may break another architecture, be sure and test on all supported architectures. +Please ensure your change works for +crossref:committers-guide[compilers,supported toolchains]. 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. @@ -3456,21 +3229,107 @@ If you are unsure of the current maintainership email {freebsd-arch} and ask. === Policy on Multiple Architectures -FreeBSD has added several new architecture ports during recent release cycles and is truly no longer an i386(TM) centric operating system. In an effort to make it easier to keep FreeBSD portable across the platforms we support, core has developed this mandate: [.blockquote] -Our 32-bit reference platform is i386, and our 64-bit reference platform is amd64. -Major design work (including major API and ABI changes) must prove itself on at least one 32-bit and at least one 64-bit platform, preferably the primary reference platforms, before it may be committed to the source tree. - -The i386 and amd64 platforms were chosen due to being more readily available to developers and as representatives of more diverse processor and system designs - big versus little endian, register file versus register stack, different DMA and cache implementations, hardware page tables versus software TLB management etc. - -We will continue to re-evaluate this policy as cost and availability of the 64-bit platforms change. +Major design work (including major API and ABI changes) must prove itself on at least one Tier 1 platform before it may be committed to the source tree. Developers should also be aware of our Tier Policy for the long term support of hardware architectures. The rules here are intended to provide guidance during the development process, and are distinct from the requirements for features and architectures listed in that section. The Tier rules for feature support on architectures at release-time are more strict than the rules for changes during the development process. +[[compilers]] +=== Policy on Multiple Compilers + +The FreeBSD base system builds with both Clang and GCC. +The project does this in a careful and controlled way to maximize benefits from this extra work, while keeping the extra work to a minimum. +Supporting both Clang and GCC improves the flexibility our users have. +These compilers have different strengths and weaknesses, and supporting both allows users to pick the best one for their needs. +Clang and GCC support similar dialects of C and C++, necessitating a relatively small amount of conditional code. +The project gains increased code coverage and improves the code quality by using features from both compilers. +The project is able to build in more user environments and leverage more CI environments by supporting this range, increasing convenience for users and giving them more tools to test with. +By carefully constraining the range of versions supported to modern versions of these compilers, the project avoids unduly increasing the testing matrix. +Older and obscure compilers, as well as older dialects of the languages, have extremely limited support that allow user programs to build with them, but without constraining the base system to being built with them. +The exact balance continues to evolve to ensure the benefits of extra work remain greater than the burdens it imposes. +The project used to support really old Intel compilers or old GCC versions, but we traded supporting those obsolete compilers for a carefully selected range of modern compilers. +This section documents where we use different compilers, and the expectations around that. + +The FreeBSD base system includes an in-tree Clang compiler. +Due to being in the tree, this compiler is the most supported compiler. +All changes must compile with it, prior to commit. +Complete testing, as appropriate for the change, should be done with this compiler. + +The FreeBSD base system also supports various versions of Clang and GCC as out-of-tree compilers. +For large or risky changes, committers should do a test build with a +supported version of GCC. +Out of tree compilers are available as packages. +GCC compilers are available as `${TARGET_ARCH}-gcc${VERSION}` packages, such as package:devel/freebsd-gcc14@aarch64[aarch64-gcc14]. +Clang compilers are available as `llvm${VERSION}` packages, such as +package:devel/llvm18[llvm18]. +The project runs automated CI jobs to build everything with these compilers. +Committers are expected to fix the jobs they break with their changes. +Committers may test builds of userspace or individual kernels by setting `CROSS_TOOLCHAIN` to the package name, for example `CROSS_TOOLCHAIN=aarch64-gcc14` or `CROSS_TOOLCHAIN=llvm18`. +For universe or tinderbox builds, `USE_GCC_TOOLCHAINS=gcc${VERSION}` builds all architectures using the appropriate GCC compiler packages. +For universe or tinderbox builds using an out-of-tree Clang, pass `CROSS_TOOLCHAIN=llvm${VERSION}`. +Note that while all architectures in the base system can be compiled by Clang, +only a few architectures can be fully built by GCC. + +The FreeBSD project also has some CI pipelines on github. +For pull requests on github and some branches pushed to github forks, a number of cross compilation jobs run. +These test FreeBSD building using versions of Clang that lag the in-tree compiler by one or more major versions. + +The FreeBSD project is also upgrading compilers. +Both Clang and GCC are fast moving targets. +Some work to change things in the tree, for example removing the old-style K&R function declarations and definitions, will land in the tree prior to the compiler landing. +Committers should try to be mindful about this and be receptive to looking into problems with their code or changes with these new compilers. +Also, just after a new compiler version hits the tree, people may need to compile things with the old version if there was an undetected regression suspected. + +In addition to the compiler, LLVM's LLD and GNU's binutils are used indirectly by the compiler. +Committers should be mindful of variations in assembler syntax and features of the linkers and ensure both variants work. +These components will be tested as part of FreeBSD's CI jobs for Clang or GCC. + +The FreeBSD project provides headers and libraries that allow other compilers to be used to build software not in the base system. +These headers have support for making the environment as strict as the standard, supporting prior dialects of ANSI-C back to C89, and other edge cases our large ports collection has uncovered. +This support constrains retirement of older standards in places like header files, but does not constrain updating the base system to newer dialects. +Nor does it require the base system to compile with these older standards as a whole. +Breaking this support will cause packages in the ports collection to fail, so should be avoided where possible, and promptly fixed when it is easy to do so. + +The FreeBSD build system currently accommodates these different environments. +As new warnings are added to compilers, the project tries to fix them. +However, sometimes these warnings require extensive rework, so are suppressed in some way by using make variables that evaluate to the proper thing depending on the compiler version. +Developers should be mindful of this, and ensure any compiler specific flags are properly conditionalized. + +==== Current Compiler Versions +The versions of supported compilers for a given branch such as `main` or `stable/X` varies over time. +The authoritative source for supported compiler versions are automated CI jobs tested in GitHub's cross-build actions and Jenkins. + +[.tblbasic] +[cols="10*",options="header",] +|=== +|Branch | In-tree Compiler +|llvm12 | llvm13 | llvm14 | llvm15 | llvm18 +|amd64-gcc12 | amd64-gcc13 | amd64-gcc14 + +|main | llvm 19 +| | | | Y | Y +| Y | Y | Y + +|stable/15 | llvm 19 +| | | Y | | Y +| Y | Y | Y + +|stable/14 | llvm 19 +| Y | Y | Y | | +| Y | | Y + +|stable/13 | llvm 19 +| Y | Y | Y | | +| Y | | Y +|=== + +GCC toolchains are tested for amd64 via CI jobs in Jenkins. +LLVM toolchains are tested for aarch64 and arm64 in GitHub's cross-build actions. + === Other Suggestions When committing documentation changes, use a spell checker before committing. @@ -3573,10 +3432,10 @@ The native "ABI" generally shares certain properties with the kernel ABI such as Tiers are defined for both kernels and userland ABIs. In the common case, a platform's kernel and FreeBSD ABIs are assigned to the same tier. -=== Tier 1: Fully-Supported Architectures +==== Tier 1: Fully-Supported Architectures Tier 1 platforms are the most mature FreeBSD platforms. -They are supported by the security officer, release engineering, and port management teams. +They are supported by the security officer, release engineering, and Ports Management Team. Tier 1 architectures are expected to be Production Quality with respect to all aspects of the FreeBSD operating system, including installation and development environments. The FreeBSD Project provides the following guarantees to consumers of Tier 1 platforms: @@ -3609,10 +3468,10 @@ Collectively, developers are required to provide the following to maintain the T * Changes cannot break the userland ABI. If an ABI change is required, ABI compatibility for existing binaries should be provided via use of symbol versioning or shared library version bumps. * Changes merged to stable branches cannot break the protected portions of the kernel ABI. If a kernel ABI change is required, the change should be modified to preserve functionality of existing kernel modules. -=== Tier 2: Developmental and Niche Architectures +==== Tier 2: Developmental and Niche Architectures Tier 2 platforms are functional, but less mature FreeBSD platforms. -They are not supported by the security officer, release engineering, and port management teams. +They are not supported by the security officer, release engineering, and Ports Management Team. Tier 2 platforms may be Tier 1 platform candidates that are still under active development. Architectures reaching end of life may also be moved from Tier 1 status to Tier 2 status as the availability of resources to continue to maintain the system in a Production Quality state diminishes. @@ -3637,10 +3496,10 @@ Collectively, developers are required to provide the following to maintain the T * While changes are permitted to break the userland ABI, the ABI should not be broken gratuitously. Significant userland ABI changes should be restricted to major versions. * New features that are not yet implemented on Tier 2 architectures should provide a means of disabling them on those architectures. -=== Tier 3: Experimental Architectures +==== Tier 3: Experimental Architectures Tier 3 platforms have at least partial FreeBSD support. -They are _not_ supported by the security officer, release engineering, and port management teams. +They are _not_ supported by the security officer, release engineering, and Ports Management Team. Tier 3 platforms are architectures in the early stages of development, for non-mainstream hardware platforms, or which are considered legacy systems unlikely to see broad future use. Initial support for Tier 3 platforms may exist in a separate repository rather than the main source repository. @@ -3648,7 +3507,7 @@ Initial support for Tier 3 platforms may exist in a separate repository rather t The FreeBSD Project provides no guarantees to consumers of Tier 3 platforms and is not committed to maintaining resources to support development. Tier 3 platforms may not always be buildable, nor are any kernel or userland ABIs considered stable. -=== Unsupported Architectures +==== Unsupported Architectures Other platforms are not supported in any form by the project. The project previously described these as Tier 4 systems. @@ -3670,13 +3529,26 @@ For a platform to be promoted to a higher tier, any missing support guarantees m [[ports-qa-add-new]] ==== How do I add a new port? -First, please read the section about repository copies. +Adding a port to the tree is relatively simple. Once the port is ready to be +added, as explained later crossref:committers-guide[ports-qa-add-new-extra,here], you need to add the port's directory entry in the category's [.filename]#Makefile#. +In this [.filename]#Makefile#, ports are listed in alphabetical order and added to the `SUBDIR` variable, like this: + +[.programlisting] +.... + SUBDIR += newport +.... -The easiest way to add a new port is the `addport` script located in the [.filename]#ports/Tools/scripts# directory. -It adds a port from the directory specified, determining the category automatically from the port [.filename]#Makefile#. -It also adds an entry to the port's category [.filename]#Makefile#. -It was written by `{mharo}`, `{will}`, and `{garga}`. -When sending questions about this script to the {freebsd-ports}, please also CC `{crees}`, the current maintainer. +Once the port and its category's Makefile are ready, the new port can be committed: +[source,shell] +.... +% git add category/Makefile category/newport +% git commit +% git push +.... +[TIP] +==== +Don't forget to crossref:committers-guide[port-commit-message-formats,setup git hooks for the ports tree as explained here]; a specific hook has been developed to verify the category's [.filename]#Makefile#. +==== [[ports-qa-add-new-extra]] ==== Any other things I need to know when I add a new port? @@ -3684,7 +3556,7 @@ When sending questions about this script to the {freebsd-ports}, please also CC Check the port, preferably to make sure it compiles and packages correctly. The extref:{porters-handbook}testing[Porters Handbook's Testing Chapter] contains more detailed instructions. -See the extref:{porters-handbook}testing[Portclippy / Portfmt, testing-portclippy] and the extref:{porters-handbook}testing[Poudriere, testing-poudriere] sections. +See the extref:{porters-handbook}testing[Portclippy / Portfmt, testing-portclippy] and the extref:{porters-handbook}testing[poudriere, testing-poudriere] sections. You do not necessarily have to eliminate all warnings but make sure you have fixed the simple ones. @@ -3695,7 +3567,7 @@ To close a PR, change the state to `Issue Resolved` and the resolution as `Fixed [NOTE] ==== -If for some reason using extref:{porters-handbook}testing[Poudriere, testing-poudriere] to test the new port is not possible, the bare minimum of testing includes this sequence: +If for some reason using extref:{porters-handbook}testing[poudriere, testing-poudriere] to test the new port is not possible, the bare minimum of testing includes this sequence: [source,shell] .... @@ -3735,7 +3607,6 @@ When using Git, consider using man:git-grep[1], it is much faster than `grep -r` * Remove the port's files and directory with `git rm`. * Remove the `SUBDIR` listing of the port in the parent directory [.filename]#Makefile#. * Add an entry to [.filename]#ports/MOVED#. -* Search for entries in [.filename]#ports/security/vuxml/vuln.xml# and adjust them accordingly. In particular, check for previous packages with the new name which version could include the new port. * Remove the port from [.filename]#ports/LEGAL# if it is there. ==== @@ -3751,6 +3622,7 @@ When sending questions about this script to the {freebsd-ports}, please also CC . Perform a thorough check of the ports collection for any dependencies on the old port location/name, and update them. Running `grep` on [.filename]#INDEX# is not enough because some ports have dependencies enabled by compile-time options. A full man:git-grep[1] of the ports collection is recommended. . Remove the `SUBDIR` entry from the old category Makefile and add a `SUBDIR` entry to the new category Makefile. . Add an entry to [.filename]#ports/MOVED#. +. Search for entries in xml files inside [.filename]#ports/security/vuxml# and adjust them accordingly. In particular, check for previous packages with the new name which version could include the new port. . Move the port with `git mv`. . Commit the changes. ==== @@ -3778,7 +3650,8 @@ It usually lasted a couple of weeks. During that time, build problems were fixed, and the release packages were built. This practice is no longer used, as the packages for the releases are built from the current stable, quarterly branch. -For more information on how to merge commits to the quarterly branch, see <<ports-qa-misc-request-mfh>>. +For more information on how to merge commits to the quarterly branch, see +crossref:committers-guide[ports-qa-misc-request-mfh, What is the procedure to request authorization for merging a commit to the quarterly branch?]. [[ports-qa-quarterly]] === Quarterly Branches @@ -3800,8 +3673,8 @@ Merging commits to the quarterly branch (a process we call MFH for a historical % git push .... -where '$HASH' is the hash of the commit you want to copy over to the quarterly branch. -The -x parameter ensures the hash '$HASH' of the main branch is included in the new commit message of the quarterly branch. +where `$HASH` is the hash of the commit you want to copy over to the quarterly branch. +The `-x` parameter ensures the hash `$HASH` of the `main` branch is included in the new commit message of the quarterly branch. [[ports-qa-new-category]] === Creating a New Category @@ -3809,7 +3682,7 @@ The -x parameter ensures the hash '$HASH' of the main branch is included in the [[ports-qa-new-category-how]] ==== What is the procedure for creating a new category? -Please see extref:{porters-handbook}[Proposing a New Category, proposing-categories] in the Porter's Handbook. +Please see extref:{porters-handbook}makefiles[Proposing a New Category, proposing-categories] in the Porter's Handbook. Once that procedure has been followed and the PR has been assigned to the {portmgr}, it is their decision whether or not to approve it. If they do, it is their responsibility to: @@ -3836,14 +3709,14 @@ To do this, you will need to: . If you want to be really thorough, now might be a good time to run man:portlint[1]. ====== + -. Check that the ``PKGORIGIN``s are correct. The ports system uses each port's `CATEGORIES` entry to create its `PKGORIGIN`, which is used to connect installed packages to the port directory they were built from. If this entry is wrong, common port tools like man:pkg_version[1] and man:portupgrade[1] fail. +. Check that the ``PKGORIGIN``s are correct. The ports system uses each port's `CATEGORIES` entry to create its `PKGORIGIN`, which is used to connect installed packages to the port directory they were built from. If this entry is wrong, common port tools like man:pkg-version[8] and man:portupgrade[1] fail. + To do this, use the [.filename]#chkorigin.sh# tool: `env PORTSDIR=/path/to/ports sh -e /path/to/ports/Tools/scripts/chkorigin.sh`. This will check every port in the ports tree, even those not connected to the build, so you can run it directly after the move operation. Hint: do not forget to look at the ``PKGORIGIN``s of any slave ports of the ports you just moved! . On your own local system, test the proposed changes: first, comment out the SUBDIR entries in the old ports' categories' [.filename]##Makefile##s; then enable building the new category in [.filename]#ports/Makefile#. Run make checksubdirs in the affected category directories to check the SUBDIR entries. Next, in the [.filename]#ports/# directory, run make index. This can take over 40 minutes on even modern systems; however, it is a necessary step to prevent problems for other people. . Once this is done, you can commit the updated [.filename]#ports/Makefile# to connect the new category to the build and also commit the [.filename]#Makefile# changes for the old category or categories. . Add appropriate entries to [.filename]#ports/MOVED#. . Update the documentation by modifying: -** the extref:{porters-handbook}[list of categories, PORTING-CATEGORIES] in the Porter's Handbook +** the extref:{porters-handbook}makefiles[list of categories, porting-categories] in the Porter's Handbook + . Only once all the above have been done, and no one is any longer reporting problems with the new ports, should the old ports be deleted from their previous locations in the repository. ==== @@ -3852,7 +3725,7 @@ To do this, use the [.filename]#chkorigin.sh# tool: `env PORTSDIR=/path/to/ports This is much simpler than a physical category. Only a few modifications are needed: -* the extref:{porters-handbook}[list of categories, PORTING-CATEGORIES] in the Porter's Handbook +* the extref:{porters-handbook}makefiles[list of categories, porting-categories] in the Porter's Handbook [[ports-qa-misc-questions]] === Miscellaneous Questions @@ -3878,7 +3751,7 @@ No unauthorized commits may ever be made to ports maintained by those groups. The packages are built multiple times each week. If a port fails, the maintainer will receive an email from `pkg-fallout@FreeBSD.org`. -Reports for all the package builds (official, experimental, and non-regression) are aggregated at link:pkg-status.FreeBSD.org[pkg-status.FreeBSD.org]. +Reports for all the package builds (official, experimental, and non-regression) are aggregated at link:https://pkg-status.FreeBSD.org[pkg-status.FreeBSD.org]. [[ports-qa-misc-INDEX]] ==== I added a new port. Do I need to add it to the [.filename]#INDEX#? @@ -3924,65 +3797,33 @@ Full package builds will be done with the patches provided by the submitter, and == Issues Specific to Developers Who Are Not Committers A few people who have access to the FreeBSD machines do not have commit bits. -Almost all of this document will apply to these developers as well (except things specific to commits and the mailing list memberships that go with them). +Almost all of this document will apply to these developers as well (except things specific to commits and the mailing list memberships that go with them). In particular, we recommend that you read: -* <<admin>> -* <<conventions-everyone>> +* crossref:committers-guide[admin, Administrative Details] +* crossref:committers-guide[conventions-everyone, For Everyone] + [NOTE] ==== Get your mentor to add you to the "Additional Contributors" ([.filename]#doc/shared/contrib-additional.adoc#), if you are not already listed there. ==== -* <<developer.relations>> -* <<ssh.guide>> -* <<rules>> +* crossref:committers-guide[developer.relations, Developer Relations] +* crossref:committers-guide[ssh.guide, SSH Quick-Start Guide] +* crossref:committers-guide[rules, The FreeBSD Committers' Big List of Rules] [[google-analytics]] == Information About Google Analytics -As of December 12, 2012, Google Analytics was enabled on the FreeBSD Project website to collect anonymized usage statistics regarding usage of the site. -The information collected is valuable to the FreeBSD Documentation Project, to identify various problems on the FreeBSD website. +As of December 12, 2012, Google Analytics was enabled on the FreeBSD Project website to collect anonymized usage statistics regarding usage of the site. -[[google-analytics-policy]] -=== Google Analytics General Policy - -The FreeBSD Project takes visitor privacy very seriously. -As such, the FreeBSD Project website honors the "Do Not Track" header _before_ fetching the tracking code from Google. -For more information, please see the https://www.FreeBSD.org/privacy/[FreeBSD Privacy Policy]. - -Google Analytics access is _not_ arbitrarily allowed - access must be requested, voted on by the `{doceng}`, and explicitly granted. - -Requests for Google Analytics data must include a specific purpose. -For example, a valid reason for requesting access would be "to see the most frequently used web browsers when viewing FreeBSD web pages to ensure page rendering speeds are acceptable." - -Conversely, "to see what web browsers are most frequently used" (without stating __why__) would be rejected. - -All requests must include the timeframe for which the data would be required. -For example, it must be explicitly stated if the requested data would be needed for a timeframe covering a span of 3 weeks, or if the request would be one-time only. - -Any request for Google Analytics data without a clear, reasonable reason beneficial to the FreeBSD Project will be rejected. - -[[google-analytics-data]] -=== Data Available Through Google Analytics - -A few examples of the types of Google Analytics data available include: - -* Commonly used web browsers -* Page load times -* Site access by language +[NOTE] +==== +As of March 3, 2022, Google Analytics was removed from the FreeBSD Project. +==== [[misc]] == Miscellaneous Questions -=== Are there changes that can be committed without asking the maintainer for approval? - -Blanket approval for most ports applies to these types of fixes: - -* Most infrastructure changes to a port (that is, modernizing, but not changing the functionality). For example, the blanket covers converting to new `USES` macros, enabling verbose builds, and switching to new ports system syntaxes. -* Trivial and _tested_ build and runtime fixes. -* Documentations or metadata changes to ports, like [.filename]#pkg-descr# or `COMMENT`. - === How do I access people.FreeBSD.org to put up personal or project information? `people.FreeBSD.org` is the same as `freefall.FreeBSD.org`. @@ -4016,7 +3857,7 @@ FreeBSD committers can get a free 4-CD or DVD set at conferences from http://www https://gandi.net[Gandi] provides website hosting, cloud computing, domain registration, and X.509 certificate services. Gandi offers an E-rate discount to all FreeBSD developers. -In order to streamline the process of getting the discount first set up a Gandi account, fill in the billing information and select the currency. +To streamline the process of getting the discount first set up a Gandi account, fill in the billing information and select the currency. Then send an mail to mailto:non-profit@gandi.net[non-profit@gandi.net] using your `@freebsd.org` mail address, and indicate your Gandi handle. [[benefits-rsync]] diff --git a/documentation/content/en/articles/committers-guide/_index.po b/documentation/content/en/articles/committers-guide/_index.po new file mode 100644 index 0000000000..c1f608dfab --- /dev/null +++ b/documentation/content/en/articles/committers-guide/_index.po @@ -0,0 +1,8967 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-17 20:53+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/committers-guide/_index.adoc:1 +#, no-wrap +msgid "Introductory information for FreeBSD committers" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/committers-guide/_index.adoc:1 +#: documentation/content/en/articles/committers-guide/_index.adoc:12 +#, no-wrap +msgid "Committer's Guide" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:45 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:48 +msgid "" +"This document provides information for the FreeBSD committer community. All " +"new committers should read this document before they start, and existing " +"committers are strongly encouraged to review it from time to time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:53 +msgid "" +"Almost all FreeBSD developers have commit rights to one or more " +"repositories. However, a few developers do not, and some of the information " +"here applies to them as well. (For instance, some people only have rights " +"to work with the Problem Report database.) Please see crossref:committers-" +"guide[non-committers, Issues Specific to Developers Who Are Not Committers] " +"for more information." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:55 +msgid "" +"This document may also be of interest to members of the FreeBSD community " +"who want to learn more about how the project works." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:57 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:61 +#, no-wrap +msgid "Administrative Details" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:68 +#, no-wrap +msgid "_Login Methods_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:70 +#, no-wrap +msgid "man:ssh[1], protocol 2 only" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:71 +#, no-wrap +msgid "_Main Shell Host_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:73 +#, no-wrap +msgid "`freefall.FreeBSD.org`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:74 +#, no-wrap +msgid "_Reference Machines_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:76 +#, no-wrap +msgid "`ref*.FreeBSD.org`, `universe*.freeBSD.org` (see also link:https://www.FreeBSD.org/internal/machines/[FreeBSD Project Hosts])" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:77 +#, no-wrap +msgid "_SMTP Host_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:79 +#, no-wrap +msgid "`smtp.FreeBSD.org:587` (see also crossref:committers-guide[smtp-setup, SMTP Access Setup])." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:80 +#, no-wrap +msgid "`_src/_` Git Repository" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:82 +#, no-wrap +msgid "`ssh://git@gitrepo.FreeBSD.org/src.git`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:83 +#, no-wrap +msgid "`_doc/_` Git Repository" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:85 +#, no-wrap +msgid "`ssh://git@gitrepo.FreeBSD.org/doc.git`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:86 +#, no-wrap +msgid "`_ports/_` Git Repository" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:88 +#, no-wrap +msgid "`ssh://git@gitrepo.FreeBSD.org/ports.git`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:89 +#, no-wrap +msgid "_Internal Mailing Lists_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:91 +#, no-wrap +msgid "developers (technically called all-developers), doc-developers, doc-committers, ports-developers, ports-committers, src-developers, src-committers. (Each project repository has its own -developers and -committers mailing lists. Archives for these lists can be found in the files [.filename]#/local/mail/repository-name-developers-archive# and [.filename]#/local/mail/repository-name-committers-archive# on `freefall.FreeBSD.org`.)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:92 +#, no-wrap +msgid "_Core Team monthly reports_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:94 +#, no-wrap +msgid "[.filename]#/home/core/public/reports# on the `FreeBSD.org` cluster." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:95 +#, no-wrap +msgid "_Ports Management Team monthly reports_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:97 +#, no-wrap +msgid "[.filename]#/home/portmgr/public/monthly-reports# on the `FreeBSD.org` cluster." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:98 +#, no-wrap +msgid "_Noteworthy `src/` Git Branches:_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:99 +#, no-wrap +msgid "`stable/n` (`n`-STABLE), `main` (-CURRENT)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:103 +#, no-wrap +msgid "" +"man:ssh[1] is required to connect to the project hosts. For more information,\n" +"\tsee crossref:committers-guide[ssh.guide, SSH Quick-Start Guide].\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:105 +msgid "Useful links:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:107 +msgid "link:https://www.FreeBSD.org/internal/[FreeBSD Project Internal Pages]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:108 +msgid "link:https://www.FreeBSD.org/internal/machines/[FreeBSD Project Hosts]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:109 +msgid "" +"link:https://www.FreeBSD.org/administration/[FreeBSD Project Administrative " +"Groups]" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:111 +#, no-wrap +msgid "OpenPGP Keys for FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:116 +msgid "" +"Cryptographic keys conforming to the OpenPGP (__Pretty Good Privacy__) " +"standard are used by the FreeBSD project to authenticate committers. " +"Messages carrying important information like public SSH keys can be signed " +"with the OpenPGP key to prove that they are really from the committer. See " +"https://nostarch.com/releases/pgp_release.pdf[PGP & GPG: Email for the " +"Practical Paranoid by Michael Lucas] and https://en.wikipedia.org/wiki/" +"Pretty_Good_Privacy[] for more information." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:118 +#, no-wrap +msgid "Creating a Key" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:122 +msgid "" +"Existing keys can be used, but should be checked with " +"[.filename]#documentation/tools/checkkey.sh# first. In this case, make sure " +"the key has a FreeBSD user ID." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:124 +msgid "" +"For those who do not yet have an OpenPGP key, or need a new key to meet " +"FreeBSD security requirements, here we show how to generate one." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:129 +msgid "" +"Install [.filename]#security/gnupg#. Enter these lines in " +"[.filename]#~/.gnupg/gpg.conf# to set minimum acceptable defaults for " +"signing and new key preferences (see the link:https://www.gnupg.org/" +"documentation/manuals/gnupg/GPG-Options.html[GnuPG options documentation] " +"for more details):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:136 +#, no-wrap +msgid "" +"# Sorted list of preferred algorithms for signing (strongest to weakest).\n" +"personal-digest-preferences SHA512 SHA384 SHA256 SHA224\n" +"# Default preferences for new keys\n" +"default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 CAMELLIA256 AES192 CAMELLIA192 AES CAMELLIA128 CAST5 BZIP2 ZLIB ZIP Uncompressed\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:138 +msgid "Generate a key:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:145 +#, no-wrap +msgid "" +"% gpg --full-gen-key\n" +"gpg (GnuPG) 2.1.8; Copyright (C) 2015 Free Software Foundation, Inc.\n" +"This is free software: you are free to change and redistribute it.\n" +"There is NO WARRANTY, to the extent permitted by law.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:166 +#, no-wrap +msgid "" +"Warning: using insecure memory!\n" +"Please select what kind of key you want:\n" +" (1) RSA and RSA (default)\n" +" (2) DSA and Elgamal\n" +" (3) DSA (sign only)\n" +" (4) RSA (sign only)\n" +"Your selection? 1\n" +"RSA keys may be between 1024 and 4096 bits long.\n" +"What keysize do you want? (2048) 2048 <.>\n" +"Requested keysize is 2048 bits\n" +"Please specify how long the key should be valid.\n" +"\t 0 = key does not expire\n" +" <n> = key expires in n days\n" +" <n>w = key expires in n weeks\n" +" <n>m = key expires in n months\n" +" <n>y = key expires in n years\n" +"Key is valid for? (0) 3y <.>\n" +"Key expires at Wed Nov 4 17:20:20 2015 MST\n" +"Is this correct? (y/N) y\n" +"GnuPG needs to construct a user ID to identify your key.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:172 +#, no-wrap +msgid "" +"Real name: Chucky Daemon <.>\n" +"Email address: notreal@example.com\n" +"Comment:\n" +"You selected this USER-ID:\n" +"\"Chucky Daemon <notreal@example.com>\"\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:175 +#, no-wrap +msgid "" +"Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o\n" +"You need a Passphrase to protect your secret key.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:178 +msgid "" +"2048-bit keys with a three-year expiration provide adequate protection at " +"present (2022-10)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:180 +msgid "" +"A three year key lifespan is short enough to obsolete keys weakened by " +"advancing computer power, but long enough to reduce key management problems." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:182 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:186 +msgid "" +"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: https://" +"world.std.com/~reinhold/diceware.html[], https://www.iusmentis.com/security/" +"passphrasefaq/[], https://xkcd.com/936/[], https://en.wikipedia.org/wiki/" +"Passphrase[]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:190 +msgid "" +"Protect the private key and passphrase. If either the private key or " +"passphrase may have been compromised or disclosed, immediately notify " +"mailto:accounts@FreeBSD.org[accounts@FreeBSD.org] and revoke the key." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:193 +msgid "" +"Committing the new key is shown in crossref:committers-guide[commit-steps, " +"Steps for New Committers]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:195 +#, no-wrap +msgid "Kerberos and LDAP web Password for FreeBSD Cluster" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:200 +msgid "" +"The FreeBSD cluster requires a Kerberos password to access certain " +"services. The Kerberos password also serves as the LDAP web password, since " +"LDAP is proxying to Kerberos in the cluster. Some of the services which " +"require this include:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:202 +msgid "https://bugs.freebsd.org/bugzilla[Bugzilla]" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:204 +msgid "" +"To create a new Kerberos account in the FreeBSD cluster, or to reset a " +"Kerberos password for an existing account using a random password generator:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:208 +#, no-wrap +msgid "% ssh kpasswd.freebsd.org\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:213 +msgid "This must be done from a machine outside of the FreeBSD.org cluster." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:216 +msgid "" +"A Kerberos password can also be set manually by logging into " +"`freefall.FreeBSD.org` and running:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:220 +#, no-wrap +msgid "% kpasswd\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:226 +msgid "" +"Unless the Kerberos-authenticated services of the FreeBSD.org cluster have " +"been used previously, `Client unknown` will be shown. This error means that " +"the `ssh kpasswd.freebsd.org` method shown above must be used first to " +"initialize the Kerberos account." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:229 +#, no-wrap +msgid "Commit Bit Types" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:235 +msgid "" +"The FreeBSD repository has a number of components which, when combined, " +"support the basic operating system source, documentation, third party " +"application ports infrastructure, and various maintained utilities. When " +"FreeBSD commit bits are allocated, the areas of the tree where the bit may " +"be used are specified. Generally, the areas associated with a bit reflect " +"who authorized the allocation of the commit bit. Additional areas of " +"authority may be added at a later date: when this occurs, the committer " +"should follow normal commit bit allocation procedures for that area of the " +"tree, seeking approval from the appropriate entity and possibly getting a " +"mentor for that area for some period of time." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:241 +#, no-wrap +msgid "__Committer Type__" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:242 +#, no-wrap +msgid "__Responsible__" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:244 +#, no-wrap +msgid "__Tree Components__" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:245 +#, no-wrap +msgid "src" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:246 +#, no-wrap +msgid "srcmgr@" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:248 +#, no-wrap +msgid "src/" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:249 +#, no-wrap +msgid "doc" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:250 +#, no-wrap +msgid "doceng@" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:252 +#, no-wrap +msgid "doc/, ports/, src/ documentation" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:253 +#, no-wrap +msgid "ports" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:254 +#, no-wrap +msgid "portmgr@" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:255 +#, no-wrap +msgid "ports/" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:260 +msgid "" +"Commit bits allocated prior to the development of the notion of areas of " +"authority may be appropriate for use in many parts of the tree. However, " +"common sense dictates that a committer who has not previously worked in an " +"area of the tree seek review prior to committing, seek approval from the " +"appropriate responsible party, and/or work with a mentor. Since the rules " +"regarding code maintenance differ by area of the tree, this is as much for " +"the benefit of the committer working in an area of less familiarity as it is " +"for others working on the tree." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:262 +msgid "" +"Committers are encouraged to seek review for their work as part of the " +"normal development process, regardless of the area of the tree where the " +"work is occurring." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:263 +#, no-wrap +msgid "Policy for Committer Activity in Other Trees" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:266 +msgid "" +"All committers may modify [.filename]#src/share/misc/committers-*.dot#, " +"[.filename]#src/usr.bin/calendar/calendars/calendar.freebsd#, and " +"[.filename]#ports/astro/xearth/files#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:267 +msgid "" +"doc committers may commit documentation changes to [.filename]#src# files, " +"such as manual pages, READMEs, fortune databases, calendar files, and " +"comment fixes without approval from a src committer, subject to the normal " +"care and tending of commits." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:269 +msgid "" +"Any committer may make changes to any other tree with an \"Approved by\" " +"from a non-mentored committer with the appropriate bit. Mentored committers " +"can provide a \"Reviewed by\" but not an \"Approved by\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:270 +msgid "" +"Committers can acquire an additional bit by the usual process of finding a " +"mentor who will propose them to srcmgr, doceng, or portmgr, as appropriate. " +"When approved, they will be added to 'access' and the normal mentoring " +"period will ensue, which will involve a continuing of \"Approved by\" for " +"some period." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:272 +#, no-wrap +msgid "Documentation Implicit (Blanket) Approval" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:276 +msgid "" +"Some types of fixes have \"blanket approval\" from the {doceng}, allowing " +"any committer to fix those categories of problems on any part of the doc " +"tree. These fixes do not need approval or review from a doc committer if " +"the author doesn't have a doc commit bit." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:278 +msgid "Blanket approval applies to these types of fixes:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:280 +msgid "Typos" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:281 +msgid "Trivial fixes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:283 +msgid "" +"Punctuation, URLs, dates, paths and file names with outdated or incorrect " +"information, and other common mistakes that may confound the readers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:286 +msgid "" +"Over the years, some implicit approvals were granted in the doc tree. This " +"list shows the most common cases:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:288 +msgid "" +"Changes in [.filename]#documentation/content/en/books/porters-handbook/" +"versions/_index.adoc#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:290 +msgid "" +"extref:{porters-handbook}versions/[__FreeBSD_version Values (Porter's " +"Handbook)], mainly used for src committers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:291 +msgid "Changes in [.filename]#doc/shared/contrib-additional.adoc#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:293 +msgid "" +"extref:{contributors}[Additional FreeBSD Contributors, contrib-additional] " +"maintenance." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:294 +msgid "All link:#commit-steps[Steps for New Committers], doc related" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:295 +msgid "Security advisories; Errata Notices; Releases;" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:297 +msgid "Used by {security-officer} and {re}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:298 +msgid "Changes in [.filename]#website/content/en/donations/donors.adoc#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:300 +msgid "Used by {donations}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:302 +msgid "" +"Before any commit, a build test is necessary; see the 'Overview' and 'The " +"FreeBSD Documentation Build Process' sections of the extref:{fdp-primer}" +"[FreeBSD Documentation Project Primer for New Contributors] for more details." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:304 +#, no-wrap +msgid "Git Primer" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:307 +#, no-wrap +msgid "Git basics" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:314 +msgid "" +"When one searches for \"Git Primer\" a number of good ones come up. Daniel " +"Miessler's link:https://danielmiessler.com/study/git/[A git primer] and " +"Willie Willus' link:https://gist.github.com/williewillus/" +"068e9a8543de3a7ef80adb2938657b6b[Git - Quick Primer] are both good " +"overviews. The Git book is also complete, but much longer https://git-" +"scm.com/book/en/v2. There is also this website https://dangitgit.com/ for " +"common traps and pitfalls of Git, in case you need guidance to fix things " +"up. Finally, an introduction link:https://eagain.net/articles/git-for-" +"computer-scientists/[targeted at computer scientists] has proven helpful to " +"some at explaining the Git world view." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:316 +msgid "" +"This document will assume that you've read through it and will try not to " +"belabor the basics (though it will cover them briefly)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:318 +#, no-wrap +msgid "Git Mini Primer" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:321 +msgid "" +"This primer is less ambitiously scoped than the old Subversion Primer, but " +"should cover the basics." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:322 +#, no-wrap +msgid "Scope" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:328 +msgid "" +"If you want to download FreeBSD, compile it from sources, and generally keep " +"up to date that way, this primer is for you. It covers getting the sources, " +"updating the sources, bisecting and touches briefly on how to cope with a " +"few local changes. It covers the basics, and tries to give good pointers to " +"more in-depth treatment for when the reader finds the basics insufficient. " +"Other sections of this guide cover more advanced topics related to " +"contributing to the project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:332 +msgid "" +"The goal of this section is to highlight those bits of Git needed to track " +"sources. They assume a basic understanding of Git. There are many primers " +"for Git on the web, but the https://git-scm.com/book/en/v2[Git Book] " +"provides one of the better treatments." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:334 +#, no-wrap +msgid "Getting Started For Developers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:337 +msgid "" +"This section describes the read-write access for committers to push the " +"commits from developers or contributors." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:339 +#, no-wrap +msgid "Daily use" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:344 +msgid "" +"In the examples below, replace `${repo}` with the name of the desired " +"FreeBSD repository: `doc`, `ports`, or `src`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:347 +msgid "Clone the repository:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:351 +#, no-wrap +msgid "% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/${repo}.git\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:354 +msgid "Then you should have the official mirrors as your remote:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:360 +#, no-wrap +msgid "" +"% git remote -v\n" +"freebsd https://git.freebsd.org/${repo}.git (fetch)\n" +"freebsd https://git.freebsd.org/${repo}.git (push)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:363 +msgid "Configure the FreeBSD committer data:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:366 +msgid "" +"The commit hook in repo.freebsd.org checks the \"Commit\" field matches the " +"committer's information in FreeBSD.org. The easiest way to get the " +"suggested config is by executing `/usr/local/bin/gen-gitconfig.sh` script on " +"freefall:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:373 +#, no-wrap +msgid "" +"% gen-gitconfig.sh\n" +"[...]\n" +"% git config user.name (your name in gecos)\n" +"% git config user.email (your login)@FreeBSD.org\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:376 +msgid "Set the push URL:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:380 +#, no-wrap +msgid "% git remote set-url --push freebsd git@gitrepo.freebsd.org:${repo}.git\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:383 +msgid "" +"Then you should have separated fetch and push URLs as the most efficient " +"setup:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:389 +#, no-wrap +msgid "" +"% git remote -v\n" +"freebsd https://git.freebsd.org/${repo}.git (fetch)\n" +"freebsd git@gitrepo.freebsd.org:${repo}.git (push)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:392 +msgid "" +"Again, note that `gitrepo.freebsd.org` has been canonicalized to " +"`repo.freebsd.org`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:394 +msgid "Install commit message template hook:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:396 +msgid "For doc repository:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:401 +#, no-wrap +msgid "" +"% cd .git/hooks\n" +"% ln -s ../../.hooks/prepare-commit-msg\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:404 +msgid "For ports repository:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:408 +#, no-wrap +msgid "% git config --add core.hooksPath .hooks\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:411 +msgid "For src repository:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:416 +#, no-wrap +msgid "" +"% cd .git/hooks\n" +"% ln -s ../../tools/tools/git/hooks/prepare-commit-msg\n" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:419 +#, no-wrap +msgid "\"admin\" branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:422 +msgid "" +"The `access` and `mentors` files are stored in an orphan branch, `internal/" +"admin`, in each repository." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:424 +msgid "" +"Following example is how to check out the `internal/admin` branch to a local " +"branch named `admin`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:430 +#, no-wrap +msgid "" +"% git config --add remote.freebsd.fetch '+refs/internal/*:refs/internal/*'\n" +"% git fetch\n" +"% git checkout -b admin internal/admin\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:432 +msgid "Alternatively, you can add a worktree for the `admin` branch:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:436 +#, no-wrap +msgid "git worktree add -b admin ../${repo}-admin internal/admin\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:440 +msgid "" +"For browsing `internal/admin` branch on web: `https://cgit.freebsd.org/$" +"{repo}/log/?h=internal/admin`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:442 +msgid "For pushing, specify the full refspec:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:446 +#, no-wrap +msgid "git push freebsd HEAD:refs/internal/admin\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:448 +#, no-wrap +msgid "Keeping Current With The FreeBSD src Tree" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:455 +msgid "" +"First step: cloning a tree. This downloads the entire tree. There are two " +"ways to download. Most people will want to do a deep clone of the " +"repository. However, there are times when you may wish to do a shallow " +"clone." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:456 +#, no-wrap +msgid "Branch Names" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:458 +msgid "FreeBSD-CURRENT uses the `main` branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:460 +msgid "`main` is the default branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:462 +msgid "For FreeBSD-STABLE, branch names include `stable/12` and `stable/13`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:464 +msgid "" +"For FreeBSD-RELEASE, release engineering branch names include `releng/12.4` " +"and `releng/13.2`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:466 +msgid "https://www.freebsd.org/releng/[] shows:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:468 +msgid "`main` and `stable/⋯` branches open" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:469 +msgid "`releng/⋯` branches, each of which is frozen when a release is tagged." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:471 +msgid "Examples:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:473 +msgid "" +"tag https://cgit.freebsd.org/src/tag/?h=release/13.1.0[release/13.1.0] on " +"the https://cgit.freebsd.org/src/log/?h=releng/13.1[releng/13.1] branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:474 +msgid "" +"tag https://cgit.freebsd.org/src/tag/?h=release/13.2.0[release/13.2.0] on " +"the https://cgit.freebsd.org/src/log/?h=releng/13.2[releng/13.2] branch." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:475 +#, no-wrap +msgid "Repositories" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:478 +msgid "" +"Please see the crossref:committers-guide[admin,Administrative Details] for " +"the latest information on where to get FreeBSD sources. $URL below can be " +"obtained from that page." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:481 +msgid "" +"Note: The project doesn't use submodules as they are a poor fit for our " +"workflows and development model. How we track changes in third-party " +"applications is discussed elsewhere and generally of little concern to the " +"casual user." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:482 +#, no-wrap +msgid "Deep Clone" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:486 +msgid "" +"A deep clone pulls in the entire tree, as well as all the history and " +"branches. It is the easiest to do. It also allows you to use Git's " +"worktree feature to have all your active branches checked out into separate " +"directories but with only one copy of the repository." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:489 +#, no-wrap +msgid "% git clone -o freebsd $URL -b branch [<directory>]\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:494 +msgid "" +"will create a deep clone. `branch` should be one of the branches listed in " +"the previous section. If no `branch` is given: the default (`main`) will be " +"used. If no `<directory>` is given: the name of the new directory will " +"match the name of the repo ([.filename]#doc#, [.filename]#ports# or " +"[.filename]#src#)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:499 +msgid "" +"You will want a deep clone if you are interested in the history, plan on " +"making local changes, or plan on working on more than one branch. It is the " +"easiest to keep up to date as well. If you are interested in the history, " +"but are working with only one branch and are short on space, you can also " +"use --single-branch to only download the one branch (though some merge " +"commits will not reference the merged-from branch which may be important for " +"some users who are interested in detailed versions of history)." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:500 +#, no-wrap +msgid "Shallow Clone" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:506 +msgid "" +"A shallow clone copies just the most current code, but none or little of the " +"history. This can be useful when you need to build a specific revision of " +"FreeBSD, or when you are just starting out and plan to track the tree more " +"fully. You can also use it to limit history to only so many revisions. " +"However, see below for a significant limitation of this approach." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:510 +#, no-wrap +msgid "% git clone -o freebsd -b branch --depth 1 $URL [dir]\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:515 +msgid "" +"This clones the repository, but only has the most recent version in the " +"repository. The rest of the history is not downloaded. Should you change " +"your mind later, you can do `git fetch --unshallow` to get the old history." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:520 +msgid "" +"When you make a shallow clone, you will lose the commit count in your uname " +"output. This can make it more difficult to determine if your system needs " +"to be updated when a security advisory is issued." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:522 +#, no-wrap +msgid "Building" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:526 +msgid "" +"Once you've downloaded, building is done as described in the handbook, e.g.:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:533 +#, no-wrap +msgid "" +"% cd src\n" +"% make buildworld\n" +"% make buildkernel\n" +"% make installkernel\n" +"% make installworld\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:535 +msgid "so that won't be covered in depth here." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:538 +msgid "" +"If you want to build a custom kernel, extref:{handbook}[the kernel config " +"section, kernelconfig] of the FreeBSD Handbook recommends creating a file " +"MYKERNEL under sys/${ARCH}/conf with your changes against GENERIC. To have " +"MYKERNEL disregarded by Git, it can be added to .git/info/exclude." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:539 +#, no-wrap +msgid "Updating" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:543 +msgid "" +"To update both types of trees uses the same commands. This pulls in all the " +"revisions since your last update." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:546 +#, no-wrap +msgid "% git pull --ff-only\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:551 +msgid "" +"will update the tree. In Git, a 'fast forward' merge is one that only needs " +"to set a new branch pointer and doesn't need to re-create the commits. By " +"always doing a fast forward merge/pull, you'll ensure that you have an exact " +"copy of the FreeBSD tree. This will be important if you want to maintain " +"local patches." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:554 +msgid "" +"See below for how to manage local changes. The simplest is to use `--" +"autostash` on the `git pull` command, but more sophisticated options are " +"available." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:555 +#, no-wrap +msgid "Selecting a Specific Version" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:559 +msgid "" +"In Git, `git checkout` checks out both branches and specific versions. " +"Git's versions are the long hashes rather than a sequential number." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:561 +msgid "" +"When you checkout a specific version, just specify the hash you want on the " +"command line (the git log command can help you decide which hash you might " +"want):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:564 +#, no-wrap +msgid "% git checkout 08b8197a74\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:567 +msgid "" +"and you have that checked out. You will be greeted with a message similar " +"to the following:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:570 +#, no-wrap +msgid "Note: checking out '08b8197a742a96964d2924391bf9fdfeb788865d'.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:574 +#, no-wrap +msgid "" +"You are in a 'detached HEAD' state. You can look around, make experimental\n" +"changes and commit them, and you can discard any commits you make in this\n" +"state without impacting any branches by performing another checkout.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:577 +#: documentation/content/en/articles/committers-guide/_index.adoc:1746 +#, no-wrap +msgid "" +"If you want to create a new branch to retain commits you create, you may\n" +"do so (now or later) by using -b with the checkout command again. Example:\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:579 +#: documentation/content/en/articles/committers-guide/_index.adoc:1748 +#, no-wrap +msgid " git checkout -b <new-branch-name>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:581 +#, no-wrap +msgid "HEAD is now at 08b8197a742a hook gpiokeys.4 to the build\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:585 +msgid "" +"where the last line is generated from the hash you are checking out and the " +"first line of the commit message from that revision. The hash can be " +"abbreviated to the shortest unique length. Git itself is inconsistent about " +"how many digits it displays." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:586 +#, no-wrap +msgid "Bisecting" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:590 +msgid "" +"Sometimes, things go wrong. The last version worked, but the one you just " +"updated to does not. A developer may ask you to bisect the problem to track " +"down which commit caused the regression." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:595 +msgid "" +"Git makes bisecting changes easy with a powerful `git bisect` command. " +"Here's a brief outline of how to use it. For more information, you can view " +"https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-" +"elimination or https://git-scm.com/docs/git-bisect for more details. The " +"man git-bisect page is good at describing what can go wrong, what to do when " +"versions won't build, when you want to use terms other than 'good' and " +"'bad', etc, none of which will be covered here." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:602 +msgid "" +"`git bisect start --first-parent` will start the bisection process. Next, " +"you need to tell a range to go through. `git bisect good XXXXXX` will tell " +"it the working version and `git bisect bad XXXXX` will tell it the bad " +"version. The bad version will almost always be HEAD (a special tag for what " +"you have checked out). The good version will be the last one you checked " +"out. The `--first-parent` argument is necessary so that subsequent `git " +"bisect` commands do not try to check out a vendor branch which lacks the " +"full FreeBSD source tree." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:606 +msgid "" +"If you want to know the last version you checked out, you should use `git " +"reflog`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:611 +#, no-wrap +msgid "" +"5ef0bd68b515 (HEAD -> main, freebsd/main, freebsd/HEAD) HEAD@{0}: pull --ff-only: Fast-forward\n" +"a8163e165c5b (upstream/main) HEAD@{1}: checkout: moving from b6fb97efb682994f59b21fe4efb3fcfc0e5b9eeb to main\n" +"...\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:615 +msgid "" +"shows me moving the working tree to the `main` branch (a816...) and then " +"updating from upstream (to 5ef0...). In this case, bad would be HEAD (or " +"5ef0bd68b515) and good would be a8163e165c5b. As you can see from the " +"output, HEAD@{1} also often works, but isn't foolproof if you have done " +"other things to your Git tree after updating, but before you discover the " +"need to bisect." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:619 +msgid "" +"Set the 'good' version first, then set the bad (though the order doesn't " +"matter). When you set the bad version, it will give you some statistics on " +"the process:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:626 +#, no-wrap +msgid "" +"% git bisect start --first-parent\n" +"% git bisect good a8163e165c5b\n" +"% git bisect bad HEAD\n" +"Bisecting: 1722 revisions left to test after this (roughly 11 steps)\n" +"[c427b3158fd8225f6afc09e7e6f62326f9e4de7e] Fixup r361997 by balancing parens. Duh.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:635 +msgid "" +"You would then build/install that version. If it's good you'd type `git " +"bisect good` otherwise `git bisect bad`. If the version doesn't compile, " +"type `git bisect skip`. You will get a similar message to the above after " +"each step. When you are done, report the bad version to the developer (or " +"fix the bug yourself and send a patch). `git bisect reset` will end the " +"process and return you back to where you started (usually tip of `main`). " +"Again, the git-bisect manual (linked above) is a good resource for when " +"things go wrong or for unusual cases." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:637 +#, no-wrap +msgid "Signing the commits, tags, and pushes, with GnuPG" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:642 +msgid "" +"Git knows how to sign commits, tags, and pushes. When you sign a Git commit " +"or a tag, you can prove that the code you submitted came from you and wasn't " +"altered while you were transferring it. You also can prove that you " +"submitted the code and not someone else." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:644 +msgid "" +"A more in-depth documentation on signing commits and tags can be found in " +"the https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work[Git Tools - " +"Signing Your Work] chapter of the Git's book." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:646 +msgid "" +"The rationale behind signing pushes can be found in the https://github.com/" +"git/git/commit/a85b377d0419a9dfaca8af2320cc33b051cbed04[commit that " +"introduced the feature]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:649 +msgid "" +"The best way is to simply tell Git you always want to sign commits, tags, " +"and pushes. You can do this by setting a few configuration variables:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:656 +#, no-wrap +msgid "" +"% git config --add user.signingKey LONG-KEY-ID\n" +"% git config --add commit.gpgSign true\n" +"% git config --add tag.gpgSign true\n" +"% git config --add push.gpgSign if-asked\n" +msgstr "" + +#. push.gpgSign should probably be set to `yes` once we enable it, or be set with --global, so that it is enabled for all repositories. +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:664 +msgid "" +"To avoid possible collisions, make sure you give a long key id to Git. You " +"can get the long id with: `gpg --list-secret-keys --keyid-format LONG`." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:670 +msgid "" +"To use specific subkeys, and not have GnuPG to resolve the subkey to a " +"primary key, attach `!` to the key. For example, to encrypt for the subkey " +"`DEADBEEF`, use `DEADBEEF!`." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:672 +#, no-wrap +msgid "Verifying signatures" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:675 +msgid "" +"Commit signatures can be verified by running either `git verify-commit " +"<commit hash>`, or `git log --show-signature`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:677 +msgid "" +"Tag signatures can be verified with `git verify-tag <tag name>`, or `git tag " +"-v <tag name>`." +msgstr "" + +# +# +#. Commented out for now until we decide what to do. +#. Git pushes are a bit different, they live in a special ref in the repository. +#. TODO: write how to verify them +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:686 +#, no-wrap +msgid "Ports Considerations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:689 +msgid "" +"The ports tree operates the same way. The branch names are different and " +"the repositories are in different locations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:692 +msgid "" +"The cgit repository web interface for use with web browsers is at https://" +"cgit.FreeBSD.org/ports/ . The production Git repository is at https://" +"git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or " +"anongit@git.FreeBSD.org:ports.git)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:696 +msgid "" +"There is also a mirror on GitHub, see extref:{handbook}/mirrors[External " +"mirrors, mirrors] for an overview. The _latest_ branch is `main`. The " +"_quarterly_ branches are named `yyyyQn` for year 'yyyy' and quarter 'n'." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:698 +#, no-wrap +msgid "Commit message formats" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:702 +msgid "" +"A hook is available in the ports repository to help you write up your commit " +"messages in https://cgit.freebsd.org/ports/tree/.hooks/prepare-commit-" +"msg[.hooks/prepare-commit-message]. It can be enabled by running ``git " +"config --add core.hooksPath .hooks``." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:704 +msgid "" +"The main point being that a commit message should be formatted in the " +"following way:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:707 +#, no-wrap +msgid "category/port: Summary.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:709 +#, no-wrap +msgid "Description of why the changes where made.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:711 +#, no-wrap +msgid "PR:\t 12345\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:717 +msgid "" +"The first line is the subject of the commit, it contains what port was " +"changed, and a summary of the commit. It should contain 50 characters or " +"less." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:719 +msgid "A blank line should separate it from the rest of the commit message." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:721 +msgid "" +"The rest of the commit message should be wrapped at the 72 characters " +"boundary." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:723 +msgid "" +"Another blank line should be added if there are any metadata fields, so that " +"they are easily distinguishable from the commit message." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:725 +#, no-wrap +msgid "Managing Local Changes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:728 +msgid "" +"This section addresses tracking local changes. If you have no local changes " +"you can skip this section." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:734 +msgid "" +"One item that is important for all of them: all changes are local until " +"pushed. Unlike Subversion, Git uses a distributed model. For users, for " +"most things, there is very little difference. However, if you have local " +"changes, you can use the same tool to manage them as you use to pull in " +"changes from FreeBSD. All changes that you have not pushed are local and " +"can easily be modified (git rebase, discussed below does this)." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:735 +#, no-wrap +msgid "Keeping local changes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:742 +msgid "" +"The simplest way to keep local changes (especially trivial ones) is to use " +"`git stash`. In its simplest form, you use `git stash` to record the " +"changes (which pushes them onto the stash stack). Most people use this to " +"save changes before updating the tree as described above. They then use " +"`git stash apply` to re-apply them to the tree. The stash is a stack of " +"changes that can be examined with `git stash list`. The git-stash man page " +"(https://git-scm.com/docs/git-stash) has all the details." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:746 +msgid "" +"This method is suitable when you have tiny tweaks to the tree. When you " +"have anything non trivial, you'll likely be better off keeping a local " +"branch and rebasing. Stashing is also integrated with the `git pull` " +"command: just add `--autostash` to the command line." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:747 +#, no-wrap +msgid "Keeping a local branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:754 +msgid "" +"It is much easier to keep a local branch with Git than Subversion. In " +"Subversion you need to merge the commit, and resolve the conflicts. This is " +"manageable, but can lead to a convoluted history that's hard to upstream " +"should that ever be necessary, or hard to replicate if you need to do so. " +"Git also allows one to merge, along with the same problems. That's one way " +"to manage the branch, but it's the least flexible." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:758 +msgid "" +"In addition to merging, Git supports the concept of 'rebasing' which avoids " +"these issues. The `git rebase` command replays all the commits of a branch " +"at a newer location on the parent branch. We will cover the most common " +"scenarios that arise using it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:760 +msgid "====== Create a branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:765 +msgid "" +"Let's say you want to make a change to FreeBSD's ls command to never, ever " +"do color. There are many reasons to do this, but this example will use that " +"as a baseline. The FreeBSD ls command changes from time to time, and you'll " +"need to cope with those changes. Fortunately, with Git rebase it usually is " +"automatic." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:787 +#, no-wrap +msgid "" +"% cd src\n" +"% git checkout main\n" +"% git checkout -b no-color-ls\n" +"% cd bin/ls\n" +"% vi ls.c # hack the changes in\n" +"% git diff # check the changes\n" +"diff --git a/bin/ls/ls.c b/bin/ls/ls.c\n" +"index 7378268867ef..cfc3f4342531 100644\n" +"--- a/bin/ls/ls.c\n" +"+++ b/bin/ls/ls.c\n" +"@@ -66,6 +66,7 @@ __FBSDID(\"$FreeBSD$\");\n" +" #include <stdlib.h>\n" +" #include <string.h>\n" +" #include <unistd.h>\n" +"+#undef COLORLS\n" +" #ifdef COLORLS\n" +" #include <termcap.h>\n" +" #include <signal.h>\n" +"% # these look good, make the commit...\n" +"% git commit ls.c\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:794 +msgid "" +"The commit will pop you into an editor to describe what you've done. Once " +"you enter that, you have your own **local** branch in the Git repo. Build " +"and install it like you normally would, following the directions in the " +"handbook. Git differs from other version control systems in that you have " +"to tell it explicitly which files to commit. I have opted to do it on the " +"commit command line, but you can also do it with `git add` which many of the " +"more in depth tutorials cover." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:796 +msgid "====== Time to update" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:801 +msgid "" +"When it is time to bring in a new version, it is almost the same as w/o the " +"branches. You would update like you would above, but there is one extra " +"command before you update, and one after. The following assumes you are " +"starting with an unmodified tree. It is important to start rebasing " +"operations with a clean tree (Git requires this)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:807 +#, no-wrap +msgid "" +"% git checkout main\n" +"% git pull --ff-only\n" +"% git rebase -i main no-color-ls\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:812 +msgid "" +"This will bring up an editor that lists all the commits in it. For this " +"example, do not change it at all. This is typically what you are doing " +"while updating the baseline (though you also use the Git rebase command to " +"curate the commits you have in the branch)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:814 +msgid "" +"Once you are done with the above, you have to move the commits to ls.c " +"forward from the old version of FreeBSD to the newer one." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:821 +msgid "" +"Sometimes there are merge conflicts. That is OK. Do not panic. Instead, " +"handle them the same as any other merge conflicts. To keep it simple, I " +"will just describe a common issue that may arise. A pointer to a complete " +"treatment can be found at the end of this section." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:824 +msgid "" +"Let's say the includes changes upstream in a radical shift to terminfo as " +"well as a name change for the option. When you updated, you might see " +"something like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:834 +#, no-wrap +msgid "" +"Auto-merging bin/ls/ls.c\n" +"CONFLICT (content): Merge conflict in bin/ls/ls.c\n" +"error: could not apply 646e0f9cda11... no color ls\n" +"Resolve all conflicts manually, mark them as resolved with\n" +"\"git add/rm <conflicted_files>\", then run \"git rebase --continue\".\n" +"You can instead skip this commit: run \"git rebase --skip\".\n" +"To abort and get back to the state before \"git rebase\", run \"git rebase --abort\".\n" +"Could not apply 646e0f9cda11... no color ls\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:836 +msgid "which looks scary." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:838 +msgid "" +"If you bring up an editor, you will see it is a typical 3-way merge conflict " +"resolution that you may be familiar with from other source code systems (the " +"rest of ls.c has been omitted):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:848 +#, no-wrap +msgid "" +" <<<<<<< HEAD\n" +" #ifdef COLORLS_NEW\n" +" #include <terminfo.h>\n" +" =======\n" +" #undef COLORLS\n" +" #ifdef COLORLS\n" +" #include <termcap.h>\n" +" >>>>>>> 646e0f9cda11... no color ls\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:851 +msgid "The new code is first, and your code is second." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:853 +msgid "" +"The right fix here is to just add a #undef COLORLS_NEW before #ifdef and " +"then delete the old changes:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:858 +#, no-wrap +msgid "" +"#undef COLORLS_NEW\n" +"#ifdef COLORLS_NEW\n" +"#include <terminfo.h>\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:860 +msgid "save the file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:862 +msgid "The rebase was interrupted, so you have to complete it:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:866 +#, no-wrap +msgid "" +"% git add ls.c\n" +"% git rebase --continue\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:871 +msgid "" +"which tells Git that ls.c has been fixed and to continue the rebase " +"operation. Since there was a conflict, you will get kicked into the editor " +"to update the commit message if necessary. If the commit message is still " +"accurate, just exit the editor." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:876 +msgid "" +"If you get stuck during the rebase, do not panic. git rebase --abort will " +"take you back to a clean slate. It is important, though, to start with an " +"unmodified tree. An aside: The above mentioned `git reflog` comes in handy " +"here, as it will have a list of all the (intermediate) commits that you can " +"view or inspect or cherry-pick." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:879 +msgid "" +"For more on this topic, https://www.freecodecamp.org/news/the-ultimate-guide-" +"to-git-merge-and-git-rebase/ provides a rather extensive treatment. It is a " +"good resource for issues that arise occasionally but are too obscure for " +"this guide." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:880 +#, no-wrap +msgid "Switching to a Different FreeBSD Branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:883 +msgid "" +"If you wish to shift from stable/12 to the current branch. If you have a " +"deep clone, the following will suffice:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:887 +#, no-wrap +msgid "" +"% git checkout main\n" +"% # build and install here...\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:892 +msgid "" +"If you have a local branch, though, there are one or two caveats. First, " +"rebase will rewrite history, so you will likely want to do something to save " +"it. Second, jumping branches tends to cause more conflicts. If we pretend " +"the example above was relative to stable/12, then to move to `main`, I'd " +"suggest the following:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:897 +#, no-wrap +msgid "" +"% git checkout no-color-ls\n" +"% git checkout -b no-color-ls-stable-12 # create another name for this branch\n" +"% git rebase -i stable/12 no-color-ls --onto main\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:904 +msgid "" +"What the above does is checkout no-color-ls. Then create a new name for it " +"(no-color-ls-stable-12) in case you need to get back to it. Then you rebase " +"onto the `main` branch. This will find all the commits to the current no-" +"color-ls branch (back to where it meets up with the stable/12 branch) and " +"then it will replay them onto the `main` branch creating a new no-color-ls " +"branch there (which is why I had you create a place holder name)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:906 +#, no-wrap +msgid "MFC (Merge From Current) Procedures" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:907 +#, no-wrap +msgid "Summary" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:911 +msgid "" +"MFC workflow can be summarized as `git cherry-pick -x` plus `git commit --" +"amend` to adjust the commit message. For multiple commits, use `git rebase " +"-i` to squash them together and edit the commit message." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:912 +#, no-wrap +msgid "Single commit MFC" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:918 +#, no-wrap +msgid "" +"% git checkout stable/X\n" +"% git cherry-pick -x $HASH --edit\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:922 +msgid "" +"For MFC commits, for example a vendor import, you would need to specify one " +"parent for cherry-pick purposes. Normally, that would be the \"first " +"parent\" of the branch you are cherry-picking from, so:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:927 +#, no-wrap +msgid "" +"% git checkout stable/X\n" +"% git cherry-pick -x $HASH -m 1 --edit\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:930 +msgid "" +"If things go wrong, you'll either need to abort the cherry-pick with `git " +"cherry-pick --abort` or fix it up and do a `git cherry-pick --continue`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:933 +msgid "" +"Once the cherry-pick is finished, push with `git push`. If you get an error " +"due to losing the commit race, use `git pull --rebase` and try to push again." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:934 +#, no-wrap +msgid "MFC to RELENG branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:938 +msgid "" +"MFCs to branches that require approval require a bit more care. The process " +"is the same for either a typical merge or an exceptional direct commit." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:940 +msgid "" +"Merge or direct commit to the appropriate `stable/X` branch first before " +"merging to the `releng/X.Y` branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:941 +msgid "" +"Use the hash that's in the `stable/X` branch for the MFC to `releng/X.Y` " +"branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:942 +msgid "Leave both \"cherry picked from\" lines in the commit message." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:943 +msgid "Be sure to add the `Approved by:` line when you are in the editor." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:948 +#, no-wrap +msgid "" +"% git checkout releng/13.0\n" +"% git cherry-pick -x $HASH --edit\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:951 +msgid "" +"If you forget to to add the `Approved by:` line, you can do a `git commit --" +"amend` to edit the commit message before you push the change." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:952 +#, no-wrap +msgid "Multiple commit MFC" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:963 +#, no-wrap +msgid "" +"% git checkout -b tmp-branch stable/X\n" +"% for h in $HASH_LIST; do git cherry-pick -x $h; done\n" +"% git rebase -i stable/X\n" +"# mark each of the commits after the first as 'squash'\n" +"# Update the commit message to reflect all elements of commit, if necessary.\n" +"# Be sure to retain the \"cherry picked from\" lines.\n" +"% git push freebsd HEAD:stable/X\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:966 +msgid "If the push fails due to losing the commit race, rebase and try again:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:974 +#, no-wrap +msgid "" +"% git checkout stable/X\n" +"% git pull\n" +"% git checkout tmp-branch\n" +"% git rebase stable/X\n" +"% git push freebsd HEAD:stable/X\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:977 +msgid "Once the MFC is complete, you can delete the temporary branch:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:982 +#, no-wrap +msgid "" +"% git checkout stable/X\n" +"% git branch -d tmp-branch\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:984 +#, no-wrap +msgid "MFC a vendor import" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:989 +msgid "" +"Vendor imports are the only thing in the tree that creates a merge commit in " +"the `main` branch. Cherry picking merge commits into stable/XX presents an " +"additional difficulty because there are two parents for a merge commit. " +"Generally, you'll want the first parent's diff since that's the diff to " +"`main` (though there may be some exceptions)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:993 +#, no-wrap +msgid "% git cherry-pick -x -m 1 $HASH\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:996 +msgid "" +"is typically what you want. This will tell cherry-pick to apply the correct " +"diff." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1000 +msgid "" +"There are some, hopefully, rare cases where it's possible that the `main` " +"branch was merged backwards by the conversion script. Should that be the " +"case (and we've not found any yet), you'd change the above to `-m 2` to " +"pickup the proper parent. Just do:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1004 +#, no-wrap +msgid "" +"% git cherry-pick --abort\n" +"% git cherry-pick -x -m 2 $HASH\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1006 +msgid "to do that. The `--abort` will cleanup the failed first attempt." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1007 +#, no-wrap +msgid "Redoing a MFC" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1011 +msgid "" +"If you do a MFC, and it goes horribly wrong and you want to start over, then " +"the easiest way is to use `git reset --hard` like so:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1014 +#, no-wrap +msgid "% git reset --hard freebsd/stable/12\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1017 +msgid "" +"though if you have some revs you want to keep, and others you don't, using " +"`git rebase -i` is better." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1018 +#, no-wrap +msgid "Considerations when MFCing" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1021 +msgid "" +"When committing source commits to stable and releng branches, we have the " +"following goals:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1023 +msgid "" +"Clearly mark direct commits distinct from commits that land a change from " +"another branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1024 +msgid "Avoid introducing known breakage into stable and releng branches." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1025 +msgid "" +"Allow developers to determine which changes have or have not been landed " +"from one branch to another." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1027 +msgid "" +"With Subversion, we used the following practices to achieve these goals:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1029 +msgid "" +"Using `MFC` and `MFS` tags to mark commits that merged changes from another " +"branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1030 +msgid "Squashing fixup commits into the main commit when merging a change." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1031 +msgid "Recording mergeinfo so that `svn mergeinfo --show-revs` worked." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1035 +msgid "" +"With Git, we will need to use different strategies to achieve the same " +"goals. This document aims to define best practices when merging source " +"commits using Git that achieve these goals. In general, we aim to use Git's " +"native support to achieve these goals rather than enforcing practices built " +"on Subversion's model." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1038 +msgid "" +"One general note: due to technical differences with Git, we will not be " +"using Git \"merge commits\" (created via `git merge`) in stable or releng " +"branches. Instead, when this document refers to \"merge commits\", it means " +"a commit originally made to `main` that is replicated or \"landed\" to a " +"stable branch, or a commit from a stable branch that is replicated to a " +"releng branch with some variation of `git cherry-pick`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1039 +#, no-wrap +msgid "Finding Eligible Hashes to MFC" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1045 +msgid "" +"Git provides some built-in support for this via the `git cherry` and `git " +"log --cherry` commands. These commands compare the raw diffs of commits " +"(but not other metadata such as log messages) to determine if two commits " +"are identical. This works well when each commit from `main` is landed as a " +"single commit to a stable branch, but it falls over if multiple commits from " +"`main` are squashed together as a single commit to a stable branch. The " +"project makes extensive use of `git cherry-pick -x` with all lines preserved " +"to work around these difficulties and is working on automated tooling to " +"take advantage of this." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1046 +#, no-wrap +msgid "Commit message standards" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1047 +#, no-wrap +msgid "Marking MFCs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1050 +msgid "The project has adopted the following practice for marking MFCs:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1052 +msgid "" +"Use the `-x` flag with `git cherry-pick`. This adds a line to the commit " +"message that includes the hash of the original commit when merging. Since it " +"is added by Git directly, committers do not have to manually edit the commit " +"log when merging." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1054 +msgid "" +"When merging multiple commits, keep all the \"cherry picked from\" lines." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1055 +#, no-wrap +msgid "Trim Metadata?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1059 +msgid "" +"One area that was not clearly documented with Subversion (or even CVS) is " +"how to format metadata in log messages for MFC commits. Should it include " +"the metadata from the original commit unchanged, or should it be altered to " +"reflect information about the MFC commit itself?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1068 +msgid "" +"Historical practice has varied, though some of the variance is by field. " +"For example, MFCs that are relevant to a PR generally include the PR field " +"in the MFC so that MFC commits are included in the bug tracker's audit " +"trail. Other fields are less clear. For example, Phabricator shows the " +"diff of the last commit tagged to a review, so including Phabricator URLs " +"replaces the main commit with the landed commits. The list of reviewers is " +"also not clear. If a reviewer has approved a change to `main`, does that " +"mean they have approved the MFC commit? Is that true if it's identical code " +"only, or with merely trivial rework? It's clearly not true for more " +"extensive reworks. Even for identical code what if the commit doesn't " +"conflict but introduces an ABI change? A reviewer may have ok'd a commit for " +"`main` due to the ABI breakage but may not approve of merging the same " +"commit as-is. One will have to use one's best judgment until clear " +"guidelines can be agreed upon." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1072 +msgid "" +"For MFCs regulated by re@, new metadata fields are added, such as the " +"Approved by tag for approved commits. This new metadata will have to be " +"added via `git commit --amend` or similar after the original commit has been " +"reviewed and approved. We may also want to reserve some metadata fields in " +"MFC commits such as Phabricator URLs for use by re@ in the future." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1075 +msgid "" +"Preserving existing metadata provides a very simple workflow. Developers " +"use `git cherry-pick -x` without having to edit the log message." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1078 +msgid "" +"If instead we choose to adjust metadata in MFCs, developers will have to " +"edit log messages explicitly via the use of `git cherry-pick --edit` or `git " +"commit --amend`. However, as compared to svn, at least the existing commit " +"message can be pre-populated and metadata fields can be added or removed " +"without having to re-enter the entire commit message." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1080 +msgid "" +"The bottom line is that developers will likely need to curate their commit " +"message for MFCs that are non-trivial." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:1082 +#, no-wrap +msgid "Vendor Imports with Git" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1085 +msgid "This section describes the vendor import procedure with Git in detail." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1086 +#, no-wrap +msgid "Branch naming convention" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1089 +msgid "" +"All vendor branches and tags start with `vendor/`. These branches and tags " +"are visible by default." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1094 +msgid "" +"This chapter follows the convention that the `freebsd` origin is the origin " +"name for the official FreeBSD Git repository. If you use a different " +"convention, replace `freebsd` with the name you use instead in the examples " +"below." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1098 +msgid "" +"We will explore an example for updating NetBSD's mtree that is in our tree. " +"The vendor branch for this is `vendor/NetBSD/mtree`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1099 +#, no-wrap +msgid "Updating an old vendor import" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1105 +msgid "" +"The vendor trees usually have only the subset of the third-party software " +"that is appropriate to FreeBSD. These trees are usually tiny in comparison " +"to the FreeBSD tree. Git worktrees are thus quite small and fast and the " +"preferred method to use. Make sure that whatever directory you choose below " +"(the `../mtree`) does not currently exist." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1109 +#, no-wrap +msgid "% git worktree add ../mtree vendor/NetBSD/mtree\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1111 +#, no-wrap +msgid "Update the Sources in the Vendor Branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1114 +msgid "" +"Prepare a full, clean tree of the vendor sources. Import everything but " +"merge only what is needed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1118 +msgid "" +"This example assumes the NetBSD source is checked out from their GitHub " +"mirror in `~/git/NetBSD`. Note that \"upstream\" might have added or " +"removed files, so we want to make sure deletions are propagated as well. " +"package:net/rsync[] is commonly installed, so I'll use that." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1132 +#, no-wrap +msgid "" +"% cd ../mtree\n" +"% rsync -va --del --exclude=\".git\" ~/git/NetBSD/usr.sbin/mtree/ .\n" +"% git add -A\n" +"% git status\n" +"...\n" +"% git diff --staged\n" +"...\n" +"% git commit -m \"Vendor import of NetBSD's mtree at 2020-12-11\"\n" +"[vendor/NetBSD/mtree 8e7aa25fcf1] Vendor import of NetBSD's mtree at 2020-12-11\n" +" 7 files changed, 114 insertions(+), 82 deletions(-)\n" +"% git tag -a vendor/NetBSD/mtree/20201211\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1145 +msgid "" +"It is critical to verify that the source code you are importing comes from a " +"trustworthy source. Many open-source projects use cryptographic signatures " +"to sign code changes, git tags, and/or source code tarballs. Always verify " +"these signatures, and use isolation mechanisms like jails, chroot, in " +"combination with a dedicated, non-privileged user account that is different " +"from the one you regularly use (see the Updating the FreeBSD source tree " +"section below for more details), until you are confident that the source " +"code you are importing looks safe. Following the upstream development and " +"occasionally reviewing the upstream code changes can greatly help in " +"improving code quality and benefit everyone involved. It is also a good idea " +"to examine the git diff results before importing them into the vendor area." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1149 +msgid "" +"Always run the `git diff` and `git status` commands and examine the results " +"carefully. When in doubt, it is useful to do a `git annotate` on the vendor " +"branch or the upstream git repository to see who and why a change was made." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1152 +msgid "" +"In the example above we used `-m` to illustrate, but you should compose a " +"proper message in an editor (using a commit message template)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1157 +msgid "" +"It is also important to create an annotated tag using `git tag -a`, " +"otherwise the push will be rejected. Only annotated tags are allowed to be " +"pushed. The annotated tag gives you a chance to enter a commit message. " +"Enter the version you are importing, along with any salient new features or " +"fixes in that version." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1158 +#, no-wrap +msgid "Updating the FreeBSD Copy" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1161 +msgid "At this point you can push the import to `vendor` into our repo." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1165 +#, no-wrap +msgid "% git push --follow-tags freebsd vendor/NetBSD/mtree\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1168 +msgid "" +"`--follow-tags` tells `git push` to also push tags associated with the " +"locally committed revision." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1169 +#, no-wrap +msgid "Updating the FreeBSD source tree" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1173 +msgid "" +"Now you need to update the mtree in FreeBSD. The sources live in `contrib/" +"mtree` since it is upstream software." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1179 +msgid "" +"From time to time, we may have to make changes to the contributed code to " +"better satisfy FreeBSD's needs. Whenever possible, please try to contribute " +"the local changes back to the upstream projects, this helps them to better " +"support FreeBSD, and also saves your time for future conflict resolutions " +"when importing updates." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1184 +#, no-wrap +msgid "" +"% cd ../src\n" +"% git subtree merge -P contrib/mtree vendor/NetBSD/mtree\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1194 +msgid "" +"This would generate a subtree merge commit of `contrib/mtree` against the " +"local `vendor/NetBSD/mtree` branch. Examine the diff from the merge result " +"and the contents of the upstream branch. If the merge reduced our local " +"changes to more trivial difference like blank line or indenting changes, try " +"amending the local changes to reduce diff against upstream, or try to " +"contribute the remaining changes back to the upstream project. If there " +"were conflicts, you would need to fix them before committing. Include " +"details about the changes being merged in the merge commit message." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1208 +msgid "" +"Some open-source software includes a `configure` script that generates files " +"used to define how the code is built; usually, these generated files like " +"`config.h` should be updated as part of the import process. When doing this, " +"always keep in mind that these scripts are executable code running under the " +"current user's credentials. This process should always be run in an isolated " +"environment, ideally inside a jail that does not have network access, and " +"with an unprivileged account; or, at minimum, a dedicated account that is " +"different from the user account you normally use for everyday purposes or " +"for pushing to the FreeBSD source code repository. This minimizes the risk " +"of encountering bugs that can cause data loss or, in worse cases, " +"maliciously planted code. Using an isolated jail also prevents the configure " +"scripts from detecting locally installed software packages, which may lead " +"to unexpected results." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1215 +msgid "" +"When testing your changes, run them in a chroot or jailed environment, or " +"even within a virtual machine first, especially for kernel or library " +"modifications. This approach helps prevent adverse interactions with your " +"working environment. It can be particularly beneficial for changes to " +"libraries that many base system components use, among others." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1216 +#, no-wrap +msgid "Rebasing your change against latest FreeBSD source tree" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1219 +msgid "" +"Because the current policy recommends against using merges, if the upstream " +"FreeBSD `main` moved forward before you get a chance to push, you would have " +"to redo the merge." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1222 +msgid "" +"Regular `git rebase` or `git pull --rebase` doesn't know how to rebase a " +"merge commit **as a merge commit**, so instead of that you would have to " +"recreate the commit." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1224 +msgid "" +"The following steps should be taken to easily recreate the merge commit as " +"if `git rebase --merge-commits` worked properly:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1226 +msgid "cd to the top of the repo" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1227 +msgid "Create a side branch `XXX` with the **contents** of the merged tree." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1228 +msgid "" +"Update this side branch `XXX` to be merged and up-to-date with FreeBSD's " +"`main` branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1229 +msgid "" +"In the worst case scenario, you would still have to resolve merge conflicts, " +"if there was any, but this should be really rare." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1230 +msgid "" +"Resolve conflicts, and collapse multiple commits down to 1 if need be " +"(without conflicts, there's no collapse needed)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1231 +msgid "checkout `main`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1232 +msgid "create a branch `YYY` (allows for easier unwinding if things go wrong)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1233 +msgid "Re-do the subtree merge" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1234 +msgid "" +"Instead of resolving any conflicts from the subtree merge, checkout the " +"contents of XXX on top of it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1235 +msgid "" +"The trailing `.` is important, as is being at the top level of the repo." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1236 +msgid "" +"Rather than switching branches to XXX, it splats the contents of XXX on top " +"of the repo" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1237 +msgid "" +"Commit the results with the prior commit message (the example assumes " +"there's only one merge on the XXX branch)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1238 +msgid "Make sure the branches are the same." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1239 +msgid "" +"Do whatever review you need, including having others check it out if you " +"think that's needed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1240 +msgid "" +"Push the commit, if you 'lost the race' again, just redo these steps again " +"(see below for a recipe)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1241 +msgid "Delete the branches once the commit is upstream. They are throw-a-way." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1243 +msgid "" +"The commands one would use, following the above example of mtree, would be " +"like so (the `#` starts a comment to help link commands to descriptions " +"above):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1256 +#, no-wrap +msgid "" +"% cd ../src\t\t\t# CD to top of tree\n" +"% git checkout -b XXX\t\t# create new throw-away XXX branch for merge\n" +"% git fetch freebsd\t\t# Get changes from upstream from upstream\n" +"% git merge freebsd/main\t# Merge the changes and resolve conflicts\n" +"% git checkout -b YYY freebsd/main # Create new throw-away YYY branch for redo\n" +"% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree merge\n" +"% git checkout XXX .\t\t# XXX branch has the conflict resolution\n" +"% git commit -c XXX~1\t\t# -c reuses the commit message from commit before rebase\n" +"% git diff XXX YYY\t\t# Should be empty\n" +"% git show YYY\t\t\t# Should only have changes you want, and be a merge commit from vendor branch\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1259 +msgid "" +"Note: if things go wrong with the commit, you can reset the `YYY` branch by " +"reissuing the checkout command that created it with -B to start over:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1262 +#, no-wrap +msgid "% git checkout -B YYY freebsd/main # Create new throw-away YYY branch if starting over is just going to be easier\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1264 +#, no-wrap +msgid "Pushing the changes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1269 +msgid "" +"Once you think you have a set of changes that are good, you can push it to a " +"fork off GitHub or GitLab for others to review. One nice thing about Git is " +"that it allows you to publish rough drafts of your work for others to " +"review. While Phabricator is good for content review, publishing the " +"updated vendor branch and merge commits lets others check the details as " +"they will eventually appear in the repository." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1271 +msgid "" +"After review, when you are sure it is a good change, you can push it to the " +"FreeBSD repo:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1277 +#, no-wrap +msgid "" +"% git push freebsd YYY:main\t# put the commit on upstream's 'main' branch\n" +"% git branch -D XXX\t\t# Throw away the throw-a-way branches.\n" +"% git branch -D YYY\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1284 +msgid "" +"Note: I used `XXX` and `YYY` to make it obvious they are terrible names and " +"should not leave your machine. If you use such names for other work, then " +"you'll need to pick different names, or risk losing the other work. There " +"is nothing magic about these names. Upstream will not allow you to push " +"them, but never the less, please pay attention to the exact commands above. " +"Some commands use syntax that differs only slightly from typical uses and " +"that different behavior is critical to this recipe working." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1285 +#, no-wrap +msgid "How to redo things if need be" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1289 +msgid "" +"If you've tried to do the push in the previous section and it fails, then " +"you should do the following to 'redo' things. This sequence keeps the " +"commit with the commit message always at XXX~1 to make committing easier." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1298 +#, no-wrap +msgid "" +"% git checkout -B XXX YYY\t# recreate that throw-away-branch XXX and switch to it\n" +"% git merge freebsd/main\t# Merge the changes and resolve conflicts\n" +"% git checkout -B YYY freebsd/main # Recreate new throw-away YYY branch for redo\n" +"% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree merge\n" +"% git checkout XXX .\t\t# XXX branch has the conflict resolution\n" +"% git commit -c XXX~1\t\t# -c reuses the commit message from commit before rebase\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1301 +msgid "Then go check it out as above and push as above when ready." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:1302 +#, no-wrap +msgid "Creating a new vendor branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1309 +msgid "" +"There are a number of ways to create a new vendor branch. The recommended " +"way is to create a new repository and then merge that with FreeBSD. If one " +"is importing `glorbnitz` into the FreeBSD tree, release 3.1415. For the " +"sake of simplicity, we will not trim this release. It is a simple user " +"command that puts the nitz device into different magical glorb states and is " +"small enough trimming will not save much." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1310 +#, no-wrap +msgid "Create the repo" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1319 +#, no-wrap +msgid "" +"% cd /some/where\n" +"% mkdir glorbnitz\n" +"% cd glorbnitz\n" +"% git init\n" +"% git checkout -b vendor/glorbnitz\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1322 +msgid "" +"At this point, you have a new repo, where all new commits will go on the " +"`vendor/glorbnitz` branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1324 +msgid "" +"Git experts can also do this right in their FreeBSD clone, using `git " +"checkout --orphan vendor/glorbnitz` if they are more comfortable with that." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1325 +#, no-wrap +msgid "Copy the sources in" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1329 +msgid "" +"Since this is a new import, you can just cp the sources in, or use tar or " +"even rsync as shown above. And we will add everything, assuming no dot " +"files." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1334 +#, no-wrap +msgid "" +"% cp -r ~/glorbnitz/* .\n" +"% git add *\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1337 +msgid "" +"At this point, you should have a pristine copy of glorbnitz ready to commit." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1341 +#, no-wrap +msgid "% git commit -m \"Import GlorbNitz frobnosticator revision 3.1415\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1346 +msgid "" +"As above, I used `-m` for simplicity, but you should likely create a commit " +"message that explains what a Glorb is and why you'd use a Nitz to get it. " +"Not everybody will know so, for your actual commit, you should follow the " +"crossref:committers-guide[commit-log-message,commit log message] section " +"instead of emulating the brief style used here." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1347 +#, no-wrap +msgid "Now import it into our repository" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1350 +msgid "Now you need to import the branch into our repository." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1356 +#, no-wrap +msgid "" +"% cd /path/to/freebsd/repo/src\n" +"% git remote add glorbnitz /some/where/glorbnitz\n" +"% git fetch glorbnitz vendor/glorbnitz\n" +msgstr "" + +#. perhaps the real treasure was the friends it made along the way... +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1360 +msgid "" +"Note the vendor/glorbnitz branch is in the repo. At this point the `/some/" +"where/glorbnitz` can be deleted, if you like. It was only a means to an end." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1362 +#, no-wrap +msgid "Tag and push" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1365 +msgid "" +"Steps from here on out are much the same as they are in the case of updating " +"a vendor branch, though without the updating the vendor branch step." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1373 +#, no-wrap +msgid "" +"% git worktree add ../glorbnitz vendor/glorbnitz\n" +"% cd ../glorbnitz\n" +"% git tag --annotate vendor/glorbnitz/3.1415\n" +"# Make sure the commit is good with \"git show\"\n" +"% git push --follow-tags freebsd vendor/glorbnitz\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1376 +msgid "By 'good' we mean:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1378 +msgid "All the right files are present" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1379 +msgid "None of the wrong files are present" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1380 +msgid "The vendor branch points at something sensible" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1381 +msgid "The tag looks good, and is annotated" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1382 +msgid "" +"The commit message for the tag has a quick summary of what's new since the " +"last tag" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1383 +#, no-wrap +msgid "Time to finally merge it into the base tree" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1392 +#, no-wrap +msgid "" +"% cd ../src\n" +"% git subtree add -P contrib/glorbnitz vendor/glorbnitz\n" +"# Make sure the commit is good with \"git show\"\n" +"% git commit --amend # one last sanity check on commit message\n" +"% git push freebsd\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1395 +msgid "Here 'good' means:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1397 +msgid "" +"All the right files, and none of the wrong ones, were merged into contrib/" +"glorbnitz." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1398 +msgid "No other changes are in the tree." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1399 +msgid "" +"The commit messages look crossref:committers-guide[commit-log-message,good]. " +"It should contain a summary of what's changed since the last merge to the " +"FreeBSD `main` branch and any caveats." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1400 +msgid "" +"UPDATING should be updated if there is anything of note, such as user " +"visible changes, important upgrade concerns, etc." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1405 +msgid "" +"This hasn't connected `glorbnitz` to the build yet. How so do that is " +"specific to the software being imported and is beyond the scope of this " +"tutorial." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1407 +#, no-wrap +msgid "Keeping current" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1413 +msgid "" +"So, time passes. It's time now to update the tree for the latest changes " +"upstream. When you checkout `main` make sure that you have no diffs. It's " +"a lot easier to commit those to a branch (or use `git stash`) before doing " +"the following." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1416 +msgid "" +"If you are used to `git pull`, we strongly recommend using the `--ff-only` " +"option, and further setting it as the default option. Alternatively, `git " +"pull --rebase` is useful if you have changes staged in the `main` branch." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1420 +#, no-wrap +msgid "% git config --global pull.ff only\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1423 +msgid "" +"You may need to omit the --global if you want this setting to apply to only " +"this repository." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1429 +#, no-wrap +msgid "" +"% cd freebsd-src\n" +"% git checkout main\n" +"% git pull (--ff-only|--rebase)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1433 +msgid "" +"There is a common trap, that the combination command `git pull` will try to " +"perform a merge, which would sometimes creates a merge commit that didn't " +"exist before. This can be harder to recover from." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1435 +msgid "The longer form is also recommended." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1442 +#, no-wrap +msgid "" +"% cd freebsd-src\n" +"% git checkout main\n" +"% git fetch freebsd\n" +"% git merge --ff-only freebsd/main\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1447 +msgid "" +"These commands reset your tree to the `main` branch, and then update it from " +"where you pulled the tree from originally. It's important to switch to " +"`main` before doing this so it moves forward. Now, it's time to move the " +"changes forward:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1451 +#, no-wrap +msgid "% git rebase -i main working\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1458 +msgid "" +"This will bring up an interactive screen to change the defaults. For now, " +"just exit the editor. Everything should just apply. If not, then you'll " +"need to resolve the diffs. https://docs.github.com/en/free-pro-team@latest/" +"github/using-git/resolving-merge-conflicts-after-a-git-rebase[This github " +"document] can help you navigate this process." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1460 +#, no-wrap +msgid "Time to push changes upstream" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1463 +msgid "" +"First, ensure that the push URL is properly configured for the upstream " +"repository." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1467 +#, no-wrap +msgid "% git remote set-url --push freebsd ssh://git@gitrepo.freebsd.org/src.git\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1471 +msgid "" +"Then, verify that user name and email are configured right. We require that " +"they exactly match the passwd entry in FreeBSD cluster." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1473 +msgid "Use" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1477 +#, no-wrap +msgid "freefall% gen-gitconfig.sh\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1480 +msgid "" +"on freefall.freebsd.org to get a recipe that you can use directly, assuming /" +"usr/local/bin is in the PATH." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1485 +msgid "" +"The below command merges the `working` branch into the upstream `main` " +"branch. It's important that you curate your changes to be just like you " +"want them in the FreeBSD source repo before doing this. This syntax pushes " +"the `working` branch to `main`, moving the `main` branch forward. You will " +"only be able to do this if this results in a linear change to `main` (e.g. " +"no merges)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1489 +#, no-wrap +msgid "% git push freebsd working:main\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1492 +msgid "" +"If your push is rejected due to losing a commit race, rebase your branch " +"before trying again:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1499 +#, no-wrap +msgid "" +"% git checkout working\n" +"% git fetch freebsd\n" +"% git rebase freebsd/main\n" +"% git push freebsd working:main\n" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1502 +#, no-wrap +msgid "Time to push changes upstream (alternative)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1507 +msgid "" +"Some people find it easier to merge their changes to their local `main` " +"before pushing to the remote repository. Also, `git arc stage` moves " +"changes from a branch to the local `main` when you need to do a subset of a " +"branch. The instructions are similar to the prior section:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1512 +#, no-wrap +msgid "" +"% git checkout main\n" +"% git merge --ff-only `working`\n" +"% git push freebsd\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1515 +msgid "If you lose the race, then try again with" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1519 +#, no-wrap +msgid "" +"% git pull --rebase\n" +"% git push freebsd\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1522 +msgid "" +"These commands will fetch the most recent `freebsd/main` and then rebase the " +"local `main` changes on top of that, which is what you want when you lose " +"the commit race. Note: merging vendor branch commits will not work with " +"this technique." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1523 +#, no-wrap +msgid "Finding the Subversion Revision" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1527 +msgid "" +"You'll need to make sure that you've fetched the notes (see the " +"crossref:committers-guide[git-mini-daily-use, Daily use]for details). Once " +"you have these, notes will show up in the git log command like so:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1531 +#, no-wrap +msgid "% git log\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1534 +msgid "If you have a specific version in mind, you can use this construct:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1538 +#, no-wrap +msgid "% git log --grep revision=XXXX\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1542 +msgid "" +"to find the specific revision. The hex number after 'commit' is the hash " +"you can use to refer to this commit." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:1544 +#, no-wrap +msgid "Git FAQ" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1547 +msgid "" +"This section provides a number of targeted answers to questions that are " +"likely to come up often for users and developers." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1552 +msgid "" +"We use the common convention of having the origin for the FreeBSD repository " +"being 'freebsd' rather than the default 'origin' to allow people to use that " +"for their own development and to minimize \"whoops\" pushes to the wrong " +"repository." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1554 +#, no-wrap +msgid "Users" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1556 +#, no-wrap +msgid "How do I track -current and -stable with only one copy of the repository?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1561 +#, no-wrap +msgid "" +"**Q:** Although disk space is not a huge issue, it's more efficient to use only one copy of the repository.\n" +"With SVN mirroring, I could checkout multiple trees from the same repository.\n" +"How do I do this with Git?\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1565 +#, no-wrap +msgid "" +"**A:** You can use Git worktrees.\n" +"There's a number of ways to do this, but the simplest way is to use a clone to track -current, and a worktree to track stable releases.\n" +"While using a 'bare repository' has been put forward as a way to cope, it's more complicated and will not be documented here.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1568 +msgid "" +"First, you need to clone the FreeBSD repository, shown here cloning into " +"`freebsd-current` to reduce confusion. $URL is whatever mirror works best " +"for you:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1572 +#, no-wrap +msgid "% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' $URL freebsd-current\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1575 +msgid "then once that's cloned, you can simply create a worktree from it:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1580 +#, no-wrap +msgid "" +"% cd freebsd-current\n" +"% git worktree add ../freebsd-stable-12 stable/12\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1584 +msgid "" +"this will checkout `stable/12` into a directory named `freebsd-stable-12` " +"that's a peer to the `freebsd-current` directory. Once created, it's " +"updated very similarly to how you might expect:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1594 +#, no-wrap +msgid "" +"% cd freebsd-current\n" +"% git checkout main\n" +"% git pull --ff-only\n" +"# changes from upstream now local and current tree updated\n" +"% cd ../freebsd-stable-12\n" +"% git merge --ff-only freebsd/stable/12\n" +"# now your stable/12 is up to date too\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1597 +msgid "" +"I recommend using `--ff-only` because it's safer and you avoid accidentally " +"getting into a 'merge nightmare' where you have an extra change in your " +"tree, forcing a complicated merge rather than a simple one." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1599 +msgid "" +"Here's https://adventurist.me/posts/00296[a good writeup] that goes into " +"more detail." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1600 +#, no-wrap +msgid "Developers" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1602 +#, no-wrap +msgid "Ooops! I committed to `main`, instead of another branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1605 +#, no-wrap +msgid "**Q:** From time to time, I goof up and mistakenly commit to the `main` branch. What do I do?\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1607 +#, no-wrap +msgid "**A:** First, don't panic.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1611 +msgid "" +"Second, don't push. In fact, you can fix almost anything if you haven't " +"pushed. All the answers in this section assume no push has happened." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1613 +msgid "" +"The following answer assumes you committed to `main` and want to create a " +"branch called `issue`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1619 +#, no-wrap +msgid "" +"% git checkout -b issue # Create the 'issue' branch\n" +"% git checkout -B main freebsd/main # Reset main to upstream\n" +"% git checkout issue # Back to where you were\n" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1621 +#, no-wrap +msgid "Ooops! I committed something to the wrong branch!" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1625 +#, no-wrap +msgid "" +"**Q:** I was working on feature on the `wilma` branch, but accidentally committed a change relevant to the `fred` branch in 'wilma'.\n" +"What do I do?\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1629 +#, no-wrap +msgid "" +"**A:** The answer is similar to the previous one, but with cherry picking.\n" +"This assumes there's only one commit on wilma, but will generalize to more complicated situations.\n" +"It also assumes that it's the last commit on wilma (hence using wilma in the `git cherry-pick` command), but that too can be generalized.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1637 +#, no-wrap +msgid "" +"# We're on branch wilma\n" +"% git checkout fred\t\t# move to fred branch\n" +"% git cherry-pick wilma\t\t# copy the misplaced commit\n" +"% git checkout wilma\t\t# go back to wilma branch\n" +"% git reset --hard HEAD^\t# move what wilma refers to back 1 commit\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1640 +msgid "" +"If it is not the last commit, you can cherry-pick that one change from wilma " +"onto fred, then use `git rebase -i` to remove the change from wilma." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1647 +#, no-wrap +msgid "" +"# We're on branch wilma\n" +"% git checkout fred\t\t\t# move to fred branch\n" +"% git cherry-pick HASH_OF_CHANGE\t# copy the misplaced commit\n" +"% git rebase -i main wilma\t\t# drop the cherry-picked change\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1650 +#, no-wrap +msgid "**Q:** But what if I want to commit a few changes to `main`, but keep the rest in `wilma` for some reason?\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1656 +#, no-wrap +msgid "" +"**A:** The same technique above also works if you are wanting to 'land' parts of the branch you are working on into `main` before the rest of the branch is ready (say you noticed an unrelated typo, or fixed an incidental bug).\n" +"You can cherry pick those changes into `main`, then push to the parent repository.\n" +"Once you've done that, cleanup couldn't be simpler: just `git rebase -i`.\n" +"Git will notice you've done this and skip the common changes automatically (even if you had to change the commit message or tweak the commit slightly).\n" +"There's no need to switch back to wilma to adjust it: just rebase!\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1658 +#, no-wrap +msgid "**Q:** I want to split off some changes from branch `wilma` into branch `fred`\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1664 +#, no-wrap +msgid "" +"**A:** The more general answer would be the same as the previous.\n" +"You'd checkout/create the `fred` branch, cherry pick the changes you want from `wilma` one at a time, then rebase `wilma` to remove those changes you cherry picked.\n" +"`git rebase -i main wilma` will toss you into an editor, and remove the `pick` lines that correspond to the commits you copied to `fred`.\n" +"If all goes well, and there are no conflicts, you're done.\n" +"If not, you'll need to resolve the conflicts as you go.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1669 +msgid "" +"The other way to do this would be to checkout `wilma` and then create the " +"branch `fred` to point to the same point in the tree. You can then `git " +"rebase -i` both these branches, selecting the changes you want in `fred` or " +"`wilma` by retaining the pick likes, and deleting the rest from the editor. " +"Some people would create a tag/branch called `pre-split` before starting in " +"case something goes wrong in the split. You can undo it with the following " +"sequence:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1676 +#, no-wrap +msgid "" +"% git checkout pre-split\t# Go back\n" +"% git branch -D fred\t\t# delete the fred branch\n" +"% git checkout -B wilma\t\t# reset the wilma branch\n" +"% git branch -d pre-split\t# Pretend it didn't happen\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1680 +msgid "" +"The last step is optional. If you are going to try again to split, you'd " +"omit it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1684 +#, no-wrap +msgid "" +"**Q:** But I did things as I read along and didn't see your advice at the end to create a branch, and now `fred` and `wilma` are all screwed up.\n" +"How do I find what `wilma` was before I started.\n" +"I don't know how many times I moved things around.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1686 +#, no-wrap +msgid "**A:** All is not lost. You can figure out it, so long as it hasn't been too long, or too many commits (hundreds).\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1690 +msgid "" +"So I created a wilma branch and committed a couple of things to it, then " +"decided I wanted to split it into fred and wilma. Nothing weird happened " +"when I did that, but let's say it did. The way to look at what you've done " +"is with the `git reflog`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1705 +#, no-wrap +msgid "" +"% git reflog\n" +"6ff9c25 (HEAD -> wilma) HEAD@{0}: rebase -i (finish): returning to refs/heads/wilma\n" +"6ff9c25 (HEAD -> wilma) HEAD@{1}: rebase -i (start): checkout main\n" +"869cbd3 HEAD@{2}: rebase -i (start): checkout wilma\n" +"a6a5094 (fred) HEAD@{3}: rebase -i (finish): returning to refs/heads/fred\n" +"a6a5094 (fred) HEAD@{4}: rebase -i (pick): Encourage contributions\n" +"1ccd109 (freebsd/main, main) HEAD@{5}: rebase -i (start): checkout main\n" +"869cbd3 HEAD@{6}: rebase -i (start): checkout fred\n" +"869cbd3 HEAD@{7}: checkout: moving from wilma to fred\n" +"869cbd3 HEAD@{8}: commit: Encourage contributions\n" +"...\n" +"%\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1713 +msgid "" +"Here we see the changes I've made. You can use it to figure out where " +"things went wrong. I'll just point out a few things here. The first one is " +"that HEAD@{X} is a 'commitish' thing, so you can use that as an argument to " +"a command. Although if that command commits anything to the repository, the " +"X numbers change. You can also use the hash (first column)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1721 +msgid "" +"Next, 'Encourage contributions' was the last commit I made to `wilma` before " +"I decided to split things up. You can also see the same hash is there when " +"I created the `fred` branch to do that. I started by rebasing `fred` and " +"you see the 'start', each step, and the 'finish' for that process. While we " +"don't need it here, you can figure out exactly what happened. Fortunately, " +"to fix this, you can follow the prior answer's steps, but with the hash " +"`869cbd3` instead of `pre-split`. While that seems a bit verbose, it's easy " +"to remember since you're doing one thing at a time. You can also stack:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1726 +#, no-wrap +msgid "" +"% git checkout -B wilma 869cbd3\n" +"% git branch -D fred\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1733 +msgid "" +"and you are ready to try again. The `checkout -B` with the hash combines " +"checking out and creating a branch for it. The `-B` instead of `-b` forces " +"the movement of a pre-existing branch. Either way works, which is what's " +"great (and awful) about Git. One reason I tend to use `git checkout -B xxxx " +"hash` instead of checking out the hash, and then creating / moving the " +"branch is purely to avoid the slightly distressing message about detached " +"heads:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1739 +#, no-wrap +msgid "" +"% git checkout 869cbd3\n" +"M\tfaq.md\n" +"Note: checking out '869cbd3'.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1743 +#, no-wrap +msgid "" +"You are in 'detached HEAD' state. You can look around, make experimental\n" +"changes and commit them, and you can discard any commits you make in this\n" +"state without impacting any branches by performing another checkout.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1751 +#, no-wrap +msgid "" +"HEAD is now at 869cbd3 Encourage contributions\n" +"% git checkout -B wilma\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1754 +msgid "" +"this produces the same effect, but I have to read a lot more and severed " +"heads aren't an image I like to contemplate." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1755 +#, no-wrap +msgid "Ooops! I did a `git pull` and it created a merge commit, what do I do?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1759 +#, no-wrap +msgid "" +"**Q:** I was on autopilot and did a `git pull` for my development tree and that created a merge commit on `main`.\n" +"How do I recover?\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1761 +#, no-wrap +msgid "**A:** This can happen when you invoke the pull with your development branch checked out.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1763 +msgid "Many developers use `git pull --rebase` to avoid this situation." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1766 +msgid "" +"Right after the pull, you will have the new merge commit checked out. Git " +"supports a `HEAD^#` syntax to examine the parents of a merge commit:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1771 +#, no-wrap +msgid "" +"git log --oneline HEAD^1 # Look at the first parent's commits\n" +"git log --oneline HEAD^2 # Look at the second parent's commits\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1775 +msgid "" +"From those logs, you can easily identify which commit is your development " +"work. Then you simply reset your branch to the corresponding `HEAD^#`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1779 +#, no-wrap +msgid "git reset --hard HEAD^1\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1782 +msgid "" +"In addition, a `git pull --rebase` at this stage will rebase your changes to " +"'main' to the latest 'freebsd/main'." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1784 +#, no-wrap +msgid "**Q:** But I also need to fix my `main` branch. How do I do that?\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1787 +#, no-wrap +msgid "" +"**A:** Git keeps track of the remote repository branches in a `freebsd/` namespace.\n" +"To fix your `main` branch, just make it point to the remote's `main`:\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1791 +#, no-wrap +msgid "git branch -f main freebsd/main\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1796 +msgid "" +"There's nothing magical about branches in Git: they are just labels on a " +"graph that are automatically moved forward by making commits. So the above " +"works because you're just moving a label. There's no metadata about the " +"branch that needs to be preserved due to this." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1797 +#, no-wrap +msgid "Mixing and matching branches" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1801 +#, no-wrap +msgid "" +"**Q:** So I have two branches `worker` and `async` that I'd like to combine into one branch called `feature`\n" +"while maintaining the commits in both.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1803 +#, no-wrap +msgid "**A:** This is a job for cherry pick.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1809 +#, no-wrap +msgid "" +"% git checkout worker\n" +"% git checkout -b feature\t# create a new branch\n" +"% git cherry-pick main..async\t# bring in the changes\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1814 +msgid "" +"You now have a new branch called `feature`. This branch combines commits " +"from both branches. You can further curate it with `git rebase`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1816 +#, no-wrap +msgid "**Q:** I have a branch called `driver` and I'd like to break it up into `kernel` and `userland` so I can evolve them separately and commit each branch as it becomes ready.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1819 +#, no-wrap +msgid "" +"**A:** This takes a little bit of prep work, but `git rebase` will do the heavy\n" +"lifting here.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1825 +#, no-wrap +msgid "" +"% git checkout driver\t\t# Checkout the driver\n" +"% git checkout -b kernel\t# Create kernel branch\n" +"% git checkout -b userland\t# Create userland branch\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1830 +msgid "" +"Now you have two identical branches. So, it's time to separate out the " +"commits. We'll assume first that all the commits in `driver` go into either " +"the `kernel` or the `userland` branch, but not both." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1834 +#, no-wrap +msgid "% git rebase -i main kernel\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1837 +msgid "" +"and just include the changes you want (with a 'p' or 'pick' line) and just " +"delete the commits you don't (this sounds scary, but if worse comes to " +"worse, you can throw this all away and start over with the `driver` branch " +"since you've not yet moved it)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1841 +#, no-wrap +msgid "% git rebase -i main userland\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1844 +msgid "and do the same thing you did with the `kernel` branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1847 +#, no-wrap +msgid "" +"**Q:** Oh great! I followed the above and forgot a commit in the `kernel` branch.\n" +"How do I recover?\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1850 +#, no-wrap +msgid "" +"**A:** You can use the `driver` branch to find the hash of the commit is missing and\n" +"cherry pick it.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1856 +#, no-wrap +msgid "" +"% git checkout kernel\n" +"% git log driver\n" +"% git cherry-pick $HASH\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1862 +#, no-wrap +msgid "" +"**Q:** OK. I have the same situation as the above, but my commits are all mixed up.\n" +"I need parts of one commit to go to one branch and the rest to go to the other.\n" +"In fact, I have several.\n" +"Your rebase method to select sounds tricky.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1865 +#, no-wrap +msgid "" +"**A:** In this situation, you'd be better off to curate the original branch to separate\n" +"out the commits, and then use the above method to split the branch.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1870 +msgid "" +"So let's assume that there's just one commit with a clean tree. You can " +"either use `git rebase` with an `edit` line, or you can use this with the " +"commit on the tip. The steps are the same either way. The first thing we " +"need to do is to back up one commit while leaving the changes uncommitted in " +"the tree:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1874 +#, no-wrap +msgid "% git reset HEAD^\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1877 +msgid "" +"Note: Do not, repeat do not, add `--hard` here since that also removes the " +"changes from your tree." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1881 +msgid "" +"Now, if you are lucky, the change needing to be split up falls entirely " +"along file lines. In that case you can just do the usual `git add` for the " +"files in each group than do a `git commit`. Note: when you do this, you'll " +"lose the commit message when you do the reset, so if you need it for some " +"reason, you should save a copy (though `git log $HASH` can recover it)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1884 +msgid "" +"If you are not lucky, you'll need to split apart files. There's another " +"tool to do that which you can apply one file at a time." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1888 +#, no-wrap +msgid "git add -i foo/bar.c\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1894 +msgid "" +"will step through the diffs, prompting you, one at time, whether to include " +"or exclude the hunk. Once you're done, `git commit` and you'll have the " +"remainder in your tree. You can run it multiple times as well, and even " +"over multiple files (though I find it easier to do one file at a time and " +"use the `git rebase -i` to fold the related commits together)." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1895 +#, no-wrap +msgid "Joining the FreeBSD GitHub oranization." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1898 +#, no-wrap +msgid "**Q:** How do I join the FreeBSD GitHub organization?\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1902 +#, no-wrap +msgid "" +"**A:** Please see https://wiki.freebsd.org/GitHub#Joining_the_Organisation[our GitHub Wiki Info] page for details.\n" +"Briefly, all FreeBSD committers may join.\n" +"Those who are not committers who request joining will be considered on a case by case basis.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1903 +#, no-wrap +msgid "Cloning and Mirroring" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1906 +#, no-wrap +msgid "**Q:** I'd like to mirror the entire Git repository, how do I do that?\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1908 +#, no-wrap +msgid "**A:** If all you want to do is mirror, then\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1912 +#, no-wrap +msgid "% git clone --mirror $URL\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1916 +msgid "" +"will do the trick. However, there are two disadvantages to this if you want " +"to use it for anything other than a mirror you'll reclone." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1920 +msgid "" +"First, this is a 'bare repository' which has the repository database, but no " +"checked out worktree. This is great for mirroring, but terrible for day to " +"day work. There's a number of ways around this with `git worktree`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1928 +#, no-wrap +msgid "" +"% git clone --mirror https://git.freebsd.org/ports.git ports.git\n" +"% cd ports.git\n" +"% git worktree add ../ports main\n" +"% git worktree add ../quarterly branches/2020Q4\n" +"% cd ../ports\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1931 +msgid "" +"But if you aren't using your mirror for further local clones, then it's a " +"poor match." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1934 +msgid "" +"The second disadvantage is that Git normally rewrites the refs (branch name, " +"tags, etc) from upstream so that your local refs can evolve independently of " +"upstream. This means that you'll lose changes if you are committing to this " +"repository on anything other than private project branches." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1936 +#, no-wrap +msgid "**Q:** So what can I do instead?\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1939 +#, no-wrap +msgid "" +"**A:** Well, you can stuff all of the upstream repository's refs into a private namespace in your local repository.\n" +"Git clones everything via a 'refspec' and the default refspec is:\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1943 +#, no-wrap +msgid " fetch = +refs/heads/*:refs/remotes/freebsd/*\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1946 +msgid "which says just fetch the branch refs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1950 +msgid "" +"However, the FreeBSD repository has a number of other things in it. To see " +"those, you can add explicit refspecs for each ref namespace, or you can " +"fetch everything. To setup your repository to do that:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1954 +#, no-wrap +msgid "git config --add remote.freebsd.fetch '+refs/*:refs/freebsd/*'\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1958 +msgid "" +"which will put everything in the upstream repository into your local " +"repository's `refs/freebsd/` namespace. Please note, that this also grabs " +"all the unconverted vendor branches and the number of refs associated with " +"them is quite large." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1960 +msgid "" +"You'll need to refer to these 'refs' with their full name because they " +"aren't in and of Git's regular namespaces." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1964 +#, no-wrap +msgid "git log refs/freebsd/vendor/zlib/1.2.10\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1967 +msgid "" +"would look at the log for the vendor branch for zlib starting at 1.2.10." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:1968 +#, no-wrap +msgid "Collaborating with others" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1972 +msgid "" +"One of the keys to good software development on a project as large as " +"FreeBSD is the ability to collaborate with others before you push your " +"changes to the tree. The FreeBSD project's Git repositories do not, yet, " +"allow user-created branches to be pushed to the repository, and therefore if " +"you wish to share your changes with others you must use another mechanism, " +"such as a hosted GitLab or GitHub, to share changes in a user-generated " +"branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1974 +msgid "" +"The following instructions show how to set up a user-generated branch, based " +"on the FreeBSD `main` branch, and push it to GitHub." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1977 +msgid "" +"Before you begin, make sure that your local Git repo is up to date and has " +"the correct origins set crossref:committers-guide[keeping_current,as shown " +"above]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1984 +msgid "" +"```` % git remote -v freebsd https://git.freebsd.org/src.git (fetch) " +"freebsd ssh://git@gitrepo.freebsd.org/src.git (push) ````" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1987 +msgid "" +"The first step is to create a fork of https://github.com/freebsd/freebsd-" +"src[FreeBSD] on GitHub following these https://docs.github.com/en/github/" +"getting-started-with-github/fork-a-repo[guidelines]. The destination of the " +"fork should be your own, personal, GitHub account (gvnn3 in my case)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1989 +msgid "Now add a remote on your local system that points to your fork:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1997 +#, no-wrap +msgid "" +"% git remote add github git@github.com:gvnn3/freebsd-src.git\n" +"% git remote -v\n" +"github\tgit@github.com:gvnn3/freebsd-src.git (fetch)\n" +"github\tgit@github.com:gvnn3/freebsd-src.git (push)\n" +"freebsd\thttps://git.freebsd.org/src.git (fetch)\n" +"freebsd\tssh://git@gitrepo.freebsd.org/src.git (push)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2000 +msgid "" +"With this in place you can create a branch crossref:committers-" +"guide[keeping_a_local_branch,as shown above]." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2004 +#, no-wrap +msgid "% git checkout -b gnn-pr2001-fix\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2008 +msgid "" +"Make whatever modifications you wish in your branch. Build, test, and once " +"you're ready to collaborate with others it's time to push your changes into " +"your hosted branch. Before you can push you'll have to set the appropriate " +"upstream, as Git will tell you the first time you try to push to your " +"+github+ remote:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2014 +#, no-wrap +msgid "" +"% git push github\n" +"fatal: The current branch gnn-pr2001-fix has no upstream branch.\n" +"To push the current branch and set the remote as upstream, use\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2016 +#, no-wrap +msgid " git push --set-upstream github gnn-pr2001-fix\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2019 +msgid "Setting the push as +git+ advises allows it to succeed:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2037 +#, no-wrap +msgid "" +"% git push --set-upstream github gnn-feature\n" +"Enumerating objects: 20486, done.\n" +"Counting objects: 100% (20486/20486), done.\n" +"Delta compression using up to 8 threads\n" +"Compressing objects: 100% (12202/12202), done.\n" +"Writing objects: 100% (20180/20180), 56.25 MiB | 13.15 MiB/s, done.\n" +"Total 20180 (delta 11316), reused 12972 (delta 7770), pack-reused 0\n" +"remote: Resolving deltas: 100% (11316/11316), completed with 247 local objects.\n" +"remote:\n" +"remote: Create a pull request for 'gnn-feature' on GitHub by visiting:\n" +"remote: https://github.com/gvnn3/freebsd-src/pull/new/gnn-feature\n" +"remote:\n" +"To github.com:gvnn3/freebsd-src.git\n" +" * [new branch] gnn-feature -> gnn-feature\n" +"Branch 'gnn-feature' set up to track remote branch 'gnn-feature' from 'github'.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2040 +msgid "Subsequent changes to the same branch will push correctly by default:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2053 +#, no-wrap +msgid "" +"% git push\n" +"Enumerating objects: 4, done.\n" +"Counting objects: 100% (4/4), done.\n" +"Delta compression using up to 8 threads\n" +"Compressing objects: 100% (2/2), done.\n" +"Writing objects: 100% (3/3), 314 bytes | 1024 bytes/s, done.\n" +"Total 3 (delta 1), reused 1 (delta 0), pack-reused 0\n" +"remote: Resolving deltas: 100% (1/1), completed with 1 local object.\n" +"To github.com:gvnn3/freebsd-src.git\n" +" 9e5243d7b659..cf6aeb8d7dda gnn-feature -> gnn-feature\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2057 +msgid "" +"At this point your work is now in your branch on +GitHub+ and you can share " +"the link with other collaborators." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2059 +#, no-wrap +msgid "Landing a github pull request" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2064 +msgid "" +"This section documents how to land a GitHub pull request that's submitted " +"against the FreeBSD Git mirrors at GitHub. While this is not an official " +"way to submit patches at this time, sometimes good fixes come in this way " +"and it is easiest just to bring them into a committer's tree and have them " +"pushed into the FreeBSD's tree from there. Similar steps can be used to " +"pull branches from other repositories and land those. When committing pull " +"requests from others, one should take extra care to examine all the changes " +"to ensure they are exactly as represented." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2068 +msgid "" +"Before beginning, make sure that the local Git repo is up to date and has " +"the correct origins set crossref:committers-guide[keeping_current,as shown " +"above]. In addition, make sure to have the following origins:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2075 +#, no-wrap +msgid "" +"% git remote -v\n" +"freebsd https://git.freebsd.org/src.git (fetch)\n" +"freebsd ssh://git@gitrepo.freebsd.org/src.git (push)\n" +"github https://github.com/freebsd/freebsd-src (fetch)\n" +"github https://github.com/freebsd/freebsd-src (fetch)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2090 +msgid "" +"Often pull requests are simple: requests that contain only a single commit. " +"In this case, a streamlined approach may be used, though the approach in the " +"prior section will also work. Here, a branch is created, the change is " +"cherry picked, the commit message adjusted, and sanity-checked before being " +"pushed. The branch `staging` is used in this example but it can be any " +"name. This technique works for any number of commits in the pull request, " +"especially when the changes apply cleanly to the FreeBSD tree. However, " +"when there's multiple commits, especially when minor adjustments are needed, " +"`git rebase -i` works better than `git cherry-pick`. Briefly, these " +"commands create a branch; cherry-picks the changes from the pull request; " +"tests it; adjusts the commit messages; and fast forward merges it back to " +"`main`. The PR number is `$PR` below. When adjusting the message, add " +"`Pull Request: https://github.com/freebsd-src/pull/$PR`. All pull requests " +"committed to the FreeBSD repository should be reviewed by at least one " +"person. This need not be the person committing it, but in that case the " +"person committing it should trust the other reviewers competence to review " +"the commit. Committers that do a code review of pull requests before " +"pushing them into the repo should add a `Reviewed by:` line to the commit, " +"because in this case it is not implicit. Add anybody that reviews and " +"approves the commit on github to `Reviewed by:` as well. As always, care " +"should be taken to ensure the change does what it is supposed to, and that " +"no malicious code is present." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:2094 +msgid "" +"In addition, please check to make sure that the pull request author name is " +"not anonymous. Github's web editing interface generates names like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2097 +#, no-wrap +msgid "Author: github-user <38923459+github-user@users.noreply.github.com>\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2100 +msgid "" +"A polite request to the author for a better name and/or email should be " +"made. Extra care should be taken to ensure no style issue or malicious code " +"is introduced." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2113 +#, no-wrap +msgid "" +"% git fetch github pull/$PR/head:staging\n" +"% git rebase -i main staging\t# to move the staging branch forward, adjust commit message here\n" +"<do testing here, as needed>\n" +"% git checkout main\n" +"% git pull --ff-only\t\t# to get the latest if time has passed\n" +"% git checkout main\n" +"% git merge --ff-only staging\n" +"<test again if needed>\n" +"% git push freebsd --push-option=confirm-author\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2118 +msgid "" +"For complicated pull requests that have multiple commits with conflicts, " +"follow the following outline." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2120 +msgid "checkout the pull request `git checkout github/pull/XXX`" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2121 +msgid "create a branch to rebase `git checkout -b staging`" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2122 +msgid "" +"rebase the `staging` branch to the latest `main` with `git rebase -i main " +"staging`" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2123 +msgid "resolve conflicts and do whatever testing is needed" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2124 +msgid "fast forward the `staging` branch into `main` as above" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2125 +msgid "final sanity check of changes to make sure all is well" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2126 +msgid "push to FreeBSD's Git repository." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2128 +msgid "" +"This will also work when bringing branches developed elsewhere into the " +"local tree for committing." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2131 +msgid "" +"Once finished with the pull request, close it using GitHub's web interface. " +"It is worth noting that if your `github` origin uses `https://`, the only " +"step you'll need a GitHub account for is closing the pull request." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:2133 +#, no-wrap +msgid "Version Control History" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2136 +msgid "The project has moved to crossref:committers-guide[git-primer,git]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2142 +msgid "" +"The FreeBSD source repository switched from CVS to Subversion on May 31st, " +"2008. The first real SVN commit is __r179447__. The source repository " +"switched from Subversion to Git on December 23rd, 2020. The last real svn " +"commit is __r368820__. The first real git commit hash is " +"__5ef5f51d2bef80b0ede9b10ad5b0e9440b60518c__." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2148 +msgid "" +"The FreeBSD `doc/www` repository switched from CVS to Subversion on May " +"19th, 2012. The first real SVN commit is __r38821__. The documentation " +"repository switched from Subversion to Git on December 8th, 2020. The last " +"SVN commit is __r54737__. The first real git commit hash is " +"__3be01a475855e7511ad755b2defd2e0da5d58bbe__." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2154 +msgid "" +"The FreeBSD `ports` repository switched from CVS to Subversion on July 14th, " +"2012. The first real SVN commit is __r300894__. The ports repository " +"switched from Subversion to Git on April 6, 2021. The last SVN commit is " +"__r569609__ The first real git commit hash is " +"__ed8d3eda309dd863fb66e04bccaa513eee255cbf__." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:2156 +#, no-wrap +msgid "Setup, Conventions, and Traditions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2161 +msgid "" +"There are a number of things to do as a new developer. The first set of " +"steps is specific to committers only. These steps must be done by a mentor " +"for those who are not committers." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2163 +#, no-wrap +msgid "For New Committers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2166 +msgid "" +"Those who have been given commit rights to the FreeBSD repositories must " +"follow these steps." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2168 +msgid "Get mentor approval before committing each of these changes!" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2169 +msgid "" +"All [.filename]#src# commits go to FreeBSD-CURRENT first before being merged " +"to FreeBSD-STABLE. The FreeBSD-STABLE branch must maintain ABI and API " +"compatibility with earlier versions of that branch. Do not merge changes " +"that break this compatibility." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2174 +#, no-wrap +msgid "*Steps for New Committers*\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2176 +msgid "Add an Author Entity" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2178 +msgid "" +"[.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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2179 +msgid "Update the List of Developers and Contributors" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2181 +msgid "" +"[.filename]#doc/shared/contrib-committers.adoc# - Add an entry, which will " +"then appear in the \"Developers\" section of the extref:{contributors}" +"[Contributors List, staff-committers]. Entries are sorted by last name." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2183 +msgid "" +"[.filename]#doc/shared/contrib-additional.adoc# - _Remove_ the entry. " +"Entries are sorted by first name." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2184 +msgid "Add a News Item" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2186 +msgid "" +"[.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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2187 +msgid "Add a PGP Key" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2189 +msgid "" +"`{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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2191 +msgid "" +"Use [.filename]#doc/documentation/tools/checkkey.sh# to verify that keys " +"meet minimal best-practices standards." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2193 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:2197 +msgid "" +"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://" +"docs.FreeBSD.org/pgpkeys/pgpkeys.txt[https://docs.FreeBSD.org/pgpkeys/" +"pgpkeys.txt]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2199 +msgid "Update Mentor and Mentee Information" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2201 +msgid "" +"[.filename]#src/share/misc/committers-<repository>.dot# - Add an entry to " +"the current committers section, where _repository_ is `doc`, `ports`, or " +"`src`, depending on the commit privileges granted." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2203 +msgid "" +"Add an entry for each additional mentor/mentee relationship in the bottom " +"section." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2204 +msgid "Generate a Kerberos Password" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2206 +msgid "" +"See crossref:committers-guide[kerberos-ldap, Kerberos and LDAP web Password " +"for FreeBSD Cluster] to generate or set a Kerberos account for use with " +"other FreeBSD services like the link:https://bugs.freebsd.org/bugzilla/[bug-" +"tracking database] (you get a bug-tracking account as part of that step)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2207 +msgid "Optional: Enable Wiki Account" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2211 +msgid "" +"link: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 link:https://wiki.freebsd.org/Wiki/About[Wiki/About " +"page] to obtain one. Contact mailto:wiki-admin@FreeBSD.org[wiki-" +"admin@FreeBSD.org] if you need help with your Wiki account." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2212 +msgid "Optional: Update Wiki Information" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2214 +msgid "" +"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], https://wiki.freebsd.org/" +"Community/Dogs[Dogs of FreeBSD], and or https://wiki.freebsd.org/Community/" +"Cats[Cats of FreeBSD] pages." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2215 +msgid "Optional: Update Ports with Personal Information" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2217 +msgid "" +"[.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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2218 +msgid "Optional: Prevent Duplicate Mailings" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2220 +msgid "" +"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." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2223 +#, no-wrap +msgid "For Everyone" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2229 +msgid "" +"Introduce yourself to the other developers, otherwise no one will have any " +"idea who you are or what you are working on. The introduction need not be a " +"comprehensive biography, just write a paragraph or two about who you are, " +"what you plan to be working on as a developer in FreeBSD, and who will be " +"your mentor. Email this to the {developers-name} and you will be on your way!" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2230 +msgid "" +"Log into `freefall.FreeBSD.org` and create a [.filename]#/var/forward/user# " +"(where _user_ is your username) file containing the e-mail address where you " +"want mail addressed to _yourusername_@FreeBSD.org to be forwarded. This " +"includes all of the commit messages as well as any other mail addressed to " +"the {committers-name} and the {developers-name}. Really large mailboxes " +"which have taken up permanent residence on `freefall` may get truncated " +"without warning if space needs to be freed, so forward it or save it " +"elsewhere." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:2234 +msgid "" +"If your e-mail system uses SPF with strict rules, you should exclude " +"`mx2.FreeBSD.org` from SPF checks." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2237 +msgid "" +"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`." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:2241 +msgid "" +"Those who are developers but not committers will not be subscribed to the " +"committers or developers mailing lists. The subscriptions are derived from " +"the access rights." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:2245 +#, no-wrap +msgid "SMTP Access Setup" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2248 +msgid "" +"For those willing to send e-mail messages through the FreeBSD.org " +"infrastructure, follow the instructions below:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2252 +msgid "Point your mail client at `smtp.FreeBSD.org:587`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2253 +msgid "Enable STARTTLS." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2254 +msgid "Ensure your `From:` address is set to `_yourusername_@FreeBSD.org`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2256 +msgid "" +"For authentication, you can use your FreeBSD Kerberos username and password " +"(see crossref:committers-guide[kerberos-ldap, Kerberos and LDAP web Password " +"for FreeBSD Cluster]). The `_yourusername_/mail` principal is preferred, as " +"it is only valid for authenticating to mail resources." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:2260 +msgid "Do not include `@FreeBSD.org` when entering in your username." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/committers-guide/_index.adoc:2262 +#, no-wrap +msgid "Additional Notes" +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:2266 +msgid "" +"Will only accept mail from `_yourusername_@FreeBSD.org`. If you are " +"authenticated as one user, you are not permitted to send mail from another." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:2267 +msgid "" +"A header will be appended with the SASL username: (`Authenticated sender: " +"_username_`)." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:2268 +msgid "" +"Host has various rate limits in place to cut down on brute force attempts." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:2272 +#, no-wrap +msgid "Using a Local MTA to Forward Emails to the FreeBSD.org SMTP Service" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2275 +msgid "" +"It is also possible to use a local MTA to forward locally sent emails to the " +"FreeBSD.org SMTP servers." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/committers-guide/_index.adoc:2277 +#, no-wrap +msgid "Using Postfix" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2282 +msgid "" +"To tell a local Postfix instance that anything from " +"`_yourusername_@FreeBSD.org` should be forwarded to the FreeBSD.org servers, " +"add this to your [.filename]#main.cf#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2290 +#, no-wrap +msgid "" +"sender_dependent_relayhost_maps = hash:/usr/local/etc/postfix/relayhost_maps\n" +"smtp_sasl_auth_enable = yes\n" +"smtp_sasl_security_options = noanonymous\n" +"smtp_sasl_password_maps = hash:/usr/local/etc/postfix/sasl_passwd\n" +"smtp_use_tls = yes\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2293 +msgid "" +"Create [.filename]#/usr/local/etc/postfix/relayhost_maps# with the following " +"content:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2297 +#, no-wrap +msgid "yourusername@FreeBSD.org [smtp.freebsd.org]:587\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2300 +msgid "" +"Create [.filename]#/usr/local/etc/postfix/sasl_passwd# with the following " +"content:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2304 +#, no-wrap +msgid "[smtp.freebsd.org]:587 yourusername:yourpassword\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2307 +msgid "" +"If the email server is used by other people, you may want to prevent them " +"from sending e-mails from your address. To achieve this, add this to your " +"[.filename]#main.cf#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2312 +#, no-wrap +msgid "" +"smtpd_sender_login_maps = hash:/usr/local/etc/postfix/sender_login_maps\n" +"smtpd_sender_restrictions = reject_known_sender_login_mismatch\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2315 +msgid "" +"Create [.filename]#/usr/local/etc/postfix/sender_login_maps# with the " +"following content:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2319 +#, no-wrap +msgid "yourusername@FreeBSD.org yourlocalusername\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2322 +msgid "" +"Where _yourlocalusername_ is the SASL username used to connect to the local " +"instance of Postfix." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/committers-guide/_index.adoc:2325 +#, no-wrap +msgid "Using OpenSMTPD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2330 +msgid "" +"To tell a local OpenSMTPD instance that anything from " +"`_yourusername_@FreeBSD.org` should be forwarded to the FreeBSD.org servers, " +"add this to your [.filename]#smtpd.conf#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2335 +#, no-wrap +msgid "" +"action \"freebsd\" relay host smtp+tls://freebsd@smtp.freebsd.org:587 auth <secrets>\n" +"match from any auth yourlocalusername mail-from \"_yourusername_@freebsd.org\" for any action \"freebsd\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2338 +msgid "" +"Where _yourlocalusername_ is the SASL username used to connect to the local " +"instance of OpenSMTPD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2340 +msgid "" +"Create [.filename]#/usr/local/etc/mail/secrets# with the following content:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2344 +#, no-wrap +msgid "freebsd\tyourusername:yourpassword\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/committers-guide/_index.adoc:2348 +#, no-wrap +msgid "Using Exim" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2354 +#, no-wrap +msgid "" +"To direct a local Exim instance to forward all mail from `_example_@FreeBSD.org`\n" +" to FreeBSD.org servers, add this to Exim [.filename]#configuration#:\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2363 +#, no-wrap +msgid "" +"Routers section: (at the top of the list):\n" +"freebsd_send:\n" +" driver = manualroute\n" +" domains = !+local_domains\n" +" transport = freebsd_smtp\n" +" route_data = ${lookup {${lc:$sender_address}} lsearch {/usr/local/etc/exim/freebsd_send}}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2375 +#, no-wrap +msgid "" +"Transport Section:\n" +"freebsd_smtp:\n" +" driver = smtp\n" +" tls_certificate=<local certificate>\n" +" tls_privatekey=<local certificate private key>\n" +" tls_require_ciphers = EECDH+ECDSA+AESGCM:EECDH+aRSA+AESGCM:EECDH+ECDSA+SHA384:EECDH+ECDSA+SHA256:EECDH+aRSA+SHA384:EECDH+aRSA+SHA256:EECDH+AESGCM:EECDH:EDH+AESGCM:EDH+aRSA:HIGH:!MEDIUM:!LOW:!aNULL:!eNULL:!LOW:!RC4:!MD5:!EXP:!PSK:!SRP:!DSS\n" +" dkim_domain = <local DKIM domain>\n" +" dkim_selector = <local DKIM selector>\n" +" dkim_private_key= <local DKIM private key>\n" +" dnssec_request_domains = *\n" +" hosts_require_auth = smtp.freebsd.org\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2382 +#, no-wrap +msgid "" +"Authenticators:\n" +"freebsd_plain:\n" +" driver = plaintext\n" +" public_name = PLAIN\n" +" client_send = ^example/mail^examplePassword\n" +" client_condition = ${if eq{$host}{smtp.freebsd.org}}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2385 +msgid "" +"Create [.filename]#/usr/local/etc/exim/freebsd_send# with the following " +"content:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2389 +#, no-wrap +msgid "example@freebsd.org:smtp.freebsd.org::587\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2394 +#, no-wrap +msgid "Mentors" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2399 +msgid "" +"All new developers have a mentor assigned to them for the first few months. " +"A mentor is responsible for teaching the mentee the rules and conventions of " +"the project and guiding their first steps in the developer community. The " +"mentor is also personally responsible for the mentee's actions during this " +"initial period." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2402 +msgid "" +"For committers: do not commit anything without first getting mentor " +"approval. Document that approval with an `Approved by:` line in the commit " +"message." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2407 +msgid "" +"When the mentor decides that a mentee has learned the ropes and is ready to " +"commit on their own, the mentor announces it with a commit to " +"[.filename]#mentors#. This file is in the [.filename]#admin# orphan branch " +"of each repository. Detailed information on how to access these branches " +"can be found in crossref:committers-guide[admin-branch, \"admin\" branch]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:2409 +#, no-wrap +msgid "Pre-Commit Review" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2414 +msgid "" +"Code review is one way to increase the quality of software. The following " +"guidelines apply to commits to the `main` (-CURRENT) branch of the `src` " +"repository. Other branches and the `ports` and `docs` trees have their own " +"review policies, but these guidelines generally apply to commits requiring " +"review:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2416 +msgid "" +"All non-trivial changes should be reviewed before they are committed to the " +"repository." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2417 +msgid "" +"Reviews may be conducted by email, in Bugzilla, in Phabricator, or by " +"another mechanism. Where possible, reviews should be public." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2418 +msgid "" +"The developer responsible for a code change is also responsible for making " +"all necessary review-related changes." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2419 +msgid "" +"Code review can be an iterative process, which continues until the patch is " +"ready to be committed. Specifically, once a patch is sent out for review, it " +"should receive an explicit \"looks good\" before it is committed. So long as " +"it is explicit, this can take whatever form makes sense for the review " +"method." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2420 +msgid "Timeouts are not a substitute for review." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2422 +msgid "" +"Sometimes code reviews will take longer than you would hope for, especially " +"for larger features. Accepted ways to speed up review times for your patches " +"are:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2424 +msgid "" +"Review other people's patches. If you help out, everybody will be more " +"willing to do the same for you; goodwill is our currency." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2425 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2426 +msgid "" +"Ask for help on mailing lists, IRC, etc. Others may be able to either help " +"you directly, or suggest a reviewer." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2427 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2429 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2434 +msgid "" +"Developers should participate in code reviews as both reviewers and " +"reviewees. If someone is kind enough to review your code, you should return " +"the favor for someone else. Note that while anyone is welcome to review and " +"give feedback on a patch, only an appropriate subject-matter expert can " +"approve a change. This will usually be a committer who works with the code " +"in question on a regular basis." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2437 +msgid "" +"In some cases, no subject-matter expert may be available. In those cases, a " +"review by an experienced developer is sufficient when coupled with " +"appropriate testing." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:2439 +#, no-wrap +msgid "Commit Log Messages" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2442 +msgid "" +"This section contains some suggestions and traditions for how commit logs " +"are formatted." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2443 +#, no-wrap +msgid "Why are commit messages important?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2447 +msgid "" +"When you commit a change in Git, Subversion, or another version control " +"system (VCS), you're prompted to write some text describing the commit -- a " +"commit message. How important is this commit message? Should you spend some " +"significant effort writing it? Does it really matter if you write simply " +"`fixed a bug`?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2450 +msgid "" +"Most projects have more than one developer and last for some length of " +"time. Commit messages are a very important method of communicating with " +"other developers, in the present and for the future." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2453 +msgid "" +"FreeBSD has hundreds of active developers and hundreds of thousands of " +"commits spanning decades of history. Over that time the developer community " +"has learned how valuable good commit messages are; sometimes these are hard-" +"learned lessons." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2455 +msgid "Commit messages serve at least three purposes:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2457 +msgid "Communicating with other developers" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2462 +msgid "" +"FreeBSD commits generate email to various mailing lists. These include the " +"commit message along with a copy of the patch itself. Commit messages are " +"also viewed through commands like git log. These serve to make other " +"developers aware of changes that are ongoing; that other developer may want " +"to test the change, may have an interest in the topic and will want to " +"review in more detail, or may have their own projects underway that would " +"benefit from interaction." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2464 +msgid "Making Changes Discoverable" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2468 +msgid "" +"In a large project with a long history it may be difficult to find changes " +"of interest when investigating an issue or change in behaviour. Verbose, " +"detailed commit messages allow searches for changes that might be relevant. " +"For example, `git log --since 1year --grep 'USB timeout'`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2470 +msgid "Providing historical documentation" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2474 +msgid "" +"Commit messages serve to document changes for future developers, perhaps " +"years or decades later. This future developer may even be you, the original " +"author. A change that seems obvious today may be decidedly not so much " +"later on." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2476 +msgid "" +"The `git blame` command annotates each line of a source file with the change " +"(hash and subject line) that brought it in." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2478 +msgid "" +"Having established the importance, here are elements of a good FreeBSD " +"commit message:" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2479 +#, no-wrap +msgid "Start with a subject line" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2483 +msgid "" +"Commit messages should start with a single-line subject that briefly " +"summarizes the change. The subject should, by itself, allow the reader to " +"quickly determine if the change is of interest or not." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2484 +#, no-wrap +msgid "Keep subject lines short" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2489 +msgid "" +"The subject line should be as short as possible while still retaining the " +"required information. This is to make browsing Git log more efficient, and " +"so that git log --oneline can display the short hash and subject on a single " +"80-column line. A good rule of thumb is to stay below 67 characters, and " +"aim for about 50 or fewer if possible." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2490 +#, no-wrap +msgid "Prefix the subject line with a component, if applicable" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2494 +msgid "" +"If the change relates to a specific component the subject line may be " +"prefixed with that component name and a colon (:). If applicable, try to " +"use the same prefix used in previous commits to the same files." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2496 +msgid "✓ `foo: Add -k option to keep temporary data`" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2498 +msgid "" +"Include the prefix in the 67-character limit suggested above, so that `git " +"log --oneline` avoids wrapping." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2499 +#, no-wrap +msgid "Capitalize the first letter of the subject" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2503 +msgid "" +"Capitalize the first letter of the subject itself. The prefix, if any, is " +"not capitalized unless necessary (e.g., `USB:` is capitalized)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2504 +#, no-wrap +msgid "Do not end the subject line with punctuation" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2508 +msgid "" +"Do not end with a period or other punctuation. In this regard the subject " +"line is like a newspaper headline." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2509 +#, no-wrap +msgid "Separate the subject and body with a blank line" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2512 +msgid "Separate the body from the subject with a blank line." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2514 +msgid "" +"Some trivial commits do not require a body, and will have only a subject." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2516 +msgid "✓ `ls: Fix typo in usage text`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2517 +#, no-wrap +msgid "Limit messages to 72 columns" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2523 +msgid "" +"`git log` and `git format-patch` indent the commit message by four spaces. " +"Wrapping at 72 columns provides a matching margin on the right edge. " +"Limiting messages to 72 characters also keeps the commit message in " +"formatted patches below RFC 2822's suggested email line length limit of 78 " +"characters. This limit works well with a variety of tools that may render " +"commit messages; line wrapping might be inconsistent with longer line length." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2524 +#, no-wrap +msgid "Use the present tense, imperative mood" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2529 +msgid "" +"This facilitates short subject lines and provides consistency, including " +"with automatically generated commit messages (e.g., as generated by git " +"revert). This is important when reading a list of commit subjects. Think " +"of the subject as finishing the sentence \"when applied, this change will ..." +"\"." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2534 +#, no-wrap +msgid "" +"✓ `foo: Implement the -k (keep) option`\n" +"✗ `foo: Implemented the -k option`\n" +"✗ `This change implements the -k option in foo`\n" +"✗ `-k option added`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2535 +#, no-wrap +msgid "Focus on what and why, not how" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2538 +msgid "" +"Explain what the change accomplishes and why it is being done, rather than " +"how." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2542 +msgid "" +"Do not assume that the reader is familiar with the issue. Explain the " +"background and motivation for the change. Include benchmark data if you " +"have it." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2544 +msgid "" +"If there are limitations or incomplete aspects of the change, describe them " +"in the commit message." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2545 +#, no-wrap +msgid "Consider whether parts of the commit message could be code comments instead" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2548 +msgid "" +"Sometimes while writing a commit message you may find yourself writing a " +"sentence or two explaining some tricky or confusing aspect of the change. " +"When this happens consider whether it would be valuable to have that " +"explanation as a comment in the code itself." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2549 +#, no-wrap +msgid "Write commit messages for your future self" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2553 +msgid "" +"While writing the commit message for a change you have all of the context in " +"mind - what prompted the change, alternate approaches that were considered " +"and rejected, limitations of the change, and so on. Imagine yourself " +"revisiting the change a year or two in the future, and write the commit " +"message in a way that would provide that necessary context." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2554 +#, no-wrap +msgid "Commit messages should stand alone" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2558 +msgid "" +"You may include references to mailing list postings, benchmark result web " +"sites, or code review links. However, the commit message should contain all " +"of the relevant information in case these references are no longer available " +"in the future." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2562 +msgid "" +"Similarly, a commit may refer to a previous commit, for example in the case " +"of a bug fix or revert. In addition to the commit identifier (revision or " +"hash), include the subject line from the referenced commit (or another " +"suitable brief reference). With each VCS migration (from CVS to Subversion " +"to Git) revision identifiers from previous systems may become difficult to " +"follow." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:2563 +#, no-wrap +msgid "Include appropriate metadata in a footer" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2566 +msgid "" +"As well as including an informative message with each commit, some " +"additional information may be needed." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2568 +msgid "" +"This information consists of one or more lines containing the key word or " +"phrase, a colon, tabs for formatting, and then the additional information." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2570 +msgid "" +"For key words where multiple values make sense (e.g., `PR:` with a comma-" +"separated list of PRs), it is permitted to use the same keyword multiple " +"times to avoid ambiguity or improve readability." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2572 +msgid "The key words or phrases are:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2578 +#, no-wrap +msgid "`PR:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2580 +#, no-wrap +msgid "The problem report (if any) which is affected (typically, by being closed) by this commit. Multiple PRs may be specified on one line, separated by commas or spaces." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2581 +#, no-wrap +msgid "`Reported by:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2585 +#, no-wrap +msgid "" +"The name and e-mail address of the person that reported the issue; for developers, just the username on the FreeBSD cluster.\n" +"Typically used when there is no PR, for example if the issue was reported on\n" +"a mailing list." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2587 +#, no-wrap +msgid "" +"`Submitted by:` +\n" +"(deprecated)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2589 +#, no-wrap +msgid "This has been deprecated with git; submitted patches should have the author set by using `git commit --author` with a full name and valid email." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2590 +#, no-wrap +msgid "`Reviewed by:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2605 +#, no-wrap +msgid "" +"The name and e-mail address of the person or people that reviewed the change; for developers, just the username on the FreeBSD cluster. If a patch was submitted to a mailing list for review, and the review was favorable, then just include the list name. If the reviewer is not a member of the project, provide the name, email, and if ports an external role like maintainer:\n" +"\n" +"Reviewed by a developer:\n" +"[source,shell]\n" +"....\n" +"Reviewed by: username\n" +"....\n" +"\n" +"Reviewed by a ports maintainer that is not a developer:\n" +"[source,shell]\n" +"....\n" +"Reviewed by: Full Name <valid@email> (maintainer)\n" +"...." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2606 +#, no-wrap +msgid "`Tested by:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2608 +#, no-wrap +msgid "The name and e-mail address of the person or people that tested the change; for developers, just the username on the FreeBSD cluster." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2609 +#, no-wrap +msgid "`Discussed with:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2612 +#, no-wrap +msgid "" +"The name and e-mail address of the person or people that contributed to the patch by providing meaningful feedback; for developers, just the username on the FreeBSD cluster.\n" +"Typically used to credit those who did not explicitly review, test, or approve the change, but nevertheless contributed to the discussion surrounding the change, which led to improvements and a better understanding of its impact on the FreeBSD project." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2613 +#, no-wrap +msgid "`Approved by:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2639 +#, no-wrap +msgid "" +"The name and e-mail address of the person or people that approved the change; for developers, just the username on the FreeBSD cluster.\n" +"\n" +"There are several cases where approval is customary:\n" +"\n" +"* while a new committer is under mentorship\n" +"* commits to an area of the tree covered by the LOCKS file (src)\n" +"* during a release cycle\n" +"* committing to a repo where you do not hold a commit bit (e.g. src committer committing to docs)\n" +"* committing to a port maintained by someone else\n" +"\n" +"While under mentorship, get mentor approval before the commit. Enter the mentor's username in this field, and note that they are a mentor:\n" +"\n" +"[source,shell]\n" +"....\n" +"Approved by: username-of-mentor (mentor)\n" +"....\n" +"\n" +"If a team approved these commits then include the team name followed by the username of the approver in parentheses. For example:\n" +"\n" +"[source,shell]\n" +"....\n" +"Approved by: re (username)\n" +"...." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2640 +#, no-wrap +msgid "`Obtained from:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2642 +#, no-wrap +msgid "The name of the project (if any) from which the code was obtained. Do not use this line for the name of an individual person." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2643 +#, no-wrap +msgid "`Fixes:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2646 +#, no-wrap +msgid "" +"The Git short hash and the title line of a commit that is fixed by this change as returned by `git log -n 1 --pretty=format:'%h (\"%s\")' GIT-COMMIT-HASH`.\n" +"We include the commit title so that the referenced commit can be located even in the case that a future VCS migration invalidates hash references." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2647 +#, no-wrap +msgid "`MFC after:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2649 +#, no-wrap +msgid "To receive an e-mail reminder to MFC at a later date, specify the number of days, weeks, or months after which an MFC is planned." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2650 +#, no-wrap +msgid "`MFC to:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2652 +#, no-wrap +msgid "If the commit should be merged to a subset of stable branches, specify the branch names." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2653 +#, no-wrap +msgid "`MFH:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2655 +#, no-wrap +msgid "If the commit is to be merged into a ports quarterly branch name, specify the quarterly branch. For example `2021Q2`." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2656 +#, no-wrap +msgid "`Relnotes:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2658 +#, no-wrap +msgid "If the change is a candidate for inclusion in the release notes for the next release from the branch, set to `yes`." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2659 +#, no-wrap +msgid "`Security:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2661 +#, no-wrap +msgid "If the change is related to a security vulnerability or security exposure, include one or more references or a description of the issue. If possible, include a VuXML URL or a CVE ID." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2662 +#, no-wrap +msgid "`Event:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2664 +#, no-wrap +msgid "The description for the event where this commit was made. If this is a recurring event, add the year or even the month to it. For example, this could be `FooBSDcon 2019`. The idea behind this line is to put recognition to conferences, gatherings, and other types of meetups and to show that these are useful to have. Please do not use the `Sponsored by:` line for this as that is meant for organizations sponsoring certain features or developers working on them." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2665 +#, no-wrap +msgid "`Sponsored by:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2667 +#, no-wrap +msgid "Sponsoring organizations for this change, if any. Separate multiple organizations with commas. If only a portion of the work was sponsored, or different amounts of sponsorship were provided to different authors, please give appropriate credit in parentheses after each sponsor name. For example, `Example.com (alice, code refactoring), Wormulon (bob), Momcorp (cindy)` shows that Alice was sponsored by Example.com to do code refactoring, while Wormulon sponsored Bob's work and Momcorp sponsored Cindy's work. Other authors were either not sponsored or chose not to list sponsorship." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2668 +#, no-wrap +msgid "`Pull Request:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2672 +#, no-wrap +msgid "" +"This change was submitted as a pull request or merge request against one of FreeBSD's public read-only Git repositories.\n" +"It should include the entire URL to the pull request, as these often act as code reviews for the code.\n" +"For example: `https://github.com/freebsd/freebsd-src/pull/745`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2673 +#, no-wrap +msgid "`Co-authored-by:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2676 +#, no-wrap +msgid "" +"The name and email address of an additional author of the commit.\n" +"GitHub has a detailed description of the Co-authored-by trailer at https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2677 +#, no-wrap +msgid "`Signed-off-by:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2679 +#, no-wrap +msgid "ID certifies compliance with https://developercertificate.org/" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2680 +#, no-wrap +msgid "`Differential Revision:`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:2682 +#, no-wrap +msgid "The full URL of the Phabricator review. This line __must be the last line__. For example: `https://reviews.freebsd.org/D1708`." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/committers-guide/_index.adoc:2684 +#, no-wrap +msgid "Commit Log for a Commit Based on a PR" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2690 +msgid "" +"The commit is based on a patch from a PR submitted by John Smith. The " +"commit message \"PR\" field is filled." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2694 +#: documentation/content/en/articles/committers-guide/_index.adoc:2712 +#: documentation/content/en/articles/committers-guide/_index.adoc:2727 +#: documentation/content/en/articles/committers-guide/_index.adoc:2743 +#: documentation/content/en/articles/committers-guide/_index.adoc:2758 +#, no-wrap +msgid "...\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2696 +#, no-wrap +msgid "PR:\t\t12345\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2699 +msgid "" +"The committer sets the author of the patch with `git commit --author \"John " +"Smith <John.Smith@example.com>\"`." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/committers-guide/_index.adoc:2702 +#, no-wrap +msgid "Commit Log for a Commit Needing Review" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2708 +msgid "" +"The virtual memory system is being changed. After posting patches to the " +"appropriate mailing list (in this case, `freebsd-arch`) and the changes have " +"been approved." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2714 +#, no-wrap +msgid "Reviewed by:\t-arch\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/committers-guide/_index.adoc:2718 +#, no-wrap +msgid "Commit Log for a Commit Needing Approval" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2723 +msgid "" +"Commit a port, after working with the listed MAINTAINER, who said to go " +"ahead and commit." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2729 +#, no-wrap +msgid "Approved by:\tabc (maintainer)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2732 +msgid "Where _abc_ is the account name of the person who approved." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/committers-guide/_index.adoc:2734 +#, no-wrap +msgid "Commit Log for a Commit Bringing in Code from OpenBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2739 +msgid "Committing some code based on work done in the OpenBSD project." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2745 +#, no-wrap +msgid "Obtained from:\tOpenBSD\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/committers-guide/_index.adoc:2749 +#, no-wrap +msgid "Commit Log for a Change to FreeBSD-CURRENT with a Planned Commit to FreeBSD-STABLE to Follow at a Later Date." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2754 +msgid "" +"Committing some code which will be merged from FreeBSD-CURRENT into the " +"FreeBSD-STABLE branch after two weeks." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2760 +#, no-wrap +msgid "MFC after:\t2 weeks\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2763 +msgid "" +"Where _2_ is the number of days, weeks, or months after which an MFC is " +"planned. The _weeks_ option may be `day`, `days`, `week`, `weeks`, `month`, " +"`months`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2766 +msgid "It is often necessary to combine these." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2770 +msgid "" +"Consider the situation where a user has submitted a PR containing code from " +"the NetBSD project. Looking at the PR, the developer sees it is not an area " +"of the tree they normally work in, so they have the change reviewed by the " +"`arch` mailing list. Since the change is complex, the developer opts to MFC " +"after one month to allow adequate testing." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2772 +msgid "" +"The extra information to include in the commit would look something like" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/committers-guide/_index.adoc:2773 +#, no-wrap +msgid "Example Combined Commit Log" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2784 +#, no-wrap +msgid "" +"PR:\t\t54321\n" +"Reviewed by:\t-arch\n" +"Obtained from:\tNetBSD\n" +"MFC after:\t1 month\n" +"Relnotes:\tyes\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:2789 +#, no-wrap +msgid "Preferred License for New Files" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2795 +msgid "" +"The FreeBSD Project's full license policy can be found at link:https://" +"www.FreeBSD.org/internal/software-license/[https://www.FreeBSD.org/internal/" +"software-license]. The rest of this section is intended to help you get " +"started. As a rule, when in doubt, ask. It is much easier to give advice " +"than to fix the source tree." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2797 +msgid "" +"The FreeBSD Project suggests and uses this text as the preferred license " +"scheme:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2828 +#, no-wrap +msgid "" +"/*\n" +" * SPDX-License-Identifier: BSD-2-Clause\n" +" *\n" +" * Copyright (c) [year] [your name]\n" +" *\n" +" * Redistribution and use in source and binary forms, with or without\n" +" * modification, are permitted provided that the following conditions\n" +" * are met:\n" +" * 1. Redistributions of source code must retain the above copyright\n" +" * notice, this list of conditions and the following disclaimer.\n" +" * 2. Redistributions in binary form must reproduce the above copyright\n" +" * notice, this list of conditions and the following disclaimer in the\n" +" * documentation and/or other materials provided with the distribution.\n" +" *\n" +" * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND\n" +" * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\n" +" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\n" +" * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE\n" +" * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\n" +" * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS\n" +" * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n" +" * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT\n" +" * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY\n" +" * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF\n" +" * SUCH DAMAGE.\n" +" *\n" +" * [id for your version control system, if any]\n" +" */\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2834 +msgid "" +"The FreeBSD project strongly discourages the so-called \"advertising " +"clause\" in new code. Due to the large number of contributors to the " +"FreeBSD project, complying with this clause for many commercial vendors has " +"become difficult. If you have code in the tree with the advertising clause, " +"please consider removing it. In fact, please consider using the above " +"license for your code." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2838 +msgid "" +"The FreeBSD project discourages completely new licenses and variations on " +"the standard licenses. New licenses require the approval of {core-email} to " +"reside in the `src` repository. The more different licenses that are used " +"in the tree, the more problems that this causes to those wishing to utilize " +"this code, typically from unintended consequences from a poorly worded " +"license." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2842 +msgid "" +"Project policy dictates that code under some non-BSD licenses must be placed " +"only in specific sections of the repository, and in some cases, compilation " +"must be conditional or even disabled by default. For example, the GENERIC " +"kernel must be compiled under only licenses identical to or substantially " +"similar to the BSD license. GPL, APSL, CDDL, etc, licensed software must " +"not be compiled into GENERIC." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2845 +msgid "" +"Developers are reminded that in open source, getting \"open\" right is just " +"as important as getting \"source\" right, as improper handling of " +"intellectual property has serious consequences. Any questions or concerns " +"should immediately be brought to the attention of the core team." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:2847 +#, no-wrap +msgid "Keeping Track of Licenses Granted to the FreeBSD Project" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2852 +msgid "" +"Various software or data exist in the repositories where the FreeBSD project " +"has been granted a special license to be able to use them. A case in point " +"are the Terminus fonts for use with man:vt[4]. Here the author Dimitar " +"Zhekov has allowed us to use the \"Terminus BSD Console\" font under a 2-" +"clause BSD license rather than the regular Open Font License he normally " +"uses." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2857 +msgid "" +"It is clearly sensible to keep a record of any such license grants. To that " +"end, the {core-email} has decided to keep an archive of them. Whenever the " +"FreeBSD project is granted a special license we require the {core-email} to " +"be notified. Any developers involved in arranging such a license grant, " +"please send details to the {core-email} including:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2859 +msgid "" +"Contact details for people or organizations granting the special license." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2860 +msgid "" +"What files, directories etc. in the repositories are covered by the license " +"grant including the revision numbers where any specially licensed material " +"was committed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2861 +msgid "" +"The date the license comes into effect from. Unless otherwise agreed, this " +"will be the date the license was issued by the authors of the software in " +"question." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2862 +msgid "The license text." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2863 +msgid "" +"A note of any restrictions, limitations or exceptions that apply " +"specifically to FreeBSD's usage of the licensed material." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2864 +msgid "Any other relevant information." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2867 +msgid "" +"Once the {core-email} is satisfied that all the necessary details have been " +"gathered and are correct, the secretary will send a PGP-signed " +"acknowledgment of receipt including the license details. This receipt will " +"be persistently archived and serve as our permanent record of the license " +"grant." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2870 +msgid "" +"The license archive should contain only details of license grants; this is " +"not the place for any discussions around licensing or other subjects. " +"Access to data within the license archive will be available on request to " +"the {core-email}." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:2872 +#, no-wrap +msgid "SPDX Tags in the tree" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2883 +msgid "" +"The project uses https://spdx.dev[SPDX] tags in our source base. At " +"present, these tags are indented to help automated tools reconstruct license " +"requirements mechanically. All _SPDX-License-Identifier_ tags in the tree " +"should be considered to be informative. All files in the FreeBSD source " +"tree with these tags also have a copy of the license which governs use of " +"that file. In the event of a discrepancy, the verbatim license is " +"controlling. The project tries to follow the https://spdx.github.io/spdx-" +"spec/v2.2.2/[SPDX Specification, Version 2.2]. How to mark source files and " +"valid algebraic expressions are found in https://spdx.github.io/spdx-spec/" +"v2.2.2/SPDX-license-expressions/[Annex D] and https://spdx.github.io/spdx-" +"spec/v2.2.2/using-SPDX-short-identifiers-in-source-files/[Annex E]. The " +"project draws identifiers from SPDX's list of valid https://spdx.org/" +"licenses/[short license identifiers]. The project uses only the _SPDX-" +"License-Identifier_ tag." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2885 +msgid "" +"As of March 2021, approximately 25,000 out of 90,000 files in the tree have " +"been marked." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:2886 +#, no-wrap +msgid "Developer Relations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2892 +msgid "" +"When working directly on your own code or on code which is already well " +"established as your responsibility, then there is probably little need to " +"check with other committers before jumping in with a commit. When working " +"on a bug in an area of the system which is clearly orphaned (and there are a " +"few such areas, to our shame), the same applies. When modifying parts of " +"the system which are maintained, formally or informally, consider asking for " +"a review just as a developer would have before becoming a committer. For " +"ports, contact the listed `MAINTAINER` in the [.filename]#Makefile#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2896 +msgid "" +"To determine if an area of the tree is maintained, check the MAINTAINERS " +"file at the root of the tree. If nobody is listed, scan the revision " +"history to see who has committed changes in the past. To list the names and " +"email addresses of all commit authors for a given file in the last 2 years " +"and the number of commits each has authored, ordered by descending number of " +"commits, use:" +msgstr "" + +#. type: delimited block - 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2900 +#, no-wrap +msgid "% git -C /path/to/repo shortlog -sne --since=\"2 years\" -- relative/path/to/file\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2903 +msgid "" +"If queries go unanswered or the committer otherwise indicates a lack of " +"interest in the area affected, go ahead and commit it." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2908 +msgid "" +"Avoid sending private emails to maintainers. Other people might be " +"interested in the conversation, not just the final output." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2914 +msgid "" +"If there is any doubt about a commit for any reason at all, have it reviewed " +"before committing. Better to have it flamed then and there rather than when " +"it is part of the repository. If a commit does results in controversy " +"erupting, it may be advisable to consider backing the change out again until " +"the matter is settled. Remember, with a version control system we can " +"always change it back." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2918 +msgid "" +"Do not impugn the intentions of others. If they see a different solution to " +"a problem, or even a different problem, it is probably not because they are " +"stupid, because they have questionable parentage, or because they are trying " +"to destroy hard work, personal image, or FreeBSD, but basically because they " +"have a different outlook on the world. Different is good." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2921 +msgid "" +"Disagree honestly. Argue your position from its merits, be honest about any " +"shortcomings it may have, and be open to seeing their solution, or even " +"their vision of the problem, with an open mind." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2927 +msgid "" +"Accept correction. We are all fallible. When you have made a mistake, " +"apologize and get on with life. Do not beat up yourself, and certainly do " +"not beat up others for your mistake. Do not waste time on embarrassment or " +"recrimination, just fix the problem and move on." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2931 +msgid "" +"Ask for help. Seek out (and give) peer reviews. One of the ways open " +"source software is supposed to excel is in the number of eyeballs applied to " +"it; this does not apply if nobody will review code." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:2933 +#, no-wrap +msgid "If in Doubt..." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2937 +msgid "" +"When unsure about something, whether it be a technical issue or a project " +"convention be sure to ask. If you stay silent you will never make progress." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2941 +msgid "" +"If it relates to a technical issue ask on the public mailing lists. Avoid " +"the temptation to email the individual person that knows the answer. This " +"way everyone will be able to learn from the question and the answer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2943 +msgid "For project specific or administrative questions ask, in order:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2945 +msgid "Your mentor or former mentor." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2946 +msgid "An experienced committer on IRC, email, etc." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2947 +msgid "Any team with a \"hat\", as they can give you a definitive answer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2948 +msgid "If still not sure, ask on {developers-name}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2950 +msgid "" +"Once your question is answered, if no one pointed you to documentation that " +"spelled out the answer to your question, document it, as others will have " +"the same question." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:2952 +#, no-wrap +msgid "Bugzilla" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2957 +msgid "" +"The FreeBSD Project utilizes Bugzilla for tracking bugs and change " +"requests. If you commit a fix or suggestion found in the PR database, be " +"sure to close the PR. It is also considered nice if you take time to close " +"any other PRs associated with your commits." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2959 +msgid "" +"Committers with non-``FreeBSD.org`` Bugzilla accounts can have the old " +"account merged with the `FreeBSD.org` account by following these steps:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2963 +msgid "Log in using your old account." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2964 +msgid "" +"Open new bug. Choose `Services` as the Product, and `Bug Tracker` as the " +"Component. In bug description list accounts you wish to be merged." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2966 +msgid "" +"Log in using `FreeBSD.org` account and post comment to newly opened bug to " +"confirm ownership. See crossref:committers-guide[kerberos-ldap, Kerberos and " +"LDAP web Password for FreeBSD Cluster] for more details on how to generate " +"or set a password for your `FreeBSD.org` account." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2967 +msgid "" +"If there are more than two accounts to merge, post comments from each of " +"them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2970 +msgid "You can find out more about Bugzilla at:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2972 +msgid "extref:{pr-guidelines}[FreeBSD Problem Report Handling Guidelines]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2973 +msgid "link:https://www.FreeBSD.org/support/[https://www.FreeBSD.org/support]" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:2975 +#, no-wrap +msgid "Phabricator" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2979 +msgid "" +"The FreeBSD Project utilizes https://reviews.freebsd.org[Phabricator] for " +"code review requests. See the https://wiki.freebsd.org/" +"Phabricator[Phabricator wiki page] for details." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2982 +msgid "" +"Please use the `git arc` command provided by `devel/freebsd-git-devtools` " +"(install the port or package, then type `git help arc` for documentation) to " +"create and update Phabricator reviews. This will make it easier for others " +"to review and test your patches." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:2984 +msgid "" +"Committers with non-``FreeBSD.org`` Phabricator accounts can have the old " +"account renamed to the ``FreeBSD.org`` account by following these steps:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2988 +msgid "Change your Phabricator account email to your `FreeBSD.org` email." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2990 +msgid "" +"Open new bug on our bug tracker using your `FreeBSD.org` account, see " +"crossref:committers-guide[bugzilla, Bugzilla] for more information. Choose " +"`Services` as the Product, and `Code Review` as the Component. In bug " +"description request that your Phabricator account be renamed, and provide a " +"link to your Phabricator user. For example, `https://reviews.freebsd.org/p/" +"bob_example.com/`" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:2995 +msgid "" +"Phabricator accounts cannot be merged, please do not open a new account." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:2998 +#, no-wrap +msgid "Who's Who" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3001 +msgid "" +"Besides the repository meisters, there are other FreeBSD project members and " +"teams whom you will probably get to know in your role as a committer. " +"Briefly, and by no means all-inclusively, these are:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/committers-guide/_index.adoc:3002 +#, no-wrap +msgid "`{doceng}`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3008 +msgid "" +"doceng is the group responsible for the documentation build infrastructure, " +"approving new documentation committers, and ensuring that the FreeBSD " +"website and documentation on the FTP site is up to date with respect to the " +"Subversion tree. It is not a conflict resolution body. The vast majority " +"of documentation related discussion takes place on the {freebsd-doc}. More " +"details regarding the doceng team can be found in its https://" +"www.FreeBSD.org/internal/doceng/[charter]. Committers interested in " +"contributing to the documentation should familiarize themselves with the " +"extref:{fdp-primer}[Documentation Project Primer]." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/committers-guide/_index.adoc:3009 +#, no-wrap +msgid "`{re-members}`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3014 +msgid "" +"These are the members of the `{re}`. This team is responsible for setting " +"release deadlines and controlling the release process. During code freezes, " +"the release engineers have final authority on all changes to the system for " +"whichever branch is pending release status. If there is something you want " +"merged from FreeBSD-CURRENT to FreeBSD-STABLE (whatever values those may " +"have at any given time), these are the people to talk to about it." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/committers-guide/_index.adoc:3015 +#, no-wrap +msgid "`{so}`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3017 +msgid "" +"`{so-name}` is the link:https://www.FreeBSD.org/security/[FreeBSD Security " +"Officer] and oversees the `{security-officer}`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3022 +msgid "" +"{committers-name}:: {dev-src-all}, {dev-ports-all} and {dev-doc-all} are the " +"mailing lists that the version control system uses to send commit messages " +"to. _Never_ send email directly to these lists. Only send replies to this " +"list when they are short and are directly related to a commit." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3027 +msgid "" +"{developers-name}:: All committers are subscribed to -developers. This list " +"was created to be a forum for the committers \"community\" issues. Examples " +"are Core voting, announcements, etc." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3031 +msgid "" +"The {developers-name} is for the exclusive use of FreeBSD committers. To " +"develop FreeBSD, committers must have the ability to openly discuss matters " +"that will be resolved before they are publicly announced. Frank discussions " +"of work in progress are not suitable for open publication and may harm " +"FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3035 +msgid "" +"All FreeBSD committers are expected not to not publish or forward messages " +"from the {developers-name} outside the list membership without permission of " +"all of the authors. Violators will be removed from the {developers-name}, " +"resulting in a suspension of commit privileges. Repeated or flagrant " +"violations may result in permanent revocation of commit privileges." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3041 +msgid "" +"This list is _not_ intended as a place for code reviews or for any technical " +"discussion. In fact using it as such hurts the FreeBSD Project as it gives " +"a sense of a closed list where general decisions affecting all of the " +"FreeBSD using community are made without being \"open\". Last, but not " +"least __never, never ever, email the {developers-name} and CC:/BCC: another " +"FreeBSD list__. Never, ever email another FreeBSD email list and CC:/BCC: " +"the {developers-name}. Doing so can greatly diminish the benefits of this " +"list." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:3042 +#, no-wrap +msgid "SSH Quick-Start Guide" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3047 +msgid "" +"If you do not wish to type your password in every time you use man:ssh[1], " +"and you use keys to authenticate, man:ssh-agent[1] is there for your " +"convenience. If you want to use man:ssh-agent[1], make sure that you run it " +"before running other applications. X users, for example, usually do this " +"from their [.filename]#.xsession# or [.filename]#.xinitrc#. See man:ssh-" +"agent[1] for details." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3048 +msgid "" +"Generate a key pair using man:ssh-keygen[1]. The key pair will wind up in " +"your [.filename]#$HOME/.ssh/# directory." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:3052 +msgid "Only ECDSA, Ed25519 or RSA keys are supported." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3054 +msgid "" +"Send your public key ([.filename]#$HOME/.ssh/id_ecdsa.pub#, " +"[.filename]#$HOME/.ssh/id_ed25519.pub#, or [.filename]#$HOME/.ssh/" +"id_rsa.pub#) to the person setting you up as a committer so it can be put " +"into [.filename]#yourlogin# in [.filename]#/etc/ssh-keys/# on `freefall`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3059 +msgid "" +"Now man:ssh-add[1] can be used for authentication once per session. It " +"prompts for the private key's pass phrase, and then stores it in the " +"authentication agent (man:ssh-agent[1]). Use `ssh-add -d` to remove keys " +"stored in the agent." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3061 +msgid "Test with a simple remote command: `ssh freefall.FreeBSD.org ls /usr`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3063 +msgid "" +"For more information, see package:security/openssh-portable[], man:ssh[1], " +"man:ssh-add[1], man:ssh-agent[1], man:ssh-keygen[1], and man:scp[1]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3065 +msgid "" +"For information on adding, changing, or removing man:ssh[1] keys, see " +"https://wiki.freebsd.org/clusteradm/ssh-keys[this article]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:3067 +#, no-wrap +msgid "Coverity(R) Availability for FreeBSD Committers" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3071 +msgid "" +"All FreeBSD developers can obtain access to Coverity analysis results of all " +"FreeBSD Project software. All who are interested in obtaining access to the " +"analysis results of the automated Coverity runs, can sign up at http://" +"scan.coverity.com/[Coverity Scan]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3074 +msgid "" +"The FreeBSD wiki includes a mini-guide for developers who are interested in " +"working with the Coverity(R) analysis reports: https://wiki.freebsd.org/" +"CoverityPrevent[https://wiki.freebsd.org/CoverityPrevent]. Please note that " +"this mini-guide is only readable by FreeBSD developers, so if you cannot " +"access this page, you will have to ask someone to add you to the appropriate " +"Wiki access list." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3076 +msgid "" +"Finally, all FreeBSD developers who are going to use Coverity(R) are always " +"encouraged to ask for more details and usage information, by posting any " +"questions to the mailing list of the FreeBSD developers." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:3078 +#, no-wrap +msgid "The FreeBSD Committers' Big List of Rules" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3083 +msgid "" +"Everyone involved with the FreeBSD project is expected to abide by the _Code " +"of Conduct_ available from link:https://www.FreeBSD.org/internal/code-of-" +"conduct/[https://www.FreeBSD.org/internal/code-of-conduct]. As committers, " +"you form the public face of the project, and how you behave has a vital " +"impact on the public perception of it. This guide expands on the parts of " +"the _Code of Conduct_ specific to committers." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3085 +#: documentation/content/en/articles/committers-guide/_index.adoc:3115 +msgid "Respect other committers." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3086 +#: documentation/content/en/articles/committers-guide/_index.adoc:3131 +msgid "Respect other contributors." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3087 +#: documentation/content/en/articles/committers-guide/_index.adoc:3146 +msgid "Discuss any significant change _before_ committing." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3088 +msgid "" +"Respect existing maintainers (if listed in the `MAINTAINER` field in " +"[.filename]#Makefile# or in [.filename]#MAINTAINER# in the top-level " +"directory)." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3089 +#: documentation/content/en/articles/committers-guide/_index.adoc:3161 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3090 +msgid "" +"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 for the " +"maintainer in rule #5." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3091 +#: documentation/content/en/articles/committers-guide/_index.adoc:3176 +msgid "Do not fight in public with other committers; it looks bad." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3092 +msgid "" +"Respect all code freezes and read the `committers` and `developers` mailing " +"lists in a timely manner so you know when a code freeze is in effect." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3093 +#: documentation/content/en/articles/committers-guide/_index.adoc:3191 +msgid "When in doubt on any procedure, ask first!" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3094 +#: documentation/content/en/articles/committers-guide/_index.adoc:3196 +msgid "Test your changes before committing them." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3095 +#: documentation/content/en/articles/committers-guide/_index.adoc:3206 +msgid "" +"Do not commit to contributed software without _explicit_ approval from the " +"respective maintainers." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3106 +msgid "" +"As noted, breaking some of these rules can be grounds for suspension or, " +"upon repeated offense, permanent removal of commit privileges. Individual " +"members of core have the power to temporarily suspend commit privileges " +"until core as a whole has the chance to review the issue. In case of an " +"\"emergency\" (a committer doing damage to the repository), a temporary " +"suspension may also be done by the repository meisters. Only a 2/3 majority " +"of core has the authority to suspend commit privileges for longer than a " +"week or to remove them permanently. This rule does not exist to set core up " +"as a bunch of cruel dictators who can dispose of committers as casually as " +"empty soda cans, but to give the project a kind of safety fuse. If someone " +"is out of control, it is important to be able to deal with this immediately " +"rather than be paralyzed by debate. In all cases, a committer whose " +"privileges are suspended or revoked is entitled to a \"hearing\" by core, " +"the total duration of the suspension being determined at that time. A " +"committer whose privileges are suspended may also request a review of the " +"decision after 30 days and every 30 days thereafter (unless the total " +"suspension period is less than 30 days). A committer whose privileges have " +"been revoked entirely may request a review after a period of 6 months has " +"elapsed. This review policy is _strictly informal_ and, in all cases, core " +"reserves the right to either act on or disregard requests for review if they " +"feel their original decision to be the right one." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3110 +msgid "" +"In all other aspects of project operation, core is a subset of committers " +"and is bound by the __same rules__. Just because someone is in core this " +"does not mean that they have special dispensation to step outside any of the " +"lines painted here; core's \"special powers\" only kick in when it acts as a " +"group, not on an individual basis. As individuals, the core team members " +"are all committers first and core second." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3111 +#, no-wrap +msgid "Details" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3119 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3121 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3127 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3130 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3143 +msgid "" +"You were not always a committer. At one time you were a contributor. " +"Remember that at all times. Remember what it was like trying to get help " +"and attention. Do not forget that your work as a contributor was very " +"important to you. Remember what it was like. Do not discourage, belittle, " +"or demean contributors. Treat them with respect. They are our committers in " +"waiting. They are every bit as important to the project as committers. " +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3145 +msgid "" +"Consider the points raised under crossref:committers-guide[respect,Respect " +"other committers] and apply them also to contributors." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3152 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3154 +msgid "When in doubt, ask for review!" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3155 +msgid "Respect existing maintainers if listed." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3160 +msgid "" +"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 extref:" +"{developers-handbook}[Source Tree Guidelines and Policies, 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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3166 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3167 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3173 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3175 +msgid "" +"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}`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3186 +msgid "" +"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. Do not air angry words in public and do not " +"forward private correspondence or other private communications to public " +"mailing lists, mail aliases, instant messaging channels or social media " +"sites. What people say one-to-one is often much less sugar-coated than what " +"they would say in public, and such communications therefore have no place " +"there - they only serve to inflame an already bad situation. If the person " +"sending a flame-o-gram at least had the grace to send it privately, then " +"have the grace to keep it private yourself. If you feel you are being " +"unfairly treated by another developer, and it is causing you anguish, bring " +"the matter up with core rather than taking it public. Core will do its best " +"to play peace makers and get things back to sanity. 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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3187 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3190 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3195 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3205 +msgid "" +"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 compile userspace via `make buildworld`. If your changes are to a " +"branch, make sure your testing occurs with a machine which is running that " +"code. If you have a change which also may break another architecture, be " +"sure and test on all supported architectures. Please ensure your change " +"works for crossref:committers-guide[compilers,supported toolchains]. 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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3208 +msgid "" +"Contributed software is anything under the [.filename]#src/contrib#, " +"[.filename]#src/crypto#, or [.filename]#src/sys/contrib# trees." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3213 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3217 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3220 +msgid "" +"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." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3221 +#, no-wrap +msgid "Policy on Multiple Architectures" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3224 +msgid "" +"In an effort to make it easier to keep FreeBSD portable across the platforms " +"we support, core has developed this mandate:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3227 +msgid "" +"Major design work (including major API and ABI changes) must prove itself on " +"at least one Tier 1 platform before it may be committed to the source tree." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3231 +msgid "" +"Developers should also be aware of our Tier Policy for the long term support " +"of hardware architectures. The rules here are intended to provide guidance " +"during the development process, and are distinct from the requirements for " +"features and architectures listed in that section. The Tier rules for " +"feature support on architectures at release-time are more strict than the " +"rules for changes during the development process." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3233 +#, no-wrap +msgid "Policy on Multiple Compilers" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3247 +msgid "" +"The FreeBSD base system builds with both Clang and GCC. The project does " +"this in a careful and controlled way to maximize benefits from this extra " +"work, while keeping the extra work to a minimum. Supporting both Clang and " +"GCC improves the flexibility our users have. These compilers have different " +"strengths and weaknesses, and supporting both allows users to pick the best " +"one for their needs. Clang and GCC support similar dialects of C and C++, " +"necessitating a relatively small amount of conditional code. The project " +"gains increased code coverage and improves the code quality by using " +"features from both compilers. The project is able to build in more user " +"environments and leverage more CI environments by supporting this range, " +"increasing convenience for users and giving them more tools to test with. " +"By carefully constraining the range of versions supported to modern versions " +"of these compilers, the project avoids unduly increasing the testing " +"matrix. Older and obscure compilers, as well as older dialects of the " +"languages, have extremely limited support that allow user programs to build " +"with them, but without constraining the base system to being built with " +"them. The exact balance continues to evolve to ensure the benefits of extra " +"work remain greater than the burdens it imposes. The project used to " +"support really old Intel compilers or old GCC versions, but we traded " +"supporting those obsolete compilers for a carefully selected range of modern " +"compilers. This section documents where we use different compilers, and the " +"expectations around that." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3252 +msgid "" +"The FreeBSD base system includes an in-tree Clang compiler. Due to being in " +"the tree, this compiler is the most supported compiler. All changes must " +"compile with it, prior to commit. Complete testing, as appropriate for the " +"change, should be done with this compiler." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3267 +msgid "" +"The FreeBSD base system also supports various versions of Clang and GCC as " +"out-of-tree compilers. For large or risky changes, committers should do a " +"test build with a supported version of GCC. Out of tree compilers are " +"available as packages. GCC compilers are available as `${TARGET_ARCH}-gcc$" +"{VERSION}` packages, such as package:devel/freebsd-gcc14@aarch64[aarch64-" +"gcc14]. Clang compilers are available as `llvm${VERSION}` packages, such as " +"package:devel/llvm18[llvm18]. The project runs automated CI jobs to build " +"everything with these compilers. Committers are expected to fix the jobs " +"they break with their changes. Committers may test builds of userspace or " +"individual kernels by setting `CROSS_TOOLCHAIN` to the package name, for " +"example `CROSS_TOOLCHAIN=aarch64-gcc14` or `CROSS_TOOLCHAIN=llvm18`. For " +"universe or tinderbox builds, `USE_GCC_TOOLCHAINS=gcc${VERSION}` builds all " +"architectures using the appropriate GCC compiler packages. For universe or " +"tinderbox builds using an out-of-tree Clang, pass `CROSS_TOOLCHAIN=llvm$" +"{VERSION}`. Note that while all architectures in the base system can be " +"compiled by Clang, only a few architectures can be fully built by GCC." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3271 +msgid "" +"The FreeBSD project also has some CI pipelines on github. For pull requests " +"on github and some branches pushed to github forks, a number of cross " +"compilation jobs run. These test FreeBSD building using versions of Clang " +"that lag the in-tree compiler by one or more major versions." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3277 +msgid "" +"The FreeBSD project is also upgrading compilers. Both Clang and GCC are " +"fast moving targets. Some work to change things in the tree, for example " +"removing the old-style K&R function declarations and definitions, will land " +"in the tree prior to the compiler landing. Committers should try to be " +"mindful about this and be receptive to looking into problems with their code " +"or changes with these new compilers. Also, just after a new compiler " +"version hits the tree, people may need to compile things with the old " +"version if there was an undetected regression suspected." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3281 +msgid "" +"In addition to the compiler, LLVM's LLD and GNU's binutils are used " +"indirectly by the compiler. Committers should be mindful of variations in " +"assembler syntax and features of the linkers and ensure both variants work. " +"These components will be tested as part of FreeBSD's CI jobs for Clang or " +"GCC." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3287 +msgid "" +"The FreeBSD project provides headers and libraries that allow other " +"compilers to be used to build software not in the base system. These " +"headers have support for making the environment as strict as the standard, " +"supporting prior dialects of ANSI-C back to C89, and other edge cases our " +"large ports collection has uncovered. This support constrains retirement of " +"older standards in places like header files, but does not constrain updating " +"the base system to newer dialects. Nor does it require the base system to " +"compile with these older standards as a whole. Breaking this support will " +"cause packages in the ports collection to fail, so should be avoided where " +"possible, and promptly fixed when it is easy to do so." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3292 +msgid "" +"The FreeBSD build system currently accommodates these different " +"environments. As new warnings are added to compilers, the project tries to " +"fix them. However, sometimes these warnings require extensive rework, so " +"are suppressed in some way by using make variables that evaluate to the " +"proper thing depending on the compiler version. Developers should be " +"mindful of this, and ensure any compiler specific flags are properly " +"conditionalized." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3293 +#, no-wrap +msgid "Current Compiler Versions" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3296 +msgid "" +"The versions of supported compilers for a given branch such as `main` or " +"`stable/X` varies over time. The authoritative source for supported " +"compiler versions are automated CI jobs tested in GitHub's cross-build " +"actions and Jenkins." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3300 +msgid "" +"For `main`, the in-tree compiler is currently Clang 19. Currently, GCC 12, " +"13, and 14 are tested for amd64 via CI jobs in Jenkins. Clang 14 and 18 are " +"tested for aarch64 and arm64 in GitHub's cross-build actions." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3301 +#, no-wrap +msgid "Other Suggestions" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3305 +msgid "" +"When committing documentation changes, use a spell checker before " +"committing. For all XML docs, verify that the formatting directives are " +"correct by running `make lint` and package:textproc/igor[]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3307 +msgid "" +"For manual pages, run package:sysutils/manck[] and package:textproc/igor[] " +"over the manual page to verify all of the cross references and file " +"references are correct and that the man page has all of the appropriate " +"`MLINKS` installed." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3314 +msgid "" +"Do not mix style fixes with new functionality. A style fix is any change " +"which does not modify the functionality of the code. Mixing the changes " +"obfuscates the functionality change when asking for differences between " +"revisions, which can hide any new bugs. Do not include whitespace changes " +"with content changes in commits to [.filename]#doc/#. The extra clutter in " +"the diffs makes the translators' job much more difficult. Instead, make any " +"style or whitespace changes in separate commits that are clearly labeled as " +"such in the commit message." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3315 +#, no-wrap +msgid "Deprecating Features" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3318 +msgid "" +"When it is necessary to remove functionality from software in the base " +"system, follow these guidelines whenever possible:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3320 +msgid "" +"Mention is made in the manual page and possibly the release notes that the " +"option, utility, or interface is deprecated. Use of the deprecated feature " +"generates a warning." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3321 +msgid "" +"The option, utility, or interface is preserved until the next major (point " +"zero) release." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3322 +msgid "" +"The option, utility, or interface is removed and no longer documented. It is " +"now obsolete. It is also generally a good idea to note its removal in the " +"release notes." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3323 +#, no-wrap +msgid "Privacy and Confidentiality" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3326 +msgid "Most FreeBSD business is done in public." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3329 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3330 +msgid "Certain sensitive matters must remain private or held under embargo." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3336 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3337 +msgid "" +"The Security Officer has sole control over the release of security " +"advisories." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3342 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3343 +msgid "" +"Communications with Core are kept confidential for as long as necessary." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3348 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3349 +msgid "" +"Non-disclosure Agreements may be required for access to certain commercially " +"sensitive data." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3352 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3353 +msgid "Private communications must not be made public without permission." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3356 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3357 +msgid "" +"Communications on project-only or restricted access channels must be kept " +"private." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3360 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3361 +msgid "Core may approve publication." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3363 +msgid "" +"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." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:3365 +#, no-wrap +msgid "Support for Multiple Architectures" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3372 +msgid "" +"FreeBSD is a highly portable operating system intended to function on many " +"different types of hardware architectures. Maintaining clean separation of " +"Machine Dependent (MD) and Machine Independent (MI) code, as well as " +"minimizing MD code, is an important part of our strategy to remain agile " +"with regards to current hardware trends. Each new hardware architecture " +"supported by FreeBSD adds substantially to the cost of code maintenance, " +"toolchain support, and release engineering. It also dramatically increases " +"the cost of effective testing of kernel changes. As such, there is strong " +"motivation to differentiate between classes of support for various " +"architectures while remaining strong in a few key architectures that are " +"seen as the FreeBSD \"target audience\"." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3373 +#, no-wrap +msgid "Statement of General Intent" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3378 +msgid "" +"The FreeBSD Project targets \"production quality commercial off-the-shelf " +"(COTS) workstation, server, and high-end embedded systems\". By retaining a " +"focus on a narrow set of architectures of interest in these environments, " +"the FreeBSD Project is able to maintain high levels of quality, stability, " +"and performance, as well as minimize the load on various support teams on " +"the project, such as the ports team, documentation team, security officer, " +"and release engineering teams. Diversity in hardware support broadens the " +"options for FreeBSD consumers by offering new features and usage " +"opportunities, but these benefits must always be carefully considered in " +"terms of the real-world maintenance cost associated with additional platform " +"support." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3385 +msgid "" +"The FreeBSD Project differentiates platform targets into four tiers. Each " +"tier includes a list of guarantees consumers may rely on as well as " +"obligations by the Project and developers to fulfill those guarantees. " +"These lists define the minimum guarantees for each tier. The Project and " +"developers may provide additional levels of support beyond the minimum " +"guarantees for a given tier, but such additional support is not guaranteed. " +"Each platform target is assigned to a specific tier for each stable branch. " +"As a result, a platform target might be assigned to different tiers on " +"concurrent stable branches." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3386 +#, no-wrap +msgid "Platform Targets" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3393 +msgid "" +"Support for a hardware platform consists of two components: kernel support " +"and userland Application Binary Interfaces (ABIs). Kernel platform support " +"includes things needed to run a FreeBSD kernel on a hardware platform such " +"as machine-dependent virtual memory management and device drivers. A " +"userland ABI specifies an interface for user processes to interact with a " +"FreeBSD kernel and base system libraries. A userland ABI includes system " +"call interfaces, the layout and semantics of public data structures, and the " +"layout and semantics of arguments passed to subroutines. Some components of " +"an ABI may be defined by specifications such as the layout of C++ exception " +"objects or calling conventions for C functions." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3395 +msgid "" +"A FreeBSD kernel also uses an ABI (sometimes referred to as the Kernel " +"Binary Interface (KBI)) which includes the semantics and layouts of public " +"data structures and the layout and semantics of arguments to public " +"functions within the kernel itself." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3400 +msgid "" +"A FreeBSD kernel may support multiple userland ABIs. For example, FreeBSD's " +"amd64 kernel supports FreeBSD amd64 and i386 userland ABIs as well as Linux " +"x86_64 and i386 userland ABIs. A FreeBSD kernel should support a \"native\" " +"ABI as the default ABI. The native \"ABI\" generally shares certain " +"properties with the kernel ABI such as the C calling convention, sizes of " +"basic types, etc." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3402 +msgid "" +"Tiers are defined for both kernels and userland ABIs. In the common case, a " +"platform's kernel and FreeBSD ABIs are assigned to the same tier." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3403 +#, no-wrap +msgid "Tier 1: Fully-Supported Architectures" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3408 +msgid "" +"Tier 1 platforms are the most mature FreeBSD platforms. They are supported " +"by the security officer, release engineering, and Ports Management Team. " +"Tier 1 architectures are expected to be Production Quality with respect to " +"all aspects of the FreeBSD operating system, including installation and " +"development environments." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3410 +msgid "" +"The FreeBSD Project provides the following guarantees to consumers of Tier 1 " +"platforms:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3412 +msgid "" +"Official FreeBSD release images will be provided by the release engineering " +"team." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3413 +msgid "" +"Binary updates and source patches for Security Advisories and Errata Notices " +"will be provided for supported releases." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3414 +msgid "" +"Source patches for Security Advisories will be provided for supported " +"branches." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3415 +msgid "" +"Binary updates and source patches for cross-platform Security Advisories " +"will typically be provided at the time of the announcement." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3416 +msgid "" +"Changes to userland ABIs will generally include compatibility shims to " +"ensure correct operation of binaries compiled against any stable branch " +"where the platform is Tier 1. These shims might not be enabled in the " +"default install. If compatibility shims are not provided for an ABI change, " +"the lack of shims will be clearly documented in the release notes." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3417 +msgid "" +"Changes to certain portions of the kernel ABI will include compatibility " +"shims to ensure correct operation of kernel modules compiled against the " +"oldest supported release on the branch. Note that not all parts of the " +"kernel ABI are protected." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3418 +msgid "" +"Official binary packages for third party software will be provided by the " +"ports team. For embedded architectures, these packages may be cross-built " +"from a different architecture." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3419 +msgid "" +"Most relevant ports should either build or have the appropriate filters to " +"prevent inappropriate ones from building." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3420 +msgid "" +"New features which are not inherently platform-specific will be fully " +"functional on all Tier 1 architectures." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3421 +msgid "" +"Features and compatibility shims used by binaries compiled against older " +"stable branches may be removed in newer major versions. Such removals will " +"be clearly documented in the release notes." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3422 +msgid "" +"Tier 1 platforms should be fully documented. Basic operations will be " +"documented in the FreeBSD Handbook." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3423 +msgid "Tier 1 platforms will be included in the source tree." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3424 +msgid "" +"Tier 1 platforms should be self-hosting either via the in-tree toolchain or " +"an external toolchain. If an external toolchain is required, official binary " +"packages for an external toolchain will be provided." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3426 +msgid "" +"To maintain maturity of Tier 1 platforms, the FreeBSD Project will maintain " +"the following resources to support development:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3428 +msgid "" +"Build and test automation support either in the FreeBSD.org cluster or some " +"other location easily available for all developers. Embedded platforms may " +"substitute an emulator available in the FreeBSD.org cluster for actual " +"hardware." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3429 +#: documentation/content/en/articles/committers-guide/_index.adoc:3459 +msgid "Inclusion in the `make universe` and `make tinderbox` targets." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3430 +msgid "" +"Dedicated hardware in one of the FreeBSD clusters for package building " +"(either natively or via qemu-user)." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3432 +msgid "" +"Collectively, developers are required to provide the following to maintain " +"the Tier 1 status of a platform:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3434 +msgid "" +"Changes to the source tree should not knowingly break the build of a Tier 1 " +"platform." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3435 +msgid "" +"Tier 1 architectures must have a mature, healthy ecosystem of users and " +"active developers." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3436 +msgid "" +"Developers should be able to build packages on commonly available, non-" +"embedded Tier 1 systems. This can mean either native builds if non-embedded " +"systems are commonly available for the platform in question, or it can mean " +"cross-builds hosted on some other Tier 1 architecture." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3437 +msgid "" +"Changes cannot break the userland ABI. If an ABI change is required, ABI " +"compatibility for existing binaries should be provided via use of symbol " +"versioning or shared library version bumps." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3438 +msgid "" +"Changes merged to stable branches cannot break the protected portions of the " +"kernel ABI. If a kernel ABI change is required, the change should be " +"modified to preserve functionality of existing kernel modules." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3439 +#, no-wrap +msgid "Tier 2: Developmental and Niche Architectures" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3443 +msgid "" +"Tier 2 platforms are functional, but less mature FreeBSD platforms. They " +"are not supported by the security officer, release engineering, and Ports " +"Management Team." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3447 +msgid "" +"Tier 2 platforms may be Tier 1 platform candidates that are still under " +"active development. Architectures reaching end of life may also be moved " +"from Tier 1 status to Tier 2 status as the availability of resources to " +"continue to maintain the system in a Production Quality state diminishes. " +"Well-supported niche architectures may also be Tier 2." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3449 +msgid "" +"The FreeBSD Project provides the following guarantees to consumers of Tier 2 " +"platforms:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3451 +msgid "" +"The ports infrastructure should include basic support for Tier 2 " +"architectures sufficient to support building ports and packages. This " +"includes support for basic packages such as ports-mgmt/pkg, but there is no " +"guarantee that arbitrary ports will be buildable or functional." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3452 +msgid "" +"New features which are not inherently platform-specific should be feasible " +"on all Tier 2 architectures if not implemented." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3453 +msgid "Tier 2 platforms will be included in the source tree." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3454 +msgid "" +"Tier 2 platforms should be self-hosting either via the in-tree toolchain or " +"an external toolchain. If an external toolchain is required, official binary " +"packages for an external toolchain will be provided." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3455 +msgid "" +"Tier 2 platforms should provide functional kernels and userlands even if an " +"official release distribution is not provided." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3457 +msgid "" +"To maintain maturity of Tier 2 platforms, the FreeBSD Project will maintain " +"the following resources to support development:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3461 +msgid "" +"Collectively, developers are required to provide the following to maintain " +"the Tier 2 status of a platform:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3463 +msgid "" +"Changes to the source tree should not knowingly break the build of a Tier 2 " +"platform." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3464 +msgid "" +"Tier 2 architectures must have an active ecosystem of users and developers." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3465 +msgid "" +"While changes are permitted to break the userland ABI, the ABI should not be " +"broken gratuitously. Significant userland ABI changes should be restricted " +"to major versions." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3466 +msgid "" +"New features that are not yet implemented on Tier 2 architectures should " +"provide a means of disabling them on those architectures." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3467 +#, no-wrap +msgid "Tier 3: Experimental Architectures" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3471 +msgid "" +"Tier 3 platforms have at least partial FreeBSD support. They are _not_ " +"supported by the security officer, release engineering, and Ports Management " +"Team." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3474 +msgid "" +"Tier 3 platforms are architectures in the early stages of development, for " +"non-mainstream hardware platforms, or which are considered legacy systems " +"unlikely to see broad future use. Initial support for Tier 3 platforms may " +"exist in a separate repository rather than the main source repository." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3477 +msgid "" +"The FreeBSD Project provides no guarantees to consumers of Tier 3 platforms " +"and is not committed to maintaining resources to support development. Tier " +"3 platforms may not always be buildable, nor are any kernel or userland ABIs " +"considered stable." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3478 +#, no-wrap +msgid "Unsupported Architectures" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3482 +msgid "" +"Other platforms are not supported in any form by the project. The project " +"previously described these as Tier 4 systems." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3485 +msgid "" +"After a platform transitions to unsupported, all support for the platform is " +"removed from the source, ports and documentation trees. Note that ports " +"support should remain as long as the platform is supported in a branch " +"supported by ports." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3486 +#, no-wrap +msgid "Policy on Changing the Tier of an Architecture" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3490 +msgid "" +"Systems may only be moved from one tier to another by approval of the " +"FreeBSD Core Team, which shall make that decision in collaboration with the " +"Security Officer, Release Engineering, and ports management teams. For a " +"platform to be promoted to a higher tier, any missing support guarantees " +"must be satisfied before the promotion is completed." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:3492 +#, no-wrap +msgid "Ports Specific FAQ" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3495 +#, no-wrap +msgid "Adding a New Port" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3498 +#, no-wrap +msgid "How do I add a new port?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3503 +msgid "" +"Adding a port to the tree is relatively simple. Once the port is ready to be " +"added, as explained later crossref:committers-guide[ports-qa-add-new-" +"extra,here], you need to add the port's directory entry in the category's " +"[.filename]#Makefile#. In this [.filename]#Makefile#, ports are listed in " +"alphabetical order and added to the `SUBDIR` variable, like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3507 +#, no-wrap +msgid "\tSUBDIR += newport\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3510 +msgid "" +"Once the port and its category's Makefile are ready, the new port can be " +"committed:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3515 +#, no-wrap +msgid "" +"% git add category/Makefile category/newport\n" +"% git commit\n" +"% git push\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3519 +msgid "" +"Don't forget to crossref:committers-guide[port-commit-message-formats,setup " +"git hooks for the ports tree as explained here]; a specific hook has been " +"developed to verify the category's [.filename]#Makefile#." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3522 +#, no-wrap +msgid "Any other things I need to know when I add a new port?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3525 +msgid "" +"Check the port, preferably to make sure it compiles and packages correctly." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3528 +msgid "" +"The extref:{porters-handbook}testing[Porters Handbook's Testing Chapter] " +"contains more detailed instructions. See the extref:{porters-handbook}" +"testing[Portclippy / Portfmt, testing-portclippy] and the extref:{porters-" +"handbook}testing[poudriere, testing-poudriere] sections." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3530 +msgid "" +"You do not necessarily have to eliminate all warnings but make sure you have " +"fixed the simple ones." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3532 +msgid "" +"If the port came from a submitter who has not contributed to the Project " +"before, add that person's name to the extref:{contributors}[Additional " +"Contributors, contrib-additional] section of the FreeBSD Contributors List." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3535 +msgid "" +"Close the PR if the port came in as a PR. To close a PR, change the state " +"to `Issue Resolved` and the resolution as `Fixed`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3539 +msgid "" +"If for some reason using extref:{porters-handbook}testing[poudriere, testing-" +"poudriere] to test the new port is not possible, the bare minimum of testing " +"includes this sequence:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3549 +#, no-wrap +msgid "" +"# make install\n" +"# make package\n" +"# make deinstall\n" +"# pkg add package you built above\n" +"# make deinstall\n" +"# make reinstall\n" +"# make package\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3552 +msgid "" +"Note that poudriere is the reference for package building, it the port does " +"not build in poudriere, it will be removed." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3555 +#, no-wrap +msgid "Removing an Existing Port" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3558 +#, no-wrap +msgid "How do I remove an existing port?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3561 +msgid "" +"First, please read the section about repository copies. Before you remove " +"the port, you have to verify there are no other ports depending on it." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3563 +msgid "Make sure there is no dependency on the port in the ports collection:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3564 +msgid "The port's PKGNAME appears in exactly one line in a recent INDEX file." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3565 +msgid "" +"No other ports contains any reference to the port's directory or PKGNAME in " +"their Makefiles" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3569 +msgid "" +"When using Git, consider using man:git-grep[1], it is much faster than `grep " +"-r`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3572 +msgid "Then, remove the port:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3576 +msgid "Remove the port's files and directory with `git rm`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3577 +msgid "" +"Remove the `SUBDIR` listing of the port in the parent directory " +"[.filename]#Makefile#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3578 +#: documentation/content/en/articles/committers-guide/_index.adoc:3593 +msgid "Add an entry to [.filename]#ports/MOVED#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3579 +msgid "Remove the port from [.filename]#ports/LEGAL# if it is there." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3584 +msgid "" +"Alternatively, you can use the rmport script, from [.filename]#ports/Tools/" +"scripts#. This script was written by {vd}. When sending questions about " +"this script to the {freebsd-ports}, please also CC {crees}, the current " +"maintainer." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3586 +#, no-wrap +msgid "How do I move a port to a new location?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3591 +msgid "" +"Perform a thorough check of the ports collection for any dependencies on the " +"old port location/name, and update them. Running `grep` on " +"[.filename]#INDEX# is not enough because some ports have dependencies " +"enabled by compile-time options. A full man:git-grep[1] of the ports " +"collection is recommended." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3592 +msgid "" +"Remove the `SUBDIR` entry from the old category Makefile and add a `SUBDIR` " +"entry to the new category Makefile." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3594 +msgid "" +"Search for entries in xml files inside [.filename]#ports/security/vuxml# and " +"adjust them accordingly. In particular, check for previous packages with the " +"new name which version could include the new port." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3595 +msgid "Move the port with `git mv`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3596 +#: documentation/content/en/articles/committers-guide/_index.adoc:3607 +msgid "Commit the changes." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3599 +#, no-wrap +msgid "How do I copy a port to a new location?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3604 +msgid "Copy port with `cp -R old-cat/old-port new-cat/new-port`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3605 +msgid "Add the new port to the [.filename]#new-cat/Makefile#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3606 +msgid "Change stuff in [.filename]#new-cat/new-port#." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3610 +#, no-wrap +msgid "Ports Freeze" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3613 +#, no-wrap +msgid "What is a “ports freeze”?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3620 +msgid "" +"A “ports freeze” was a restricted state the ports tree was put in before a " +"release. It was used to ensure a higher quality for the packages shipped " +"with a release. It usually lasted a couple of weeks. During that time, " +"build problems were fixed, and the release packages were built. This " +"practice is no longer used, as the packages for the releases are built from " +"the current stable, quarterly branch." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3623 +msgid "" +"For more information on how to merge commits to the quarterly branch, see " +"crossref:committers-guide[ports-qa-misc-request-mfh, What is the procedure " +"to request authorization for merging a commit to the quarterly branch?]." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3625 +#, no-wrap +msgid "Quarterly Branches" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3628 +#, no-wrap +msgid "What is the procedure to request authorization for merging a commit to the quarterly branch?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3631 +msgid "" +"As of November 30, 2020, there is no need to seek explicit approval to " +"commit to the quarterly branch." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3633 +#, no-wrap +msgid "What is the procedure for merging commits to the quarterly branch?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3636 +msgid "" +"Merging commits to the quarterly branch (a process we call MFH for a " +"historical reason) is very similar to MFC'ing a commit in the src " +"repository, so basically:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3642 +#, no-wrap +msgid "" +"% git checkout 2021Q2\n" +"% git cherry-pick -x $HASH\n" +"(verify everything is OK, for example by doing a build test)\n" +"% git push\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3646 +msgid "" +"where `$HASH` is the hash of the commit you want to copy over to the " +"quarterly branch. The `-x` parameter ensures the hash `$HASH` of the `main` " +"branch is included in the new commit message of the quarterly branch." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3648 +#, no-wrap +msgid "Creating a New Category" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3651 +#, no-wrap +msgid "What is the procedure for creating a new category?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3656 +msgid "" +"Please see extref:{porters-handbook}[Proposing a New Category, proposing-" +"categories] in the Porter's Handbook. Once that procedure has been followed " +"and the PR has been assigned to the {portmgr}, it is their decision whether " +"or not to approve it. If they do, it is their responsibility to:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3660 +msgid "Perform any needed moves. (This only applies to physical categories.)" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3661 +msgid "" +"Update the `VALID_CATEGORIES` definition in [.filename]#ports/Mk/" +"bsd.port.mk#." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3662 +msgid "Assign the PR back to you." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3665 +#, no-wrap +msgid "What do I need to do to implement a new physical category?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3670 +msgid "" +"Upgrade each moved port's [.filename]#Makefile#. Do not connect the new " +"category to the build yet." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3672 +msgid "To do this, you will need to:" +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:3676 +msgid "" +"Change the port's `CATEGORIES` (this was the point of the exercise, " +"remember?) The new category is listed first. This will help to ensure that " +"the PKGORIGIN is correct." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:3677 +msgid "" +"Run a `make describe`. Since the top-level `make index` that you will be " +"running in a few steps is an iteration of `make describe` over the entire " +"ports hierarchy, catching any errors here will save you having to re-run " +"that step later on." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:3678 +msgid "" +"If you want to be really thorough, now might be a good time to run " +"man:portlint[1]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3681 +msgid "" +"Check that the ``PKGORIGIN``s are correct. The ports system uses each port's " +"`CATEGORIES` entry to create its `PKGORIGIN`, which is used to connect " +"installed packages to the port directory they were built from. If this entry " +"is wrong, common port tools like man:pkg-version[8] and man:portupgrade[1] " +"fail." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3683 +msgid "" +"To do this, use the [.filename]#chkorigin.sh# tool: `env PORTSDIR=/path/to/" +"ports sh -e /path/to/ports/Tools/scripts/chkorigin.sh`. This will check " +"every port in the ports tree, even those not connected to the build, so you " +"can run it directly after the move operation. Hint: do not forget to look at " +"the ``PKGORIGIN``s of any slave ports of the ports you just moved!" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3684 +msgid "" +"On your own local system, test the proposed changes: first, comment out the " +"SUBDIR entries in the old ports' categories' [.filename]##Makefile##s; then " +"enable building the new category in [.filename]#ports/Makefile#. Run make " +"checksubdirs in the affected category directories to check the SUBDIR " +"entries. Next, in the [.filename]#ports/# directory, run make index. This " +"can take over 40 minutes on even modern systems; however, it is a necessary " +"step to prevent problems for other people." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3685 +msgid "" +"Once this is done, you can commit the updated [.filename]#ports/Makefile# to " +"connect the new category to the build and also commit the " +"[.filename]#Makefile# changes for the old category or categories." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3686 +msgid "Add appropriate entries to [.filename]#ports/MOVED#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3687 +msgid "Update the documentation by modifying:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3688 +#: documentation/content/en/articles/committers-guide/_index.adoc:3697 +msgid "" +"the extref:{porters-handbook}[list of categories, PORTING-CATEGORIES] in the " +"Porter's Handbook" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3690 +msgid "" +"Only once all the above have been done, and no one is any longer reporting " +"problems with the new ports, should the old ports be deleted from their " +"previous locations in the repository." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3692 +#, no-wrap +msgid "What do I need to do to implement a new virtual category?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3695 +msgid "" +"This is much simpler than a physical category. Only a few modifications are " +"needed:" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:3699 +#: documentation/content/en/articles/committers-guide/_index.adoc:3793 +#, no-wrap +msgid "Miscellaneous Questions" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3702 +#, no-wrap +msgid "Are there changes that can be committed without asking the maintainer for approval?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3705 +msgid "Blanket approval for most ports applies to these types of fixes:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3707 +msgid "" +"Most infrastructure changes to a port (that is, modernizing, but not " +"changing the functionality). For example, the blanket covers converting to " +"new `USES` macros, enabling verbose builds, and switching to new ports " +"system syntaxes." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3708 +msgid "Trivial and _tested_ build and runtime fixes." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3709 +msgid "" +"Documentations or metadata changes to ports, like [.filename]#pkg-descr# or " +"`COMMENT`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3714 +msgid "" +"Exceptions to this are anything maintained by the {portmgr}, or the " +"{security-officer}. No unauthorized commits may ever be made to ports " +"maintained by those groups." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3717 +#, no-wrap +msgid "How do I know if my port is building correctly or not?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3721 +msgid "" +"The packages are built multiple times each week. If a port fails, the " +"maintainer will receive an email from `pkg-fallout@FreeBSD.org`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3723 +msgid "" +"Reports for all the package builds (official, experimental, and non-" +"regression) are aggregated at link:pkg-status.FreeBSD.org[pkg-" +"status.FreeBSD.org]." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3725 +#, no-wrap +msgid "I added a new port. Do I need to add it to the [.filename]#INDEX#?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3728 +msgid "" +"No. The file can either be generated by running `make index`, or a pre-" +"generated version can be downloaded with `make fetchindex`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3730 +#, no-wrap +msgid "Are there any other files I am not allowed to touch?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3734 +msgid "" +"Any file directly under [.filename]#ports/#, or any file under a " +"subdirectory that starts with an uppercase letter ([.filename]#Mk/#, " +"[.filename]#Tools/#, etc.). In particular, the {portmgr} is very protective " +"of [.filename]#ports/Mk/bsd.port*.mk# so do not commit changes to those " +"files unless you want to face their wrath." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3736 +#, no-wrap +msgid "What is the proper procedure for updating the checksum for a port distfile when the file changes without a version change?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3740 +msgid "" +"When the checksum for a distribution file is updated due to the author " +"updating the file without changing the port revision, the commit message " +"includes a summary of the relevant diffs between the original and new " +"distfile to ensure that the distfile has not been corrupted or maliciously " +"altered. If the current version of the port has been in the ports tree for " +"a while, a copy of the old distfile will usually be available on the ftp " +"servers; otherwise the author or maintainer should be contacted to find out " +"why the distfile has changed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:3742 +#, no-wrap +msgid "How can an experimental test build of the ports tree (exp-run) be requested?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3746 +msgid "" +"An exp-run must be completed before patches with a significant ports impact " +"are committed. The patch can be against the ports tree or the base system." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3748 +msgid "" +"Full package builds will be done with the patches provided by the submitter, " +"and the submitter is required to fix detected problems _(fallout)_ before " +"commit." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3752 +msgid "Go to the link:https://bugs.freebsd.org/submit[Bugzilla new PR page]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3753 +msgid "Select the product your patch is about." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3754 +msgid "Fill in the bug report as normal. Remember to attach the patch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3755 +msgid "" +"If at the top it says “Show Advanced Fields” click on it. It will now say " +"“Hide Advanced Fields”. Many new fields will be available. If it already " +"says “Hide Advanced Fields”, no need to do anything." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3756 +msgid "" +"In the “Flags” section, set the “exp-run” one to `?`. As for all other " +"fields, hovering the mouse over any field shows more details." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3757 +msgid "Submit. Wait for the build to run." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3758 +msgid "{portmgr} will reply with a possible fallout." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3759 +msgid "Depending on the fallout:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3760 +msgid "" +"If there is no fallout, the procedure stops here, and the change can be " +"committed, pending any other approval required." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3761 +msgid "" +"If there is fallout, it _must_ be fixed, either by fixing the ports directly " +"in the ports tree, or adding to the submitted patch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3762 +msgid "" +"When this is done, go back to step 6 saying the fallout was fixed and wait " +"for the exp-run to be run again. Repeat as long as there are broken ports." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:3765 +#, no-wrap +msgid "Issues Specific to Developers Who Are Not Committers" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3770 +msgid "" +"A few people who have access to the FreeBSD machines do not have commit " +"bits. Almost all of this document will apply to these developers as well " +"(except things specific to commits and the mailing list memberships that go " +"with them). In particular, we recommend that you read:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3772 +msgid "crossref:committers-guide[admin, Administrative Details]" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3773 +msgid "crossref:committers-guide[conventions-everyone, For Everyone]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3777 +msgid "" +"Get your mentor to add you to the \"Additional Contributors\" " +"([.filename]#doc/shared/contrib-additional.adoc#), if you are not already " +"listed there." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3779 +msgid "crossref:committers-guide[developer.relations, Developer Relations]" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3780 +msgid "crossref:committers-guide[ssh.guide, SSH Quick-Start Guide]" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3781 +msgid "" +"crossref:committers-guide[rules, The FreeBSD Committers' Big List of Rules]" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:3783 +#, no-wrap +msgid "Information About Google Analytics" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3786 +msgid "" +"As of December 12, 2012, Google Analytics was enabled on the FreeBSD Project " +"website to collect anonymized usage statistics regarding usage of the site." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:3790 +msgid "" +"As of March 3, 2022, Google Analytics was removed from the FreeBSD Project." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3795 +#, no-wrap +msgid "How do I access people.FreeBSD.org to put up personal or project information?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3799 +msgid "" +"`people.FreeBSD.org` is the same as `freefall.FreeBSD.org`. Just create a " +"[.filename]#public_html# directory. Anything you place in that directory " +"will automatically be visible under https://people.FreeBSD.org/[https://" +"people.FreeBSD.org/]." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3800 +#, no-wrap +msgid "Where are the mailing list archives stored?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3803 +msgid "" +"The mailing lists are archived under [.filename]#/local/mail# on " +"`freefall.FreeBSD.org`." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3804 +#, no-wrap +msgid "I would like to mentor a new committer. What process do I need to follow?" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3807 +msgid "" +"See the https://www.freebsd.org/internal/new-account/[New Account Creation " +"Procedure] document on the internal pages." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:3809 +#, no-wrap +msgid "Benefits and Perks for FreeBSD Committers" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3812 +#, no-wrap +msgid "Recognition" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3816 +msgid "" +"Recognition as a competent software engineer is the longest lasting value. " +"In addition, getting a chance to work with some of the best people that " +"every engineer would dream of meeting is a great perk!" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3818 +#, no-wrap +msgid "FreeBSD Mall" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3821 +msgid "" +"FreeBSD committers can get a free 4-CD or DVD set at conferences from http://" +"www.freebsdmall.com[FreeBSD Mall, Inc.]." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3823 +#, no-wrap +msgid "`Gandi.net`" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3826 +msgid "" +"https://gandi.net[Gandi] provides website hosting, cloud computing, domain " +"registration, and X.509 certificate services." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3830 +msgid "" +"Gandi offers an E-rate discount to all FreeBSD developers. To streamline " +"the process of getting the discount first set up a Gandi account, fill in " +"the billing information and select the currency. Then send an mail to " +"mailto:non-profit@gandi.net[non-profit@gandi.net] using your `@freebsd.org` " +"mail address, and indicate your Gandi handle." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:3832 +#, no-wrap +msgid "`rsync.net`" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3835 +msgid "" +"https://rsync.net[rsync.net] provides cloud storage for offsite backup that " +"is optimized for UNIX users. Their service runs entirely on FreeBSD and ZFS." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:3836 +msgid "" +"rsync.net offers a free-forever 500 GB account to FreeBSD developers. Simply " +"sign up at https://www.rsync.net/freebsd.html[https://www.rsync.net/" +"freebsd.html] using your `@freebsd.org` address to receive this free account." +msgstr "" diff --git a/documentation/content/en/articles/contributing/_index.adoc b/documentation/content/en/articles/contributing/_index.adoc index 63ebc42b39..022dc29e2e 100644 --- a/documentation/content/en/articles/contributing/_index.adoc +++ b/documentation/content/en/articles/contributing/_index.adoc @@ -41,6 +41,8 @@ ifndef::env-beastie[] include::../../../../../shared/asciidoctor.adoc[] endif::[] +pass:[<!-- vale FreeBSD.Pronouns = NO -->] + [.abstract-title] Abstract @@ -50,7 +52,9 @@ This article describes the different ways in which an individual or organization toc::[] -So you want to contribute to FreeBSD? That is great! FreeBSD _relies_ on the contributions of its user base to survive. +So you want to contribute to FreeBSD? +That is great! +FreeBSD _relies_ on the contributions of its user base to survive. Your contributions are not only appreciated, they are vital to FreeBSD's continued growth. A large and growing number of international contributors, of greatly varying ages and areas of technical expertise, develop FreeBSD. @@ -65,8 +69,11 @@ As such, our [.filename]#TODO# lists span a very wide range of tasks: from docum People of any skill level, in almost any area, can almost certainly help the project. Commercial entities engaged in FreeBSD-related enterprises are also encouraged to contact us. -Do you need a special extension to make your product work? You will find us receptive to your requests, given that they are not too outlandish. -Are you working on a value-added product? Please let us know! We may be able to work cooperatively on some aspect of it. +Do you need a special extension to make your product work? +You will find us receptive to your requests, given that they are not too outlandish. +Are you working on a value-added product? +Please let us know! +We may be able to work cooperatively on some aspect of it. The free software world is challenging many existing assumptions about how software is developed, sold, and maintained, and we urge you to at least give it a second look. [[contrib-what]] @@ -81,9 +88,18 @@ Many people who are involved in FreeBSD are not programmers. The Project includes documentation writers, Web designers, and support people. All that these people need to contribute is an investment of time and a willingness to learn. -. Read through the FAQ and Handbook periodically. If anything is poorly explained, ambiguous, out of date or incorrect, let us know. Even better, send us a fix (AsciiDoc is not difficult to learn, but there is no objection to plain text submissions). -. Help translate FreeBSD documentation into your native language. If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date and correct. First take a look at the extref:{fdp-primer}[Translations FAQ, translations] in the FreeBSD Documentation Project Primer. You are not committing yourself to translating every single FreeBSD document by doing this - as a volunteer, you can do as much or as little translation as you desire. Once someone begins translating, others almost always join the effort. If you only have the time or energy to translate one part of the documentation, please translate the installation instructions. -. Read the {freebsd-questions} occasionally (or even regularly). It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself! These forums can also be a source of ideas for things to improve upon. +. Read through the FAQ and Handbook periodically. +If anything is poorly explained, ambiguous, out of date or incorrect, let us know. +Even better, send us a fix (AsciiDoc is not difficult to learn, but there is no objection to plain text submissions). +. Help translate FreeBSD documentation into your native language. +If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date and correct. +First take a look at the extref:{fdp-primer}translations[Translations FAQ, translations] in the FreeBSD Documentation Project Primer. +You are not committing yourself to translating every single FreeBSD document by doing this - as a volunteer, you can do as much or as little translation as you desire. +Once someone begins translating, others almost always join the effort. +If you only have the time or energy to translate one part of the documentation, please translate the installation instructions. +. Read the {freebsd-questions} occasionally (or even regularly). +It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself! +These forums can also be a source of ideas for things to improve upon. [[ongoing-programmer-tasks]] === Ongoing Programmer Tasks @@ -92,14 +108,21 @@ Most of the tasks listed here may require a considerable investment of time, an However, there are also many useful tasks which are suitable for "weekend hackers". . If you run FreeBSD-CURRENT and have a good Internet connection, there is a machine `current.FreeBSD.org` which builds a full release once a day-every now and again, try to install the latest release from it and report any failures in the process. -. Read the {freebsd-bugs}. There may be a problem you can comment constructively on or with patches you can test. Or you could even try to fix one of the problems yourself. +. Read the {freebsd-bugs}. +There may be a problem you can comment constructively on or with patches you can test. +Or you could even try to fix one of the problems yourself. . If you know of any bug fixes which have been successfully applied to -CURRENT but have not been merged into -STABLE after a decent interval (normally a couple of weeks), send the committer a polite reminder. . Move contributed software to [.filename]#src/contrib# in the source tree. . Make sure code in [.filename]#src/contrib# is up to date. -. Build the source tree (or just part of it) with extra warnings enabled and clean up the warnings. A list of build warnings can also be found from our https://ci.freebsd.org[CI] by selecting a build and checking "LLVM/Clang Warnings". +. Build the source tree (or just part of it) with extra warnings enabled and clean up the warnings. +A list of build warnings can also be found from our https://ci.freebsd.org[CI] by selecting a build and checking "LLVM/Clang Warnings". . Fix warnings for ports which do deprecated things like using `gets()` or including [.filename]#malloc.h#. . If you have contributed any ports and you had to make FreeBSD-specific changes, send your patches back to the original authors (this will make your life easier when they bring out the next version). -. Get copies of formal standards like POSIX(R). Compare FreeBSD's behavior to that required by the standard. If the behavior differs, particularly in subtle or obscure corners of the specification, send in a PR about it. If you are able, figure out how to fix it and include a patch in the PR. If you think the standard is wrong, ask the standards body to consider the question. +. Get copies of formal standards like POSIX(R). +Compare FreeBSD's behavior to that required by the standard. +If the behavior differs, particularly in subtle or obscure corners of the specification, send in a PR about it. +If you are able, figure out how to fix it and include a patch in the PR. +If you think the standard is wrong, ask the standards body to consider the question. . Suggest further tasks for this list! === Work through the PR Database @@ -126,9 +149,10 @@ Whether you are looking for an ongoing role, or a fun challenge for a rainy day, There are a number of easy ways you can contribute to keeping the ports tree up to date and in good working order: * Find some cool or useful software and extref:{porters-handbook}[create a port] for it. -* There are a large number of ports that have no maintainer. Become a maintainer and <<adopt-port>>. -* If you have created or adopted a port, be aware of <<maintain-port>>. -* When you are looking for a quick challenge you could <<fix-broken>>. +* There are a large number of ports that have no maintainer. +Become a maintainer and crossref:contributing[adopt-port, Adopting an unmaintained port]. +* If you have created or adopted a port, be aware of crossref:contributing[maintain-port, The challenge for port maintainers]. +* When you are looking for a quick challenge you could crossref:contributing[fix-broken, Finding and fixing a broken port]. === Pick one of the items from the Ideas page @@ -145,14 +169,44 @@ Contributions to the system generally fall into one or more of the following 5 c An idea or suggestion of _general_ technical interest should be mailed to the {freebsd-hackers}. Likewise, people with an interest in such things (and a tolerance for a _high_ volume of mail!) may subscribe to the {freebsd-hackers}. -See extref:{handbook}[The FreeBSD Handbook, eresources-mail] for more information about this and other mailing lists. +See extref:{handbook}eresources[The FreeBSD Handbook, eresources-mail] for more information about this and other mailing lists. + +If you are submitting a simple patch to the src repo, please consider submitting it to the project's GitHub mirror as https://github.com/freebsd/freebsd-src/pulls[a pull request]. +Suitable submissions should: + +* It is ready or nearly ready to be committed. +A committer should be able to land this patch with less than 10 minutes of additional work. +* It passes all the GitHub CI jobs. +* You can respond to feedback quickly. +* It touches fewer than about 10 files and the changes are less than about 200 lines. +Changes larger than this may be OK, or you may be asked to submit multiple pull requests of a more manageable size. +* Each logical change is a separate commit within the pull request. +Commit messages for each change should follow extref:{committers-guide}#commit-log-message[commit log guide]. +* All commits have your name and valid email address as you'd like to see them in the FreeBSD repository as the author. +Fake github.com addresses cannot be used. +* The scope of the pull request should not change during review. +If the review suggests changes that expand the scope, please create an independent pull request. +* Fixup commits should be squashed with the commit they are fixing. +Each commit in your branch should be suitable for FreeBSD's repository. +* Commits should include one or more `Signed-off-by:` lines with full name and email address certifying https://developercertificate.org/[Developer Certificate of Origin]. + +When updating pull request, please rebase with a forced push rather than a merge commit. +More complex changes may be submitted as pull requests, but they may be closed if they are too large, too unwieldy, become inactive, need further discussion in the community, or need extensive revision. +Please avoid creating large, wide-ranging cleanup patches: they are too large and lack the focus needed for a good review. +Misdirected patches may be redirected to a more appropriate forum for the patch to be resolved. + +Pull requests submitted to the ports repository may or may not see action, based on the whims of developers. +For now, you will have a better experience if you follow the ports submission +process crossref:contributing[ports-contributing, Contributing to ports]. + +The docs team also accepts pull requests via GitHub, but has not established any policy for them yet. If you find a bug or are submitting a specific change, please report it using the https://bugs.FreeBSD.org/submit/[bug submission form]. Try to fill-in each field of the bug report. Unless they exceed 65KB, include any patches directly in the report. If the patch is suitable to be applied to the source tree put `[PATCH]` in the synopsis of the report. When including patches, _do not_ use cut-and-paste because cut-and-paste turns tabs into spaces and makes them unusable. -When patches are a lot larger than 20KB, consider compressing them (eg. with man:gzip[1] or man:bzip2[1]) prior to uploading them. +When patches are a lot larger than 20KB, consider compressing them (for example with man:gzip[1] or man:bzip2[1]) prior to uploading them. After filing a report, you should receive confirmation along with a tracking number. Keep this tracking number so that you can update us with details about the problem. @@ -169,7 +223,7 @@ Send submissions and changes (even small ones are welcome!) using the same metho An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. There is a special on-going release of FreeBSD known as "FreeBSD-CURRENT" which is made available in a variety of ways for the convenience of developers working actively on the system. -See extref:{handbook}[The FreeBSD Handbook, current-stable] for more information about getting and using FreeBSD-CURRENT. +See extref:{handbook}cutting-edge[The FreeBSD Handbook, current-stable] for more information about getting and using FreeBSD-CURRENT. Working from older sources unfortunately means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. Chances of this can be minimized somewhat by subscribing to the {freebsd-announce} and the {freebsd-current} lists, where discussions on the current state of the system take place. @@ -199,8 +253,7 @@ Once you have a set of diffs (which you may test with the man:patch[1] command), _Do not_ just send the diffs to the {freebsd-hackers} or they will get lost! We greatly appreciate your submission (this is a volunteer project!); because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do. Indicate your submission by including `[PATCH]` in the synopsis of the report. -If you feel it appropriate (e.g. you have added, deleted, or renamed files), bundle your changes into a `tar` file. -Archives created with man:shar[1] are also welcome. +If you feel it appropriate (for example you have added, deleted, or renamed files), bundle your changes into a `tar` file. If your change is of a potentially sensitive nature, such as if you are unsure of copyright issues governing its further distribution then you should send it to {core-email} directly rather than submitting as a bug report. The {core-email} reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. @@ -221,12 +274,13 @@ The complete listing can be found on the link:https://www.FreeBSD.org/internal/s === Money or Hardware -We are always very happy to accept donations to further the cause of the FreeBSD Project and, in a volunteer effort like ours, a little can go a long way! Donations of hardware are also very important to expanding our list of supported peripherals since we generally lack the funds to buy such items ourselves. +We are always very happy to accept donations to further the cause of the FreeBSD Project and, in a volunteer effort like ours, a little can go a long way! +Donations of hardware are also very important to expanding our list of supported peripherals since we generally lack the funds to buy such items ourselves. [[donations]] ==== Donating Funds -The https://www.freebsdfoundation.org[FreeBSD Foundation] is a non-profit, tax-exempt foundation established to further the goals of the FreeBSD Project. +The https://www.freebsdfoundation.org[FreeBSD Foundation] is a non-profit, tax-exempt foundation established to further the goals of the FreeBSD Project. As a 501(c)3 entity, the Foundation is generally exempt from US federal income tax as well as Colorado State income tax. Donations to a tax-exempt entity are often deductible from taxable federal income. @@ -265,27 +319,20 @@ There are a large number of unmaintained ports. It is a good idea to start with adopting a port that you use regularly. Unmaintained ports have their `MAINTAINER` set to `ports@FreeBSD.org`. -A list of unmaintained ports and their current errors and problem reports can be seen at the http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org[FreeBSD Ports Monitoring System]. +Many unmaintained ports can have pending updates, this can be seen at the https://portscout.freebsd.org/ports@freebsd.org.html[FreeBSD Ports distfile scanner]. On https://portsfallout.com/fallout?port=&maintainer=ports%40FreeBSD.org[PortsFallout] can be seen a list of unmaintained ports with errors. -Many unmaintained ports can have pending updates, this can be seen at the https://portscout.freebsd.org/ports@freebsd.org.html[FreeBSD Ports distfile scanner]. - -Some ports affect a large number of others due to dependencies and slave port relationships. +Some ports affect a large number of others due to dependencies and secondary port relationships. Generally, we want people to have some experience before they maintain such ports. -You can find out whether or not a port has dependencies or slave ports by looking at a master index of ports called [.filename]#INDEX#. -(The name of the file varies by release of FreeBSD; for instance, [.filename]#INDEX-8#.) Some ports have conditional dependencies that are not included in a default [.filename]#INDEX# build. +You can find out whether or not a port has dependencies or secondary ports by looking at a primary index of ports called [.filename]#INDEX#. +(The name of the file varies by release of FreeBSD; for instance, [.filename]#INDEX-13#.) Some ports have conditional dependencies that are not included in a default [.filename]#INDEX# build. We expect you to be able to recognize such ports by looking through other ports' [.filename]#Makefile#'s. -[NOTE] -====== -The FreeBSD Ports Monitoring System (portsmon) is currently not working due to latest Python updates. -====== - ==== How to adopt the port -First make sure you understand your <<maintain-port>>. +First make sure you understand your crossref:contributing[maintain-port, The challenge for port maintainers]. Also read the extref:{porters-handbook}[Porter's Handbook]. _Please do not commit yourself to more than you feel you can comfortably handle._ @@ -295,7 +342,7 @@ If the port has build errors or needs updating, you may wish to include any othe This will help because many committers are less willing to assign maintainership to someone who does not have a known track record with FreeBSD. Submitting PRs that fix build errors or update ports are the best ways to establish one. -File your PR with category `ports` and class `change-request`. +File your PR with Product `Ports & Packages`. A committer will examine your PR, commit the changes, and finally close the PR. Sometimes this process can take a little while (committers are volunteers, too :). @@ -316,19 +363,24 @@ An additional challenge is to keep individual ports working within the Ports Col As a maintainer, you will need to manage the following challenges: -* *New software versions and updates.* New versions and updates of existing ported software become available all the time, and these need to be incorporated into the Ports Collection in order to provide up-to-date software. +* *New software versions and updates.* New versions and updates of existing ported software become available all the time, and these need to be incorporated into the Ports Collection to provide up-to-date software. * *Changes to dependencies.* If significant changes are made to the dependencies of your port, it may need to be updated so that it will continue to work correctly. * *Changes affecting dependent ports.* If other ports depend on a port that you maintain, changes to your port may require coordination with other maintainers. -* *Interaction with other users, maintainers and developers.* Part of being a maintainer is taking on a support role. You are not expected to provide general support (but we welcome it if you choose to do so). What you should provide is a point of coordination for FreeBSD-specific issues regarding your ports. +* *Interaction with other users, maintainers and developers.* Part of being a maintainer is taking on a support role. +You are not expected to provide general support (but we welcome it if you choose to do so). What you should provide is a point of coordination for FreeBSD-specific issues regarding your ports. -* *Bug hunting.* A port may be affected by bugs which are specific to FreeBSD. You will need to investigate, find, and fix these bugs when they are reported. Thoroughly testing a port to identify problems before they make their way into the Ports Collection is even better. +* *Bug hunting.* A port may be affected by bugs which are specific to FreeBSD. +You will need to investigate, find, and fix these bugs when they are reported. +Thoroughly testing a port to identify problems before they make their way into the Ports Collection is even better. -* *Changes to ports infrastructure and policy.* Occasionally the systems that are used to build ports and packages are updated or a new recommendation affecting the infrastructure is made. You should be aware of these changes in case your ports are affected and require updating. +* *Changes to ports infrastructure and policy.* Occasionally the systems that are used to build ports and packages are updated or a new recommendation affecting the infrastructure is made. +You should be aware of these changes in case your ports are affected and require updating. -* *Changes to the base system.* FreeBSD is under constant development. Changes to software, libraries, the kernel or even policy changes can cause flow-on change requirements to ports. +* *Changes to the base system.* FreeBSD is under constant development. +Changes to software, libraries, the kernel or even policy changes can cause flow-on change requirements to ports. ==== Maintainer responsibilities @@ -358,11 +410,18 @@ You need to be able to generate a patch between the original port and your updat + 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. -** Make sure your port's dependencies are complete. The recommended way of doing this is by installing your own ports tinderbox. See <<resources>> for more information. -** Check that the packing list is up to date. This involves adding in any new files and directories and removing unused entries. -** Verify your port using man:portlint[1] as a guide. See <<resources>> for important information about using portlint. -** 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]. +** 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. +** Make sure your port's dependencies are complete. +The recommended way of doing this is by installing your own ports tinderbox. +See crossref:contributing[resources, Resources for ports maintainers and contributors] for more information. +** Check that the packing list is up to date. +This involves adding in any new files and directories and removing unused entries. +** Verify your port using man:portlint[1] as a guide. +See crossref:contributing[resources, Resources for ports maintainers and contributors] for important information about using portlint. +** 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 package:ports-mgmt/poudriere[]. . Submit changes + @@ -373,7 +432,7 @@ Please refer to extref:{problem-reports}[Writing FreeBSD Problem Reports] for in ====== Please do not submit a man:shar[1] archive of the entire port; instead, use man:git-format-patch[1] or man:diff[1] `-ruN`. In this way, committers can much more easily see exactly what changes are being made. -The Porter's Handbook section on extref:{porters-handbook}[Upgrading, port-upgrading] has more information. +The Porter's Handbook section on extref:{porters-handbook}upgrading[Upgrading, port-upgrading] has more information. ====== . Wait + @@ -387,7 +446,8 @@ A prompt response will help get your PR committed faster, and is better for main . 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! +The PR will then be closed by the committer. +That is it! ==== ===== Ensure your ports continue to build correctly @@ -430,7 +490,8 @@ If the failure was reported to you by a user, ask them to send you information w . 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. +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. @@ -523,29 +584,23 @@ If you can make them feel that their contribution is appreciated (and it should There are some really good places to find a port that needs some attention. You can use the https://bugs.freebsd.org/search[web interface] to the Problem Report database to search through and view unresolved PRs. -The majority of ports PRs are updates, but with a little searching and skimming over synopses you should be able to find something interesting to work on (the `sw-bug` class is a good place to start). - -The other place is the http://portsmon.FreeBSD.org/[FreeBSD Ports Monitoring System]. -In particular look for unmaintained ports with build errors and ports that are marked `BROKEN`. +The majority of ports PRs are updates, but with a little searching and skimming over synopses you should be able to find something interesting to work on. https://portsfallout.com/[PortsFallout] shows port issues gathered from the FreeBSD package building. It is OK to send changes for a maintained port as well, but remember to ask the maintainer in case they are already working on the problem. -Once you have found a bug or problem, collect information, investigate and fix! If there is an existing PR, follow up to that. +Once you have found a bug or problem, collect information, investigate and fix! +If there is an existing PR, follow up to that. Otherwise create a new PR. Your changes will be reviewed and, if everything checks out, committed. -[NOTE] -====== -The FreeBSD Ports Monitoring System (portsmon) is currently not working due to latest Python updates. -====== - [[mortal-coil]] === When to call it quits As your interests and commitments change, you may find that you no longer have time to continue some (or all) of your ports contributions. -That is fine! Please let us know if you are no longer using a port or have otherwise lost time or interest in being a maintainer. +That is fine! +Please let us know if you are no longer using a port or have otherwise lost time or interest in being a maintainer. In this way we can go ahead and allow other people to try to work on existing problems with the port without waiting for your response. Remember, FreeBSD is a volunteer project, so if maintaining a port is no fun any more, it is probably time to let someone else do it! @@ -556,22 +611,20 @@ By this, we mean that there are unresolved problems or pending updates that have [[resources]] === Resources for ports maintainers and contributors -The extref:{porters-handbook}[Porter's Handbook] is your hitchhiker's guide to the ports system. Keep it handy! +The extref:{porters-handbook}[Porter's Handbook] is your hitchhiker's guide to the ports system. +Keep it handy! extref:{problem-reports}[Writing FreeBSD Problem Reports] describes how to best formulate and submit a PR. -In 2005 more than eleven thousand ports PRs were submitted! Following this article will greatly assist us in reducing the time needed to handle your PRs. +In 2005 more than eleven thousand ports PRs were submitted! +Following this article will greatly assist us in reducing the time needed to handle your PRs. The https://bugs.freebsd.org/bugzilla/query.cgi[Problem Report database]. -The http://portsmon.FreeBSD.org/[FreeBSD Ports Monitoring System (portsmon)] can show you cross-referenced information about ports such as build errors and problem reports. -If you are a maintainer you can use it to check on the build status of your ports. -As a contributor you can use it to find broken and unmaintained ports that need to be fixed. - The http://portscout.FreeBSD.org[FreeBSD Ports distfile scanner (portscout)] can show you ports for which the distfiles are not fetchable. You can check on your own ports or use it to find ports that need their `MASTER_SITES` updated. package:ports-mgmt/poudriere[] is the most thorough way to test a port through the entire cycle of installation, packaging, and deinstallation. -Documentation is located at the https://github.com/freebsd/poudriere[poudriere github repository] +Documentation is located at the https://github.com/freebsd/poudriere[poudriere GitHub repository] man:portlint[1] is an application which can be used to verify that your port conforms to many important stylistic and functional guidelines. portlint is a simple heuristic application, so you should use it __only as a guide__. @@ -587,7 +640,8 @@ https://portsfallout.com/[PortsFallout] is a place to help in searching for the [[ideas-contributing]] == Getting Started in Other Areas -Looking for something interesting to get started that is not mentioned elsewhere in this article? The FreeBSD Project has several Wiki pages containing areas within which new contributors can get ideas on how to get started. +Looking for something interesting to get started that is not mentioned elsewhere in this article? +The FreeBSD Project has several Wiki pages containing areas within which new contributors can get ideas on how to get started. The https://wiki.freebsd.org/JuniorJobs[Junior Jobs] page has a list of projects that might be of interest to people just getting started in FreeBSD, and want to work on interesting things to get their feet wet. diff --git a/documentation/content/en/articles/contributing/_index.po b/documentation/content/en/articles/contributing/_index.po new file mode 100644 index 0000000000..b5c3a104a4 --- /dev/null +++ b/documentation/content/en/articles/contributing/_index.po @@ -0,0 +1,1644 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-12-29 08:30-0500\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/contributing/_index.adoc:1 +#, no-wrap +msgid "How to contribute to the FreeBSD Project" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/contributing/_index.adoc:1 +#: documentation/content/en/articles/contributing/_index.adoc:13 +#, no-wrap +msgid "Contributing to FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:45 +msgid "pass:[<!-- vale FreeBSD.Pronouns = NO -->]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:48 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:50 +msgid "" +"This article describes the different ways in which an individual or " +"organization may contribute to the FreeBSD Project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:52 +msgid "'''" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:59 +msgid "" +"So you want to contribute to FreeBSD? That is great! FreeBSD _relies_ on the " +"contributions of its user base to survive. Your contributions are not only " +"appreciated, they are vital to FreeBSD's continued growth." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:62 +msgid "" +"A large and growing number of international contributors, of greatly varying " +"ages and areas of technical expertise, develop FreeBSD. There is always " +"more work to be done than there are people available to do it, and more help " +"is always appreciated." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:66 +msgid "" +"As a volunteer, what you do is limited only by what you want to do. " +"However, we do ask that you are aware of what other members of the FreeBSD " +"community will expect of you. You may want to take this into account before " +"deciding to volunteer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:70 +msgid "" +"The FreeBSD project is responsible for an entire operating system " +"environment, rather than just a kernel or a few scattered utilities. As " +"such, our [.filename]#TODO# lists span a very wide range of tasks: from " +"documentation, beta testing and presentation, to the system installer and " +"highly specialized types of kernel development. People of any skill level, " +"in almost any area, can almost certainly help the project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:78 +msgid "" +"Commercial entities engaged in FreeBSD-related enterprises are also " +"encouraged to contact us. Do you need a special extension to make your " +"product work? You will find us receptive to your requests, given that they " +"are not too outlandish. Are you working on a value-added product? Please " +"let us know! We may be able to work cooperatively on some aspect of it. The " +"free software world is challenging many existing assumptions about how " +"software is developed, sold, and maintained, and we urge you to at least " +"give it a second look." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributing/_index.adoc:80 +#, no-wrap +msgid "What Is Needed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:83 +msgid "" +"The following list of tasks and sub-projects represents something of an " +"amalgam of various [.filename]#TODO# lists and user requests." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:85 +#, no-wrap +msgid "Ongoing Non-Programmer Tasks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:90 +msgid "" +"Many people who are involved in FreeBSD are not programmers. The Project " +"includes documentation writers, Web designers, and support people. All that " +"these people need to contribute is an investment of time and a willingness " +"to learn." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:94 +msgid "" +"Read through the FAQ and Handbook periodically. If anything is poorly " +"explained, ambiguous, out of date or incorrect, let us know. Even better, " +"send us a fix (AsciiDoc is not difficult to learn, but there is no objection " +"to plain text submissions)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:100 +msgid "" +"Help translate FreeBSD documentation into your native language. If " +"documentation already exists for your language, you can help translate " +"additional documents or verify that the translations are up-to-date and " +"correct. First take a look at the extref:{fdp-primer}[Translations FAQ, " +"translations] in the FreeBSD Documentation Project Primer. You are not " +"committing yourself to translating every single FreeBSD document by doing " +"this - as a volunteer, you can do as much or as little translation as you " +"desire. Once someone begins translating, others almost always join the " +"effort. If you only have the time or energy to translate one part of the " +"documentation, please translate the installation instructions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:103 +msgid "" +"Read the {freebsd-questions} occasionally (or even regularly). It can be " +"very satisfying to share your expertise and help people solve their " +"problems; sometimes you may even learn something new yourself! These forums " +"can also be a source of ideas for things to improve upon." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:105 +#, no-wrap +msgid "Ongoing Programmer Tasks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:109 +msgid "" +"Most of the tasks listed here may require a considerable investment of time, " +"an in-depth knowledge of the FreeBSD kernel, or both. However, there are " +"also many useful tasks which are suitable for \"weekend hackers\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:111 +msgid "" +"If you run FreeBSD-CURRENT and have a good Internet connection, there is a " +"machine `current.FreeBSD.org` which builds a full release once a day-every " +"now and again, try to install the latest release from it and report any " +"failures in the process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:114 +msgid "" +"Read the {freebsd-bugs}. There may be a problem you can comment " +"constructively on or with patches you can test. Or you could even try to " +"fix one of the problems yourself." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:115 +msgid "" +"If you know of any bug fixes which have been successfully applied to -" +"CURRENT but have not been merged into -STABLE after a decent interval " +"(normally a couple of weeks), send the committer a polite reminder." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:116 +msgid "" +"Move contributed software to [.filename]#src/contrib# in the source tree." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:117 +msgid "Make sure code in [.filename]#src/contrib# is up to date." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:119 +msgid "" +"Build the source tree (or just part of it) with extra warnings enabled and " +"clean up the warnings. A list of build warnings can also be found from our " +"https://ci.freebsd.org[CI] by selecting a build and checking \"LLVM/Clang " +"Warnings\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:120 +msgid "" +"Fix warnings for ports which do deprecated things like using `gets()` or " +"including [.filename]#malloc.h#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:121 +msgid "" +"If you have contributed any ports and you had to make FreeBSD-specific " +"changes, send your patches back to the original authors (this will make your " +"life easier when they bring out the next version)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:126 +msgid "" +"Get copies of formal standards like POSIX(R). Compare FreeBSD's behavior to " +"that required by the standard. If the behavior differs, particularly in " +"subtle or obscure corners of the specification, send in a PR about it. If " +"you are able, figure out how to fix it and include a patch in the PR. If " +"you think the standard is wrong, ask the standards body to consider the " +"question." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:127 +msgid "Suggest further tasks for this list!" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:128 +#, no-wrap +msgid "Work through the PR Database" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:135 +msgid "" +"The https://bugs.FreeBSD.org/search/[FreeBSD PR list] shows all the current " +"active problem reports and requests for enhancement that have been submitted " +"by FreeBSD users. The PR database includes both programmer and non-" +"programmer tasks. Look through the open PRs, and see if anything there " +"takes your interest. Some of these might be very simple tasks that just " +"need an extra pair of eyes to look over them and confirm that the fix in the " +"PR is a good one. Others might be much more complex, or might not even have " +"a fix included at all." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:138 +msgid "" +"Start with the PRs that have not been assigned to anyone else. If a PR is " +"assigned to someone else, but it looks like something you can handle, email " +"the person it is assigned to and ask if you can work on it-they might " +"already have a patch ready to be tested, or further ideas that you can " +"discuss with them." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:139 +#, no-wrap +msgid "Ongoing Ports Tasks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:144 +msgid "" +"The Ports Collection is a perpetual work in progress. We want to provide " +"our users with an easy to use, up to date, high quality repository of third " +"party software. We need people to donate some of their time and effort to " +"help us achieve this goal." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:148 +msgid "" +"Anyone can get involved, and there are lots of different ways to do so. " +"Contributing to ports is an excellent way to help \"give back\" something to " +"the project. Whether you are looking for an ongoing role, or a fun " +"challenge for a rainy day, we would love to have your help!" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:150 +msgid "" +"There are a number of easy ways you can contribute to keeping the ports tree " +"up to date and in good working order:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:152 +msgid "" +"Find some cool or useful software and extref:{porters-handbook}[create a " +"port] for it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:154 +msgid "" +"There are a large number of ports that have no maintainer. Become a " +"maintainer and crossref:contributing[adopt-port, Adopting an unmaintained " +"port]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:155 +msgid "" +"If you have created or adopted a port, be aware of crossref:" +"contributing[maintain-port, The challenge for port maintainers]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:156 +msgid "" +"When you are looking for a quick challenge you could crossref:" +"contributing[fix-broken, Finding and fixing a broken port]." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:157 +#, no-wrap +msgid "Pick one of the items from the Ideas page" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:161 +msgid "" +"The https://wiki.freebsd.org/IdeasPage[FreeBSD list of projects and ideas " +"for volunteers] is also available for people willing to contribute to the " +"FreeBSD project. The list is being regularly updated and contains items for " +"both programmers and non-programmers with information about each project." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributing/_index.adoc:163 +#, no-wrap +msgid "How to Contribute" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:166 +msgid "" +"Contributions to the system generally fall into one or more of the following " +"5 categories:" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:168 +#, no-wrap +msgid "Bug Reports and General Commentary" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:173 +msgid "" +"An idea or suggestion of _general_ technical interest should be mailed to " +"the {freebsd-hackers}. Likewise, people with an interest in such things " +"(and a tolerance for a _high_ volume of mail!) may subscribe to the {freebsd-" +"hackers}. See extref:{handbook}[The FreeBSD Handbook, eresources-mail] for " +"more information about this and other mailing lists." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:176 +msgid "" +"If you are submitting a simple patch to the src repo, please consider " +"submitting it to the project's GitHub mirror as https://github.com/freebsd/" +"freebsd-src/pulls[a pull request]. Suitable submissions should:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:179 +msgid "" +"It is ready or nearly ready to be committed. A committer should be able to " +"land this patch with less than 10 minutes of additional work." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:180 +msgid "It passes all the GitHub CI jobs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:181 +msgid "You can respond to feedback quickly." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:183 +msgid "" +"It touches fewer than about 10 files and the changes are less than about 200 " +"lines. Changes larger than this may be OK, or you may be asked to submit " +"multiple pull requests of a more manageable size." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:185 +msgid "" +"Each logical change is a separate commit within the pull request. Commit " +"messages for each change should follow extref:{committers-guide}#commit-log-" +"message[commit log guide]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:187 +msgid "" +"All commits have your name and valid email address as you'd like to see them " +"in the FreeBSD repository as the author. Fake github.com addresses cannot " +"be used." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:189 +msgid "" +"The scope of the pull request should not change during review. If the " +"review suggests changes that expand the scope, please create an independent " +"pull request." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:191 +msgid "" +"Fixup commits should be squashed with the commit they are fixing. Each " +"commit in your branch should be suitable for FreeBSD's repository." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:192 +msgid "" +"Commits should include one or more `Signed-off-by:` lines with full name and " +"email address certifying https://developercertificate.org/[Developer " +"Certificate of Origin]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:197 +msgid "" +"When updating pull request, please rebase with a forced push rather than a " +"merge commit. More complex changes may be submitted as pull requests, but " +"they may be closed if they are too large, too unwieldy, become inactive, " +"need further discussion in the community, or need extensive revision. " +"Please avoid creating large, wide-ranging cleanup patches: they are too " +"large and lack the focus needed for a good review. Misdirected patches may " +"be redirected to a more appropriate forum for the patch to be resolved." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:201 +msgid "" +"Pull requests submitted to the ports repository may or may not see action, " +"based on the whims of developers. For now, you will have a better " +"experience if you follow the ports submission process crossref:" +"contributing[ports-contributing, Contributing to ports]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:203 +msgid "" +"The docs team also accepts pull requests via GitHub, but has not established " +"any policy for them yet." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:210 +msgid "" +"If you find a bug or are submitting a specific change, please report it " +"using the https://bugs.FreeBSD.org/submit/[bug submission form]. Try to " +"fill-in each field of the bug report. Unless they exceed 65KB, include any " +"patches directly in the report. If the patch is suitable to be applied to " +"the source tree put `[PATCH]` in the synopsis of the report. When including " +"patches, _do not_ use cut-and-paste because cut-and-paste turns tabs into " +"spaces and makes them unusable. When patches are a lot larger than 20KB, " +"consider compressing them (for example with man:gzip[1] or man:bzip2[1]) " +"prior to uploading them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:213 +msgid "" +"After filing a report, you should receive confirmation along with a tracking " +"number. Keep this tracking number so that you can update us with details " +"about the problem." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:215 +msgid "" +"See also extref:{problem-reports}[this article] on how to write good problem " +"reports." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:216 +#, no-wrap +msgid "Changes to the Documentation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:221 +msgid "" +"Changes to the documentation are overseen by the {freebsd-doc}. Please look " +"at the extref:{fdp-primer}[FreeBSD Documentation Project Primer] for " +"complete instructions. Send submissions and changes (even small ones are " +"welcome!) using the same method as any other bug report." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:222 +#, no-wrap +msgid "Changes to Existing Source Code" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:227 +msgid "" +"An addition or change to the existing source code is a somewhat trickier " +"affair and depends a lot on how far out of date you are with the current " +"state of FreeBSD development. There is a special on-going release of " +"FreeBSD known as \"FreeBSD-CURRENT\" which is made available in a variety of " +"ways for the convenience of developers working actively on the system. See " +"extref:{handbook}[The FreeBSD Handbook, current-stable] for more information " +"about getting and using FreeBSD-CURRENT." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:230 +msgid "" +"Working from older sources unfortunately means that your changes may " +"sometimes be too obsolete or too divergent for easy re-integration into " +"FreeBSD. Chances of this can be minimized somewhat by subscribing to the " +"{freebsd-announce} and the {freebsd-current} lists, where discussions on the " +"current state of the system take place." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:233 +msgid "" +"Assuming that you can manage to secure fairly up-to-date sources to base " +"your changes on, the next step is to produce a set of diffs to send to the " +"FreeBSD maintainers. This is done with the man:diff[1] command." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:235 +msgid "" +"The preferred man:diff[1] format for submitting patches is the unified " +"output format generated by `diff -u`." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/contributing/_index.adoc:239 +#, no-wrap +msgid "% diff -u oldfile newfile\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:242 +msgid "or" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/contributing/_index.adoc:246 +#, no-wrap +msgid "% diff -u -r -N olddir newdir\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:249 +msgid "" +"would generate a set of unified diffs for the given source file or directory " +"hierarchy." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:251 +msgid "See man:diff[1] for more information." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:255 +msgid "" +"Once you have a set of diffs (which you may test with the man:patch[1] " +"command), you should submit them for inclusion with FreeBSD as a bug " +"report. _Do not_ just send the diffs to the {freebsd-hackers} or they will " +"get lost! We greatly appreciate your submission (this is a volunteer " +"project!); because we are busy, we may not be able to address it " +"immediately, but it will remain in the PR database until we do. Indicate " +"your submission by including `[PATCH]` in the synopsis of the report." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:257 +msgid "" +"If you feel it appropriate (for example you have added, deleted, or renamed " +"files), bundle your changes into a `tar` file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:261 +msgid "" +"If your change is of a potentially sensitive nature, such as if you are " +"unsure of copyright issues governing its further distribution then you " +"should send it to {core-email} directly rather than submitting as a bug " +"report. The {core-email} reaches a much smaller group of people who do much " +"of the day-to-day work on FreeBSD. Note that this group is also _very busy_ " +"and so you should only send mail to them where it is truly necessary." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:264 +msgid "" +"Please refer to man:intro[9] and man:style[9] for some information on coding " +"style. We would appreciate it if you were at least aware of this " +"information before submitting code." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:265 +#, no-wrap +msgid "New Code or Major Value-Added Packages" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:269 +msgid "" +"In the case of a significant contribution of a large body work, or the " +"addition of an important new feature to FreeBSD, it becomes almost always " +"necessary to either send changes as tar files or upload them to a web or FTP " +"site for other people to access. If you do not have access to a web or FTP " +"site, ask on an appropriate FreeBSD mailing list for someone to host the " +"changes for you." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:274 +msgid "" +"When working with large amounts of code, the touchy subject of copyrights " +"also invariably comes up. FreeBSD prefers free software licenses such as " +"BSD or ISC. Copyleft licenses such as GPLv2 are sometimes permitted. The " +"complete listing can be found on the link:https://www.FreeBSD.org/internal/" +"software-license/[core team licensing policy] page." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:275 +#, no-wrap +msgid "Money or Hardware" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:279 +msgid "" +"We are always very happy to accept donations to further the cause of the " +"FreeBSD Project and, in a volunteer effort like ours, a little can go a long " +"way! Donations of hardware are also very important to expanding our list of " +"supported peripherals since we generally lack the funds to buy such items " +"ourselves." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/contributing/_index.adoc:281 +#, no-wrap +msgid "Donating Funds" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:286 +msgid "" +"The https://www.freebsdfoundation.org[FreeBSD Foundation] is a non-profit, " +"tax-exempt foundation established to further the goals of the FreeBSD " +"Project. As a 501(c)3 entity, the Foundation is generally exempt from US " +"federal income tax as well as Colorado State income tax. Donations to a tax-" +"exempt entity are often deductible from taxable federal income." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:288 +msgid "Donations may be sent in check form to:" +msgstr "" + +#. type: delimited block * 4 +#: documentation/content/en/articles/contributing/_index.adoc:296 +#, no-wrap +msgid "" +"The FreeBSD Foundation\n" +"3980 Broadway Street\n" +"STE #103-107\n" +"Boulder CO 80304\n" +"USA" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:299 +msgid "" +"The FreeBSD Foundation is also able to accept https://www.freebsdfoundation." +"org/donate/[online donations] through various payment options." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:302 +msgid "" +"More information about the FreeBSD Foundation can be found in https://people." +"FreeBSD.org/~jdp/foundation/announcement.html[The FreeBSD Foundation -- an " +"Introduction]. To contact the Foundation by email, write to mailto:" +"info@FreeBSDFoundation.org[info@FreeBSDFoundation.org]." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/contributing/_index.adoc:303 +#, no-wrap +msgid "Donating Hardware" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:307 +msgid "" +"The FreeBSD Project happily accepts donations of hardware that it can find " +"good use for. If you are interested in donating hardware, please contact " +"the link:https://www.FreeBSD.org/donations/[Donations Liaison Office]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributing/_index.adoc:309 +#, no-wrap +msgid "Contributing to ports" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:312 +#, no-wrap +msgid "Adopting an unmaintained port" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/contributing/_index.adoc:314 +#, no-wrap +msgid "Choosing an unmaintained port" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:320 +msgid "" +"Taking over maintainership of ports that are unmaintained is a great way to " +"get involved. Unmaintained ports are only updated and fixed when somebody " +"volunteers to work on them. There are a large number of unmaintained " +"ports. It is a good idea to start with adopting a port that you use " +"regularly." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:323 +msgid "" +"Unmaintained ports have their `MAINTAINER` set to `ports@FreeBSD.org`. Many " +"unmaintained ports can have pending updates, this can be seen at the https://" +"portscout.freebsd.org/ports@freebsd.org.html[FreeBSD Ports distfile scanner]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:325 +msgid "" +"On https://portsfallout.com/fallout?port=&maintainer=ports%40FreeBSD." +"org[PortsFallout] can be seen a list of unmaintained ports with errors." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:328 +msgid "" +"Some ports affect a large number of others due to dependencies and secondary " +"port relationships. Generally, we want people to have some experience " +"before they maintain such ports." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:332 +msgid "" +"You can find out whether or not a port has dependencies or secondary ports " +"by looking at a primary index of ports called [.filename]#INDEX#. (The name " +"of the file varies by release of FreeBSD; for instance, [." +"filename]#INDEX-13#.) Some ports have conditional dependencies that are not " +"included in a default [.filename]#INDEX# build. We expect you to be able to " +"recognize such ports by looking through other ports' [.filename]#Makefile#'s." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/contributing/_index.adoc:333 +#, no-wrap +msgid "How to adopt the port" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:338 +msgid "" +"First make sure you understand your crossref:contributing[maintain-port, The " +"challenge for port maintainers]. Also read the extref:{porters-handbook}" +"[Porter's Handbook]. _Please do not commit yourself to more than you feel " +"you can comfortably handle._" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:344 +msgid "" +"You may request maintainership of any unmaintained port as soon as you " +"wish. Simply set `MAINTAINER` to your own email address and send a PR " +"(Problem Report) with the change. If the port has build errors or needs " +"updating, you may wish to include any other changes in the same PR. This " +"will help because many committers are less willing to assign maintainership " +"to someone who does not have a known track record with FreeBSD. Submitting " +"PRs that fix build errors or update ports are the best ways to establish one." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:348 +msgid "" +"File your PR with Product `Ports & Packages`. A committer will examine your " +"PR, commit the changes, and finally close the PR. Sometimes this process " +"can take a little while (committers are volunteers, too :)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:350 +#, no-wrap +msgid "The challenge for port maintainers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:353 +msgid "" +"This section will give you an idea of why ports need to be maintained and " +"outline the responsibilities of a port maintainer." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/contributing/_index.adoc:355 +#, no-wrap +msgid "Why ports require maintenance" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:360 +msgid "" +"Creating a port is a once-off task. Ensuring that a port is up to date and " +"continues to build and run requires an ongoing maintenance effort. " +"Maintainers are the people who dedicate some of their time to meeting these " +"goals." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:363 +msgid "" +"The foremost reason ports need maintenance is to bring the latest and " +"greatest in third party software to the FreeBSD community. An additional " +"challenge is to keep individual ports working within the Ports Collection " +"framework as it evolves." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:365 +msgid "As a maintainer, you will need to manage the following challenges:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:367 +#, no-wrap +msgid "*New software versions and updates.* New versions and updates of existing ported software become available all the time, and these need to be incorporated into the Ports Collection to provide up-to-date software.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:369 +#, no-wrap +msgid "*Changes to dependencies.* If significant changes are made to the dependencies of your port, it may need to be updated so that it will continue to work correctly.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:371 +#, no-wrap +msgid "*Changes affecting dependent ports.* If other ports depend on a port that you maintain, changes to your port may require coordination with other maintainers.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:374 +#, no-wrap +msgid "" +"*Interaction with other users, maintainers and developers.* Part of being a maintainer is taking on a support role.\n" +"You are not expected to provide general support (but we welcome it if you choose to do so). What you should provide is a point of coordination for FreeBSD-specific issues regarding your ports.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:378 +#, no-wrap +msgid "" +"*Bug hunting.* A port may be affected by bugs which are specific to FreeBSD.\n" +"You will need to investigate, find, and fix these bugs when they are reported.\n" +"Thoroughly testing a port to identify problems before they make their way into the Ports Collection is even better.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:381 +#, no-wrap +msgid "" +"*Changes to ports infrastructure and policy.* Occasionally the systems that are used to build ports and packages are updated or a new recommendation affecting the infrastructure is made.\n" +"You should be aware of these changes in case your ports are affected and require updating.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:384 +#, no-wrap +msgid "" +"*Changes to the base system.* FreeBSD is under constant development.\n" +"Changes to software, libraries, the kernel or even policy changes can cause flow-on change requirements to ports.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/contributing/_index.adoc:385 +#, no-wrap +msgid "Maintainer responsibilities" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/contributing/_index.adoc:387 +#, no-wrap +msgid "Keep your ports up to date" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:390 +msgid "" +"This section outlines the process to follow to keep your ports up to date." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:393 +msgid "" +"This is an overview. More information about upgrading a port is available " +"in the extref:{porters-handbook}[Porter's Handbook]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:397 +msgid "Watch for updates" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:402 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:405 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:406 +msgid "Incorporate changes" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:409 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:410 +msgid "Review and test" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:412 +msgid "Thoroughly review and test your changes:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:415 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:418 +msgid "" +"Make sure your port's dependencies are complete. The recommended way of " +"doing this is by installing your own ports tinderbox. See crossref:" +"contributing[resources, Resources for ports maintainers and contributors] " +"for more information." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:420 +msgid "" +"Check that the packing list is up to date. This involves adding in any new " +"files and directories and removing unused entries." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:422 +msgid "" +"Verify your port using man:portlint[1] as a guide. See crossref:" +"contributing[resources, Resources for ports maintainers and contributors] " +"for important information about using portlint." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:425 +msgid "" +"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 package:ports-mgmt/poudriere[]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:427 +#: documentation/content/en/articles/contributing/_index.adoc:496 +msgid "Submit changes" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:430 +msgid "" +"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 extref:{problem-reports}[Writing FreeBSD Problem " +"Reports] for information on how to write a really good PR." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/contributing/_index.adoc:436 +msgid "" +"Please do not submit a man:shar[1] archive of the entire port; instead, use " +"man:git-format-patch[1] or man:diff[1] `-ruN`. In this way, committers can " +"much more easily see exactly what changes are being made. The Porter's " +"Handbook section on extref:{porters-handbook}[Upgrading, port-upgrading] has " +"more information." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:438 +msgid "Wait" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:442 +msgid "" +"At some stage a committer will deal with your PR. It may take minutes, or " +"it may take one or two weeks - so please be patient. If it takes any " +"longer, please seek for help on mailing lists ({freebsd-ports}), IRC: " +"#bsdports on EFNet or #freebsd-ports on Libera for example." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:443 +msgid "Give feedback" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:446 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:447 +msgid "And Finally" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:451 +msgid "" +"Your changes will be committed and your port will have been updated. The PR " +"will then be closed by the committer. That is it!" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/contributing/_index.adoc:453 +#, no-wrap +msgid "Ensure your ports continue to build correctly" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:456 +msgid "" +"This section is about discovering and fixing problems that stop your ports " +"from building correctly." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:459 +msgid "" +"FreeBSD only guarantees that the Ports Collection works on the `-STABLE` " +"branches. In theory, you should be able to get by with running the latest " +"release of each stable branch (since the ABIs are not supposed to change) " +"but if you can run the branch, that is even better." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:463 +msgid "" +"Since the majority of FreeBSD installations run on PC-compatible machines " +"(what is termed the `i386` architecture), we expect you to keep the port " +"working on that architecture. We prefer that ports also work on the `amd64` " +"architecture running native. It is completely fair to ask for help if you " +"do not have one of these machines." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:468 +msgid "" +"The usual failure modes for non-`x86` machines are that the original " +"programmers assumed that, for instance, pointers are `int`-s, or that a " +"relatively lax older gcc compiler was being used. More and more, " +"application authors are reworking their code to remove these assumptions - " +"but if the author is not actively maintaining their code, you may need to do " +"this yourself." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:471 +msgid "" +"These are the tasks you need to perform to ensure your port is able to be " +"built:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:475 +msgid "Watch for build failures" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:477 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:478 +#: documentation/content/en/articles/contributing/_index.adoc:527 +msgid "Collect information" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:482 +msgid "" +"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:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:484 +msgid "Build logs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:485 +msgid "" +"The commands and options used to build the port (including options set in [." +"filename]#/etc/make.conf#)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:486 +msgid "" +"A list of packages installed on their system as shown by man:pkg-info[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:487 +msgid "The version of FreeBSD they are running as shown by man:uname[1] `-a`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:488 +msgid "When their ports collection was last updated" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:489 +msgid "When their ports tree and [.filename]#INDEX# was last updated" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:491 +msgid "Investigate and find a solution" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:495 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:498 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:499 +msgid "Send patches to upstream authors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:504 +msgid "" +"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. " +"Please consider sending any applicable patches to the authors as a courtesy." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/contributing/_index.adoc:506 +#, no-wrap +msgid "Investigate bug reports and PRs related to your port" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:509 +msgid "This section is about discovering and fixing bugs." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:512 +msgid "" +"FreeBSD-specific bugs are generally caused by assumptions about the build " +"and runtime environments that do not apply to FreeBSD. You are less likely " +"to encounter a problem of this type, but it can be more subtle and difficult " +"to diagnose." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:514 +msgid "" +"These are the tasks you need to perform to ensure your port continues to " +"work as intended:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:518 +msgid "Respond to bug reports" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:521 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:524 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:526 +msgid "" +"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`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:529 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:532 +msgid "" +"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:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:534 +msgid "" +"A detailed description of their actions, expected program behavior and " +"actual behavior" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:535 +msgid "Copies of input data used to trigger the bug" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:536 +msgid "" +"Information about their build and execution environment - for example, a " +"list of installed packages and the output of man:env[1]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:537 +msgid "Core dumps" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:538 +msgid "Stack traces" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:540 +msgid "Eliminate incorrect reports" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:546 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:547 +msgid "Find a solution" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:550 +msgid "" +"As with build errors, you will need to sort out a fix to the problem. " +"Again, remember to ask if you are stuck!" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:551 +msgid "Submit or approve changes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributing/_index.adoc:554 +msgid "" +"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." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/contributing/_index.adoc:556 +#, no-wrap +msgid "Providing support" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:561 +msgid "" +"Part of being a maintainer is providing support - not for the software in " +"general - but for the port and any FreeBSD-specific quirks and problems. " +"Users may contact you with questions, suggestions, problems and patches. " +"Most of the time their correspondence will be specific to FreeBSD." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:565 +msgid "" +"Occasionally you may have to invoke your skills in diplomacy, and kindly " +"point users seeking general support to the appropriate resources. Less " +"frequently you will encounter a person asking why the `RPMS` are not up to " +"date or how can they get the software to run under Foo Linux. Take the " +"opportunity to tell them that your port is up to date (if it is, of " +"course!), and suggest that they try FreeBSD." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:568 +msgid "" +"Sometimes users and developers will decide that you are a busy person whose " +"time is valuable and do some of the work for you. For example, they might:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:570 +msgid "submit a PR or send you patches to update your port," +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:571 +msgid "investigate and perhaps provide a fix to a PR, or" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:572 +msgid "otherwise submit changes to your port." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:578 +msgid "" +"In these cases your main obligation is to respond in a timely manner. " +"Again, the timeout for non-responsive maintainers is 14 days. After this " +"period changes may be committed unapproved. They have taken the trouble to " +"do this for you; so please try to at least respond promptly. Then review, " +"approve, modify or discuss their changes with them as soon as possible." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:580 +msgid "" +"If you can make them feel that their contribution is appreciated (and it " +"should be) you will have a better chance persuading them to do more things " +"for you in the future :-)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:582 +#, no-wrap +msgid "Finding and fixing a broken port" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:585 +msgid "" +"There are some really good places to find a port that needs some attention." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:588 +msgid "" +"You can use the https://bugs.freebsd.org/search[web interface] to the " +"Problem Report database to search through and view unresolved PRs. The " +"majority of ports PRs are updates, but with a little searching and skimming " +"over synopses you should be able to find something interesting to work on." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:590 +msgid "" +"https://portsfallout.com/[PortsFallout] shows port issues gathered from the " +"FreeBSD package building." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:592 +msgid "" +"It is OK to send changes for a maintained port as well, but remember to ask " +"the maintainer in case they are already working on the problem." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:597 +msgid "" +"Once you have found a bug or problem, collect information, investigate and " +"fix! If there is an existing PR, follow up to that. Otherwise create a new " +"PR. Your changes will be reviewed and, if everything checks out, committed." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:599 +#, no-wrap +msgid "When to call it quits" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:606 +msgid "" +"As your interests and commitments change, you may find that you no longer " +"have time to continue some (or all) of your ports contributions. That is " +"fine! Please let us know if you are no longer using a port or have otherwise " +"lost time or interest in being a maintainer. In this way we can go ahead " +"and allow other people to try to work on existing problems with the port " +"without waiting for your response. Remember, FreeBSD is a volunteer " +"project, so if maintaining a port is no fun any more, it is probably time to " +"let someone else do it!" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:610 +msgid "" +"In any case, the Ports Management Team (`portmgr`) reserves the right to " +"reset your maintainership if you have not actively maintained your port in " +"some time. (Currently, this is set to 3 months.) By this, we mean that " +"there are unresolved problems or pending updates that have not been worked " +"on during that time." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributing/_index.adoc:612 +#, no-wrap +msgid "Resources for ports maintainers and contributors" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:616 +msgid "" +"The extref:{porters-handbook}[Porter's Handbook] is your hitchhiker's guide " +"to the ports system. Keep it handy!" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:620 +msgid "" +"extref:{problem-reports}[Writing FreeBSD Problem Reports] describes how to " +"best formulate and submit a PR. In 2005 more than eleven thousand ports PRs " +"were submitted! Following this article will greatly assist us in reducing " +"the time needed to handle your PRs." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:622 +msgid "" +"The https://bugs.freebsd.org/bugzilla/query.cgi[Problem Report database]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:625 +msgid "" +"The http://portscout.FreeBSD.org[FreeBSD Ports distfile scanner (portscout)] " +"can show you ports for which the distfiles are not fetchable. You can check " +"on your own ports or use it to find ports that need their `MASTER_SITES` " +"updated." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:628 +msgid "" +"package:ports-mgmt/poudriere[] is the most thorough way to test a port " +"through the entire cycle of installation, packaging, and deinstallation. " +"Documentation is located at the https://github.com/freebsd/" +"poudriere[poudriere GitHub repository]" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:632 +msgid "" +"man:portlint[1] is an application which can be used to verify that your port " +"conforms to many important stylistic and functional guidelines. portlint is " +"a simple heuristic application, so you should use it __only as a guide__. " +"If portlint suggests changes which seem unreasonable, consult the extref:" +"{porters-handbook}[Porter's Handbook] or ask for advice." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:637 +msgid "" +"The {freebsd-ports} is for general ports-related discussion. It is a good " +"place to ask for help. You can link:https://lists.freebsd.org/[subscribe, " +"or read and search the list archives]. Reading the archives of the {freebsd-" +"ports-bugs} and the {svn-ports-head} may also be of interest." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:639 +msgid "" +"https://portsfallout.com/[PortsFallout] is a place to help in searching for " +"the https://lists.freebsd.org/archives/freebsd-pkg-fallout/[FreeBSD package-" +"fallout archive]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributing/_index.adoc:641 +#, no-wrap +msgid "Getting Started in Other Areas" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:645 +msgid "" +"Looking for something interesting to get started that is not mentioned " +"elsewhere in this article? The FreeBSD Project has several Wiki pages " +"containing areas within which new contributors can get ideas on how to get " +"started." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:647 +msgid "" +"The https://wiki.freebsd.org/JuniorJobs[Junior Jobs] page has a list of " +"projects that might be of interest to people just getting started in " +"FreeBSD, and want to work on interesting things to get their feet wet." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributing/_index.adoc:648 +msgid "" +"The https://wiki.freebsd.org/IdeasPage[Ideas Page] contains various \"nice " +"to have\" or \"interesting\" things to work on in the Project." +msgstr "" diff --git a/documentation/content/en/articles/contributors/_index.adoc b/documentation/content/en/articles/contributors/_index.adoc index fcedd93ebd..0937c40586 100644 --- a/documentation/content/en/articles/contributors/_index.adoc +++ b/documentation/content/en/articles/contributors/_index.adoc @@ -61,84 +61,18 @@ endif::[] Abstract This article lists individuals and organizations who have made a contribution to FreeBSD. +To see the current list of FreeBSD Committers you can take a look at the +following crossref:contributors[staff-committers, list]. ''' toc::[] -[[donors]] -== Donors Gallery - -[NOTE] -==== -As of 2010, the following section is several years out-of-date. Donations from the past several years appear https://www.FreeBSD.org/donations/donors/[here]. -==== - -The FreeBSD Project is indebted to the following donors and would like to publicly thank them here! - -* _Contributors to the central server project:_ -+ -The following individuals and businesses made it possible for the FreeBSD Project to build a new central server machine, which has replaced `freefall.FreeBSD.org` at one point, by donating the following items: - -** {mbarkah} and his employer, http://www.hemi.com/[ Hemisphere Online], donated a _Pentium Pro (P6) 200MHz CPU_ -** http://www.asacomputers.com/[ASA Computers] donated a _Tyan 1662 motherboard_. -** Joe McGuckin mailto:joe@via.net[joe@via.net] of http://www.via.net/[ViaNet Communications] donated a _Kingston ethernet controller._ -** Jack O'Neill mailto:jack@diamond.xtalwind.net[jack@diamond.xtalwind.net] donated an _NCR 53C875 SCSI controller card_. -** 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] -** {dillon} -** http://www.bluemountain.com/[Blue Mountain Arts] -** http://www.epilogue.com/[Epilogue Technology Corporation] -** {sef} -** http://www.gta.com/[Global Technology Associates, Inc] -** Don Scott Wilde -** Gianmarco Giovannelli mailto:gmarco@masternet.it[gmarco@masternet.it] -** Josef C. Grosch mailto:joeg@truenorth.org[joeg@truenorth.org] -** Robert T. Morris -** {chuckr} -** Kenneth P. Stox mailto:ken@stox.sa.enteract.com[ken@stox.sa.enteract.com] of http://www.imagescape.com/[Imaginary Landscape, LLC.] -** Dmitry S. Kohmanyuk mailto:dk@dog.farm.org[dk@dog.farm.org] -** http://www.cdrom.co.jp/[Laser5] of Japan (a portion of the profits from sales of their various FreeBSD CDROMs). -** http://www.mmjp.or.jp/fuki/[Fuki Shuppan Publishing Co.] donated a portion of their profits from _Hajimete no FreeBSD_ (FreeBSD, Getting started) to the FreeBSD and XFree86 projects. -** http://www.ascii.co.jp/[ASCII Corp.] donated a portion of their profits from several FreeBSD-related books to the FreeBSD project. -** http://www.yokogawa.co.jp/[Yokogawa Electric Corp] has generously donated significant funding to the FreeBSD project. -** http://www.buffnet.net/[BuffNET] -** http://www.pacificsolutions.com/[Pacific Solutions] -** http://www.siemens.de/[Siemens AG] via Andre Albsmeier mailto:andre.albsmeier@mchp.siemens.de[andre.albsmeier@mchp.siemens.de] -** 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. -** http://www.compaq.com[Compaq] has donated a variety of Alpha systems to the FreeBSD Project. Among the many generous donations are 4 AlphaStation DS10s, an AlphaServer DS20, AlphaServer 2100s, an AlphaServer 4100, 8 500Mhz Personal Workstations, 4 433Mhz Personal Workstations, and more! These machines are used for release engineering, package building, SMP development, and general development on the Alpha architecture. -** TRW Financial Systems, Inc. provided 130 PCs, three 68 GB file servers, twelve Ethernets, two routers and an ATM switch for debugging the diskless code. -** Dermot McDonnell donated the Toshiba XM3401B CDROM drive currently used in freefall. -** Chuck Robey mailto:chuckr@glue.umd.edu[chuckr@glue.umd.edu] contributed his floppy tape streamer for experimental work. -** Larry Altneu mailto:larry@ALR.COM[larry@ALR.COM], and {wilko}, provided Wangtek and Archive QIC-02 tape drives in order to improve the [.filename]#wt# driver. -** Ernst Winter (http://berklix.org/ewinter/[Deceased]) contributed a 2.88 MB floppy drive to the project. This will hopefully increase the pressure for rewriting the floppy disk driver. -** http://www.tekram.com/[Tekram Technologies] sent one each of their DC-390, DC-390U and DC-390F FAST and ULTRA SCSI host adapter cards for regression testing of the NCR and AMD drivers with their cards. They are also to be applauded for making driver sources for free operating systems available from their FTP server link:ftp://ftp.tekram.com/scsi/FreeBSD/[ftp://ftp.tekram.com/scsi/FreeBSD/]. -** Larry M. Augustin contributed not only a Symbios Sym8751S SCSI card, but also a set of data books, including one about the forthcoming Sym53c895 chip with Ultra-2 and LVD support, and the latest programming manual with information on how to safely use the advanced features of the latest Symbios SCSI chips. Thanks a lot! -** {kuku} donated an FX120 12 speed Mitsumi CDROM drive for IDE CDROM driver development. -** Mike Tancsa mailto:mike@sentex.ca[mike@sentex.ca] donated four various ATM PCI cards in order to help increase support of these cards as well as help support the development effort of the netatm ATM stack. - -* _Special contributors:_ - -** http://www.osd.bsdi.com/[BSDi] (formerly Walnut Creek CDROM) has donated almost more than we can say (see the 'About the FreeBSD Project' section of the extref:{handbook}[FreeBSD Handbook] for more details). In particular, we would like to thank them for the original hardware used for `freefall.FreeBSD.org`, our primary development machine, and for `thud.FreeBSD.org`, a testing and build box. We are also indebted to them for funding various contributors over the years and providing us with unrestricted use of their T1 connection to the Internet. -** The http://www.interface-business.de/[interface business GmbH, Dresden] has been patiently supporting {joerg} who has often preferred FreeBSD work over paid work, and used to fall back to their (quite expensive) EUnet Internet connection whenever his private connection became too slow or flaky to work with it... -** http://www.bsdi.com/[Berkeley Software Design, Inc.] has contributed their DOS emulator code to the remaining BSD world, which is used in the _doscmd_ command. - [[staff-committers]] == The FreeBSD Developers -These are the people who have commit privileges and do the engineering work on the FreeBSD source tree. -All core team members are also developers. +This list, which includes all members of the Core Team, names everyone who has commit privileges for one or more of the three source trees (doc, ports and src). +To see the current Core Team members you can take a look at the link:https://www.freebsd.org/administration/#t-core[administration page]. (in alphabetical order by last name): @@ -205,3 +139,75 @@ include::{include-contrib-additional}[] (in alphabetical order by first name): include::{include-contrib-386bsd}[] + +[[donors]] +== Donors Gallery + +The FreeBSD Foundation thanks https://freebsdfoundation.org/our-donors/donors/[financial and in-kind donors]. + +The https://www.freebsd.org/donations/[FreeBSD Donations Liaison] area includes a https://www.freebsd.org/donations/donors/[list of donated hardware]. + +The FreeBSD Project thanks all donors! + +[NOTE] +==== +As of 2010, the section below was several years out-of-date. +==== + +=== Contributors to the central server project + +The following individuals and businesses made it possible for the FreeBSD Project to build a new central server machine, which has replaced `freefall.FreeBSD.org` at one point, by donating the following items: + +* {mbarkah} and his employer, http://www.hemi.com/[Hemisphere Online], donated a _Pentium Pro (P6) 200MHz CPU_. +* http://www.asacomputers.com/[ASA Computers] donated a _Tyan 1662 motherboard_. +* Joe McGuckin <mailto:joe@via.net[joe@via.net]> of http://www.via.net/[ViaNet Communications] donated a _Kingston ethernet controller_. +* Jack O'Neill <mailto:jack@diamond.xtalwind.net[jack@diamond.xtalwind.net]> donated an _NCR 53C875 SCSI controller card_. +* 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]>. +* {dillon}. +* http://www.bluemountain.com/[Blue Mountain Arts]. +* http://www.epilogue.com/[Epilogue Technology Corporation]. +* {sef}. +* http://www.gta.com/[Global Technology Associates, Inc]. +* Don Scott Wilde. +* Gianmarco Giovannelli <mailto:gmarco@masternet.it[gmarco@masternet.it]>. +* Josef C. Grosch <mailto:joeg@truenorth.org[joeg@truenorth.org]>. +* Robert T. Morris. +* {chuckr}. +* Kenneth P. Stox <mailto:ken@stox.sa.enteract.com[ken@stox.sa.enteract.com]> of http://www.imagescape.com/[Imaginary Landscape, LLC.]. +* Dmitry S. Kohmanyuk <mailto:dk@dog.farm.org[dk@dog.farm.org]>. +* http://www.cdrom.co.jp/[Laser5] of Japan (a portion of the profits from sales of their various FreeBSD CDROMs). +* http://www.mmjp.or.jp/fuki/[Fuki Shuppan Publishing Co.] donated a portion of their profits from _Hajimete no FreeBSD_ (FreeBSD, Getting started) to the FreeBSD and XFree86 projects. +* http://www.ascii.co.jp/[ASCII Corp.] donated a portion of their profits from several FreeBSD-related books to the FreeBSD project. +* http://www.yokogawa.co.jp/[Yokogawa Electric Corp] has generously donated significant funding to the FreeBSD project. +* http://www.buffnet.net/[BuffNET]. +* http://www.pacificsolutions.com/[Pacific Solutions]. +* http://www.siemens.de/[Siemens AG] via Andre Albsmeier <mailto:andre.albsmeier@mchp.siemens.de[andre.albsmeier@mchp.siemens.de]>. +* 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. +* http://www.compaq.com[Compaq] has donated a variety of Alpha systems to the FreeBSD Project. Among the many generous donations are 4 AlphaStation DS10s, an AlphaServer DS20, AlphaServer 2100s, an AlphaServer 4100, 8 500Mhz Personal Workstations, 4 433Mhz Personal Workstations, and more! These machines are used for release engineering, package building, SMP development, and general development on the Alpha architecture. +* TRW Financial Systems, Inc. provided 130 PCs, three 68 GB file servers, twelve Ethernets, two routers and an ATM switch for debugging the diskless code +* Dermot McDonnell donated the Toshiba XM3401B CDROM drive currently used in _freefall_. +* Chuck Robey <mailto:chuckr@glue.umd.edu[chuckr@glue.umd.edu]> contributed his floppy tape streamer for experimental work. +* Larry Altneu <mailto:larry@alr.com[larry@alr.com],> and {wilko}, provided Wangtek and Archive QIC-02 tape drives to improve the [.filename]#wt# driver. +* Ernst Winter (http://berklix.org/ewinter/[Deceased]) contributed a 2.88 MB floppy drive to the project. This will hopefully increase the pressure for rewriting the floppy disk driver. +* http://www.tekram.com/[Tekram Technologies] sent one each of their DC-390, DC-390U and DC-390F FAST and ULTRA SCSI host adapter cards for regression testing of the NCR and AMD drivers with their cards. They are also to be applauded for making driver sources for free operating systems available from their FTP server link:ftp://ftp.tekram.com/scsi/FreeBSD/[ftp://ftp.tekram.com/scsi/FreeBSD/]. +* Larry M. Augustin contributed not only a Symbios Sym8751S SCSI card, but also a set of data books, including one about the forthcoming Sym53c895 chip with Ultra-2 and LVD support, and the latest programming manual with information on how to safely use the advanced features of the latest Symbios SCSI chips. Thanks a lot! +* {kuku} donated an FX120 12 speed Mitsumi CDROM drive for IDE CDROM driver development. +* Mike Tancsa <mailto:mike@sentex.ca[mike@sentex.ca]> donated four various ATM PCI cards to help increase support of these cards as well as help support the development effort of the netatm ATM stack. + +=== Special contributors + +* http://www.osd.bsdi.com/[BSDi] (formerly Walnut Creek CDROM) has donated almost more than we can say (see the 'About the FreeBSD Project' section of the extref:{handbook}[FreeBSD Handbook] for more details). In particular, we would like to thank them for the original hardware used for `freefall.FreeBSD.org`, our primary development machine, and for `thud.FreeBSD.org`, a testing and build box. We are also indebted to them for funding various contributors over the years and providing us with unrestricted use of their T1 connection to the Internet. +* The http://www.interface-business.de/[interface business GmbH, Dresden] has been patiently supporting {joerg} who has often preferred FreeBSD work over paid work, and used to fall back to their (quite expensive) EUnet Internet connection whenever his private connection became too slow or flaky to work with it. +* http://www.bsdi.com/[Berkeley Software Design, Inc.] has contributed their DOS emulator code to the remaining BSD world, which is used in the `doscmd` command. diff --git a/documentation/content/en/articles/contributors/_index.po b/documentation/content/en/articles/contributors/_index.po new file mode 100644 index 0000000000..7d20f87a65 --- /dev/null +++ b/documentation/content/en/articles/contributors/_index.po @@ -0,0 +1,535 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-09-14 14:59-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/contributors/_index.adoc:1 +#, no-wrap +msgid "A list of organizations and individuals who have contributed to FreeBSD" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/contributors/_index.adoc:1 +#: documentation/content/en/articles/contributors/_index.adoc:8 +#, no-wrap +msgid "Contributors to FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:62 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:66 +msgid "" +"This article lists individuals and organizations who have made a " +"contribution to FreeBSD. To see the current list of FreeBSD Committers you " +"can take a look at the following crossref:contributors[staff-committers, " +"list]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:68 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributors/_index.adoc:72 +#, no-wrap +msgid "The FreeBSD Developers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:76 +msgid "" +"This list, which includes all members of the Core Team, names everyone who " +"has commit privileges for one or more of the three source trees (doc, ports " +"and src). To see the current Core Team members you can take a look at the " +"link:https://www.freebsd.org/administration/#t-core[administration page]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:78 +msgid "(in alphabetical order by last name):" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributors/_index.adoc:82 +#, no-wrap +msgid "Core Team Alumni" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:86 +msgid "" +"The following people were members of the FreeBSD core team during the " +"periods indicated. We thank them for their past efforts in the service of " +"the FreeBSD project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:88 +#: documentation/content/en/articles/contributors/_index.adoc:98 +#: documentation/content/en/articles/contributors/_index.adoc:108 +msgid "_In rough reverse chronological order:_" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributors/_index.adoc:92 +#, no-wrap +msgid "Development Team Alumni" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:96 +msgid "" +"The following people were members of the FreeBSD development team during the " +"periods indicated. We thank them for their past efforts in the service of " +"the FreeBSD project." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributors/_index.adoc:102 +#, no-wrap +msgid "Ports Management Team Alumni" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:106 +msgid "" +"The following people were members of the FreeBSD portmgr team during the " +"periods indicated. We thank them for their past efforts in the service of " +"the FreeBSD project." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributors/_index.adoc:112 +#, no-wrap +msgid "Development Team: In Memoriam" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:116 +msgid "" +"During the many years that the FreeBSD Project has been in existence, sadly, " +"some of our developers have passed away. Here are some remembrances." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:118 +msgid "_In rough reverse chronological order of their passing:_" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributors/_index.adoc:122 +#, no-wrap +msgid "Derived Software Contributors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:126 +msgid "" +"This software was originally derived from William F. Jolitz's 386BSD release " +"0.1, though almost none of the original 386BSD specific code remains. This " +"software has been essentially re-implemented from the 4.4BSD-Lite release " +"provided by the Computer Science Research Group (CSRG) at the University of " +"California, Berkeley and associated academic contributors." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:128 +msgid "" +"There are also portions of NetBSD and OpenBSD that have been integrated into " +"FreeBSD as well, and we would therefore like to thank all the contributors " +"to NetBSD and OpenBSD for their work." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributors/_index.adoc:130 +#, no-wrap +msgid "Additional FreeBSD Contributors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:133 +#: documentation/content/en/articles/contributors/_index.adoc:140 +msgid "(in alphabetical order by first name):" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributors/_index.adoc:137 +#, no-wrap +msgid "386BSD Patch Kit Patch Contributors" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/contributors/_index.adoc:144 +#, no-wrap +msgid "Donors Gallery" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:147 +msgid "" +"The FreeBSD Foundation thanks https://freebsdfoundation.org/our-donors/" +"donors/[financial and in-kind donors]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:149 +msgid "" +"The https://www.freebsd.org/donations/[FreeBSD Donations Liaison] area " +"includes a https://www.freebsd.org/donations/donors/[list of donated " +"hardware]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:151 +msgid "The FreeBSD Project thanks all donors!" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/contributors/_index.adoc:155 +msgid "As of 2010, the section below was several years out-of-date." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributors/_index.adoc:157 +#, no-wrap +msgid "Contributors to the central server project" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:160 +msgid "" +"The following individuals and businesses made it possible for the FreeBSD " +"Project to build a new central server machine, which has replaced `freefall." +"FreeBSD.org` at one point, by donating the following items:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:162 +msgid "" +"{mbarkah} and his employer, http://www.hemi.com/[Hemisphere Online], donated " +"a _Pentium Pro (P6) 200MHz CPU_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:163 +msgid "" +"http://www.asacomputers.com/[ASA Computers] donated a _Tyan 1662 " +"motherboard_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:164 +msgid "" +"Joe McGuckin <mailto:joe@via.net[joe@via.net]> of http://www.via.net/[ViaNet " +"Communications] donated a _Kingston ethernet controller_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:165 +msgid "" +"Jack O'Neill <mailto:jack@diamond.xtalwind.net[jack@diamond.xtalwind.net]> " +"donated an _NCR 53C875 SCSI controller card_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:166 +msgid "" +"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_." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributors/_index.adoc:167 +#, no-wrap +msgid "Direct funding" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:170 +msgid "" +"The following individuals and businesses have generously contributed direct " +"funding to the project:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:172 +msgid "" +"Annelise Anderson <mailto:andrsn@hoover.stanford.edu[andrsn@hoover.stanford." +"edu]>." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:173 +msgid "{dillon}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:174 +msgid "http://www.bluemountain.com/[Blue Mountain Arts]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:175 +msgid "http://www.epilogue.com/[Epilogue Technology Corporation]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:176 +msgid "{sef}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:177 +msgid "http://www.gta.com/[Global Technology Associates, Inc]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:178 +msgid "Don Scott Wilde." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:179 +msgid "" +"Gianmarco Giovannelli <mailto:gmarco@masternet.it[gmarco@masternet.it]>." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:180 +msgid "Josef C. Grosch <mailto:joeg@truenorth.org[joeg@truenorth.org]>." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:181 +msgid "Robert T. Morris." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:182 +msgid "{chuckr}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:183 +msgid "" +"Kenneth P. Stox <mailto:ken@stox.sa.enteract.com[ken@stox.sa.enteract.com]> " +"of http://www.imagescape.com/[Imaginary Landscape, LLC.]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:184 +msgid "Dmitry S. Kohmanyuk <mailto:dk@dog.farm.org[dk@dog.farm.org]>." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:185 +msgid "" +"http://www.cdrom.co.jp/[Laser5] of Japan (a portion of the profits from " +"sales of their various FreeBSD CDROMs)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:186 +msgid "" +"http://www.mmjp.or.jp/fuki/[Fuki Shuppan Publishing Co.] donated a portion " +"of their profits from _Hajimete no FreeBSD_ (FreeBSD, Getting started) to " +"the FreeBSD and XFree86 projects." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:187 +msgid "" +"http://www.ascii.co.jp/[ASCII Corp.] donated a portion of their profits from " +"several FreeBSD-related books to the FreeBSD project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:188 +msgid "" +"http://www.yokogawa.co.jp/[Yokogawa Electric Corp] has generously donated " +"significant funding to the FreeBSD project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:189 +msgid "http://www.buffnet.net/[BuffNET]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:190 +msgid "http://www.pacificsolutions.com/[Pacific Solutions]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:191 +msgid "" +"http://www.siemens.de/[Siemens AG] via Andre Albsmeier <mailto:andre." +"albsmeier@mchp.siemens.de[andre.albsmeier@mchp.siemens.de]>." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:192 +msgid "Chris Silva <mailto:ras@interaccess.com[ras@interaccess.com]>." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributors/_index.adoc:193 +#, no-wrap +msgid "Hardware contributors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:196 +msgid "" +"The following individuals and businesses have generously contributed " +"hardware for testing and device driver development/support:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:198 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:199 +msgid "" +"http://www.compaq.com[Compaq] has donated a variety of Alpha systems to the " +"FreeBSD Project. Among the many generous donations are 4 AlphaStation DS10s, " +"an AlphaServer DS20, AlphaServer 2100s, an AlphaServer 4100, 8 500Mhz " +"Personal Workstations, 4 433Mhz Personal Workstations, and more! These " +"machines are used for release engineering, package building, SMP " +"development, and general development on the Alpha architecture." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:200 +msgid "" +"TRW Financial Systems, Inc. provided 130 PCs, three 68 GB file servers, " +"twelve Ethernets, two routers and an ATM switch for debugging the diskless " +"code" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:201 +msgid "" +"Dermot McDonnell donated the Toshiba XM3401B CDROM drive currently used in " +"_freefall_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:202 +msgid "" +"Chuck Robey <mailto:chuckr@glue.umd.edu[chuckr@glue.umd.edu]> contributed " +"his floppy tape streamer for experimental work." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:203 +msgid "" +"Larry Altneu <mailto:larry@alr.com[larry@alr.com],> and {wilko}, provided " +"Wangtek and Archive QIC-02 tape drives to improve the [.filename]#wt# driver." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:204 +msgid "" +"Ernst Winter (http://berklix.org/ewinter/[Deceased]) contributed a 2.88 MB " +"floppy drive to the project. This will hopefully increase the pressure for " +"rewriting the floppy disk driver." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:205 +msgid "" +"http://www.tekram.com/[Tekram Technologies] sent one each of their DC-390, " +"DC-390U and DC-390F FAST and ULTRA SCSI host adapter cards for regression " +"testing of the NCR and AMD drivers with their cards. They are also to be " +"applauded for making driver sources for free operating systems available " +"from their FTP server link:ftp://ftp.tekram.com/scsi/FreeBSD/[ftp://ftp." +"tekram.com/scsi/FreeBSD/]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:206 +msgid "" +"Larry M. Augustin contributed not only a Symbios Sym8751S SCSI card, but " +"also a set of data books, including one about the forthcoming Sym53c895 chip " +"with Ultra-2 and LVD support, and the latest programming manual with " +"information on how to safely use the advanced features of the latest Symbios " +"SCSI chips. Thanks a lot!" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:207 +msgid "" +"{kuku} donated an FX120 12 speed Mitsumi CDROM drive for IDE CDROM driver " +"development." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:208 +msgid "" +"Mike Tancsa <mailto:mike@sentex.ca[mike@sentex.ca]> donated four various ATM " +"PCI cards to help increase support of these cards as well as help support " +"the development effort of the netatm ATM stack." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/contributors/_index.adoc:209 +#, no-wrap +msgid "Special contributors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:212 +msgid "" +"http://www.osd.bsdi.com/[BSDi] (formerly Walnut Creek CDROM) has donated " +"almost more than we can say (see the 'About the FreeBSD Project' section of " +"the extref:{handbook}[FreeBSD Handbook] for more details). In particular, we " +"would like to thank them for the original hardware used for `freefall." +"FreeBSD.org`, our primary development machine, and for `thud.FreeBSD.org`, a " +"testing and build box. We are also indebted to them for funding various " +"contributors over the years and providing us with unrestricted use of their " +"T1 connection to the Internet." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:213 +msgid "" +"The http://www.interface-business.de/[interface business GmbH, Dresden] has " +"been patiently supporting {joerg} who has often preferred FreeBSD work over " +"paid work, and used to fall back to their (quite expensive) EUnet Internet " +"connection whenever his private connection became too slow or flaky to work " +"with it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/_index.adoc:213 +msgid "" +"http://www.bsdi.com/[Berkeley Software Design, Inc.] has contributed their " +"DOS emulator code to the remaining BSD world, which is used in the `doscmd` " +"command." +msgstr "" diff --git a/documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc b/documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc index 8234751115..bd0863552c 100644 --- a/documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc +++ b/documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc @@ -1,4 +1,43 @@ - +* Mike Karels (2016 - 2024; RIP 2024) ++ +Mike Karels, originally a microbiology Ph.D. degree candidate at University of California Berkeley (UCB), expressed interest in computers in a nearby lab which led him to change his entire career path. +He eventually became involved in the Computer Systems Research Group (CSRG) at UCB in the early 1980's. +Once there, his contributions were instrumental in the development and improvement of the BSD Unix TCP/UDP/IP implementation, including the socket interface API, one of the most widely used application programming interfaces in the history of the Internet. ++ +Over the next several years, he continued to help prepare the Berkeley Software Distribution releases for 4.3BSD, 4.3BSD-Tahoe, 4.3BSD-Reno, Networking Release 1, and Networking Release 2. +During this time, he was one of the authors of "The Design and Implementation of the 4.3BSD Unix Operating System", an important book in the field of computers and operating systems, published in 1989. ++ +After leaving the CSRG, he was a founding member of BSD Incorporated (BSDi), one of the earliest purveyors of BSD Unix software in source and binary forms. +Mike held steady through multiple organizational changes across Walnut Creek CDROM, Wind River Systems, Secure Computing, McAfee, Intel Security, and Forcepoint. ++ +In 1994, on the occasion of the 25th anniversary of Unix, the USENIX Association honored Mike with inclusion in the Unix Deck of Cards, a set of playing cards with the faces of pioneers in the early Unix +community. +He is the Seven of Spades. ++ +He also became involved with the FreeBSD Project and contributed greatly to it over the years including additions to the sysctl subsystem, and the Mandatory Access Control (MAC) framework, eventually earning a src commit bit. +After his retirement, he stepped up to help with the release engineering of FreeBSD and was elected to serve on the core team shortly before his unexpected passing on his way home from the BSDCan 2024 Conference. +Just the previous year, he gave a delightful retrospective talk on his work with BSD at BSDCan 2023 that can be viewed on YouTube: https://www.youtube.com/watch?v=XSziyKlG1ws. ++ +Mike is remembered as a brilliant software engineer, patient, humble and approachable to those needing help. +He enjoyed music, photography, and nature as well as spending time with his family. +A remembrance page for Mike can be found at https://www.gearty-delmore.com/obituaries/michael-mike-karels. +* Hans Petter Selasky (2010 - 2023; RIP 2023) ++ +The FreeBSD community remembers Hans Petter Selasky who passed away in Lillesand, Norway on June 23, 2023 at the age of 41. +Hans was an incredibly brilliant and kind person, and made many valuable contributions to FreeBSD. +He was best known for re-writing and maintaining the USB stack and the webcamd package which enables modern teleconferencing on FreeBSD. +Most recently, he worked for Mellanox (now Nvidia) to support their ConnectX series of high speed NICs on FreeBSD. +Hans’s work included major contributions to the kernel TLS framework, as well as support for NIC kTLS send and receive offload in the mce(4) driver. ++ +One example improvement was his idea to sort incoming TCP packets using the NIC provided RSS flow identifiers in order to present LRO with all packets from the same TCP connection back to back. +This idea was crucial to Netflix's ability to serve 100Gb/s of video traffic from a single machine. ++ +Outside of FreeBSD, Hans’s hobbies included music and mathematics. +He was active in his church, and contributed to its sound team. +He was a loving and dedicated uncle to his nieces and nephews. +He loved animals, especially his cat Pumba. ++ +A longer edition of this remembrance can be found on link:https://forums.freebsd.org/threads/in-memoriam-hans-petter-william-sirevag-selasky.89697/[this FreeBSD Forum page]. * Bruce D. Evans (1991 - 2019; RIP 2019) + Bruce was a programming giant who made FreeBSD his home. diff --git a/documentation/content/en/articles/contributors/contrib-develinmemoriam.po b/documentation/content/en/articles/contributors/contrib-develinmemoriam.po new file mode 100644 index 0000000000..b84f3e068c --- /dev/null +++ b/documentation/content/en/articles/contributors/contrib-develinmemoriam.po @@ -0,0 +1,383 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-03-28 20:31-0400\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:2 +msgid "Mike Karels (2016 - 2024; RIP 2024)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:6 +msgid "" +"Mike Karels, originally a microbiology Ph.D. degree candidate at University " +"of California Berkeley (UCB), expressed interest in computers in a nearby " +"lab which led him to change his entire career path. He eventually became " +"involved in the Computer Systems Research Group (CSRG) at UCB in the early " +"1980's. Once there, his contributions were instrumental in the development " +"and improvement of the BSD Unix TCP/UDP/IP implementation, including the " +"socket interface API, one of the most widely used application programming " +"interfaces in the history of the Internet." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:9 +msgid "" +"Over the next several years, he continued to help prepare the Berkeley " +"Software Distribution releases for 4.3BSD, 4.3BSD-Tahoe, 4.3BSD-Reno, " +"Networking Release 1, and Networking Release 2. During this time, he was " +"one of the authors of \"The Design and Implementation of the 4.3BSD Unix " +"Operating System\", an important book in the field of computers and " +"operating systems, published in 1989." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:12 +msgid "" +"After leaving the CSRG, he was a founding member of BSD Incorporated (BSDi), " +"one of the earliest purveyors of BSD Unix software in source and binary " +"forms. Mike held steady through multiple organizational changes across " +"Walnut Creek CDROM, Wind River Systems, Secure Computing, McAfee, Intel " +"Security, and Forcepoint." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:16 +msgid "" +"In 1994, on the occasion of the 25th anniversary of Unix, the USENIX " +"Association honored Mike with inclusion in the Unix Deck of Cards, a set of " +"playing cards with the faces of pioneers in the early Unix community. He is " +"the Seven of Spades." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:20 +msgid "" +"He also became involved with the FreeBSD Project and contributed greatly to " +"it over the years including additions to the sysctl subsystem, and the " +"Mandatory Access Control (MAC) framework, eventually earning a src commit " +"bit. After his retirement, he stepped up to help with the release " +"engineering of FreeBSD and was elected to serve on the core team shortly " +"before his unexpected passing on his way home from the BSDCan 2024 " +"Conference. Just the previous year, he gave a delightful retrospective talk " +"on his work with BSD at BSDCan 2023 that can be viewed on YouTube: https://" +"www.youtube.com/watch?v=XSziyKlG1ws." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:24 +msgid "" +"Mike is remembered as a brilliant software engineer, patient, humble and " +"approachable to those needing help. He enjoyed music, photography, and " +"nature as well as spending time with his family. A remembrance page for " +"Mike can be found at https://www.gearty-delmore.com/obituaries/michael-mike-" +"karels." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:25 +msgid "Hans Petter Selasky (2010 - 2023; RIP 2023)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:31 +msgid "" +"The FreeBSD community remembers Hans Petter Selasky who passed away in " +"Lillesand, Norway on June 23, 2023 at the age of 41. Hans was an incredibly " +"brilliant and kind person, and made many valuable contributions to FreeBSD. " +"He was best known for re-writing and maintaining the USB stack and the " +"webcamd package which enables modern teleconferencing on FreeBSD. Most " +"recently, he worked for Mellanox (now Nvidia) to support their ConnectX " +"series of high speed NICs on FreeBSD. Hans’s work included major " +"contributions to the kernel TLS framework, as well as support for NIC kTLS " +"send and receive offload in the mce(4) driver." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:34 +msgid "" +"One example improvement was his idea to sort incoming TCP packets using the " +"NIC provided RSS flow identifiers in order to present LRO with all packets " +"from the same TCP connection back to back. This idea was crucial to " +"Netflix's ability to serve 100Gb/s of video traffic from a single machine." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:39 +msgid "" +"Outside of FreeBSD, Hans’s hobbies included music and mathematics. He was " +"active in his church, and contributed to its sound team. He was a loving " +"and dedicated uncle to his nieces and nephews. He loved animals, especially " +"his cat Pumba." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:41 +msgid "" +"A longer edition of this remembrance can be found on link:https://" +"forums.freebsd.org/threads/in-memoriam-hans-petter-william-sirevag-" +"selasky.89697/[this FreeBSD Forum page]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:42 +msgid "Bruce D. Evans (1991 - 2019; RIP 2019)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:44 +msgid "Bruce was a programming giant who made FreeBSD his home." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:46 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:48 +msgid "Bruce ported Minix to the i386 around 1989." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:50 +msgid "" +"Linus Torvalds used Minix/386 to develop his own kernel, and Bruce was the " +"first person he thanked in the release-announcement." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:52 +msgid "" +"When Bill Jolitz released 386BSD 0.1 in 1992, Bruce was listed as a " +"contributor." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:54 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:56 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:58 +msgid "" +"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\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:60 +msgid "Being hard of hearing, Bruce did not attend conferences." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:62 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:64 +msgid "Twenty years later we're still not." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:65 +msgid "Kurt Lidl (2015 - 2019; RIP 2019)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:67 +msgid "" +"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\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:69 +msgid "" +"He began contributing to FreeBSD shortly after the conception of the " +"project. He became a FreeBSD source committer in October 2015." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:71 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:73 +msgid "" +"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\"]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:74 +msgid "Frank Durda IV (1995 - 2003; RIP 2018)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:76 +msgid "" +"Frank had been around the project since the very early days, contributing " +"code to the 1.x line before becoming a committer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:77 +msgid "Andrey A. Chernov (1993 - 2017; RIP 2017)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:79 +msgid "" +"Andrey contributions to FreeBSD can not be overstated. Having been involved " +"for a long there is hardly an area which he did not touch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:80 +msgid "Jürgen Lock (2006 - 2015; RIP 2015)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:82 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:83 +msgid "{alexbl} (2006 - 2011; RIP 2012)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:85 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:86 +msgid "{jb} (1997 - 2009; RIP 2009)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:88 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:89 +msgid "{jmz} (1994 - 2009; RIP 2009)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:91 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:92 +msgid "{itojun} (1997 - 2001; RIP 2008)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:94 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:95 +msgid "{cg} (1999 - 2005; RIP 2005)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:97 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:98 +msgid "{alane} (2002 - 2003; RIP 2003)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/contributors/contrib-develinmemoriam.adoc:99 +msgid "" +"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." +msgstr "" diff --git a/documentation/content/en/articles/cups/_index.adoc b/documentation/content/en/articles/cups/_index.adoc index 58930951c9..d2d983abdc 100644 --- a/documentation/content/en/articles/cups/_index.adoc +++ b/documentation/content/en/articles/cups/_index.adoc @@ -77,7 +77,7 @@ Once installed, the CUPS configuration files can be found in the directory [.fil [[printing-cups-configuring-server]] == Configuring the CUPS Print Server -After installation, a few files must be edited in order to configure the CUPS server. +After installation, a few files must be edited to configure the CUPS server. First, create or modify, as the case may be, the file [.filename]#/etc/devfs.rules# and add the following information to set the proper permissions on all potential printer devices and to associate printers with the `cups` user group: [.programlisting] @@ -105,7 +105,7 @@ devfs_system_ruleset="system" These two entries will start the CUPS print server on boot and invoke the local devfs rule created above, respectively. -In order to enable CUPS printing under certain Microsoft(R) Windows(R) clients, the line below should be uncommented in [.filename]#/usr/local/etc/cups/mime.types# and [.filename]#/usr/local/etc/cups/mime.convs#: +To enable CUPS printing under certain Microsoft(R) Windows(R) clients, the line below should be uncommented in [.filename]#/usr/local/etc/cups/mime.types# and [.filename]#/usr/local/etc/cups/mime.convs#: [.programlisting] .... @@ -116,8 +116,8 @@ Once these changes have been made, the man:devfs[8] and CUPS systems must both b [source,shell] .... -# /etc/rc.d/devfs restart -# /usr/local/etc/rc.d/cupsd restart +# service devfs restart +# service cupsd restart .... [[printing-cups-configuring-printers]] @@ -181,7 +181,7 @@ Generally, the Windows(R) administrator will run the Windows(R) `Add Printer` wi http://server-name-or-ip:631/printers/printername .... -If one has an older version of Windows(R) without native IPP printing support, then the general means of connecting to a CUPS printer is to use package:net/samba413[] and CUPS together, which is a topic outside the scope of this chapter. +If one has an older version of Windows(R) without native IPP printing support, then the general means of connecting to a CUPS printer is to use package:net/samba416[] and CUPS together, which is a topic outside the scope of this chapter. [[printing-cups-troubleshooting]] == CUPS Troubleshooting diff --git a/documentation/content/en/articles/cups/_index.po b/documentation/content/en/articles/cups/_index.po new file mode 100644 index 0000000000..96799bbd25 --- /dev/null +++ b/documentation/content/en/articles/cups/_index.po @@ -0,0 +1,502 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2023-05-21 14:43-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/cups/_index.adoc:1 +#, no-wrap +msgid "How to install and use CUPS on FreeBSD" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/cups/_index.adoc:1 +#: documentation/content/en/articles/cups/_index.adoc:11 +#, no-wrap +msgid "CUPS on FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:46 +msgid "An article about configuring CUPS on FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:48 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/cups/_index.adoc:52 +#, no-wrap +msgid "An Introduction to the Common Unix Printing System (CUPS)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:56 +msgid "" +"CUPS, the Common UNIX Printing System, provides a portable printing layer " +"for UNIX(R)-based operating systems. It has been developed by Easy Software " +"Products to promote a standard printing solution for all UNIX(R) vendors and " +"users." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:61 +msgid "" +"CUPS uses the Internet Printing Protocol (IPP) as the basis for managing " +"print jobs and queues. The Line Printer Daemon (LPD), Server Message Block " +"(SMB), and AppSocket (aka JetDirect) protocols are also supported with " +"reduced functionality. CUPS adds network printer browsing and PostScript " +"Printer Description (PPD) based printing options to support real-world " +"printing under UNIX(R). As a result, CUPS is ideally-suited for sharing and " +"accessing printers in mixed environments of FreeBSD, Linux(R), Mac OS(R) X, " +"or Windows(R)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:63 +msgid "The main site for CUPS is http://www.cups.org/[http://www.cups.org/]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/cups/_index.adoc:65 +#, no-wrap +msgid "Installing the CUPS Print Server" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:68 +msgid "" +"To install CUPS using a precompiled binary, issue the following command from " +"a root terminal:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:72 +#, no-wrap +msgid "# pkg install cups\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:76 +msgid "" +"Other optional, but recommended, packages are package:print/gutenprint[] and " +"package:print/hplip[], both of which add drivers and utilities for a variety " +"of printers. Once installed, the CUPS configuration files can be found in " +"the directory [.filename]#/usr/local/etc/cups#." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/cups/_index.adoc:78 +#, no-wrap +msgid "Configuring the CUPS Print Server" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:82 +msgid "" +"After installation, a few files must be edited to configure the CUPS " +"server. First, create or modify, as the case may be, the file [.filename]#/" +"etc/devfs.rules# and add the following information to set the proper " +"permissions on all potential printer devices and to associate printers with " +"the `cups` user group:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:90 +#, no-wrap +msgid "" +"[system=10]\n" +"add path 'unlpt*' mode 0660 group cups\n" +"add path 'ulpt*' mode 0660 group cups\n" +"add path 'lpt*' mode 0660 group cups\n" +"add path 'usb/X.Y.Z' mode 0660 group cups\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/cups/_index.adoc:96 +msgid "" +"Note that _X_, _Y_, and _Z_ should be replaced with the target USB device " +"listed in the [.filename]#/dev/usb# directory that corresponds to the " +"printer. To find the correct device, examine the output of man:dmesg[8], " +"where [.filename]#ugenX.Y# lists the printer device, which is a symbolic " +"link to a USB device in [.filename]#/dev/usb#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:99 +msgid "Next, add two lines to [.filename]#/etc/rc.conf# as follows:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:104 +#, no-wrap +msgid "" +"cupsd_enable=\"YES\"\n" +"devfs_system_ruleset=\"system\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:107 +msgid "" +"These two entries will start the CUPS print server on boot and invoke the " +"local devfs rule created above, respectively." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:109 +msgid "" +"To enable CUPS printing under certain Microsoft(R) Windows(R) clients, the " +"line below should be uncommented in [.filename]#/usr/local/etc/cups/mime." +"types# and [.filename]#/usr/local/etc/cups/mime.convs#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:113 +#, no-wrap +msgid "application/octet-stream\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:116 +msgid "" +"Once these changes have been made, the man:devfs[8] and CUPS systems must " +"both be restarted, either by rebooting the computer or issuing the following " +"two commands in a root terminal:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:121 +#, no-wrap +msgid "" +"# service devfs restart\n" +"# service cupsd restart\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/cups/_index.adoc:124 +#, no-wrap +msgid "Configuring Printers on the CUPS Print Server" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:128 +msgid "" +"After the CUPS system has been installed and configured, the administrator " +"can begin configuring the local printers attached to the CUPS print server. " +"This part of the process is very similar, if not identical, to configuring " +"CUPS printers on other UNIX(R)-based operating systems, such as a Linux(R) " +"distribution." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:133 +msgid "" +"The primary means for managing and administering the CUPS server is through " +"the web-based interface, which can be found by launching a web browser and " +"entering http://localhost:631[http://localhost:631] in the browser's URL " +"bar. If the CUPS server is on another machine on the network, substitute " +"the server's local IP address for `localhost`. The CUPS web interface is " +"fairly self-explanatory, as there are sections for managing printers and " +"print jobs, authorizing users, and more. Additionally, on the right-hand " +"side of the Administration screen are several check-boxes allowing easy " +"access to commonly-changed settings, such as whether to share published " +"printers connected to the system, whether to allow remote administration of " +"the CUPS server, and whether to allow users additional access and privileges " +"to the printers and print jobs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:137 +msgid "" +"Adding a printer is generally as easy as clicking \"Add Printer\" at the " +"Administration screen of the CUPS web interface, or clicking one of the " +"\"New Printers Found\" buttons also at the Administration screen. When " +"presented with the \"Device\" drop-down box, simply select the desired " +"locally-attached printer, and then continue through the process. If one has " +"added the package:print/gutenprint-cups[] or package:print/hplip[] ports or " +"packages as referenced above, then additional print drivers will be " +"available in the subsequent screens that might provide more stability or " +"features." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/cups/_index.adoc:139 +#, no-wrap +msgid "Configuring CUPS Clients" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:143 +msgid "" +"Once the CUPS server has been configured and printers have been added and " +"published to the network, the next step is to configure the clients, or the " +"machines that are going to access the CUPS server. If one has a single " +"desktop machine that is acting as both server and client, then much of this " +"information may not be needed." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/cups/_index.adoc:145 +#, no-wrap +msgid "UNIX(R) Clients" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:151 +msgid "" +"CUPS will also need to be installed on your UNIX(R) clients. Once CUPS is " +"installed on the clients, then CUPS printers that are shared across the " +"network are often automatically discovered by the printer managers for " +"various desktop environments such as GNOME or KDE. Alternatively, one can " +"access the local CUPS interface on the client machine at http://" +"localhost:631[http://localhost:631] and click on \"Add Printer\" in the " +"Administration section. When presented with the \"Device\" drop-down box, " +"simply select the networked CUPS printer, if it was automatically " +"discovered, or select `ipp` or `http` and enter the IPP or HTTP URI of the " +"networked CUPS printer, usually in one of the two following syntaxes:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:155 +#, no-wrap +msgid "ipp://server-name-or-ip/printers/printername\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:160 +#: documentation/content/en/articles/cups/_index.adoc:182 +#, no-wrap +msgid "http://server-name-or-ip:631/printers/printername\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:163 +msgid "" +"If the CUPS clients have difficulty finding other CUPS printers shared " +"across the network, sometimes it is helpful to add or create a file [." +"filename]#/usr/local/etc/cups/client.conf# with a single entry as follows:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:167 +#, no-wrap +msgid "ServerName server-ip\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:170 +msgid "" +"In this case, _server-ip_ would be replaced by the local IP address of the " +"CUPS server on the network." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/cups/_index.adoc:172 +#, no-wrap +msgid "Windows(R) Clients" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:178 +msgid "" +"Versions of Windows(R) prior to XP did not have the capability to natively " +"network with IPP-based printers. However, Windows(R) XP and later versions " +"do have this capability. Therefore, to add a CUPS printer in these versions " +"of Windows(R) is quite easy. Generally, the Windows(R) administrator will " +"run the Windows(R) `Add Printer` wizard, select `Network Printer` and then " +"enter the URI in the following syntax:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:185 +msgid "" +"If one has an older version of Windows(R) without native IPP printing " +"support, then the general means of connecting to a CUPS printer is to use " +"package:net/samba416[] and CUPS together, which is a topic outside the scope " +"of this chapter." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/cups/_index.adoc:187 +#, no-wrap +msgid "CUPS Troubleshooting" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/cups/_index.adoc:196 +msgid "" +"Difficulties with CUPS often lies in permissions. First, double check the " +"man:devfs[8] permissions as outlined above. Next, check the actual " +"permissions of the devices created in the file system. It is also helpful " +"to make sure your user is a member of the `cups` group. If the permissions " +"check boxes in the Administration section of the CUPS web interface do not " +"seem to be working, another fix might be to manually backup the main CUPS " +"configuration file located at [.filename]#/usr/local/etc/cups/cupsd.conf# " +"and edit the various configuration options and try different combinations of " +"configuration options. One sample [.filename]#/usr/local/etc/cups/cupsd." +"conf# to test is listed below. Please note that this sample [." +"filename]#cupsd.conf# sacrifices security for easier configuration; once the " +"administrator successfully connects to the CUPS server and configures the " +"clients, it is advisable to revisit this configuration file and begin " +"locking down access." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:202 +#, no-wrap +msgid "" +"# Log general information in error_log - change \"info\" to \"debug\" for\n" +"# troubleshooting...\n" +"LogLevel info\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:205 +#, no-wrap +msgid "" +"# Administrator user group...\n" +"SystemGroup wheel\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:210 +#, no-wrap +msgid "" +"# Listen for connections on Port 631.\n" +"Port 631\n" +"#Listen localhost:631\n" +"Listen /var/run/cups.sock\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:217 +#, no-wrap +msgid "" +"# Show shared printers on the local network.\n" +"Browsing On\n" +"BrowseOrder allow,deny\n" +"#BrowseAllow @LOCAL\n" +"BrowseAllow 192.168.1.* # change to local LAN settings\n" +"BrowseAddress 192.168.1.* # change to local LAN settings\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:221 +#, no-wrap +msgid "" +"# Default authentication type, when authentication is required...\n" +"DefaultAuthType Basic\n" +"DefaultEncryption Never # comment this line to allow encryption\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:228 +#, no-wrap +msgid "" +"# Allow access to the server from any machine on the LAN\n" +"<Location />\n" +" Order allow,deny\n" +" #Allow localhost\n" +" Allow 192.168.1.* # change to local LAN settings\n" +"</Location>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:236 +#, no-wrap +msgid "" +"# Allow access to the admin pages from any machine on the LAN\n" +"<Location /admin>\n" +" #Encryption Required\n" +" Order allow,deny\n" +" #Allow localhost\n" +" Allow 192.168.1.* # change to local LAN settings\n" +"</Location>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:245 +#, no-wrap +msgid "" +"# Allow access to configuration files from any machine on the LAN\n" +"<Location /admin/conf>\n" +" AuthType Basic\n" +" Require user @SYSTEM\n" +" Order allow,deny\n" +" #Allow localhost\n" +" Allow 192.168.1.* # change to local LAN settings\n" +"</Location>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:256 +#, no-wrap +msgid "" +"# Set the default printer/job policies...\n" +"<Policy default>\n" +" # Job-related operations must be done by the owner or an administrator...\n" +" <Limit Send-Document Send-URI Hold-Job Release-Job Restart-Job Purge-Jobs \\\n" +"Set-Job-Attributes Create-Job-Subscription Renew-Subscription Cancel-Subscription \\\n" +"Get-Notifications Reprocess-Job Cancel-Current-Job Suspend-Current-Job Resume-Job \\\n" +"CUPS-Move-Job>\n" +" Require user @OWNER @SYSTEM\n" +" Order deny,allow\n" +" </Limit>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:267 +#, no-wrap +msgid "" +" # All administration operations require an administrator to authenticate...\n" +" <Limit Pause-Printer Resume-Printer Set-Printer-Attributes Enable-Printer \\\n" +"Disable-Printer Pause-Printer-After-Current-Job Hold-New-Jobs Release-Held-New-Jobs \\\n" +"Deactivate-Printer Activate-Printer Restart-Printer Shutdown-Printer Startup-Printer \\\n" +"Promote-Job Schedule-Job-After CUPS-Add-Printer CUPS-Delete-Printer CUPS-Add-Class \\\n" +"CUPS-Delete-Class CUPS-Accept-Jobs CUPS-Reject-Jobs CUPS-Set-Default>\n" +" AuthType Basic\n" +" Require user @SYSTEM\n" +" Order deny,allow\n" +" </Limit>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:273 +#, no-wrap +msgid "" +" # Only the owner or an administrator can cancel or authenticate a job...\n" +" <Limit Cancel-Job CUPS-Authenticate-Job>\n" +" Require user @OWNER @SYSTEM\n" +" Order deny,allow\n" +" </Limit>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/cups/_index.adoc:278 +#, no-wrap +msgid "" +" <Limit All>\n" +" Order deny,allow\n" +" </Limit>\n" +"</Policy>\n" +msgstr "" diff --git a/documentation/content/en/articles/explaining-bsd/_index.adoc b/documentation/content/en/articles/explaining-bsd/_index.adoc index b188f0a2b0..82c9222170 100644 --- a/documentation/content/en/articles/explaining-bsd/_index.adoc +++ b/documentation/content/en/articles/explaining-bsd/_index.adoc @@ -4,7 +4,7 @@ authors: - author: Greg Lehey email: grog@FreeBSD.org description: Brief explanation about BSD -trademarks: ["freebsd", "amd", "apple", "intel", "linux", "opengroup", "sun", "unix", "general"] +trademarks: ["freebsd", "amd", "apple", "git", intel", "linux", "opengroup", "sun", "unix", "general"] tags: ["Explaining BSD", "BSD", "FreeBSD", "operating system"] --- @@ -145,23 +145,23 @@ Users can obtain a complete copy of any version. A large number of developers worldwide contribute to improvements to BSD. They are divided into three kinds: -* _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. +* _Contributors_ write code or documentation. They are not permitted to commit (add code) directly to the source tree. 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. 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. -On the other hand, developers making far-reaching or complicated changes are expected to submit their changes for review before committing them +On the other hand, developers making far-reaching or complicated changes are expected to submit their changes for review before committing them. In extreme cases, a core team member with a function such as Principal Architect may order that changes be removed from the tree, a process known as _backing out_. All committers receive mail describing each individual commit, so it is not possible to commit secretly. -* The _Core team_. FreeBSD and NetBSD each have a core team which manages the project. The core teams developed in the course of the projects, and their role is not always well-defined. It is not necessary to be a developer in order to be a core team member, though it is normal. The rules for the core team vary from one project to the other, but in general they have more say in the direction of the project than non-core team members have. +* The _Core team_. FreeBSD and NetBSD each have a core team which manages the project. The core teams developed in the course of the projects, and their role is not always well-defined. It is not necessary to be a developer to be a core team member, though it is normal. The rules for the core team vary from one project to the other, but in general they have more say in the direction of the project than non-core team members have. This arrangement differs from Linux in a number of ways: . No one person controls the content of the system. In practice, this difference is overrated, since the Principal Architect can require that code be backed out, and even in the Linux project several people are permitted to make changes. . On the other hand, there _is_ a central repository, a single place where you can find the entire operating system sources, including all older versions. . BSD projects maintain the entire "Operating System", not only the kernel. This distinction is only marginally useful: neither BSD nor Linux is useful without applications. The applications used under BSD are frequently the same as the applications used under Linux. -. As a result of the formalized maintenance of a single SVN source tree, BSD development is clear, and it is possible to access any version of the system by release number or by date. SVN also allows incremental updates to the system: for example, the FreeBSD repository is updated about 100 times a day. Most of these changes are small. +. As a result of the formalized maintenance of a single Git source tree, BSD development is clear, and it is possible to access any version of the system by release number or by date. Git also allows incremental updates to the system: for example, the FreeBSD repository is updated about 100 times a day. Most of these changes are small. === BSD releases @@ -171,7 +171,7 @@ In addition, the version number has a suffix indicating its purpose: . The development version of the system is called _CURRENT_. FreeBSD assigns a number to CURRENT, for example FreeBSD 5.0-CURRENT. NetBSD uses a slightly different naming scheme and appends a single-letter suffix which indicates changes in the internal interfaces, for example NetBSD 1.4.3G. OpenBSD does not assign a number ("OpenBSD-current"). All new development on the system goes into this branch. . At regular intervals, between two and four times a year, the projects bring out a _RELEASE_ version of the system, which is available on CD-ROM and for free download from FTP sites, for example OpenBSD 2.6-RELEASE or NetBSD 1.4-RELEASE. The RELEASE version is intended for end users and is the normal version of the system. NetBSD also provides _patch releases_ with a third digit, for example NetBSD 1.4.2. -. As bugs are found in a RELEASE version, they are fixed, and the fixes are added to the SVN tree. In FreeBSD, the resultant version is called the _STABLE_ version, while in NetBSD and OpenBSD it continues to be called the RELEASE version. Smaller new features can also be added to this branch after a period of test in the CURRENT branch. Security and other important bug fixes are also applied to all supported RELEASE versions. +. As bugs are found in a RELEASE version, they are fixed, and the fixes are added to the Git tree. In FreeBSD, the resultant version is called the _STABLE_ version, while in NetBSD and OpenBSD it continues to be called the RELEASE version. Smaller new features can also be added to this branch after a period of test in the CURRENT branch. Security and other important bug fixes are also applied to all supported RELEASE versions. _By contrast, Linux maintains two separate code trees: the stable version and the development version. Stable versions have an even minor version number, such as 2.0, 2.2 or 2.4. @@ -206,7 +206,7 @@ This is particularly attractive for embedded applications. === What else should I know? Since fewer applications are available for BSD than Linux, the BSD developers created a Linux compatibility package, which allows Linux programs to run under BSD. -The package includes both kernel modifications, in order to correctly perform Linux system calls, and Linux compatibility files such as the C library. +The package includes both kernel modifications, to correctly perform Linux system calls, and Linux compatibility files such as the C library. There is no noticeable difference in execution speed between a Linux application running on a Linux machine and a Linux application running on a BSD machine of the same speed. The "all from one supplier" nature of BSD means that upgrades are much easier to handle than is frequently the case with Linux. @@ -228,6 +228,6 @@ Here are some guidelines: === Who provides support, service, and training for BSD? -BSDi / http://www.freebsdmall.com[FreeBSD Mall, Inc.] have been providing support contracts for FreeBSD for nearly a decade. +http://www.ixsystems.com/[iXsystems, Inc.] provides support contracts for FreeBSD. In addition, each of the projects has a list of consultants for hire: link:https://www.FreeBSD.org/commercial/consult_bycat/[FreeBSD], http://www.netbsd.org/gallery/consultants.html[NetBSD], and http://www.openbsd.org/support.html[OpenBSD]. diff --git a/documentation/content/en/articles/explaining-bsd/_index.po b/documentation/content/en/articles/explaining-bsd/_index.po new file mode 100644 index 0000000000..932b1a44f5 --- /dev/null +++ b/documentation/content/en/articles/explaining-bsd/_index.po @@ -0,0 +1,683 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2023-09-09 18:13-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/explaining-bsd/_index.adoc:1 +#, no-wrap +msgid "Brief explanation about BSD" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/explaining-bsd/_index.adoc:1 +#: documentation/content/en/articles/explaining-bsd/_index.adoc:11 +#, no-wrap +msgid "Explaining BSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:46 +msgid "" +"In the open source world, the word \"Linux\" is almost synonymous with " +"\"Operating System\", but it is not the only open source UNIX(R) operating " +"system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:48 +msgid "" +"So what is the secret? Why is BSD not better known? This white paper " +"addresses these and other questions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:50 +msgid "" +"Throughout this paper, differences between BSD and Linux will be noted " +"__like this__." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:52 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/explaining-bsd/_index.adoc:56 +#, no-wrap +msgid "What is BSD?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:63 +msgid "" +"BSD stands for \"Berkeley Software Distribution\". It is the name of " +"distributions of source code from the University of California, Berkeley, " +"which were originally extensions to AT&T's Research UNIX(R) operating " +"system. Several open source operating system projects are based on a " +"release of this source code known as 4.4BSD-Lite. In addition, they " +"comprise a number of packages from other Open Source projects, including " +"notably the GNU project. The overall operating system comprises:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:65 +msgid "" +"The BSD kernel, which handles process scheduling, memory management, " +"symmetric multi-processing (SMP), device drivers, etc." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:66 +msgid "The C library, the base API for the system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:68 +msgid "" +"__The BSD C library is based on code from Berkeley, not the GNU project.__" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:69 +msgid "Utilities such as shells, file utilities, compilers and linkers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:71 +msgid "" +"__Some of the utilities are derived from the GNU project, others are not.__" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:72 +msgid "The X Window system, which handles graphical display." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:75 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:76 +msgid "Many other programs and utilities." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/explaining-bsd/_index.adoc:78 +#, no-wrap +msgid "What, a real UNIX(R)?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:83 +msgid "" +"The BSD operating systems are not clones, but open source derivatives of " +"AT&T's Research UNIX(R) operating system, which is also the ancestor of the " +"modern UNIX(R) System V. This may surprise you. How could that happen when " +"AT&T has never released its code as open source?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:85 +msgid "" +"It is true that AT&T UNIX(R) is not open source, and in a copyright sense " +"BSD is very definitely _not_ UNIX(R), but on the other hand, AT&T has " +"imported sources from other projects, noticeably the Computer Sciences " +"Research Group (CSRG) of the University of California in Berkeley, CA. " +"Starting in 1976, the CSRG started releasing tapes of their software, " +"calling them _Berkeley Software Distribution_ or __BSD__." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:89 +msgid "" +"Initial BSD releases consisted mainly of user programs, but that changed " +"dramatically when the CSRG landed a contract with the Defense Advanced " +"Research Projects Agency (DARPA) to upgrade the communications protocols on " +"their network, ARPANET. The new protocols were known as the __Internet " +"Protocols__, later _TCP/IP_ after the most important protocols. The first " +"widely distributed implementation was part of 4.2BSD, in 1982." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:96 +msgid "" +"In the course of the 1980s, a number of new workstation companies sprang " +"up. Many preferred to license UNIX(R) rather than developing operating " +"systems for themselves. In particular, Sun Microsystems licensed UNIX(R) " +"and implemented a version of 4.2BSD, which they called SunOS(TM). When AT&T " +"themselves were allowed to sell UNIX(R) commercially, they started with a " +"somewhat bare-bones implementation called System III, to be quickly followed " +"by System V. The System V code base did not include networking, so all " +"implementations included additional software from the BSD, including the TCP/" +"IP software, but also utilities such as the _csh_ shell and the _vi_ " +"editor. Collectively, these enhancements were known as the __Berkeley " +"Extensions__." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:105 +msgid "" +"The BSD tapes contained AT&T source code and thus required a UNIX(R) source " +"license. By 1990, the CSRG's funding was running out, and it faced " +"closure. Some members of the group decided to release the BSD code, which " +"was Open Source, without the AT&T proprietary code. This finally happened " +"with the __Networking Tape 2__, usually known as __Net/2__. Net/2 was not a " +"complete operating system: about 20% of the kernel code was missing. One of " +"the CSRG members, William F. Jolitz, wrote the remaining code and released " +"it in early 1992 as __386BSD__. At the same time, another group of ex-CSRG " +"members formed a commercial company called http://www.bsdi.com/[Berkeley " +"Software Design Inc.] and released a beta version of an operating system " +"called http://www.bsdi.com/[BSD/386], which was based on the same sources. " +"The name of the operating system was later changed to BSD/OS." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:111 +msgid "" +"386BSD never became a stable operating system. Instead, two other projects " +"split off from it in 1993: http://www.NetBSD.org/[NetBSD] and link:https://" +"www.FreeBSD.org/[FreeBSD]. The two projects originally diverged due to " +"differences in patience waiting for improvements to 386BSD: the NetBSD " +"people started early in the year, and the first version of FreeBSD was not " +"ready until the end of the year. In the meantime, the code base had " +"diverged sufficiently to make it difficult to merge. In addition, the " +"projects had different aims, as we will see below. In 1996, http://www." +"OpenBSD.org/[OpenBSD] split off from NetBSD, and in 2003, http://www." +"dragonflybsd.org/[DragonFlyBSD] split off from FreeBSD." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/explaining-bsd/_index.adoc:113 +#, no-wrap +msgid "Why is BSD not better known?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:116 +msgid "For a number of reasons, BSD is relatively unknown:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:118 +msgid "" +"The BSD developers are often more interested in polishing their code than " +"marketing it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:119 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:120 +msgid "" +"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\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:124 +msgid "" +"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\"." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/explaining-bsd/_index.adoc:126 +#, no-wrap +msgid "Comparing BSD and Linux" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:132 +msgid "" +"So what is really the difference between, say, Debian Linux and FreeBSD? For " +"the average user, the difference is surprisingly small: Both are UNIX(R) " +"like operating systems. Both are developed by non-commercial projects (this " +"does not apply to many other Linux distributions, of course). In the " +"following section, we will look at BSD and compare it to Linux. The " +"description applies most closely to FreeBSD, which accounts for an estimated " +"80% of the BSD installations, but the differences from NetBSD, OpenBSD and " +"DragonFlyBSD are small." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/explaining-bsd/_index.adoc:133 +#, no-wrap +msgid "Who owns BSD?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:138 +msgid "" +"No one person or corporation owns BSD. It is created and distributed by a " +"community of highly technical and committed contributors all over the " +"world. Some of the components of BSD are Open Source projects in their own " +"right and managed by different project maintainers." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/explaining-bsd/_index.adoc:139 +#, no-wrap +msgid "How is BSD developed and updated?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:144 +msgid "" +"The BSD kernels are developed and updated following the Open Source " +"development model. Each project maintains a publicly accessible _source " +"tree_ which contains all source files for the project, including " +"documentation and other incidental files. Users can obtain a complete copy " +"of any version." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:147 +msgid "" +"A large number of developers worldwide contribute to improvements to BSD. " +"They are divided into three kinds:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:149 +msgid "" +"_Contributors_ write code or documentation. They are not permitted to commit " +"(add code) directly to the source tree. For their code to be included in the " +"system, it must be reviewed and checked in by a registered developer, known " +"as a __committer__." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:150 +msgid "" +"_Committers_ are developers with write access to the source tree. To become " +"a committer, an individual must show ability in the area in which they are " +"active." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:157 +msgid "" +"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. On the other " +"hand, developers making far-reaching or complicated changes are expected to " +"submit their changes for review before committing them. In extreme cases, a " +"core team member with a function such as Principal Architect may order that " +"changes be removed from the tree, a process known as _backing out_. All " +"committers receive mail describing each individual commit, so it is not " +"possible to commit secretly." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:158 +msgid "" +"The _Core team_. FreeBSD and NetBSD each have a core team which manages the " +"project. The core teams developed in the course of the projects, and their " +"role is not always well-defined. It is not necessary to be a developer to be " +"a core team member, though it is normal. The rules for the core team vary " +"from one project to the other, but in general they have more say in the " +"direction of the project than non-core team members have." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:160 +msgid "This arrangement differs from Linux in a number of ways:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:162 +msgid "" +"No one person controls the content of the system. In practice, this " +"difference is overrated, since the Principal Architect can require that code " +"be backed out, and even in the Linux project several people are permitted to " +"make changes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:163 +msgid "" +"On the other hand, there _is_ a central repository, a single place where you " +"can find the entire operating system sources, including all older versions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:164 +msgid "" +"BSD projects maintain the entire \"Operating System\", not only the kernel. " +"This distinction is only marginally useful: neither BSD nor Linux is useful " +"without applications. The applications used under BSD are frequently the " +"same as the applications used under Linux." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:165 +msgid "" +"As a result of the formalized maintenance of a single Git source tree, BSD " +"development is clear, and it is possible to access any version of the system " +"by release number or by date. Git also allows incremental updates to the " +"system: for example, the FreeBSD repository is updated about 100 times a " +"day. Most of these changes are small." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/explaining-bsd/_index.adoc:166 +#, no-wrap +msgid "BSD releases" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:171 +msgid "" +"FreeBSD, NetBSD and OpenBSD provide the system in three different " +"\"releases\". As with Linux, releases are assigned a number such as 1.4.1 " +"or 3.5. In addition, the version number has a suffix indicating its purpose:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:173 +msgid "" +"The development version of the system is called _CURRENT_. FreeBSD assigns a " +"number to CURRENT, for example FreeBSD 5.0-CURRENT. NetBSD uses a slightly " +"different naming scheme and appends a single-letter suffix which indicates " +"changes in the internal interfaces, for example NetBSD 1.4.3G. OpenBSD does " +"not assign a number (\"OpenBSD-current\"). All new development on the system " +"goes into this branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:174 +msgid "" +"At regular intervals, between two and four times a year, the projects bring " +"out a _RELEASE_ version of the system, which is available on CD-ROM and for " +"free download from FTP sites, for example OpenBSD 2.6-RELEASE or NetBSD 1.4-" +"RELEASE. The RELEASE version is intended for end users and is the normal " +"version of the system. NetBSD also provides _patch releases_ with a third " +"digit, for example NetBSD 1.4.2." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:175 +msgid "" +"As bugs are found in a RELEASE version, they are fixed, and the fixes are " +"added to the Git tree. In FreeBSD, the resultant version is called the " +"_STABLE_ version, while in NetBSD and OpenBSD it continues to be called the " +"RELEASE version. Smaller new features can also be added to this branch after " +"a period of test in the CURRENT branch. Security and other important bug " +"fixes are also applied to all supported RELEASE versions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:182 +msgid "" +"_By contrast, Linux maintains two separate code trees: the stable version " +"and the development version. Stable versions have an even minor version " +"number, such as 2.0, 2.2 or 2.4. Development versions have an odd minor " +"version number, such as 2.1, 2.3 or 2.5. In each case, the number is " +"followed by a further number designating the exact release. In addition, " +"each vendor adds their own userland programs and utilities, so the name of " +"the distribution is also important. Each distribution vendor also assigns " +"version numbers to the distribution, so a complete description might be " +"something like \"TurboLinux 6.0 with kernel 2.2.14\"_" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/explaining-bsd/_index.adoc:183 +#, no-wrap +msgid "What versions of BSD are available?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:186 +msgid "" +"In contrast to the numerous Linux distributions, there are only four major " +"open source BSDs. Each BSD project maintains its own source tree and its own " +"kernel. In practice, though, there appear to be fewer divergences between " +"the userland code of the projects than there is in Linux." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:188 +msgid "" +"It is difficult to categorize the goals of each project: the differences are " +"very subjective. Basically," +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:190 +msgid "" +"FreeBSD aims for high performance and ease of use by end users, and is a " +"favourite of web content providers. It runs on a link:https://www.FreeBSD." +"org/platforms/[number of platforms] and has significantly more users than " +"the other projects." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:191 +msgid "" +"NetBSD aims for maximum portability: \"of course it runs NetBSD\". It runs " +"on machines from palmtops to large servers, and has even been used on NASA " +"space missions. It is a particularly good choice for running on old non-" +"Intel(R) hardware." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:192 +msgid "" +"OpenBSD aims for security and code purity: it uses a combination of the open " +"source concept and rigorous code reviews to create a system which is " +"demonstrably correct, making it the choice of security-conscious " +"organizations such as banks, stock exchanges and US Government departments. " +"Like NetBSD, it runs on a number of platforms." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:193 +msgid "" +"DragonFlyBSD aims for high performance and scalability under everything from " +"a single-node UP system to a massively clustered system. DragonFlyBSD has " +"several long-range technical goals, but focus lies on providing a SMP-" +"capable infrastructure that is easy to understand, maintain and develop for." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:195 +msgid "" +"There are also two additional BSD UNIX(R) operating systems which are not " +"open source, BSD/OS and Apple's Mac OS(R) X:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:197 +msgid "" +"BSD/OS was the oldest of the 4.4BSD derivatives. It was not open source, " +"though source code licenses were available at relatively low cost. It " +"resembled FreeBSD in many ways. Two years after the acquisition of BSDi by " +"Wind River Systems, BSD/OS failed to survive as an independent product. " +"Support and source code may still be available from Wind River, but all new " +"development is focused on the VxWorks embedded operating system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:198 +msgid "" +"http://www.apple.com/macosx/server/[Mac OS(R) X] is the latest version of " +"the operating system for Apple(R)'s Mac(R) line. The BSD core of this " +"operating system, http://developer.apple.com/darwin/[Darwin], is available " +"as a fully functional open source operating system for x86 and PPC " +"computers. The Aqua/Quartz graphics system and many other proprietary " +"aspects of Mac OS(R) X remain closed-source, however. Several Darwin " +"developers are also FreeBSD committers, and vice-versa." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/explaining-bsd/_index.adoc:199 +#, no-wrap +msgid "How does the BSD license differ from the GNU Public license?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:205 +msgid "" +"Linux is available under the http://www.fsf.org/copyleft/gpl.html[GNU " +"General Public License] (GPL), which is designed to eliminate closed source " +"software. In particular, any derivative work of a product released under " +"the GPL must also be supplied with source code if requested. By contrast, " +"the http://www.opensource.org/licenses/bsd-license.html[BSD license] is less " +"restrictive: binary-only distributions are allowed. This is particularly " +"attractive for embedded applications." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/explaining-bsd/_index.adoc:206 +#, no-wrap +msgid "What else should I know?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:211 +msgid "" +"Since fewer applications are available for BSD than Linux, the BSD " +"developers created a Linux compatibility package, which allows Linux " +"programs to run under BSD. The package includes both kernel modifications, " +"to correctly perform Linux system calls, and Linux compatibility files such " +"as the C library. There is no noticeable difference in execution speed " +"between a Linux application running on a Linux machine and a Linux " +"application running on a BSD machine of the same speed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:214 +msgid "" +"The \"all from one supplier\" nature of BSD means that upgrades are much " +"easier to handle than is frequently the case with Linux. BSD handles " +"library version upgrades by providing compatibility modules for earlier " +"library versions, so it is possible to run binaries which are several years " +"old with no problems." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/explaining-bsd/_index.adoc:215 +#, no-wrap +msgid "Which should I use, BSD or Linux?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:218 +msgid "" +"What does this all mean in practice? Who should use BSD, who should use " +"Linux?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:221 +msgid "This is a very difficult question to answer. Here are some guidelines:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:223 +msgid "" +"\"If it ain't broke, don't fix it\": If you already use an open source " +"operating system, and you are happy with it, there is probably no good " +"reason to change." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:224 +msgid "" +"BSD systems, in particular FreeBSD, can have notably higher performance than " +"Linux. But this is not across the board. In many cases, there is little or " +"no difference in performance. In some cases, Linux may perform better than " +"FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:225 +msgid "" +"In general, BSD systems have a better reputation for reliability, mainly as " +"a result of the more mature code base." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:226 +msgid "" +"BSD projects have a better reputation for the quality and completeness of " +"their documentation. The various documentation projects aim to provide " +"actively updated documentation, in many languages, and covering all aspects " +"of the system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:227 +msgid "The BSD license may be more attractive than the GPL." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:228 +msgid "" +"BSD can execute most Linux binaries, while Linux can not execute BSD " +"binaries. Many BSD implementations can also execute binaries from other " +"UNIX(R) like systems. As a result, BSD may present an easier migration route " +"from other systems than Linux would." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/explaining-bsd/_index.adoc:229 +#, no-wrap +msgid "Who provides support, service, and training for BSD?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:232 +msgid "" +"http://www.ixsystems.com/[iXsystems, Inc.] provides support contracts for " +"FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/explaining-bsd/_index.adoc:233 +msgid "" +"In addition, each of the projects has a list of consultants for hire: link:" +"https://www.FreeBSD.org/commercial/consult_bycat/[FreeBSD], http://www." +"netbsd.org/gallery/consultants.html[NetBSD], and http://www.openbsd.org/" +"support.html[OpenBSD]." +msgstr "" diff --git a/documentation/content/en/articles/filtering-bridges/_index.adoc b/documentation/content/en/articles/filtering-bridges/_index.adoc index 1d9f76ba83..64c7bd781b 100644 --- a/documentation/content/en/articles/filtering-bridges/_index.adoc +++ b/documentation/content/en/articles/filtering-bridges/_index.adoc @@ -44,7 +44,7 @@ Abstract Often it is useful to divide one physical network (like an Ethernet) into two separate segments without having to create subnets, and use a router to link them together. The device that connects the two networks in this way is called a bridge. -A FreeBSD system with two network interfaces is enough in order to act as a bridge. +A FreeBSD system with two network interfaces is enough to act as a bridge. A bridge works by scanning the addresses of MAC level (Ethernet addresses) of the devices connected to each of its network interfaces and then forwarding the traffic between the two networks only if the source and the destination are on different segments. Under many points of view a bridge is similar to an Ethernet switch with only two ports. @@ -78,7 +78,7 @@ Select the best choice according to your needs and abilities. Before going on, be sure to have at least two Ethernet cards that support the promiscuous mode for both reception and transmission, since they must be able to send Ethernet packets with any address, not just their own. Moreover, to have a good throughput, the cards should be PCI bus mastering cards. The best choices are still the Intel EtherExpress(TM) Pro, followed by the 3Com(R) 3c9xx series. -To simplify the firewall configuration it may be useful to have two cards of different manufacturers (using different drivers) in order to distinguish clearly which interface is connected to the router and which to the inner network. +To simplify the firewall configuration it may be useful to have two cards of different manufacturers (using different drivers) to distinguish clearly which interface is connected to the router and which to the inner network. [[filtering-bridges-kernel]] === Kernel Configuration @@ -96,7 +96,7 @@ options IPFIREWALL_VERBOSE The first line is to compile the bridge support, the second one is the firewall and the third one is the logging functions of the firewall. Now it is necessary to build and install the new kernel. -You may find detailed instructions in the extref:{handbook}[Building and Installing a Custom Kernel, kernelconfig-building] section of the FreeBSD Handbook. +You may find detailed instructions in the extref:{handbook}kernelconfig[Building and Installing a Custom Kernel, kernelconfig-building] section of the FreeBSD Handbook. [[filtering-bridges-modules]] === Modules Loading @@ -114,9 +114,9 @@ It is not required to add a similar row for the [.filename]#ipfw.ko# module, sin [[filtering-bridges-finalprep]] == Final Preparation -Before rebooting in order to load the new kernel or the required modules (according to the previously chosen installation method), you have to make some changes to the [.filename]#/etc/rc.conf# configuration file. +Before rebooting to load the new kernel or the required modules (according to the previously chosen installation method), you have to make some changes to the [.filename]#/etc/rc.conf# configuration file. The default rule of the firewall is to reject all IP packets. -Initially we will set up an `open` firewall, in order to verify its operation without any issue related to packet filtering (in case you are going to execute this procedure remotely, such configuration will avoid you to remain isolated from the network). +Initially we will set up an `open` firewall, to verify its operation without any issue related to packet filtering (in case you are going to execute this procedure remotely, such configuration will avoid you to remain isolated from the network). Put these lines in [.filename]#/etc/rc.conf#: [.programlisting] @@ -138,7 +138,7 @@ Assigning an IP to both the network cards does not make much sense, unless, duri There is another important thing to know. When running IP over Ethernet, there are actually two Ethernet protocols in use: one is IP, the other is ARP. ARP does the conversion of the IP address of a host into its Ethernet address (MAC layer). -In order to allow the communication between two hosts separated by the bridge, it is necessary that the bridge will forward ARP packets. +To allow the communication between two hosts separated by the bridge, it is necessary that the bridge will forward ARP packets. Such protocol is not included in the IP layer, since it exists only with IP over Ethernet. The FreeBSD firewall filters exclusively on the IP layer and therefore all non-IP packets (ARP included) will be forwarded without being filtered, even if the firewall is configured to not permit anything. @@ -161,14 +161,14 @@ At this point, to enable the bridge, you have to execute the following commands The first row specifies which interfaces should be activated by the bridge, the second one will enable the firewall on the bridge and finally the third one will enable the bridge. At this point you should be able to insert the machine between two sets of hosts without compromising any communication abilities between them. -If so, the next step is to add the `net.link.ether.bridge._[blah]_=_[blah]_` portions of these rows to the [.filename]#/etc/sysctl.conf# file, in order to have them execute at startup. +If so, the next step is to add the `net.link.ether.bridge._[blah]_=_[blah]_` portions of these rows to the [.filename]#/etc/sysctl.conf# file, to have them execute at startup. [[filtering-bridges-ipfirewall]] == Configuring The Firewall -Now it is time to create your own file with custom firewall rules, in order to secure the inside network. +Now it is time to create your own file with custom firewall rules, to secure the inside network. There will be some complication in doing this because not all of the firewall functionalities are available on bridged packets. -Furthermore, there is a difference between the packets that are in the process of being forwarded and packets that are being received by the local machine. +Furthermore, there is a difference between the packets that are in the process of being forwarded and packets that are being received by the local machine. In general, incoming packets are run through the firewall only once, not twice as is normally the case; in fact they are filtered only upon receipt, so rules that use `out` or `xmit` will never match. Personally, I use `in via` which is an older syntax, but one that has a sense when you read it. Another limitation is that you are restricted to use only `pass` or `drop` commands for packets filtered by a bridge. @@ -176,7 +176,7 @@ Sophisticated things like `divert`, `forward` or `reject` are not available. Such options can still be used, but only on traffic to or from the bridge machine itself (if it has an IP address). New in FreeBSD 4.0, is the concept of stateful filtering. -This is a big improvement for UDP traffic, which typically is a request going out, followed shortly thereafter by a response with the exact same set of IP addresses and port numbers (but with source and destination reversed, of course). +This is a big improvement for UDP traffic, which typically is a request going out, followed shortly thereafter by a response with the same set of IP addresses and port numbers (but with source and destination reversed, of course). For firewalls that have no statekeeping, there is almost no way to deal with this sort of traffic as a single session. But with a firewall that can "remember" an outgoing UDP packet and, for the next few minutes, allow a response, handling UDP services is trivial. The following example shows how to do it. @@ -267,16 +267,16 @@ But there is a difference: all suspected traffic will be logged. There are two rules for passing SMTP and DNS traffic towards the mail server and the name server, if you have them. Obviously the whole rule set should be flavored to personal taste, this is only a specific example (rule format is described accurately in the man:ipfw[8] man page). -Note that in order for "relay" and "ns" to work, name service lookups must work _before_ the bridge is enabled. +Note that for "relay" and "ns" to work, name service lookups must work _before_ the bridge is enabled. This is an example of making sure that you set the IP on the correct network card. Alternatively it is possible to specify the IP address instead of the host name (required if the machine is IP-less). -People that are used to setting up firewalls are probably also used to either having a `reset` or a `forward` rule for ident packets (TCP port 113). +People that are used to setting up firewalls are probably also used to either having a `reset` or a `forward` rule for ident packets (TCP port 113). Unfortunately, this is not an applicable option with the bridge, so the best thing is to simply pass them to their destination. As long as that destination machine is not running an ident daemon, this is relatively harmless. The alternative is dropping connections on port 113, which creates some problems with services like IRC (the ident probe must timeout). -The only other thing that is a little weird that you may have noticed is that there is a rule to let the bridge machine speak, and another for internal hosts. +The only other thing that is a little weird that you may have noticed is that there is a rule to let the bridge machine speak, and another for internal hosts. Remember that this is because the two sets of traffic will take different paths through the kernel and into the packet filter. The inside net will go through the bridge, while the local machine will use the normal IP stack to speak. Thus the two rules to handle the different cases. diff --git a/documentation/content/en/articles/filtering-bridges/_index.po b/documentation/content/en/articles/filtering-bridges/_index.po new file mode 100644 index 0000000000..987db4a5fc --- /dev/null +++ b/documentation/content/en/articles/filtering-bridges/_index.po @@ -0,0 +1,583 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-01-17 20:35-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/filtering-bridges/_index.adoc:1 +#, no-wrap +msgid "Configuring firewalls and filtering on FreeBSD hosts acting as bridges rather than routers" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/filtering-bridges/_index.adoc:1 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:11 +#, no-wrap +msgid "Filtering Bridges" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:48 +msgid "" +"Often it is useful to divide one physical network (like an Ethernet) into " +"two separate segments without having to create subnets, and use a router to " +"link them together. The device that connects the two networks in this way " +"is called a bridge. A FreeBSD system with two network interfaces is enough " +"to act as a bridge." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:51 +msgid "" +"A bridge works by scanning the addresses of MAC level (Ethernet addresses) " +"of the devices connected to each of its network interfaces and then " +"forwarding the traffic between the two networks only if the source and the " +"destination are on different segments. Under many points of view a bridge " +"is similar to an Ethernet switch with only two ports." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:53 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/filtering-bridges/_index.adoc:57 +#, no-wrap +msgid "Why use a filtering bridge?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:62 +msgid "" +"More and more frequently, thanks to the lowering costs of broad band " +"Internet connections (xDSL) and also because of the reduction of available " +"IPv4 addresses, many companies are connected to the Internet 24 hours on 24 " +"and with few (sometimes not even a power of 2) IP addresses. In these " +"situations it is often desirable to have a firewall that filters incoming " +"and outgoing traffic from and towards Internet, but a packet filtering " +"solution based on router may not be applicable, either due to subnetting " +"issues, the router is owned by the connectivity supplier (ISP), or because " +"it does not support such functionalities. In these scenarios the use of a " +"filtering bridge is highly advised." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:64 +msgid "" +"A bridge-based firewall can be configured and inserted between the xDSL " +"router and your Ethernet hub/switch without any IP numbering issues." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/filtering-bridges/_index.adoc:66 +#, no-wrap +msgid "How to Install" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:71 +msgid "" +"Adding bridge functionalities to a FreeBSD system is not difficult. Since " +"4.5 release it is possible to load such functionalities as modules instead " +"of having to rebuild the kernel, simplifying the procedure a great deal. In " +"the following subsections I will explain both installation ways." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:76 +msgid "" +"_Do not_ follow both instructions: a procedure _excludes_ the other one. " +"Select the best choice according to your needs and abilities." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:82 +msgid "" +"Before going on, be sure to have at least two Ethernet cards that support " +"the promiscuous mode for both reception and transmission, since they must be " +"able to send Ethernet packets with any address, not just their own. " +"Moreover, to have a good throughput, the cards should be PCI bus mastering " +"cards. The best choices are still the Intel EtherExpress(TM) Pro, followed " +"by the 3Com(R) 3c9xx series. To simplify the firewall configuration it may " +"be useful to have two cards of different manufacturers (using different " +"drivers) to distinguish clearly which interface is connected to the router " +"and which to the inner network." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/filtering-bridges/_index.adoc:84 +#, no-wrap +msgid "Kernel Configuration" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:88 +msgid "" +"So you have decided to use the older but well tested installation method. " +"To begin, you have to add the following rows to your kernel configuration " +"file:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:94 +#, no-wrap +msgid "" +"options BRIDGE\n" +"options IPFIREWALL\n" +"options IPFIREWALL_VERBOSE\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:97 +msgid "" +"The first line is to compile the bridge support, the second one is the " +"firewall and the third one is the logging functions of the firewall." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:100 +msgid "" +"Now it is necessary to build and install the new kernel. You may find " +"detailed instructions in the extref:{handbook}[Building and Installing a " +"Custom Kernel, kernelconfig-building] section of the FreeBSD Handbook." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/filtering-bridges/_index.adoc:102 +#, no-wrap +msgid "Modules Loading" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:105 +msgid "" +"If you have chosen to use the new and simpler installation method, the only " +"thing to do now is add the following row to [.filename]#/boot/loader.conf#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:109 +#, no-wrap +msgid "bridge_load=\"YES\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:113 +msgid "" +"In this way, during the system startup, the [.filename]#bridge.ko# module " +"will be loaded together with the kernel. It is not required to add a " +"similar row for the [.filename]#ipfw.ko# module, since it will be loaded " +"automatically after the execution of the steps in the following section." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/filtering-bridges/_index.adoc:115 +#, no-wrap +msgid "Final Preparation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:121 +msgid "" +"Before rebooting to load the new kernel or the required modules (according " +"to the previously chosen installation method), you have to make some changes " +"to the [.filename]#/etc/rc.conf# configuration file. The default rule of " +"the firewall is to reject all IP packets. Initially we will set up an " +"`open` firewall, to verify its operation without any issue related to packet " +"filtering (in case you are going to execute this procedure remotely, such " +"configuration will avoid you to remain isolated from the network). Put " +"these lines in [.filename]#/etc/rc.conf#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:128 +#, no-wrap +msgid "" +"firewall_enable=\"YES\"\n" +"firewall_type=\"open\"\n" +"firewall_quiet=\"YES\"\n" +"firewall_logging=\"YES\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:131 +msgid "" +"The first row will enable the firewall (and will load the module [." +"filename]#ipfw.ko# if it is not compiled in the kernel), the second one to " +"set up it in `open` mode (as explained in [.filename]#/etc/rc.firewall#), " +"the third one to not show rules loading and the fourth one to enable logging " +"support." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:137 +msgid "" +"About the configuration of the network interfaces, the most used way is to " +"assign an IP to only one of the network cards, but the bridge will work " +"equally even if both interfaces or none has a configured IP. In the last " +"case (IP-less) the bridge machine will be still more hidden, as inaccessible " +"from the network: to configure it, you have to login from console or through " +"a third network interface separated from the bridge. Sometimes, during the " +"system startup, some programs require network access, say for domain " +"resolution: in this case it is necessary to assign an IP to the external " +"interface (the one connected to Internet, where DNS server resides), since " +"the bridge will be activated at the end of the startup procedure. It means " +"that the [.filename]#fxp0# interface (in our case) must be mentioned in the " +"ifconfig section of the [.filename]#/etc/rc.conf# file, while the [." +"filename]#xl0# is not. Assigning an IP to both the network cards does not " +"make much sense, unless, during the start procedure, applications should " +"access to services on both Ethernet segments." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:144 +msgid "" +"There is another important thing to know. When running IP over Ethernet, " +"there are actually two Ethernet protocols in use: one is IP, the other is " +"ARP. ARP does the conversion of the IP address of a host into its Ethernet " +"address (MAC layer). To allow the communication between two hosts separated " +"by the bridge, it is necessary that the bridge will forward ARP packets. " +"Such protocol is not included in the IP layer, since it exists only with IP " +"over Ethernet. The FreeBSD firewall filters exclusively on the IP layer and " +"therefore all non-IP packets (ARP included) will be forwarded without being " +"filtered, even if the firewall is configured to not permit anything." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:146 +msgid "" +"Now it is time to reboot the system and use it as before: there will be some " +"new messages about the bridge and the firewall, but the bridge will not be " +"activated and the firewall, being in `open` mode, will not avoid any " +"operations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:148 +msgid "" +"If there are any problems, you should sort them out now before proceeding." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/filtering-bridges/_index.adoc:150 +#, no-wrap +msgid "Enabling the Bridge" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:153 +msgid "" +"At this point, to enable the bridge, you have to execute the following " +"commands (having the shrewdness to replace the names of the two network " +"interfaces [.filename]#fxp0# and [.filename]#xl0# with your own ones):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:159 +#, no-wrap +msgid "" +"# sysctl net.link.ether.bridge.config=fxp0:0,xl0:0\n" +"# sysctl net.link.ether.bridge.ipfw=1\n" +"# sysctl net.link.ether.bridge.enable=1\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:162 +msgid "" +"The first row specifies which interfaces should be activated by the bridge, " +"the second one will enable the firewall on the bridge and finally the third " +"one will enable the bridge." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:165 +msgid "" +"At this point you should be able to insert the machine between two sets of " +"hosts without compromising any communication abilities between them. If so, " +"the next step is to add the `net.link.ether.bridge._[blah]_=_[blah]_` " +"portions of these rows to the [.filename]#/etc/sysctl.conf# file, to have " +"them execute at startup." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/filtering-bridges/_index.adoc:167 +#, no-wrap +msgid "Configuring The Firewall" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:177 +msgid "" +"Now it is time to create your own file with custom firewall rules, to secure " +"the inside network. There will be some complication in doing this because " +"not all of the firewall functionalities are available on bridged packets. " +"Furthermore, there is a difference between the packets that are in the " +"process of being forwarded and packets that are being received by the local " +"machine. In general, incoming packets are run through the firewall only " +"once, not twice as is normally the case; in fact they are filtered only upon " +"receipt, so rules that use `out` or `xmit` will never match. Personally, I " +"use `in via` which is an older syntax, but one that has a sense when you " +"read it. Another limitation is that you are restricted to use only `pass` " +"or `drop` commands for packets filtered by a bridge. Sophisticated things " +"like `divert`, `forward` or `reject` are not available. Such options can " +"still be used, but only on traffic to or from the bridge machine itself (if " +"it has an IP address)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:185 +msgid "" +"New in FreeBSD 4.0, is the concept of stateful filtering. This is a big " +"improvement for UDP traffic, which typically is a request going out, " +"followed shortly thereafter by a response with the same set of IP addresses " +"and port numbers (but with source and destination reversed, of course). For " +"firewalls that have no statekeeping, there is almost no way to deal with " +"this sort of traffic as a single session. But with a firewall that can " +"\"remember\" an outgoing UDP packet and, for the next few minutes, allow a " +"response, handling UDP services is trivial. The following example shows how " +"to do it. It is possible to do the same thing with TCP packets. This " +"allows you to avoid some denial of service attacks and other nasty tricks, " +"but it also typically makes your state table grow quickly in size." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:189 +msgid "" +"Let's look at an example setup. Note first that at the top of [.filename]#/" +"etc/rc.firewall# there are already standard rules for the loopback interface " +"[.filename]#lo0#, so we should not have to care for them anymore. Custom " +"rules should be put in a separate file (say [.filename]#/etc/rc.firewall." +"local#) and loaded at system startup, by modifying the row of [.filename]#/" +"etc/rc.conf# where we defined the `open` firewall:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:193 +#, no-wrap +msgid "firewall_type=\"/etc/rc.firewall.local\"\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:198 +msgid "" +"You have to specify the _full_ path, otherwise it will not be loaded with " +"the risk to remain isolated from the network." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:201 +msgid "" +"For our example imagine to have the [.filename]#fxp0# interface connected " +"towards the outside (Internet) and the [.filename]#xl0# towards the inside " +"(LAN). The bridge machine has the IP `1.2.3.4` (it is not possible that your " +"ISP can give you an address quite like this, but for our example it is good)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:206 +#, no-wrap +msgid "" +"# Things that we have kept state on before get to go through in a hurry\n" +"add check-state\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:211 +#, no-wrap +msgid "" +"# Throw away RFC 1918 networks\n" +"add drop all from 10.0.0.0/8 to any in via fxp0\n" +"add drop all from 172.16.0.0/12 to any in via fxp0\n" +"add drop all from 192.168.0.0/16 to any in via fxp0\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:217 +#, no-wrap +msgid "" +"# Allow the bridge machine to say anything it wants\n" +"# (if the machine is IP-less do not include these rows)\n" +"add pass tcp from 1.2.3.4 to any setup keep-state\n" +"add pass udp from 1.2.3.4 to any keep-state\n" +"add pass ip from 1.2.3.4 to any\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:222 +#, no-wrap +msgid "" +"# Allow the inside hosts to say anything they want\n" +"add pass tcp from any to any in via xl0 setup keep-state\n" +"add pass udp from any to any in via xl0 keep-state\n" +"add pass ip from any to any in via xl0\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:234 +#, no-wrap +msgid "" +"# TCP section\n" +"# Allow SSH\n" +"add pass tcp from any to any 22 in via fxp0 setup keep-state\n" +"# Allow SMTP only towards the mail server\n" +"add pass tcp from any to relay 25 in via fxp0 setup keep-state\n" +"# Allow zone transfers only by the secondary name server [dns2.nic.it]\n" +"add pass tcp from 193.205.245.8 to ns 53 in via fxp0 setup keep-state\n" +"# Pass ident probes. It is better than waiting for them to timeout\n" +"add pass tcp from any to any 113 in via fxp0 setup keep-state\n" +"# Pass the \"quarantine\" range\n" +"add pass tcp from any to any 49152-65535 in via fxp0 setup keep-state\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:240 +#, no-wrap +msgid "" +"# UDP section\n" +"# Allow DNS only towards the name server\n" +"add pass udp from any to ns 53 in via fxp0 keep-state\n" +"# Pass the \"quarantine\" range\n" +"add pass udp from any to any 49152-65535 in via fxp0 keep-state\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:247 +#, no-wrap +msgid "" +"# ICMP section\n" +"# Pass 'ping'\n" +"add pass icmp from any to any icmptypes 8 keep-state\n" +"# Pass error messages generated by 'traceroute'\n" +"add pass icmp from any to any icmptypes 3\n" +"add pass icmp from any to any icmptypes 11\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:250 +#, no-wrap +msgid "" +"# Everything else is suspect\n" +"add drop log all from any to any\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:254 +msgid "" +"Those of you who have set up firewalls before may notice some things " +"missing. In particular, there are no anti-spoofing rules, in fact we did " +"_not_ add:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/filtering-bridges/_index.adoc:258 +#, no-wrap +msgid "add deny all from 1.2.3.4/8 to any in via fxp0\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:264 +msgid "" +"That is, drop packets that are coming in from the outside claiming to be " +"from our network. This is something that you would commonly do to be sure " +"that someone does not try to evade the packet filter, by generating " +"nefarious packets that look like they are from the inside. The problem with " +"that is that there is _at least_ one host on the outside interface that you " +"do not want to ignore: the router. But usually, the ISP anti-spoofs at " +"their router, so we do not need to bother that much." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:267 +msgid "" +"The last rule seems to be an exact duplicate of the default rule, that is, " +"do not let anything pass that is not specifically allowed. But there is a " +"difference: all suspected traffic will be logged." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:273 +msgid "" +"There are two rules for passing SMTP and DNS traffic towards the mail server " +"and the name server, if you have them. Obviously the whole rule set should " +"be flavored to personal taste, this is only a specific example (rule format " +"is described accurately in the man:ipfw[8] man page). Note that for " +"\"relay\" and \"ns\" to work, name service lookups must work _before_ the " +"bridge is enabled. This is an example of making sure that you set the IP on " +"the correct network card. Alternatively it is possible to specify the IP " +"address instead of the host name (required if the machine is IP-less)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:278 +msgid "" +"People that are used to setting up firewalls are probably also used to " +"either having a `reset` or a `forward` rule for ident packets (TCP port " +"113). Unfortunately, this is not an applicable option with the bridge, so " +"the best thing is to simply pass them to their destination. As long as that " +"destination machine is not running an ident daemon, this is relatively " +"harmless. The alternative is dropping connections on port 113, which " +"creates some problems with services like IRC (the ident probe must timeout)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:285 +msgid "" +"The only other thing that is a little weird that you may have noticed is " +"that there is a rule to let the bridge machine speak, and another for " +"internal hosts. Remember that this is because the two sets of traffic will " +"take different paths through the kernel and into the packet filter. The " +"inside net will go through the bridge, while the local machine will use the " +"normal IP stack to speak. Thus the two rules to handle the different " +"cases. The `in via fxp0` rules work for both paths. In general, if you use " +"`in via` rules throughout the filter, you will need to make an exception for " +"locally generated packets, because they did not come in via any of our " +"interfaces." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/filtering-bridges/_index.adoc:287 +#, no-wrap +msgid "Contributors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:291 +msgid "" +"Many parts of this article have been taken, updated and adapted from an old " +"text about bridging, edited by Nick Sayer. A pair of inspirations are due " +"to an introduction on bridging by Steve Peterson." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:293 +msgid "" +"A big thanks to Luigi Rizzo for the implementation of the bridge code in " +"FreeBSD and for the time he has dedicated to me answering all of my related " +"questions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/filtering-bridges/_index.adoc:294 +msgid "" +"A thanks goes out also to Tom Rhodes who looked over my job of translation " +"from Italian (the original language of this article) into English." +msgstr "" diff --git a/documentation/content/en/articles/fonts/_index.po b/documentation/content/en/articles/fonts/_index.po new file mode 100644 index 0000000000..33a5802983 --- /dev/null +++ b/documentation/content/en/articles/fonts/_index.po @@ -0,0 +1,1215 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2022-02-01 09:21-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/fonts/_index.adoc:1 +#, no-wrap +msgid "A description of the various font technologies in FreeBSD, and how to use them with different programs" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/fonts/_index.adoc:1 +#: documentation/content/en/articles/fonts/_index.adoc:12 +#, no-wrap +msgid "Fonts and FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:45 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:48 +msgid "" +"This document contains a description of the various font files that may be " +"used with FreeBSD and the syscons driver, X11, Ghostscript and Groff. " +"Cookbook examples are provided for switching the syscons display to 80x60 " +"mode, and for using type 1 fonts with the above application programs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:50 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/fonts/_index.adoc:54 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:59 +msgid "" +"There are many sources of fonts available, and one might ask how they might " +"be used with FreeBSD. The answer can be found by carefully searching the " +"documentation for the component that one would like to use. This is very " +"time consuming, so this tutorial is an attempt to provide a shortcut for " +"others who might be interested." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/fonts/_index.adoc:61 +#, no-wrap +msgid "Basic Terminology" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:65 +msgid "" +"There are many different font formats and associated font file suffixes. A " +"few that will be addressed here are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:66 +#: documentation/content/en/articles/fonts/_index.adoc:110 +#, no-wrap +msgid "[.filename]#.pfa#, [.filename]#.pfb#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:68 +msgid "" +"PostScript(R) type 1 fonts. The [.filename]#.pfa# is the __A__scii form and " +"[.filename]#.pfb# the __B__inary form." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:69 +#, no-wrap +msgid "[.filename]#.afm#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:71 +msgid "The font metrics associated with a type 1 font." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:72 +#, no-wrap +msgid "[.filename]#.pfm#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:74 +msgid "The printer font metrics associated with a type 1 font." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:75 +#: documentation/content/en/articles/fonts/_index.adoc:116 +#, no-wrap +msgid "[.filename]#.ttf#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:77 +msgid "A TrueType(R) font" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:78 +#, no-wrap +msgid "[.filename]#.fot#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:80 +msgid "An indirect reference to a TrueType font (not an actual font)" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:81 +#, no-wrap +msgid "[.filename]#.fon#, [.filename]#.fnt#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:83 +msgid "Bitmapped screen fonts" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:86 +msgid "" +"The [.filename]#.fot# is used by Windows(R) as sort of a symbolic link to " +"the actual TrueType(R) font ([.filename]#.ttf#) file. The [.filename]#.fon# " +"font files are also used by Windows. I know of no way to use this font " +"format with FreeBSD." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/fonts/_index.adoc:88 +#, no-wrap +msgid "What Font Formats Can I Use?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:94 +msgid "" +"Which font file format is useful depends on the application being used. " +"FreeBSD by itself uses no fonts. Application programs and/or drivers may " +"make use of the font files. Here is a small cross reference of application/" +"driver to the font type suffixes:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:95 +#, no-wrap +msgid "Driver" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:97 +#, no-wrap +msgid "vt" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:99 +msgid "[.filename]#.hex#" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:100 +#, no-wrap +msgid "syscons" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:102 +msgid "[.filename]#.fnt#" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:103 +#, no-wrap +msgid "Application" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:105 +#, no-wrap +msgid "Ghostscript" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:107 +msgid "[.filename]#.pfa#, [.filename]#.pfb#, [.filename]#.ttf#" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:108 +#, no-wrap +msgid "X11" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:111 +#, no-wrap +msgid "Groff" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:113 +msgid "[.filename]#.pfa#, [.filename]#.afm#" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:114 +#, no-wrap +msgid "Povray" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:121 +msgid "" +"The [.filename]#.fnt# suffix is used quite frequently. I suspect that " +"whenever someone wanted to create a specialized font file for their " +"application, more often than not they chose this suffix. Therefore, it is " +"likely that files with this suffix are not all the same format; " +"specifically, the [.filename]#.fnt# files used by syscons under FreeBSD may " +"not be the same format as a [.filename]#.fnt# one encounters in the MS-" +"DOS(R)/Windows(R) environment. I have not made any attempt at using other [." +"filename]#.fnt# files other than those provided with FreeBSD." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/fonts/_index.adoc:123 +#, no-wrap +msgid "Setting a Virtual Console to 80x60 Line Mode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:127 +msgid "" +"First, an 8x8 font must be loaded. To do this, [.filename]#/etc/rc.conf# " +"should contain the line (change the font name to an appropriate one for your " +"locale):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:131 +#, no-wrap +msgid "font8x8=\"iso-8x8\"\t\t# font 8x8 from /usr/share/syscons/fonts/* (or NO).\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:134 +msgid "The command to actually switch the mode is man:vidcontrol[1]:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:138 +#, no-wrap +msgid "% vidcontrol VGA_80x60\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:142 +msgid "" +"Various screen-oriented programs, such as man:vi[1], must be able to " +"determine the current screen dimensions. As this is achieved this through " +"`ioctl` calls to the console driver (such as man:syscons[4]) they will " +"correctly determine the new screen dimensions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:145 +msgid "" +"To make this more seamless, one can embed these commands in the startup " +"scripts so it takes place when the system boots. To do this is add this " +"line to [.filename]#/etc/rc.conf#." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:149 +#, no-wrap +msgid "allscreens_flags=\"VGA_80x60\"\t# Set this vidcontrol mode for all virtual screens\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:152 +msgid "References: man:rc.conf[5], man:vidcontrol[1]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/fonts/_index.adoc:154 +#, no-wrap +msgid "Using Type 1 Fonts with X11" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:159 +msgid "" +"X11 can use either the [.filename]#.pfa# or the [.filename]#.pfb# format " +"fonts. The X11 fonts are located in various subdirectories under [." +"filename]#/usr/X11R6/lib/X11/fonts#. Each font file is cross referenced to " +"its X11 name by the contents of [.filename]#fonts.dir# in each directory." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:165 +msgid "" +"There is already a directory named [.filename]#Type1#. The most straight " +"forward way to add a new font is to put it into this directory. A better " +"way is to keep all new fonts in a separate directory and use a symbolic link " +"to the additional font. This allows one to more easily keep track of ones " +"fonts without confusing them with the fonts that were originally provided. " +"For example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:171 +#, no-wrap +msgid "" +"Create a directory to contain the font files\n" +"% mkdir -p /usr/local/share/fonts/type1\n" +"% cd /usr/local/share/fonts/type1\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:173 +#, no-wrap +msgid "Place the .pfa, .pfb and .afm files here\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:175 +#, no-wrap +msgid "One might want to keep readme files, and other documentation\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:179 +#, no-wrap +msgid "" +"for the fonts here also\n" +"% cp /cdrom/fonts/atm/showboat/showboat.pfb .\n" +"% cp /cdrom/fonts/atm/showboat/showboat.afm .\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:182 +#, no-wrap +msgid "" +"Maintain an index to cross reference the fonts\n" +"% echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:186 +msgid "" +"Now, to use a new font with X11, one must make the font file available and " +"update the font name files. The X11 font names look like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:200 +#, no-wrap +msgid "" +"-bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1\n" +" | | | | | | | | | | | | \\ \\\n" +" | | | | | \\ \\ \\ \\ \\ \\ \\ +----+- character set\n" +" | | | | \\ \\ \\ \\ \\ \\ \\ +- average width\n" +" | | | | \\ \\ \\ \\ \\ \\ +- spacing\n" +" | | | \\\t\\ \\ \\ \\ \\ +- vertical res.\n" +" | | | \\\t \\\t\\ \\ \\ +- horizontal res.\n" +" | | | \\\t \\\t \\ \\ +- points\n" +" | | | \\ \\\t \\ +- pixels\n" +" | | | \\ \\\t \\\n" +" foundry family weight slant width additional style\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:206 +msgid "" +"A new name needs to be created for each new font. If you have some " +"information from the documentation that accompanied the font, then it could " +"serve as the basis for creating the name. If there is no information, then " +"you can get some idea by using man:strings[1] on the font file. For example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:234 +#, no-wrap +msgid "" +"% strings showboat.pfb | more\n" +"%!FontType1-1.0: Showboat 001.001\n" +"%%CreationDate: 1/15/91 5:16:03 PM\n" +"%%VMusage: 1024 45747\n" +"% Generated by Fontographer 3.1\n" +"% Showboat\n" +" 1991 by David Rakowski. Alle Rechte Vorbehalten.\n" +"FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup\n" +"/UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse\n" +"{save true}{false}ifelse}{false}ifelse\n" +"12 dict begin\n" +"/FontInfo 9 dict dup begin\n" +" /version (001.001) readonly def\n" +" /FullName (Showboat) readonly def\n" +" /FamilyName (Showboat) readonly def\n" +" /Weight (Medium) readonly def\n" +" /ItalicAngle 0 def\n" +" /isFixedPitch false def\n" +" /UnderlinePosition -106 def\n" +" /UnderlineThickness 16 def\n" +" /Notice (Showboat\n" +" 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def\n" +"end readonly def\n" +"/FontName /Showboat def\n" +"--stdin--\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:237 +msgid "Using this information, a possible name might be:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:241 +#, no-wrap +msgid "-type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:244 +msgid "The components of our name are:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:245 +#, no-wrap +msgid "Foundry" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:247 +msgid "Lets just name all the new fonts `type1`." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:248 +#, no-wrap +msgid "Family" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:250 +msgid "The name of the font." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:251 +#, no-wrap +msgid "Weight" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:254 +msgid "" +"Normal, bold, medium, semibold, etc. From the man:strings[1] output above, " +"it appears that this font has a weight of __medium__." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:255 +#, no-wrap +msgid "Slant" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:258 +msgid "" +"__r__oman, __i__talic, __o__blique, etc. Since the _ItalicAngle_ is zero, " +"_roman_ will be used." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:259 +#, no-wrap +msgid "Width" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:262 +msgid "" +"Normal, wide, condensed, extended, etc. Until it can be examined, the " +"assumption will be __normal__." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:263 +#, no-wrap +msgid "Additional style" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:265 +msgid "" +"Usually omitted, but this will indicate that the font contains decorative " +"capital letters." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:266 +#, no-wrap +msgid "Spacing" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:269 +msgid "" +"proportional or monospaced. _Proportional_ is used since _isFixedPitch_ is " +"false." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:273 +msgid "" +"All of these names are arbitrary, but one should strive to be compatible " +"with the existing conventions. A font is referenced by name with possible " +"wild cards by an X11 program, so the name chosen should make some sense. " +"One might begin by simply using" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:277 +#, no-wrap +msgid "...-normal-r-normal-...-p-...\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:280 +msgid "" +"as the name, and then use man:xfontsel[1] to examine it and adjust the name " +"based on the appearance of the font." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:282 +msgid "So, to complete our example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:288 +#, no-wrap +msgid "" +"Make the font accessible to X11\n" +"% cd /usr/X11R6/lib/X11/fonts/Type1\n" +"% ln -s /usr/local/share/fonts/type1/showboat.pfb .\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:301 +#, no-wrap +msgid "" +"Edit fonts.dir and fonts.scale, adding the line describing the font\n" +"and incrementing the number of fonts which is found on the first line.\n" +"% ex fonts.dir\n" +":1p\n" +"25\n" +":1c\n" +"26\n" +".\n" +":$a\n" +"showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1\n" +".\n" +":wq\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:304 +#, no-wrap +msgid "" +"fonts.scale seems to be identical to fonts.dir...\n" +"% cp fonts.dir fonts.scale\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:307 +#, no-wrap +msgid "" +"Tell X11 that things have changed\n" +"% xset fp rehash\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:310 +#, no-wrap +msgid "" +"Examine the new font\n" +"% xfontsel -pattern -type1-*\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:313 +msgid "" +"References: man:xfontsel[1], man:xset[1], The X Windows System in a " +"Nutshell, http://www.ora.com/[O'Reilly & Associates]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/fonts/_index.adoc:315 +#, no-wrap +msgid "Using Type 1 Fonts with Ghostscript" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:321 +msgid "" +"Ghostscript references a font via its [.filename]#Fontmap#. This must be " +"modified in a similar way to the X11 [.filename]#fonts.dir#. Ghostscript " +"can use either the [.filename]#.pfa# or the [.filename]#.pfb# format fonts. " +"Using the font from the previous example, here is how to use it with " +"Ghostscript:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:327 +#, no-wrap +msgid "" +"Put the font in Ghostscript's font directory\n" +"% cd /usr/local/share/ghostscript/fonts\n" +"% ln -s /usr/local/share/fonts/type1/showboat.pfb .\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:335 +#, no-wrap +msgid "" +"Edit Fontmap so Ghostscript knows about the font\n" +"% cd /usr/local/share/ghostscript/4.01\n" +"% ex Fontmap\n" +":$a\n" +"/Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat\n" +".\n" +":wq\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:351 +#, no-wrap +msgid "" +"Use Ghostscript to examine the font\n" +"% gs prfont.ps\n" +"Aladdin Ghostscript 4.01 (1996-7-10)\n" +"Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights\n" +"reserved.\n" +"This software comes with NO WARRANTY: see the file PUBLIC for details.\n" +"Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb...\n" +" /1899520 581354 1300084 13826 0 done.\n" +"GS>Showboat DoFont\n" +"Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb...\n" +" 1939688 565415 1300084 16901 0 done.\n" +">>showpage, press <return> to continue<<\n" +">>showpage, press <return> to continue<<\n" +">>showpage, press <return> to continue<<\n" +"GS>quit\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:354 +msgid "References: [.filename]#fonts.txt# in the Ghostscript 4.01 distribution" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/fonts/_index.adoc:356 +#, no-wrap +msgid "Using Type 1 Fonts with Groff" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:363 +msgid "" +"Now that the new font can be used by both X11 and Ghostscript, how can one " +"use the new font with groff? First of all, since we are dealing with type 1 " +"PostScript(R) fonts, the groff device that is applicable is the _ps_ " +"device. A font file must be created for each font that groff can use. A " +"groff font name is just a file in [.filename]#/usr/share/groff_font/devps#. " +"With our example, the font file could be [.filename]#/usr/share/groff_font/" +"devps/SHOWBOAT#. The file must be created using tools provided by groff." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:367 +msgid "" +"The first tool is `afmtodit`. This is not normally installed, so it must be " +"retrieved from the source distribution. I found I had to change the first " +"line of the file, so I did:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:376 +#, no-wrap +msgid "" +"% cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp\n" +"% ex /tmp/afmtodit.pl\n" +":1c\n" +"#!/usr/bin/perl -P-\n" +".\n" +":wq\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:380 +msgid "" +"This tool will create the groff font file from the metrics file ([." +"filename]#.afm# suffix.) Continuing with our example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:388 +#, no-wrap +msgid "" +"Many .afm files are in Mac format... ^M delimited lines\n" +"We need to convert them to UNIX(R) style ^J delimited lines\n" +"% cd /tmp\n" +"% cat /usr/local/share/fonts/type1/showboat.afm |\n" +"\ttr '\\015' '\\012' >showboat.afm\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:392 +#, no-wrap +msgid "" +"Now create the groff font file\n" +"% cd /usr/share/groff_font/devps\n" +"% /tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:395 +msgid "The font can now be referenced with the name SHOWBOAT." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:402 +msgid "" +"If Ghostscript is used to drive the printers on the system, then nothing " +"more needs to be done. However, if true PostScript(R) printers are used, " +"then the font must be downloaded to the printer in order for the font to be " +"used (unless the printer happens to have the showboat font built in or on an " +"accessible font disk.) The final step is to create a downloadable font. " +"The `pfbtops` tool is used to create the [.filename]#.pfa# format of the " +"font, and [.filename]#download# is modified to reference the new font. The " +"[.filename]#download# must reference the internal name of the font. This " +"can easily be determined from the groff font file as illustrated:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:407 +#, no-wrap +msgid "" +"Create the .pfa font file\n" +"% pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:410 +msgid "" +"Of course, if [.filename]#.pfa# is already available, just use a symbolic " +"link to reference it." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:422 +#, no-wrap +msgid "" +"Get the internal font name\n" +"% fgrep internalname SHOWBOAT\n" +"internalname Showboat\n" +"Tell groff that the font must be downloaded\n" +"% ex download\n" +":$a\n" +"Showboat showboat.pfa\n" +".\n" +":wq\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:425 +msgid "To test the font:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:456 +#, no-wrap +msgid "" +"% cd /tmp\n" +"% cat >example.t <<EOF\n" +".sp 5\n" +".ps 16\n" +"This is an example of the Showboat font:\n" +".br\n" +".ps 48\n" +".vs (\\n(.s+2)p\n" +".sp\n" +".ft SHOWBOAT\n" +"ABCDEFGHI\n" +".br\n" +"JKLMNOPQR\n" +".br\n" +"STUVWXYZ\n" +".sp\n" +".ps 16\n" +".vs (\\n(.s+2)p\n" +".fp 5 SHOWBOAT\n" +".ft R\n" +"To use it for the first letter of a paragraph, it will look like:\n" +".sp 50p\n" +"\\s(48\\f5H\\s0\\fRere is the first sentence of a paragraph that uses the\n" +"showboat font as its first letter.\n" +"Additional vertical space must be used to allow room for the larger\n" +"letter.\n" +"EOF\n" +"% groff -Tps example.t >example.ps\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:459 +#, no-wrap +msgid "" +"To use ghostscript/ghostview\n" +"% ghostview example.ps\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:462 +#, no-wrap +msgid "" +"To print it\n" +"% lpr -Ppostscript example.ps\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:465 +msgid "" +"References: [.filename]#/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man#, " +"man:groff_font[5], man:groff_char[7], man:pfbtops[1]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/fonts/_index.adoc:467 +#, no-wrap +msgid "Converting TrueType Fonts to a groff/PostScript Format For groff" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:471 +msgid "" +"This potentially requires a bit of work, simply because it depends on some " +"utilities that are not installed as part of the base system. They are:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:472 +#, no-wrap +msgid "`ttf2pf`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:475 +msgid "" +"TrueType to PostScript conversion utilities. This allows conversion of a " +"TrueType font to an ascii font metric ([.filename]#.afm#) file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:479 +msgid "" +"Currently available at http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/" +"ttf2pf/[http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/]. " +"Note: These files are PostScript programs and must be downloaded to disk by " +"holding down kbd:[Shift] when clicking on the link. Otherwise, your browser " +"may try to launch ghostview to view them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:481 +msgid "The files of interest are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:483 +msgid "[.filename]#GS_TTF.PS#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:484 +msgid "[.filename]#PF2AFM.PS#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:485 +msgid "[.filename]#ttf2pf.ps#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:491 +msgid "" +"The funny upper/lower case is due to their being intended also for DOS " +"shells. [.filename]#ttf2pf.ps# makes use of the others as upper case, so " +"any renaming must be consistent with this. (Actually, [.filename]#GS_TTF." +"PS# and [.filename]#PFS2AFM.PS# are supposedly part of the Ghostscript " +"distribution, but it is just as easy to use these as an isolated utility. " +"FreeBSD does not seem to include the latter.) You also may want to have " +"these installed to [.filename]#/usr/local/share/groff_font/devps#(?)." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/fonts/_index.adoc:492 +#, no-wrap +msgid "`afmtodit`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:495 +msgid "" +"Creates font files for use with groff from ascii font metrics file. This " +"usually resides in the directory, [.filename]#/usr/src/contrib/groff/" +"afmtodit#, and requires some work to get going." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/fonts/_index.adoc:499 +msgid "" +"If you are paranoid about working in the [.filename]#/usr/src# tree, simply " +"copy the contents of the above directory to a work location." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:503 +msgid "In the work area, you will need to make the utility. Just type:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:507 +#, no-wrap +msgid "# make -f Makefile.sub afmtodit\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:510 +msgid "" +"You may also need to copy [.filename]#/usr/contrib/groff/devps/generate/" +"textmap# to [.filename]#/usr/share/groff_font/devps/generate# if it does not " +"already exist." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:512 +msgid "Once all these utilities are in place, you are ready to commence:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:514 +msgid "Create [.filename]#.afm# by typing:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:518 +#, no-wrap +msgid "% gs -dNODISPLAY -q -- ttf2pf.ps TTF_name PS_font_name AFM_name\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:521 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:524 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:526 +msgid "" +"For example, to convert the 30f9 Barcode font using the default file names, " +"use the following command:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:534 +#, no-wrap +msgid "" +"% gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf\n" +"Aladdin Ghostscript 5.10 (1997-11-23)\n" +"Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved.\n" +"This software comes with NO WARRANTY: see the file PUBLIC for details.\n" +"Converting 3of9.ttf to 3of9.pfa and 3of9.afm.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:537 +msgid "" +"If you want the converted fonts to be stored in [.filename]#A.pfa# and [." +"filename]#B.afm#, then use this command:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:545 +#, no-wrap +msgid "" +"% gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf A B\n" +"Aladdin Ghostscript 5.10 (1997-11-23)\n" +"Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved.\n" +"This software comes with NO WARRANTY: see the file PUBLIC for details.\n" +"Converting 3of9.ttf to A.pfa and B.afm.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:548 +msgid "Create the groff PostScript file:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:552 +msgid "" +"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.)" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:556 +#, no-wrap +msgid "% afmtodit -d DESC -e text.enc file.afm generate/textmap PS_font_name\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:560 +msgid "" +"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:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/fonts/_index.adoc:564 +#, no-wrap +msgid "% afmtodit -d DESC -e text.enc 3of9.afm generate/textmap 3of9\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:567 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:570 +msgid "" +"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]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/fonts/_index.adoc:572 +#, no-wrap +msgid "Can TrueType Fonts be Used with Other Programs?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:576 +msgid "" +"The TrueType font format is used by Windows, Windows 95, and Mac's. It is " +"quite popular and there are a great number of fonts available in this format." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:580 +msgid "" +"Unfortunately, there are few applications that I am aware of that can use " +"this format: Ghostscript and Povray come to mind. Ghostscript's support, " +"according to the documentation, is rudimentary and the results are likely to " +"be inferior to type 1 fonts. Povray version 3 also has the ability to use " +"TrueType fonts, but I rather doubt many people will be creating documents as " +"a series of raytraced pages :-)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:583 +msgid "" +"This rather dismal situation may soon change. The http://www.freetype.org/" +"[FreeType Project] is currently developing a useful set of FreeType tools:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:585 +msgid "" +"The `xfsft` font server for X11 can serve TrueType fonts in addition to " +"regular fonts. Though currently in beta, it is said to be quite usable. See " +"http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/[Juliusz Chroboczek's page] " +"for further information. Porting instructions for FreeBSD can be found at " +"http://math.missouri.edu/~stephen/software/[Stephen Montgomery's software " +"page]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:586 +msgid "" +"xfstt is another font server for X11, available under link:ftp://sunsite.unc." +"edu/pub/Linux/X11/fonts/[ftp://sunsite.unc.edu/pub/Linux/X11/fonts/]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:587 +msgid "" +"A program called `ttf2bdf` can produce BDF files suitable for use in an X " +"environment from TrueType files. Linux binaries are said to be available " +"from link:ftp://crl.nmsu.edu/CLR/multiling/General/[ftp://crl.nmsu.edu/CLR/" +"multiling/General/]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:588 +msgid "and others ..." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/fonts/_index.adoc:590 +#, no-wrap +msgid "Where Can Additional Fonts be Obtained?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:595 +msgid "" +"Many fonts are available on the Internet. They are either entirely free, or " +"are share-ware. In addition many fonts are available in the [.filename]#x11-" +"fonts/# category in the ports collection" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/fonts/_index.adoc:597 +#, no-wrap +msgid "Additional Questions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:600 +msgid "What use are the [.filename]#.pfm# files?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:601 +msgid "" +"Can one generate the [.filename]#.afm# from a [.filename]#.pfa# or [." +"filename]#.pfb#?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:602 +msgid "" +"How to generate the groff character mapping files for PostScript fonts with " +"non-standard character names?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:603 +msgid "Can xditview and devX?? devices be set up to access all the new fonts?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/fonts/_index.adoc:603 +msgid "" +"It would be good to have examples of using TrueType fonts with Povray and " +"Ghostscript." +msgstr "" diff --git a/documentation/content/en/articles/freebsd-questions/_index.adoc b/documentation/content/en/articles/freebsd-questions/_index.adoc index 426b20577f..052c202ffd 100644 --- a/documentation/content/en/articles/freebsd-questions/_index.adoc +++ b/documentation/content/en/articles/freebsd-questions/_index.adoc @@ -101,7 +101,7 @@ The following criteria should help for 99% of all questions, however: . If the question relates to a bug, and you are _sure_ that it is a bug (for example, you can pinpoint the place in the code where it happens, and you maybe have a fix), then send the message to `FreeBSD-hackers`. . If the question relates to enhancements to FreeBSD, and you can make suggestions about how to implement them, then send the message to `FreeBSD-hackers`. -There are also a number of other extref:{handbook}[specialized mailing lists, eresources-mail], which caters to more specific interests. +There are also a number of other extref:{handbook}eresources[specialized mailing lists, eresources-mail], which caters to more specific interests. The criteria above still apply, and it is in your interest to stick to them, since you are more likely to get good results that way. == Before Submitting a Question @@ -110,7 +110,7 @@ You can (and should) do some things yourself before asking a question on one of * Try solving the problem on your own. If you post a question which shows that you have tried to solve the problem, your question will generally attract more positive attention from people reading it. Trying to solve the problem yourself will also enhance your understanding of FreeBSD, and will eventually let you use your knowledge to help others by answering questions posted to the mailing lists. * Read the manual pages, and the FreeBSD documentation (either installed in [.filename]#/usr/doc# or accessible via WWW at http://www.FreeBSD.org[http://www.FreeBSD.org]), especially the extref:{handbook}[handbook] and the extref:{faq}[FAQ]. -* Browse and/or search the archives for the mailing list, to see if your question or a similar one has been asked (and possibly answered) on the list. You can browse and/or search the mailing list archives at https://www.FreeBSD.org/mail[https://www.FreeBSD.org/mail] and https://www.FreeBSD.org/search/#mailinglists[https://www.FreeBSD.org/search/#mailinglists] respectively. This can be done at other WWW sites as well, for example at http://marc.theaimsgroup.com[http://marc.theaimsgroup.com]. +* Browse and/or search the archives for the mailing list, to see if your question or a similar one has been asked (and possibly answered) on the list. You can browse and/or search the mailing list archives at https://www.FreeBSD.org/mail[https://www.FreeBSD.org/mail] and https://www.FreeBSD.org/search/#mailinglists[https://www.FreeBSD.org/search/#mailinglists] respectively. * Use a search engine such as http://www.google.com[Google] or http://www.yahoo.com[Yahoo] to find answers to your question. == How to Submit a Question diff --git a/documentation/content/en/articles/freebsd-questions/_index.po b/documentation/content/en/articles/freebsd-questions/_index.po new file mode 100644 index 0000000000..9856b90616 --- /dev/null +++ b/documentation/content/en/articles/freebsd-questions/_index.po @@ -0,0 +1,683 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2023-09-09 18:13-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: Title = +#: documentation/content/en/articles/freebsd-questions/_index.adoc:1 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:11 +#, no-wrap +msgid "How to get Best Results from the FreeBSD-questions Mailing List" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:47 +msgid "" +"This document provides useful information for people looking to prepare an e-" +"mail to the FreeBSD-questions mailing list. Advice and hints are given that " +"will maximize the chance that the reader will receive useful replies." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:49 +msgid "" +"This document is regularly posted to the FreeBSD-questions mailing list." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:51 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-questions/_index.adoc:54 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:58 +msgid "" +"`FreeBSD-questions` is a mailing list maintained by the FreeBSD project to " +"help people who have questions about the normal use of FreeBSD. Another " +"group, `FreeBSD-hackers`, discusses more advanced questions such as future " +"development work." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:65 +msgid "" +"The term \"hacker\" has nothing to do with breaking into other people's " +"computers. The correct term for the latter activity is \"cracker\", but the " +"popular press has not found out yet. The FreeBSD hackers disapprove " +"strongly of cracking security, and have nothing to do with it. For a longer " +"description of hackers, see Eric Raymond's http://www.catb.org/~esr/faqs/" +"hacker-howto.html[How To Become A Hacker]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:68 +msgid "" +"This is a regular posting aimed to help both those seeking advice from " +"FreeBSD-questions (the \"newcomers\"), and also those who answer the " +"questions (the \"hackers\")." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:72 +msgid "" +"Inevitably there is some friction, which stems from the different viewpoints " +"of the two groups. The newcomers accuse the hackers of being arrogant, " +"stuck-up, and unhelpful, while the hackers accuse the newcomers of being " +"stupid, unable to read plain English, and expecting everything to be handed " +"to them on a silver platter. Of course, there is an element of truth in " +"both these claims, but for the most part these viewpoints come from a sense " +"of frustration." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:75 +msgid "" +"In this document, I would like to do something to relieve this frustration " +"and help everybody get better results from FreeBSD-questions. In the " +"following section, I recommend how to submit a question; after that, we will " +"look at how to answer one." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-questions/_index.adoc:76 +#, no-wrap +msgid "How to Subscribe to FreeBSD-questions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:82 +msgid "" +"FreeBSD-questions is a mailing list, so you need mail access. Point your " +"WWW browser to the {freebsd-questions}. In the section titled \"Subscribe " +"or unsubscribe online\" fill in the \"Your email address\" field and hit " +"\"Subscribe\". Or send an email to freebsd-questions+subscribe@freebsd.org." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:84 +msgid "" +"You will receive a confirmation message from mlmmj; follow the included " +"instructions to complete your subscription." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-questions/_index.adoc:85 +#, no-wrap +msgid "How to Unsubscribe from FreeBSD-questions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:90 +msgid "" +"Point your WWW browser to the {freebsd-questions}. In the section titled " +"\"Subscribe or unsubscribe online\" fill in the \"Your email address\" field " +"and hit \"Unsubscribe\". Or send an email to freebsd-" +"questions+unsubscribe@freebsd.org." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:92 +msgid "" +"A confirmation message will be sent to you from mlmmj; follow the included " +"instructions to finish unsubscribing." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-questions/_index.adoc:93 +#, no-wrap +msgid "Should I ask `-questions` or `-hackers`?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:98 +msgid "" +"Two mailing lists handle general questions about FreeBSD, `FreeBSD-" +"questions` and `FreeBSD-hackers`. In some cases, it is not really clear " +"which group you should ask. The following criteria should help for 99% of " +"all questions, however:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:100 +msgid "" +"If the question is of a general nature, ask `FreeBSD-questions`. Examples " +"might be questions about installing FreeBSD or the use of a particular " +"UNIX(R) utility." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:101 +msgid "" +"If you think the question relates to a bug, but you are not sure, or you do " +"not know how to look for it, send the message to `FreeBSD-questions`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:102 +msgid "" +"If the question relates to a bug, and you are _sure_ that it is a bug (for " +"example, you can pinpoint the place in the code where it happens, and you " +"maybe have a fix), then send the message to `FreeBSD-hackers`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:103 +msgid "" +"If the question relates to enhancements to FreeBSD, and you can make " +"suggestions about how to implement them, then send the message to `FreeBSD-" +"hackers`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:106 +msgid "" +"There are also a number of other extref:{handbook}[specialized mailing " +"lists, eresources-mail], which caters to more specific interests. The " +"criteria above still apply, and it is in your interest to stick to them, " +"since you are more likely to get good results that way." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-questions/_index.adoc:107 +#, no-wrap +msgid "Before Submitting a Question" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:110 +msgid "" +"You can (and should) do some things yourself before asking a question on one " +"of the mailing lists:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:112 +msgid "" +"Try solving the problem on your own. If you post a question which shows that " +"you have tried to solve the problem, your question will generally attract " +"more positive attention from people reading it. Trying to solve the problem " +"yourself will also enhance your understanding of FreeBSD, and will " +"eventually let you use your knowledge to help others by answering questions " +"posted to the mailing lists." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:113 +msgid "" +"Read the manual pages, and the FreeBSD documentation (either installed in [." +"filename]#/usr/doc# or accessible via WWW at http://www.FreeBSD.org[http://" +"www.FreeBSD.org]), especially the extref:{handbook}[handbook] and the extref:" +"{faq}[FAQ]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:114 +msgid "" +"Browse and/or search the archives for the mailing list, to see if your " +"question or a similar one has been asked (and possibly answered) on the " +"list. You can browse and/or search the mailing list archives at https://www." +"FreeBSD.org/mail[https://www.FreeBSD.org/mail] and https://www.FreeBSD.org/" +"search/#mailinglists[https://www.FreeBSD.org/search/#mailinglists] " +"respectively." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:115 +msgid "" +"Use a search engine such as http://www.google.com[Google] or http://www." +"yahoo.com[Yahoo] to find answers to your question." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-questions/_index.adoc:116 +#, no-wrap +msgid "How to Submit a Question" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:119 +msgid "" +"When submitting a question to FreeBSD-questions, consider the following " +"points:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:121 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:122 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:123 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:126 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:129 +msgid "" +"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:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:131 +msgid "exmh" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:132 +msgid "Microsoft(R) Exchange" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:133 +msgid "Microsoft(R) Outlook(R)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:135 +msgid "" +"Try not to use MIME: a lot of people use mailers which do not get on very " +"well with MIME." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:136 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:137 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:138 +msgid "" +"Specify as much information as possible. This is a difficult area, and we " +"need to expand on what information you need to submit, but here is a start:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:140 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:141 +msgid "" +"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?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:143 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:144 +msgid "" +"If you get error messages, do not say \"I get error messages\", say (for " +"example) \"I get the error message 'No route to host'\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:145 +msgid "" +"If your system panics, do not say \"My system panicked\", say (for example) " +"\"my system panicked with the message 'free vnode isn't'\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:146 +msgid "" +"If you have difficulty installing FreeBSD, please tell us what hardware you " +"have. In particular, it is important to know the IRQs and I/O addresses of " +"the boards installed in your machine." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:147 +msgid "" +"If you have difficulty getting PPP to run, describe the configuration. Which " +"version of PPP do you use? What kind of authentication do you have? Do you " +"have a static or dynamic IP address? What kind of messages do you get in the " +"log file?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:149 +msgid "" +"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; it is a real pain, and 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 man:dmesg[8], redirect the output to a file and " +"include that. For example," +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:153 +#, no-wrap +msgid "% dmesg > /tmp/dmesg.out\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:156 +msgid "This redirects the information to the file [.filename]#/tmp/dmesg.out#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:157 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-questions/_index.adoc:160 +msgid "" +"To summarize, let's assume you know the answer to the following question " +"(yes, it is the same one in each case). You choose which of these two " +"questions you would be more prepared to answer:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/freebsd-questions/_index.adoc:161 +#, no-wrap +msgid "Message 1" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:171 +#, no-wrap +msgid "" +"Subject: HELP!!?!??\n" +"I just can't get hits damn silly FereBSD system to\n" +"workd, and Im really good at this tsuff, but I have never seen\n" +"anythign sho difficult to install, it jst wont work whatever I try\n" +"so why don't you guys tell me what I doing wrong.\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/freebsd-questions/_index.adoc:174 +#, no-wrap +msgid "Message 2" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:180 +#, no-wrap +msgid "Subject: Problems installing FreeBSD\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:187 +#, no-wrap +msgid "" +"I've just got the FreeBSD 2.1.5 CDROM from Walnut Creek, and I'm having a lot\n" +"of difficulty installing it. I have a 66 MHz 486 with 16 MB of\n" +"memory and an Adaptec 1540A SCSI board, a 1.2GB Quantum Fireball\n" +"disk and a Toshiba 3501XA CDROM drive. The installation works just\n" +"fine, but when I try to reboot the system, I get the message\n" +"Missing Operating System.\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-questions/_index.adoc:190 +#, no-wrap +msgid "How to Follow up to a Question" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:195 +msgid "" +"Often you will want to send in additional information to a question you have " +"already sent. The best way to do this is to reply to your original " +"message. This has three advantages:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:197 +msgid "" +"You include the original message text, so people will know what you are " +"talking about. Do not forget to trim unnecessary text out, though." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:198 +msgid "" +"The text in the subject line stays the same (you did remember to put one in, " +"did you not?). Many mailers will sort messages by subject. This helps group " +"messages together." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:199 +msgid "" +"The message reference numbers in the header will refer to the previous " +"message. Some mailers, such as http://www.mutt.org/[mutt], can _thread_ " +"messages, showing the exact relationships between the messages." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-questions/_index.adoc:200 +#, no-wrap +msgid "How to Answer a Question" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:203 +msgid "Before you answer a question to FreeBSD-questions, consider:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:205 +msgid "" +"A lot of the points on submitting questions also apply to answering " +"questions. Read them." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:206 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:209 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:210 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:211 +msgid "" +"Are you sure you understand the question? Very frequently, the person who " +"asks the question is confused or does not express themselves very well. Even " +"with the best understanding of the system, it is easy to send a reply which " +"does not answer the question. This does not help: you will leave the person " +"who submitted the question more frustrated or confused than ever. If nobody " +"else answers, and you are not too sure either, you can always ask for more " +"information." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:212 +msgid "" +"Are you sure your answer is correct? If not, wait a day or so. If nobody " +"else comes up with a better answer, you can still reply and say, for " +"example, \"I do not know if this is correct, but since nobody else has " +"replied, why don't you try replacing your ATAPI CDROM with a frog?\"." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:213 +msgid "" +"Unless there is a good reason to do otherwise, reply to the sender and to " +"FreeBSD-questions. Many people on the FreeBSD-questions are \"lurkers\": " +"they learn by reading messages sent and replied to by others. If you take a " +"message which is of general interest off the list, you are depriving these " +"people of their information. Be careful with group replies; lots of people " +"send messages with hundreds of CCs. If this is the case, be sure to trim the " +"Cc: lines appropriately." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:214 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:215 +msgid "" +"Use some technique to identify which text came from the original message, " +"and which text you add. I personally find that prepending \"`>`\" to the " +"original message works best. Leaving white space after the \"`> ;`\" and " +"leave empty lines between your text and the original text both make the " +"result more readable." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:216 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:217 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:218 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:221 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-questions/_index.adoc:223 +msgid "" +"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." +msgstr "" diff --git a/documentation/content/en/articles/freebsd-releng/_index.adoc b/documentation/content/en/articles/freebsd-releng/_index.adoc index 86d34f3ba1..60460d3c92 100644 --- a/documentation/content/en/articles/freebsd-releng/_index.adoc +++ b/documentation/content/en/articles/freebsd-releng/_index.adoc @@ -9,7 +9,7 @@ organizations: - organization: Rubicon Communications, LLC (Netgate) webpage: https://www.netgate.com/ description: Describes the approach used by the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System. It describes the tools available for those interested in producing customized FreeBSD releases for corporate rollouts or commercial productization -trademarks: ["freebsd", "intel", "general"] +trademarks: ["freebsd", "intel", "general", "git"] tags: ["releases", "engineering", "process", "FreeBSD"] --- @@ -28,13 +28,13 @@ tags: ["releases", "engineering", "process", "FreeBSD"] :teamPostmaster: FreeBSD Postmaster Team :teamRe: FreeBSD Release Engineering Team :teamSecteam: FreeBSD Security Team -:branchHead: head/ +:branchHead: main :branchStable: stable/ -:branchStablex: stable/12/ +:branchStablex: stable/13 :branchReleng: releng/ -:branchRelengx: releng/12.0/ -:branchReleasex: release/12.0.0/ -:branchRevision: 12.0 +:branchRelengx: releng/13.0 +:tagReleasex: release/13.0.0 +:branchRevision: 13.0 :images-path: articles/freebsd-releng/ @@ -63,11 +63,6 @@ Abstract This article describes the release engineering process of the FreeBSD Project. -[NOTE] -==== -This document has not yet been updated to describe the current release procedures of the FreeBSD Release Engineering team following the transition from Subversion to Git. -==== - ''' toc::[] @@ -83,7 +78,7 @@ The default minimum timeframe before merging to {branchStable} branches is three Although a general rule to wait a minimum of three days before merging from {branchHead}, there are a few special circumstances where an immediate merge may be necessary, such as a critical security fix, or a bug fix that directly inhibits the release build process. -After several months, and the number of changes in the {branchStable} branch have grown significantly, it is time to release the next version of FreeBSD. +After several months, and the number of changes in the {branchStable} branch have grown significantly, it is time to release the next version of FreeBSD. These releases have been historically referred to as "point" releases. In between releases from the {branchStable} branches, approximately every two (2) years, a release will be cut directly from {branchHead}. @@ -93,28 +88,28 @@ This article will highlight the workflow and responsibilities of the {teamRe} fo The following sections of this article describe: -<<releng-prep>>:: +crossref:freebsd-releng[releng-prep, General Information and Preparation]:: General information and preparation before starting the release cycle. -<<releng-website>>:: +crossref:freebsd-releng[releng-website, Website Changes During the Release Cycle]:: Website Changes During the Release Cycle -<<releng-terms>>:: +crossref:freebsd-releng[releng-terms, Release Engineering Terminology]:: Terminology and general information, such as the "code slush" and "code freeze", used throughout this document. -<<releng-head>>:: +crossref:freebsd-releng[releng-head, Release from {branchHead}]:: The Release Engineering process for a "dot-zero" release. -<<releng-stable>>:: +crossref:freebsd-releng[releng-stable, Release from {branchStable}]:: The Release Engineering process for a "point" release. -<<releng-building>>:: +crossref:freebsd-releng[releng-building, Building FreeBSD Installation Media]:: Information related to the specific procedures to build installation medium. -<<releng-mirrors>>:: +crossref:freebsd-releng[releng-mirrors, Publishing FreeBSD Installation Media to Project Mirrors]:: Procedures to publish installation medium. -<<releng-wrapup>>:: +crossref:freebsd-releng[releng-wrapup, Wrapping up the Release Cycle]:: Wrapping up the release cycle. [[releng-prep]] @@ -221,7 +216,7 @@ For example, a FreeBSD developer may request blanket approvals from the start of [NOTE] ==== -In order to keep track of blanket approvals, the {teamRe} uses an internal repository to keep a running log of such requests, which defines the area upon which a blanket approval was granted, the author(s), when the blanket approval expires, and the reason the approval was granted. +To keep track of blanket approvals, the {teamRe} uses an internal repository to keep a running log of such requests, which defines the area upon which a blanket approval was granted, the author(s), when the blanket approval expires, and the reason the approval was granted. One example of this is granting blanket approval to [.filename]#release/doc/# to all {teamRe} members until the final `RC` to update the release notes and other release-related documentation. ==== @@ -266,13 +261,10 @@ The code slush does not enforce commit approvals to the branch. The code freeze marks the point in time where all commits to the branch require explicit approval from the {teamRe}. -The FreeBSD Subversion repository contains several hooks to perform sanity checks before any commit is actually committed to the tree. +The FreeBSD Git repository contains several hooks to perform sanity checks before any commit is actually committed to the tree. One of these hooks will evaluate if committing to a particular branch requires specific approval. -To enforce commit approvals by the {teamRe}, the Release Engineer updates [.filename]#base/svnadmin/conf/approvers#, and commits the change back to the repository. -Once this is done, any change to the branch must include an "Approved by:" line in the commit message. - -The "Approved by:" line must match the second column in [.filename]#base/svnadmin/conf/approvers#, otherwise the commit will be rejected by the repository hooks. +To enforce commit approvals by the {teamRe}, the Release Engineering Team must approve any changes to the branch, in which case the commit log must include an `Approved by: re (login)` line, where "login" is the login ID of the approver. [NOTE] ==== @@ -292,13 +284,13 @@ This section describes the changes to the website that should occur as the relea [NOTE] ==== -The files specified throughout this section are relative to the `head/` branch of the `doc` repository in Subversion. +The files specified throughout this section are relative to the `{branchHead}` branch of the `doc` repository. ==== [[releng-website-prerelease]] === Website Changes Before the Release Cycle Begins -When the release cycle schedule is available, these files need to be updated to enable various different functionalities on the FreeBSD Project website: +When the release cycle schedule is available, these files need to be updated to enable different functionalities on the FreeBSD Project website: [.informaltable] [cols="1,1", frame="none", options="header"] @@ -325,7 +317,7 @@ When transitioning from `PRERELEASE` to `BETA`, these files need to be updated t | File to Edit | What to Change -|[.filename]#share/releases.adoc# +|[.filename]#~/shared/releases.adoc# |Update `betarel-vers` to `BETA__1__` |[.filename]#~/website/data/en/news/news.toml# @@ -338,11 +330,7 @@ When transitioning from `PRERELEASE` to `BETA`, these files need to be updated t |Add the new `BETA`, `RC`, or final `RELEASE` to the template |=== -Once the {branchRelengx} branch is created, the various release-related documents need to be generated and manually added to the `doc/` repository. - -Within [.filename]#release/doc#, invoke to generate [.filename]#errata.html#, [.filename]#hardware.html#, [.filename]#readme.html#, and [.filename]#relnotes.html# pages, which are then added to [.filename]#doc/head/en_US.ISO8859-1/htdocs/releases/X.YR/#, where _X.Y_ represents the major and minor version number of the release. - -The `fbsd:nokeywords` property must be set to `on` on the newly-added files before the pre-commit hooks will allow them to be added to the repository. +Once the {branchRelengx} branch is created, the various release-related documents need to be added to the `doc/` repository. [NOTE] ==== @@ -373,21 +361,26 @@ FreeBSD `ALPHA` snapshots should be built approximately once a week. For the first `ALPHA` build, the `BRANCH` value in [.filename]#sys/conf/newvers.sh# needs to be changed from `CURRENT` to `ALPHA1`. For subsequent `ALPHA` builds, increment each `ALPHA__N__` value by one. -See <<releng-building>> for information on building the `ALPHA` images. +See crossref:freebsd-releng[releng-building, Building FreeBSD Installation Media] for information on building the `ALPHA` images. [[releng-head-branching]] === Creating the {branchStablex} Branch When creating the {branchStable} branch, several changes are required in both the new {branchStable} branch and the {branchHead} branch. The files listed are relative to the repository root. -To create the new {branchStablex} branch in Subversion: +To create the new {branchStablex} branch in Git: + +[NOTE] +==== +Make sure that you are in the {branchHead} branch +==== [source,shell,subs="attributes"] .... -% svn cp ^/head {branchStablex} +% git checkout -b {branchStablex} .... -Once the {branchStablex} branch has been committed, make the following edits: +Once the {branchStablex} branch has been created, make the following edits: [.informaltable] [cols="1,1", frame="none", options="header"] @@ -395,10 +388,10 @@ Once the {branchStablex} branch has been committed, make the following edits: | File to Edit | What to Change -|[.filename]#stable/12/UPDATING# +|[.filename]#UPDATING# |Update the FreeBSD version, and remove the notice about `WITNESS` -|[.filename]#stable/12/contrib/jemalloc/include/jemalloc/jemalloc_FreeBSD.h# +|[.filename]#contrib/jemalloc/include/jemalloc/jemalloc_FreeBSD.h# a| [source,shell,subs="attributes"] @@ -408,37 +401,37 @@ a| #endif .... -|[.filename]#stable/12/lib/clang/llvm.build.mk# +|[.filename]#lib/clang/llvm.build.mk# |Uncomment `-DNDEBUG` -|[.filename]#stable/12/sys/\*/conf/GENERIC*# +|[.filename]#sys/\*/conf/GENERIC*# |Remove debugging support -|[.filename]#stable/12/sys/*/conf/MINIMAL# +|[.filename]#sys/*/conf/MINIMAL# |Remove debugging support -|[.filename]#stable/12/release/release.conf.sample# +|[.filename]#release/release.conf.sample# |Update `SRCBRANCH` -|[.filename]#stable/12/sys/*/conf/GENERIC-NODEBUG# +|[.filename]#sys/*/conf/GENERIC-NODEBUG# |Remove these kernel configurations -|[.filename]#stable/12/sys/arm/conf/std.arm*# +|[.filename]#sys/arm/conf/std.arm*# |Remove debugging options -|[.filename]#stable/12/sys/conf/newvers.sh# +|[.filename]#sys/conf/newvers.sh# |Update the `BRANCH` value to reflect `BETA1` -|[.filename]#stable/12/share/mk/src.opts.mk# +|[.filename]#share/mk/src.opts.mk# |Move `REPRODUCIBLE_BUILD` from `\__DEFAULT_NO_OPTIONS` to `__DEFAULT_YES_OPTIONS` -|[.filename]#stable/12/share/mk/src.opts.mk# -|Move `LLVM_ASSERTIONS` from `\__DEFAULT_YES_OPTIONS` to `__DEFAULT_NO_OPTIONS` (FreeBSD 13.x and later only) +|[.filename]#share/mk/src.opts.mk# +|Move `LLVM_ASSERTIONS` from `\__DEFAULT_YES_OPTIONS` to `__DEFAULT_NO_OPTIONS` -|[.filename]#stable/12/libexec/rc/rc.conf# +|[.filename]#libexec/rc/rc.conf# |Set `dumpdev` from `AUTO` to `NO` (it is configurable via for those that want it enabled by default) -|[.filename]#stable/12/release/Makefile# +|[.filename]#release/Makefile# |Remove the `debug.witness.trace` entries |=== @@ -450,34 +443,34 @@ Then in the {branchHead} branch, which will now become a new major version: | File to Edit | What to Change -|[.filename]#head/UPDATING# +|[.filename]#UPDATING# |Update the FreeBSD version -|[.filename]#head/sys/conf/newvers.sh# +|[.filename]#sys/conf/newvers.sh# |Update the `BRANCH` value to reflect `CURRENT`, and increment `REVISION` -|[.filename]#head/Makefile.inc1# +|[.filename]#Makefile.inc1# |Update `TARGET_TRIPLE` and `MACHINE_TRIPLE` -|[.filename]#head/sys/sys/param.h# +|[.filename]#sys/sys/param.h# |Update `__FreeBSD_version` -|[.filename]#head/gnu/usr.bin/cc/cc_tools/freebsd-native.h# +|[.filename]#gnu/usr.bin/cc/cc_tools/freebsd-native.h# |Update `FBSD_MAJOR` and `FBSD_CC_VER` -|[.filename]#head/contrib/gcc/config.gcc# +|[.filename]#contrib/gcc/config.gcc# |Append the `freebsdversion.h` section -|[.filename]#head/lib/clang/llvm.build.mk# +|[.filename]#lib/clang/llvm.build.mk# |Update the value of `OS_VERSION` -|[.filename]#head/lib/clang/freebsd_cc_version.h# +|[.filename]#lib/clang/freebsd_cc_version.h# |Update `FREEBSD_CC_VERSION` -|[.filename]#head/lib/clang/include/lld/Common/Version.inc# +|[.filename]#lib/clang/include/lld/Common/Version.inc# |Update `LLD_REVISION_STRING` -|[.filename]#head/Makefile.libcompat# +|[.filename]#Makefile.libcompat# |Update `LIB32CPUFLAGS` |=== @@ -516,18 +509,12 @@ These files are all relative to the top-most level of the stable branch: Following the code slush, the next phase of the release cycle is the code freeze. This is the point at which all commits to the stable branch require explicit approval from the {teamRe}. -This is enforced by pre-commit hooks in the Subversion repository by editing [.filename]#base/svnadmin/conf/approvers# to include a regular expression matching the {branchStablex} branch for the release: - -[.programlisting,subs="attributes"] -.... -^/{branchStablex} re -^/{branchRelengx} re -.... +This is enforced by {git-admin-email} who handles the repository. [NOTE] ==== There are two general exceptions to requiring commit approval during the release cycle. -The first is any change that needs to be committed by the Release Engineer in order to proceed with the day-to-day workflow of the release cycle, the other is security fixes that may occur during the release cycle. +The first is any change that needs to be committed by the Release Engineer to proceed with the day-to-day workflow of the release cycle, the other is security fixes that may occur during the release cycle. ==== Once the code freeze is in effect, the next build from the branch is labeled `BETA1`. @@ -540,13 +527,18 @@ Subsequent `BETA` builds do not require updates to any files other than [.filena === Creating the {branchRelengx} Branch When the first `RC` (Release Candidate) build is ready to begin, the {branchReleng} branch is created. -This is a multi-step process that must be done in a specific order, in order to avoid anomalies such as overlaps with `__FreeBSD_version` values, for example. +This is a multi-step process that must be done in a specific order, to avoid anomalies such as overlaps with `__FreeBSD_version` values, for example. The paths listed below are relative to the repository root. The order of commits and what to change are: +[NOTE] +==== +Make sure that you are in the {branchStablex} branch +==== + [source,shell,subs="attributes"] .... -% svn cp ^/{branchStablex} {branchRelengx} +% git checkout -b {branchRelengx} .... [.informaltable] @@ -555,38 +547,39 @@ The order of commits and what to change are: | File to Edit | What to Change -|[.filename]#releng/12.0/sys/conf/newvers.sh# +|[.filename]#sys/conf/newvers.sh# |Change `BETA__X__` to `RC1` -|[.filename]#releng/12.0/sys/sys/param.h# +|[.filename]#sys/sys/param.h# |Update `__FreeBSD_version` -|[.filename]#releng/12.0/etc/pkg/FreeBSD.conf# +|[.filename]#sys/conf/kern.opts.mk# +|Move `REPRODUCIBLE_BUILD` from `__DEFAULT_NO_OPTIONS` to `__DEFAULT_YES_OPTIONS` + +|[.filename]#etc/pkg/FreeBSD.conf# |Replace `latest` with `quarterly` as the default package repository location -|[.filename]#releng/12.0/release/pkg_repos/release-dvd.conf# +|[.filename]#release/pkg_repos/release-dvd.conf# |Replace `latest` with `quarterly` as the default package repository location -|[.filename]#stable/12/sys/conf/newvers.sh# +|[.filename]#sys/conf/newvers.sh# |Update `BETA__X__` with `PRERELEASE` -|[.filename]#stable/12/sys/sys/param.h# +|[.filename]#sys/sys/param.h# |Update `__FreeBSD_version` - -|[.filename]#svnadmin/conf/approvers# -|Add a new approvers line for the releng branch as was done for the stable branch |=== +Then, {git-admin-email} adds new approvers for the releng branch as did for the stable branch. + [source,shell,subs="attributes"] .... -% svn propdel -R svn:mergeinfo {branchRelengx} -% svn commit {branchRelengx} -% svn commit {branchStablex} +% git add . +% git commit .... Now that two new `__FreeBSD_version` values exist, also update [.filename]#~/documentation/content/en/books/porters-handbook/versions/chapter.adoc# in the Documentation Project repository. -After the first `RC` build has completed and tested, the {branchStable} branch can be "thawed" by removing (or commenting) the ^/{branchStablex} entry in [.filename]#svnadmin/conf/approvers#. +After the first `RC` build has completed and tested, the {branchStable} branch can be "thawed" by {git-admin-email}. Following the availability of the first `RC`, {teamBugmeister} should be emailed to add the new FreeBSD `-RELEASE` to the `versions` available in the drop-down menu shown in the bug tracker. @@ -598,11 +591,6 @@ This section describes the general procedures producing FreeBSD development snap [[releng-build-scripts]] === Release Build Scripts -This section describes the build scripts used by {teamRe} to produce development snapshots and releases. - -[[releng-build-scripts-single]] -==== The [.filename]#release.sh# Script - Prior to FreeBSD 9.0-RELEASE, [.filename]#src/release/Makefile# was updated to support , and the [.filename]#src/release/generate-release.sh# script was introduced as a wrapper to automate invoking the targets. Prior to FreeBSD 9.2-RELEASE, [.filename]#src/release/release.sh# was introduced, which heavily based on [.filename]#src/release/generate-release.sh# included support to specify configuration files to override various options and environment variables. @@ -635,98 +623,9 @@ Then invoke [.filename]#src/release/release.sh# as: See and [.filename]#src/release/release.conf.sample# for more details and example usage. -[[releng-build-scripts-multiple]] -==== The [.filename]#thermite.sh# Wrapper Script - -In order to make cross building the full set of architectures supported on a given branch faster, easier, and reduce human error factors, a wrapper script around [.filename]#src/release/release.sh# was written to iterate through the various combinations of architectures and invoke [.filename]#src/release/release.sh# using a configuration file specific to that architecture. - -The wrapper script is called [.filename]#thermite.sh#, which is available in the FreeBSD Subversion repository at `svn://svn.freebsd.org/base/user/gjb/thermite/`, in addition to configuration files used to build {branchHead} and {branchStablex} development snapshots. - -Using [.filename]#thermite.sh# is covered in <<releng-build-snapshot>> and <<releng-build-release>>. - -Each architecture and individual kernel have their own configuration file used by [.filename]#release.sh#. -Each branch has its own [.filename]#defaults-X.conf# configuration which contains entries common throughout each architecture, where overrides or special variables are set and/or overridden in the per-build files. - -The per-build configuration file naming scheme is in the form of [.filename]#${revision}-${TARGET_ARCH}-${KERNCONF}-${type}.conf#, where the uppercase variables are equivalent to what uses in the build system, and lowercase variables are set within the configuration files, mapping to the major version of the respective branch. - -Each branch also has its own [.filename]#builds-X.conf# configuration, which is used by [.filename]#thermite.sh#. The [.filename]#thermite.sh# script iterates through each ${revision}, ${TARGET_ARCH}, ${KERNCONF}, and ${type} value, creating a master list of what to build. -However, a given combination from the list will only be built if the respective configuration file exists, which is where the naming scheme above is relevant. - -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] -==== -The [.filename]#builds-12.conf#, [.filename]#defaults-12.conf#, and [.filename]#main.conf# configuration files exist to reduce repetition between the various per-build files. -==== - -[[releng-build-snapshot]] -=== Building FreeBSD Development Snapshots - -The official release build machines have a specific filesystem layout, which using ZFS, [.filename]#thermite.sh# takes heavy advantage of with clones and snapshots, ensuring a pristine build environment. - -The build scripts reside in [.filename]#/releng/scripts-snapshot/scripts# or [.filename]#/releng/scripts-release/scripts# respectively, to avoid collisions between an `RC` build from a releng branch versus a `STABLE` snapshot from the respective stable branch. - -A separate dataset exists for the final build images, [.filename]#/snap/ftp#. This directory contains both snapshots and releases directories. -They are only used if the `EVERYTHINGISFINE` variable is defined in [.filename]#main.conf#. - -[NOTE] -==== -The `EVERYTHINGISFINE` variable name was chosen to avoid colliding with a variable that might be possibly set in the user environment, accidentally enabling the behavior that depends on it being defined. -==== - -As [.filename]#thermite.sh# iterates through the master list of combinations and locates the per-build configuration file, a ZFS dataset is created under [.filename]#/releng#, such as [.filename]#/releng/12-amd64-GENERIC-snap#. -The `src/`, `ports/`, and `doc/` trees are checked out to separate ZFS datasets, such as [.filename]#/releng/12-src-snap#, which are then cloned and mounted into the respective build datasets. -This is done to avoid checking out a given tree more than once. - -Assuming these filesystem paths, [.filename]#thermite.sh# would be invoked as: - -[source,shell,subs="attributes"] -.... -# cd /releng/scripts-snapshot/scripts -# ./setrev.sh -b {branchStablex} -# ./zfs-cleanup.sh -c ./builds-12.conf -# ./thermite.sh -c ./builds-12.conf -.... - -Once the builds have completed, additional helper scripts are available to generate development snapshot emails which are sent to the `freebsd-snapshots@freebsd.org` mailing list: - -[source,shell,subs="attributes"] -.... -# cd /releng/scripts-snapshot/scripts -# ./get-checksums.sh -c ./builds-12.conf | ./generate-email.pl > snapshot-12-mail -.... - -[NOTE] -==== -The generated output should be double-checked for correctness, and the email itself should be PGP signed, in-line. -==== - -[NOTE] -==== -These helper scripts only apply to development snapshot builds. -Announcements during the release cycle (excluding the final release announcement) are created from an email template. -A sample of the email template currently used can be found link:here[here]. -==== - [[releng-build-release]] === Building FreeBSD Releases -Similar to building FreeBSD development snapshots, [.filename]#thermite.sh# would be invoked the same way. -The difference between development snapshots and release builds, `BETA` and `RC` included, is that the configuration files must be named with `release` instead of `snap` as the type, as mentioned above. - -In addition, the `BUILDTYPE` and `types` must be changed from `snap` to `release` in [.filename]#defaults-12.conf# and [.filename]#builds-12.conf#, respectively. - -When building `BETA`, `RC`, and the final `RELEASE`, also statically set `BUILDSVNREV` to the revision on the branch reflecting the name change, `BUILDDATE` to the date the builds are started in `YYYYMMDD` format. -If the `doc/` and `ports/` trees have been tagged, also set `PORTBRANCH` and `DOCBRANCH` to the relevant tag path in the Subversion repository, replacing `HEAD` with the last changed revision. -Also set `releasesrc` in [.filename]#builds-12.conf# to the relevant branch, such as {branchStablex} or {branchRelengx}. - During the release cycle, a copy of [.filename]#CHECKSUM.SHA512# and [.filename]#CHECKSUM.SHA256# for each architecture are stored in the {teamRe} internal repository in addition to being included in the various announcement emails. Each [.filename]#MANIFEST# containing the hashes of [.filename]#base.txz#, [.filename]#kernel.txz#, etc. are added to package:misc/freebsd-release-manifests[] in the Ports Collection, as well. @@ -744,18 +643,22 @@ In preparation for the release build, several files need to be updated: |[.filename]#UPDATING# |Add the anticipated announcement date -|[.filename]#lib/csu/common/crtbrand.c# +|[.filename]#lib/csu/common/crtbrand.S# |Replace `__FreeBSD_version` with the value in [.filename]#sys/sys/param.h# |=== -After building the final `RELEASE`, the {branchRelengx} branch is tagged as {branchReleasex} using the revision from which the `RELEASE` was built. -Similar to creating the {branchStablex} and {branchRelengx} branches, this is done with `svn cp`. +After building the final `RELEASE`, the {branchRelengx} branch is tagged as {tagReleasex} using the revision from which the `RELEASE` was built. +Similar to creating the {branchStablex} and {branchRelengx} branches, this is done with `git tag`. From the repository root: +[NOTE] +==== +Make sure that you are in the {branchRelengx} branch +==== + [source,shell,subs="attributes"] .... -% svn cp ^/{branchRelengx}@r306420 {branchReleasex} -% svn commit {branchReleasex} +% git tag {tagReleasex} .... [[releng-mirrors]] @@ -792,14 +695,14 @@ On `ftp-master` in the FreeBSD Project infrastructure, this step requires `root` === Publishing FreeBSD Installation Media Once the images are staged in [.filename]#/archive/tmp/#, they are ready to be made public by putting them in [.filename]#/archive/pub/FreeBSD#. -In order to reduce propagation time, is used to create hard links from [.filename]#/archive/tmp# to [.filename]#/archive/pub/FreeBSD#. +To reduce propagation time, is used to create hard links from [.filename]#/archive/tmp# to [.filename]#/archive/pub/FreeBSD#. [NOTE] ==== -In order for this to be effective, both [.filename]#/archive/tmp# and [.filename]#/archive/pub# must reside on the same logical filesystem. +For this to be effective, both [.filename]#/archive/tmp# and [.filename]#/archive/pub# must reside on the same logical filesystem. ==== -There is a caveat, however, where rsync must be used after in order to correct the symbolic links in [.filename]#pub/FreeBSD/snapshots/ISO-IMAGES# which will replace with a hard link, increasing the propagation time. +There is a caveat, however, where rsync must be used after to correct the symbolic links in [.filename]#pub/FreeBSD/snapshots/ISO-IMAGES# which will replace with a hard link, increasing the propagation time. [NOTE] ==== @@ -838,12 +741,13 @@ To request an Errata Notice after a release cycle has completed, a developer sho The completed Errata Notice template should be emailed together with either a patch against the {branchReleng} branch or a list of revisions from the {branchStable} branch. For Errata Notice requests immediately following the release, the request should be emailed to both the {teamRe} and the {teamSecteam}. -Once the {branchReleng} branch has been handed over to the {teamSecteam} as described in <<releng-wrapup-handoff>>, Errata Notice requests should be sent to the {teamSecteam}. +Once the {branchReleng} branch has been handed over to the {teamSecteam} as +described in crossref:freebsd-releng[releng-wrapup-handoff, Handoff to the {teamSecteam}], Errata Notice requests should be sent to the {teamSecteam}. [[releng-wrapup-handoff]] === Handoff to the {teamSecteam} -Roughly two weeks following the release, the Release Engineer updates [.filename]#svnadmin/conf/approvers# changing the approver column from `re` to `(so|security-officer)` for the {branchRelengx} branch. +Roughly two weeks following the release, the Release Engineer updates the Git repository changing the approver from the Release engineering team to the security officer for the {branchRelengx} branch. [[releng-eol]] == Release End-of-Life @@ -861,7 +765,6 @@ When a release reaches End-of-Life, references to that release should be removed | File | What to Change - |[.filename]#~/website/themes/beastie/layouts/index.html# |Remove `u-relXXX-announce` and `u-relXXX-announce` references. @@ -869,11 +772,14 @@ When a release reaches End-of-Life, references to that release should be removed |Move the `u-relXXX-*` variables from the supported release list to the Legacy Releases list. |[.filename]#~/website/content/en/releng/_index.adoc# -|Update the appropriate releng branch to refelect the branch is no longer supported. +|Update the appropriate releng branch to reflect the branch is no longer supported. |[.filename]#~/website/content/en/security/_index.adoc# |Remove the branch from the supported branch list. +|[.filename]#~/website/content/en/security/unsupported.adoc# +|Add the branch to the unsupported branch list. + |[.filename]#~/website/content/en/where.adoc# |Remove the URLs for the release. diff --git a/documentation/content/en/articles/freebsd-releng/_index.po b/documentation/content/en/articles/freebsd-releng/_index.po new file mode 100644 index 0000000000..7373d89eb2 --- /dev/null +++ b/documentation/content/en/articles/freebsd-releng/_index.po @@ -0,0 +1,1873 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-12-29 08:30-0500\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/freebsd-releng/_index.adoc:1 +#, no-wrap +msgid "Describes the approach used by the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System. It describes the tools available for those interested in producing customized FreeBSD releases for corporate rollouts or commercial productization" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/freebsd-releng/_index.adoc:1 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:16 +#, no-wrap +msgid "FreeBSD Release Engineering" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:63 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:65 +msgid "" +"This article describes the release engineering process of the FreeBSD " +"Project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:67 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-releng/_index.adoc:71 +#, no-wrap +msgid "Introduction to the FreeBSD Release Engineering Process" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:75 +msgid "" +"Development of FreeBSD has a very specific workflow. In general, all " +"changes to the FreeBSD base system are committed to the {branchHead} branch, " +"which reflects the top of the source tree." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:78 +msgid "" +"After a reasonable testing period, changes can then be merged to the " +"{branchStable} branches. The default minimum timeframe before merging to " +"{branchStable} branches is three (3) days." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:80 +msgid "" +"Although a general rule to wait a minimum of three days before merging from " +"{branchHead}, there are a few special circumstances where an immediate merge " +"may be necessary, such as a critical security fix, or a bug fix that " +"directly inhibits the release build process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:83 +msgid "" +"After several months, and the number of changes in the {branchStable} branch " +"have grown significantly, it is time to release the next version of " +"FreeBSD. These releases have been historically referred to as \"point\" " +"releases." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:86 +msgid "" +"In between releases from the {branchStable} branches, approximately every " +"two (2) years, a release will be cut directly from {branchHead}. These " +"releases have been historically referred to as \"dot-zero\" releases." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:88 +msgid "" +"This article will highlight the workflow and responsibilities of the " +"{teamRe} for both \"dot-zero\" and \"point\"' releases." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:90 +msgid "The following sections of this article describe:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/freebsd-releng/_index.adoc:91 +#, no-wrap +msgid "crossref:freebsd-releng[releng-prep, General Information and Preparation]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:93 +msgid "General information and preparation before starting the release cycle." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/freebsd-releng/_index.adoc:94 +#, no-wrap +msgid "crossref:freebsd-releng[releng-website, Website Changes During the Release Cycle]" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-releng/_index.adoc:96 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:281 +#, no-wrap +msgid "Website Changes During the Release Cycle" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/freebsd-releng/_index.adoc:97 +#, no-wrap +msgid "crossref:freebsd-releng[releng-terms, Release Engineering Terminology]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:99 +msgid "" +"Terminology and general information, such as the \"code slush\" and \"code " +"freeze\", used throughout this document." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/freebsd-releng/_index.adoc:100 +#, no-wrap +msgid "crossref:freebsd-releng[releng-head, Release from {branchHead}]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:102 +msgid "The Release Engineering process for a \"dot-zero\" release." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/freebsd-releng/_index.adoc:103 +#, no-wrap +msgid "crossref:freebsd-releng[releng-stable, Release from {branchStable}]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:105 +msgid "The Release Engineering process for a \"point\" release." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/freebsd-releng/_index.adoc:106 +#, no-wrap +msgid "crossref:freebsd-releng[releng-building, Building FreeBSD Installation Media]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:108 +msgid "" +"Information related to the specific procedures to build installation medium." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/freebsd-releng/_index.adoc:109 +#, no-wrap +msgid "crossref:freebsd-releng[releng-mirrors, Publishing FreeBSD Installation Media to Project Mirrors]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:111 +msgid "Procedures to publish installation medium." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/freebsd-releng/_index.adoc:112 +#, no-wrap +msgid "crossref:freebsd-releng[releng-wrapup, Wrapping up the Release Cycle]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:114 +msgid "Wrapping up the release cycle." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-releng/_index.adoc:116 +#, no-wrap +msgid "General Information and Preparation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:121 +msgid "" +"Approximately two months before the start of the release cycle, the {teamRe} " +"decides on a schedule for the release. The schedule includes the various " +"milestone points of the release cycle, such as freeze dates, branch dates, " +"and build dates. For example:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:126 +#, no-wrap +msgid "Milestone" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:128 +#, no-wrap +msgid "Anticipated Date" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:129 +#, no-wrap +msgid "{branchHead} slush:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:131 +#, no-wrap +msgid "May 27, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:132 +#, no-wrap +msgid "{branchHead} freeze:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:134 +#, no-wrap +msgid "June 10, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:135 +#, no-wrap +msgid "{branchHead} KBI freeze:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:137 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:140 +#, no-wrap +msgid "June 24, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:138 +#, no-wrap +msgid "`doc/` tree slush [1]:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:141 +#, no-wrap +msgid "Ports quarterly branch [2]:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:143 +#, no-wrap +msgid "July 1, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:144 +#, no-wrap +msgid "{branchStablex} branch:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:146 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:149 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:152 +#, no-wrap +msgid "July 8, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:147 +#, no-wrap +msgid "`doc/` tree tag [3]:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:150 +#, no-wrap +msgid "BETA1 build starts:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:153 +#, no-wrap +msgid "{branchHead} thaw:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:155 +#, no-wrap +msgid "July 9, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:156 +#, no-wrap +msgid "BETA2 build starts:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:158 +#, no-wrap +msgid "July 15, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:159 +#, no-wrap +msgid "BETA3 build starts [*]:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:161 +#, no-wrap +msgid "July 22, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:162 +#, no-wrap +msgid "{branchRelengx} branch:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:164 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:167 +#, no-wrap +msgid "July 29, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:165 +#, no-wrap +msgid "RC1 build starts:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:168 +#, no-wrap +msgid "{branchStablex} thaw:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:170 +#, no-wrap +msgid "July 30, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:171 +#, no-wrap +msgid "RC2 build starts:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:173 +#, no-wrap +msgid "August 5, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:174 +#, no-wrap +msgid "Final Ports package builds [4]:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:176 +#, no-wrap +msgid "August 6, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:177 +#, no-wrap +msgid "Ports release tag:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:179 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:182 +#, no-wrap +msgid "August 12, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:180 +#, no-wrap +msgid "RC3 build starts [*]:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:183 +#, no-wrap +msgid "RELEASE build starts:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:185 +#, no-wrap +msgid "August 19, 2016" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:186 +#, no-wrap +msgid "RELEASE announcement:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:187 +#, no-wrap +msgid "September 2, 2016" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:192 +msgid "Items marked with \"[*]\" are \"as needed\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:195 +msgid "The `doc/` tree slush is coordinated by the {teamDoceng}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:196 +msgid "" +"The Ports quarterly branch used is determined by when the final `RC` build " +"is planned. A new quarterly branch is created on the first day of the " +"quarter, so this metric should be used when taking the release cycle " +"milestones into account. The quarterly branch is created by the " +"{teamPortmgr}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:197 +msgid "The `doc/` tree is tagged by the {teamDoceng}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:198 +msgid "" +"The final Ports package build is done by the {teamPortmgr} after the final " +"(or what is expected to be final) `RC` build." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:202 +msgid "" +"If the release is being created from an existing {branchStable} branch, the " +"KBI freeze date can be excluded, since the KBI is already considered frozen " +"on established {branchStable} branches." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:207 +msgid "" +"When writing the release cycle schedule, a number of things need to be taken " +"into consideration, in particular milestones where the target date depends " +"on predefined milestones upon which there is a dependency. For example, the " +"Ports Collection release tag originates from the active quarterly branch at " +"the time of the last `RC`. This in part defines which quarterly branch is " +"used, when the release tag can happen, and what revision of the ports tree " +"is used for the final `RELEASE` build." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:209 +msgid "" +"After general agreement on the schedule, the {teamRe} emails the schedule to " +"the FreeBSD Developers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:212 +msgid "" +"It is somewhat typical that many developers will inform the {teamRe} about " +"various works-in-progress. In some cases, an extension for the in-progress " +"work will be requested, and in other cases, a request for \"blanket " +"approval\" to a particular subset of the tree will be made." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:216 +msgid "" +"When such requests are made, it is important to make sure timelines (even if " +"estimated) are discussed. For blanket approvals, the length of time for the " +"blanket approval should be made clear. For example, a FreeBSD developer may " +"request blanket approvals from the start of the code slush until the start " +"of the `RC` builds." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:221 +msgid "" +"To keep track of blanket approvals, the {teamRe} uses an internal repository " +"to keep a running log of such requests, which defines the area upon which a " +"blanket approval was granted, the author(s), when the blanket approval " +"expires, and the reason the approval was granted. One example of this is " +"granting blanket approval to [.filename]#release/doc/# to all {teamRe} " +"members until the final `RC` to update the release notes and other release-" +"related documentation." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:226 +msgid "" +"The {teamRe} also uses this repository to track pending approval requests " +"that are received just prior to starting various builds during the release " +"cycle, which the Release Engineer specifies the cutoff period with an email " +"to the FreeBSD developers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:229 +msgid "" +"Depending on the underlying set of code in question, and the overall impact " +"the set of code has on FreeBSD as a whole, such requests may be approved or " +"denied by the {teamRe}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:233 +msgid "" +"The same applies to work-in-progress extensions. For example, in-progress " +"work for a new device driver that is otherwise isolated from the rest of the " +"tree may be granted an extension. A new scheduler, however, may not be " +"feasible, especially if such dramatic changes do not exist in another branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:235 +msgid "" +"The schedule is also added to the Project website, in the `doc/` repository, " +"in [.filename]#~/website/content/en/releases/{branchRevision}R/schedule." +"adoc#. This file is continuously updated as the release cycle progresses." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:239 +msgid "" +"In most cases, the [.filename]#schedule.adoc# can be copied from a prior " +"release and updated accordingly." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:242 +msgid "" +"In addition to adding [.filename]#schedule.adoc# to the website, [." +"filename]#~/shared/releases.adoc# is also updated to add the link to the " +"schedule to various subpages, as well as enabling the link to the schedule " +"on the Project website index page." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:244 +msgid "" +"The schedule is also linked from [.filename]#~/website/content/en/releng/" +"_index.adoc#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:246 +msgid "" +"Approximately one month prior to the scheduled \"code slush\", the {teamRe} " +"sends a reminder email to the FreeBSD Developers." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-releng/_index.adoc:248 +#, no-wrap +msgid "Release Engineering Terminology" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:251 +msgid "" +"This section describes some of the terminology used throughout the rest of " +"this document." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:253 +#, no-wrap +msgid "The Code Slush" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:256 +msgid "" +"Although the code slush is not a hard freeze on the tree, the {teamRe} " +"requests that bugs in the existing code base take priority over new features." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:258 +msgid "The code slush does not enforce commit approvals to the branch." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:260 +#, no-wrap +msgid "The Code Freeze" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:263 +msgid "" +"The code freeze marks the point in time where all commits to the branch " +"require explicit approval from the {teamRe}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:266 +msgid "" +"The FreeBSD Git repository contains several hooks to perform sanity checks " +"before any commit is actually committed to the tree. One of these hooks " +"will evaluate if committing to a particular branch requires specific " +"approval." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:268 +msgid "" +"To enforce commit approvals by the {teamRe}, the Release Engineering Team " +"must approve any changes to the branch, in which case the commit log must " +"include an `Approved by: re (login)` line, where \"login\" is the login ID " +"of the approver." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:272 +msgid "" +"During the code freeze, FreeBSD committers are urged to follow the link:" +"https://wiki.freebsd.org/Releng/ChangeRequestGuidelines[Change Request " +"Guidelines]." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:275 +#, no-wrap +msgid "The KBI/KPI Freeze" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:279 +msgid "" +"KBI/KPI stability implies that the caller of a function across two different " +"releases of software that implement the function results in the same end " +"state. The caller, whether it is a process, thread, or function, expects " +"the function to operate in a certain way, otherwise the KBI/KPI stability on " +"the branch is broken." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:284 +msgid "" +"This section describes the changes to the website that should occur as the " +"release cycle progresses." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:288 +msgid "" +"The files specified throughout this section are relative to the `{branchHead}" +"` branch of the `doc` repository." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:291 +#, no-wrap +msgid "Website Changes Before the Release Cycle Begins" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:294 +msgid "" +"When the release cycle schedule is available, these files need to be updated " +"to enable different functionalities on the FreeBSD Project website:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:299 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:318 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:389 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:444 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:492 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:548 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:638 +#, no-wrap +msgid "File to Edit" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:301 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:320 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:391 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:446 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:494 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:550 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:640 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:768 +#, no-wrap +msgid "What to Change" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:302 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:305 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:321 +#, no-wrap +msgid "[.filename]#~/shared/releases.adoc#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:304 +#, no-wrap +msgid "Change `beta-upcoming` from `IGNORE` to `INCLUDE`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:307 +#, no-wrap +msgid "Change `beta-testing` from `IGNORE` to `INCLUDE`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:310 +#, no-wrap +msgid "Website Changes During `BETA` or `RC`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:313 +msgid "" +"When transitioning from `PRERELEASE` to `BETA`, these files need to be " +"updated to enable the \"Help Test\" block on the download page. All files " +"are relative to [.filename]#head/# in the `doc` repository:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:323 +#, no-wrap +msgid "Update `betarel-vers` to `BETA__1__`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:324 +#, no-wrap +msgid "[.filename]#~/website/data/en/news/news.toml#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:326 +#, no-wrap +msgid "Add an entry announcing the `BETA`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:327 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:790 +#, no-wrap +msgid "[.filename]#~/website/static/security/advisory-template.txt#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:329 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:331 +#, no-wrap +msgid "Add the new `BETA`, `RC`, or final `RELEASE` to the template" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:330 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:793 +#, no-wrap +msgid "[.filename]#~/website/static/security/errata-template.txt#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:334 +msgid "" +"Once the {branchRelengx} branch is created, the various release-related " +"documents need to be added to the `doc/` repository." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:338 +msgid "" +"The relevant release-related documents exist in the [.filename]#doc# " +"repository for FreeBSD 12.x and later." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:341 +#, no-wrap +msgid "Ports Changes During `BETA`, `RC`, and the Final `RELEASE`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:345 +msgid "" +"For each build during the release cycle, the `MANIFEST` files containing the " +"`SHA256` of the various distribution sets, such as `base.txz`, `kernel.txz`, " +"and so on, are added to the package:misc/freebsd-release-manifests[] port. " +"This allows utilities other than , such as package:ports-mgmt/poudriere[], " +"to safely use these distribution sets by providing a mechanism through which " +"the checksums can be verified." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-releng/_index.adoc:347 +#, no-wrap +msgid "Release from {branchHead}" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:350 +msgid "" +"This section describes the general procedures of the FreeBSD release cycle " +"from the {branchHead} branch." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:352 +#, no-wrap +msgid "FreeBSD \"`ALPHA`\" Builds" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:356 +msgid "" +"Starting with the FreeBSD 10.0-RELEASE cycle, the notion of \"`ALPHA`\" " +"builds was introduced. Unlike the `BETA` and `RC` builds, `ALPHA` builds " +"are not included in the FreeBSD Release schedule." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:358 +msgid "" +"The idea behind `ALPHA` builds is to provide regular FreeBSD-provided builds " +"before the creation of the {branchStable} branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:360 +msgid "FreeBSD `ALPHA` snapshots should be built approximately once a week." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:363 +msgid "" +"For the first `ALPHA` build, the `BRANCH` value in [.filename]#sys/conf/" +"newvers.sh# needs to be changed from `CURRENT` to `ALPHA1`. For subsequent " +"`ALPHA` builds, increment each `ALPHA__N__` value by one." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:365 +msgid "" +"See crossref:freebsd-releng[releng-building, Building FreeBSD Installation " +"Media] for information on building the `ALPHA` images." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:367 +#, no-wrap +msgid "Creating the {branchStablex} Branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:372 +msgid "" +"When creating the {branchStable} branch, several changes are required in " +"both the new {branchStable} branch and the {branchHead} branch. The files " +"listed are relative to the repository root. To create the new " +"{branchStablex} branch in Git:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:376 +msgid "Make sure that you are in the {branchHead} branch" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:381 +#, no-wrap +msgid "% git checkout -b {branchStablex}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:384 +msgid "" +"Once the {branchStablex} branch has been created, make the following edits:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:392 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:447 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:644 +#, no-wrap +msgid "[.filename]#UPDATING#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:394 +#, no-wrap +msgid "Update the FreeBSD version, and remove the notice about `WITNESS`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:395 +#, no-wrap +msgid "[.filename]#contrib/jemalloc/include/jemalloc/jemalloc_FreeBSD.h#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:404 +#, no-wrap +msgid "" +"[source,shell,subs=\"attributes\"]\n" +"....\n" +"#ifndef MALLOC_PRODUCTION\n" +"#define MALLOC_PRODUCTION\n" +"#endif\n" +"...." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:405 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:465 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:501 +#, no-wrap +msgid "[.filename]#lib/clang/llvm.build.mk#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:407 +#, no-wrap +msgid "Uncomment `-DNDEBUG`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:408 +#, no-wrap +msgid "[.filename]#sys/\\*/conf/GENERIC*#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:410 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:413 +#, no-wrap +msgid "Remove debugging support" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:411 +#, no-wrap +msgid "[.filename]#sys/*/conf/MINIMAL#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:414 +#, no-wrap +msgid "[.filename]#release/release.conf.sample#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:416 +#, no-wrap +msgid "Update `SRCBRANCH`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:417 +#, no-wrap +msgid "[.filename]#sys/*/conf/GENERIC-NODEBUG#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:419 +#, no-wrap +msgid "Remove these kernel configurations" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:420 +#, no-wrap +msgid "[.filename]#sys/arm/conf/std.arm*#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:422 +#, no-wrap +msgid "Remove debugging options" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:423 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:450 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:495 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:551 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:566 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:641 +#, no-wrap +msgid "[.filename]#sys/conf/newvers.sh#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:425 +#, no-wrap +msgid "Update the `BRANCH` value to reflect `BETA1`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:426 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:429 +#, no-wrap +msgid "[.filename]#share/mk/src.opts.mk#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:428 +#, no-wrap +msgid "Move `REPRODUCIBLE_BUILD` from `\\__DEFAULT_NO_OPTIONS` to `__DEFAULT_YES_OPTIONS`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:431 +#, no-wrap +msgid "Move `LLVM_ASSERTIONS` from `\\__DEFAULT_YES_OPTIONS` to `__DEFAULT_NO_OPTIONS`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:432 +#, no-wrap +msgid "[.filename]#libexec/rc/rc.conf#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:434 +#, no-wrap +msgid "Set `dumpdev` from `AUTO` to `NO` (it is configurable via for those that want it enabled by default)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:435 +#, no-wrap +msgid "[.filename]#release/Makefile#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:436 +#, no-wrap +msgid "Remove the `debug.witness.trace` entries" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:439 +msgid "" +"Then in the {branchHead} branch, which will now become a new major version:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:449 +#, no-wrap +msgid "Update the FreeBSD version" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:452 +#, no-wrap +msgid "Update the `BRANCH` value to reflect `CURRENT`, and increment `REVISION`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:453 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:498 +#, no-wrap +msgid "[.filename]#Makefile.inc1#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:455 +#, no-wrap +msgid "Update `TARGET_TRIPLE` and `MACHINE_TRIPLE`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:456 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:554 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:569 +#, no-wrap +msgid "[.filename]#sys/sys/param.h#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:458 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:556 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:570 +#, no-wrap +msgid "Update `__FreeBSD_version`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:459 +#, no-wrap +msgid "[.filename]#gnu/usr.bin/cc/cc_tools/freebsd-native.h#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:461 +#, no-wrap +msgid "Update `FBSD_MAJOR` and `FBSD_CC_VER`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:462 +#, no-wrap +msgid "[.filename]#contrib/gcc/config.gcc#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:464 +#, no-wrap +msgid "Append the `freebsdversion.h` section" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:467 +#, no-wrap +msgid "Update the value of `OS_VERSION`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:468 +#, no-wrap +msgid "[.filename]#lib/clang/freebsd_cc_version.h#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:470 +#, no-wrap +msgid "Update `FREEBSD_CC_VERSION`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:471 +#, no-wrap +msgid "[.filename]#lib/clang/include/lld/Common/Version.inc#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:473 +#, no-wrap +msgid "Update `LLD_REVISION_STRING`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:474 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:504 +#, no-wrap +msgid "[.filename]#Makefile.libcompat#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:475 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:505 +#, no-wrap +msgid "Update `LIB32CPUFLAGS`" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-releng/_index.adoc:478 +#, no-wrap +msgid "Release from {branchStable}" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:481 +msgid "" +"This section describes the general procedures of the FreeBSD release cycle " +"from an extablished {branchStable} branch." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:483 +#, no-wrap +msgid "FreeBSD `stable` Branch Code Slush" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:487 +msgid "" +"In preparation for the code freeze on a `stable` branch, several files need " +"to be updated to reflect the release cycle is officially in progress. These " +"files are all relative to the top-most level of the stable branch:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:497 +#, no-wrap +msgid "Update the `BRANCH` value to reflect `PRERELEASE`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:500 +#, no-wrap +msgid "Update `TARGET_TRIPLE`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:503 +#, no-wrap +msgid "Update `OS_VERSION`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:508 +#, no-wrap +msgid "FreeBSD `BETA` Builds" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:513 +msgid "" +"Following the code slush, the next phase of the release cycle is the code " +"freeze. This is the point at which all commits to the stable branch require " +"explicit approval from the {teamRe}. This is enforced by {git-admin-email} " +"who handles the repository." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:518 +msgid "" +"There are two general exceptions to requiring commit approval during the " +"release cycle. The first is any change that needs to be committed by the " +"Release Engineer to proceed with the day-to-day workflow of the release " +"cycle, the other is security fixes that may occur during the release cycle." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:522 +msgid "" +"Once the code freeze is in effect, the next build from the branch is labeled " +"`BETA1`. This is done by updating the `BRANCH` value in [.filename]#sys/" +"conf/newvers.sh# from `PRERELEASE` to `BETA1`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:525 +msgid "" +"Once this is done, the first set of `BETA` builds are started. Subsequent " +"`BETA` builds do not require updates to any files other than [.filename]#sys/" +"conf/newvers.sh#, incrementing the `BETA` build number." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:527 +#, no-wrap +msgid "Creating the {branchRelengx} Branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:533 +msgid "" +"When the first `RC` (Release Candidate) build is ready to begin, the " +"{branchReleng} branch is created. This is a multi-step process that must be " +"done in a specific order, to avoid anomalies such as overlaps with " +"`__FreeBSD_version` values, for example. The paths listed below are " +"relative to the repository root. The order of commits and what to change " +"are:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:537 +msgid "Make sure that you are in the {branchStablex} branch" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:542 +#, no-wrap +msgid "% git checkout -b {branchRelengx}\n" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:553 +#, no-wrap +msgid "Change `BETA__X__` to `RC1`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:557 +#, no-wrap +msgid "[.filename]#sys/conf/kern.opts.mk#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:559 +#, no-wrap +msgid "Move `REPRODUCIBLE_BUILD` from `__DEFAULT_NO_OPTIONS` to `__DEFAULT_YES_OPTIONS`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:560 +#, no-wrap +msgid "[.filename]#etc/pkg/FreeBSD.conf#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:562 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:565 +#, no-wrap +msgid "Replace `latest` with `quarterly` as the default package repository location" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:563 +#, no-wrap +msgid "[.filename]#release/pkg_repos/release-dvd.conf#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:568 +#, no-wrap +msgid "Update `BETA__X__` with `PRERELEASE`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:573 +msgid "" +"Then, {git-admin-email} adds new approvers for the releng branch as did for " +"the stable branch." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:578 +#, no-wrap +msgid "" +"% git add .\n" +"% git commit\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:581 +msgid "" +"Now that two new `__FreeBSD_version` values exist, also update [.filename]#~/" +"documentation/content/en/books/porters-handbook/versions/chapter.adoc# in " +"the Documentation Project repository." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:583 +msgid "" +"After the first `RC` build has completed and tested, the {branchStable} " +"branch can be \"thawed\" by {git-admin-email}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:585 +msgid "" +"Following the availability of the first `RC`, {teamBugmeister} should be " +"emailed to add the new FreeBSD `-RELEASE` to the `versions` available in the " +"drop-down menu shown in the bug tracker." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-releng/_index.adoc:587 +#, no-wrap +msgid "Building FreeBSD Installation Media" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:590 +msgid "" +"This section describes the general procedures producing FreeBSD development " +"snapshots and releases." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:592 +#, no-wrap +msgid "Release Build Scripts" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:595 +msgid "" +"Prior to FreeBSD 9.0-RELEASE, [.filename]#src/release/Makefile# was updated " +"to support , and the [.filename]#src/release/generate-release.sh# script was " +"introduced as a wrapper to automate invoking the targets." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:598 +msgid "" +"Prior to FreeBSD 9.2-RELEASE, [.filename]#src/release/release.sh# was " +"introduced, which heavily based on [.filename]#src/release/generate-release." +"sh# included support to specify configuration files to override various " +"options and environment variables. Support for configuration files provided " +"support for cross building each architecture for a release by specifying a " +"separate configuration file for each invocation." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:600 +msgid "" +"As a brief example of using [.filename]#src/release/release.sh# to build a " +"single release in [.filename]#/scratch#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:604 +#, no-wrap +msgid "# /bin/sh /usr/src/release/release.sh\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:607 +msgid "" +"As a brief example of using [.filename]#src/release/release.sh# to build a " +"single, cross-built release using a different target directory, create a " +"custom [.filename]#release.conf# containing:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:615 +#, no-wrap +msgid "" +"# release.sh configuration for powerpc/powerpc64\n" +"CHROOTDIR=\"/scratch-powerpc64\"\n" +"TARGET=\"powerpc\"\n" +"TARGET_ARCH=\"powerpc64\"\n" +"KERNEL=\"GENERIC64\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:618 +msgid "Then invoke [.filename]#src/release/release.sh# as:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:622 +#, no-wrap +msgid "# /bin/sh /usr/src/release/release.sh -c $HOME/release.conf\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:625 +msgid "" +"See and [.filename]#src/release/release.conf.sample# for more details and " +"example usage." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:627 +#, no-wrap +msgid "Building FreeBSD Releases" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:631 +msgid "" +"During the release cycle, a copy of [.filename]#CHECKSUM.SHA512# and [." +"filename]#CHECKSUM.SHA256# for each architecture are stored in the {teamRe} " +"internal repository in addition to being included in the various " +"announcement emails. Each [.filename]#MANIFEST# containing the hashes of [." +"filename]#base.txz#, [.filename]#kernel.txz#, etc. are added to package:misc/" +"freebsd-release-manifests[] in the Ports Collection, as well." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:633 +msgid "In preparation for the release build, several files need to be updated:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:643 +#, no-wrap +msgid "Update the `BRANCH` value to `RELEASE`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:646 +#, no-wrap +msgid "Add the anticipated announcement date" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:647 +#, no-wrap +msgid "[.filename]#lib/csu/common/crtbrand.S#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:648 +#, no-wrap +msgid "Replace `__FreeBSD_version` with the value in [.filename]#sys/sys/param.h#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:653 +msgid "" +"After building the final `RELEASE`, the {branchRelengx} branch is tagged as " +"{tagReleasex} using the revision from which the `RELEASE` was built. " +"Similar to creating the {branchStablex} and {branchRelengx} branches, this " +"is done with `git tag`. From the repository root:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:657 +msgid "Make sure that you are in the {branchRelengx} branch" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:662 +#, no-wrap +msgid "% git tag {tagReleasex}\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-releng/_index.adoc:665 +#, no-wrap +msgid "Publishing FreeBSD Installation Media to Project Mirrors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:668 +msgid "" +"This section describes the procedure to publish FreeBSD development " +"snapshots and releases to the Project mirrors." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:670 +#, no-wrap +msgid "Staging FreeBSD Installation Media Images" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:673 +msgid "Staging FreeBSD snapshots and releases is a two part process:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:675 +msgid "Creating the directory structure to match the hierarchy on `ftp-master`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:678 +msgid "" +"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:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:682 +#, no-wrap +msgid "# make -C /usr/src/release -f Makefile.mirrors EVERYTHINGISFINE=1 ftp-stage\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:685 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:686 +msgid "" +"Copying the files to a staging directory on `ftp-master` before moving the " +"files into [.filename]#pub/# to begin propagation to the Project mirrors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:688 +msgid "" +"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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:692 +msgid "" +"On `ftp-master` in the FreeBSD Project infrastructure, this step requires " +"`root` level access, as this step must be executed as the `archive` user." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:695 +#, no-wrap +msgid "Publishing FreeBSD Installation Media" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:699 +msgid "" +"Once the images are staged in [.filename]#/archive/tmp/#, they are ready to " +"be made public by putting them in [.filename]#/archive/pub/FreeBSD#. To " +"reduce propagation time, is used to create hard links from [.filename]#/" +"archive/tmp# to [.filename]#/archive/pub/FreeBSD#." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:703 +msgid "" +"For this to be effective, both [.filename]#/archive/tmp# and [.filename]#/" +"archive/pub# must reside on the same logical filesystem." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:706 +msgid "" +"There is a caveat, however, where rsync must be used after to correct the " +"symbolic links in [.filename]#pub/FreeBSD/snapshots/ISO-IMAGES# which will " +"replace with a hard link, increasing the propagation time." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:710 +msgid "" +"As with the staging steps, this requires `root` level access, as this step " +"must be executed as the `archive` user." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:713 +msgid "As the `archive` user:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:719 +#, no-wrap +msgid "" +"% cd /archive/tmp/snapshots\n" +"% pax -r -w -l . /archive/pub/FreeBSD/snapshots\n" +"% /usr/local/bin/rsync -avH /archive/tmp/snapshots/* /archive/pub/FreeBSD/snapshots/\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:722 +msgid "Replace _snapshots_ with _releases_ as appropriate." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-releng/_index.adoc:724 +#, no-wrap +msgid "Wrapping up the Release Cycle" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:727 +msgid "This section describes general post-release tasks." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:729 +#, no-wrap +msgid "Post-Release Errata Notices" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:733 +msgid "" +"As the release cycle approaches conclusion, it is common to have several EN " +"(Errata Notice) candidates to address issues that were discovered late in " +"the cycle. Following the release, the {teamRe} and the {teamSecteam} " +"revisit changes that were not approved prior to the final release, and " +"depending on the scope of the change in question, may issue an EN." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:737 +msgid "The actual process of issuing ENs is handled by the {teamSecteam}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:740 +msgid "" +"To request an Errata Notice after a release cycle has completed, a developer " +"should fill out the https://www.freebsd.org/security/errata-template." +"txt[Errata Notice template], in particular the `Background`, `Problem " +"Description`, `Impact`, and if applicable, `Workaround` sections." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:742 +msgid "" +"The completed Errata Notice template should be emailed together with either " +"a patch against the {branchReleng} branch or a list of revisions from the " +"{branchStable} branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:746 +msgid "" +"For Errata Notice requests immediately following the release, the request " +"should be emailed to both the {teamRe} and the {teamSecteam}. Once the " +"{branchReleng} branch has been handed over to the {teamSecteam} as described " +"in crossref:freebsd-releng[releng-wrapup-handoff, Handoff to the " +"{teamSecteam}], Errata Notice requests should be sent to the {teamSecteam}." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:748 +#, no-wrap +msgid "Handoff to the {teamSecteam}" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:751 +msgid "" +"Roughly two weeks following the release, the Release Engineer updates the " +"Git repository changing the approver from the Release engineering team to " +"the security officer for the {branchRelengx} branch." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-releng/_index.adoc:753 +#, no-wrap +msgid "Release End-of-Life" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:756 +msgid "" +"This section describes the website-related files to update when a release " +"reaches EoL (End-of-Life)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-releng/_index.adoc:758 +#, no-wrap +msgid "Website Updates for End-of-Life" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-releng/_index.adoc:761 +msgid "" +"When a release reaches End-of-Life, references to that release should be " +"removed and/or updated on the website:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:766 +#, no-wrap +msgid "File" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:769 +#, no-wrap +msgid "[.filename]#~/website/themes/beastie/layouts/index.html#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:771 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:789 +#, no-wrap +msgid "Remove `u-relXXX-announce` and `u-relXXX-announce` references." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:772 +#, no-wrap +msgid "[.filename]#~/website/content/en/releases/_index.adoc#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:774 +#, no-wrap +msgid "Move the `u-relXXX-*` variables from the supported release list to the Legacy Releases list." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:775 +#, no-wrap +msgid "[.filename]#~/website/content/en/releng/_index.adoc#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:777 +#, no-wrap +msgid "Update the appropriate releng branch to reflect the branch is no longer supported." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:778 +#, no-wrap +msgid "[.filename]#~/website/content/en/security/_index.adoc#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:780 +#, no-wrap +msgid "Remove the branch from the supported branch list." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:781 +#, no-wrap +msgid "[.filename]#~/website/content/en/security/unsupported.adoc#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:783 +#, no-wrap +msgid "Add the branch to the unsupported branch list." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:784 +#, no-wrap +msgid "[.filename]#~/website/content/en/where.adoc#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:786 +#, no-wrap +msgid "Remove the URLs for the release." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:787 +#, no-wrap +msgid "[.filename]#~/website/themes/beastie/layouts/partials/sidenav.html#" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-releng/_index.adoc:792 +#: documentation/content/en/articles/freebsd-releng/_index.adoc:794 +#, no-wrap +msgid "Remove references to the release and releng branch." +msgstr "" diff --git a/documentation/content/en/articles/freebsd-src-lsp/_index.adoc b/documentation/content/en/articles/freebsd-src-lsp/_index.adoc index 87286645a7..753e4f78f0 100644 --- a/documentation/content/en/articles/freebsd-src-lsp/_index.adoc +++ b/documentation/content/en/articles/freebsd-src-lsp/_index.adoc @@ -46,13 +46,30 @@ toc::[] [[intro]] == Introduction -This guide is about setting up a FreeBSD src tree with language servers performing source code indexing. +This guide is about setting up a FreeBSD src tree with language servers performing source code indexing. The guide describes the steps for Vim/NeoVim and VSCode. If you use a different text editor you can use this guide as a reference and search the equivalent commands for your preferred editor. -[[ports-required]] -== Required Ports +[[requirements]] +== Requirements -Some ports are required throughout the guide. -Choose a favorite combination of tools from each category below: +In order to follow this guide we need to install certain requirements. We need a Language server, `ccls` or `clangd`, and optionally a compilation database. + +The installation of the Language server can be performed via `pkg` or via ports. If we chose `clangd` we need to install `llvm`. + +Using `pkg` to install `ccls`: + +[source,shell] +.... +# pkg install ccls +.... + +If we want to use `clangd` we need to install `llvm` (The example command uses `llvm15` but choose the version you desire): + +[source,shell] +.... +# pkg install llvm15 +.... + +To install via ports choose a favorite combination of tools from each category below: * Language server implementations ** package:devel/ccls[] @@ -114,12 +131,14 @@ au User lsp_setup call lsp#register_server({ .... au User lsp_setup call lsp#register_server({ \ 'name': 'clangd', - \ 'cmd': {server_info->['clangd12', '--background-index', '--header-insertion=never']}, + \ 'cmd': {server_info->['clangd15', '--background-index', '--header-insertion=never']}, \ 'allowlist': ['c', 'cpp', 'objc'], \ 'initialization_options': {}, \ }) .... +Depending on the version that you installed for `clangd` you might need to update the `server-info` to point to the correct binary. + Please refer to link:https://github.com/prabirshrestha/vim-lsp/blob/master/README.md#registering-servers[] to learn about setting up key bindings and code completion. The official site of clangd is link:https://clangd.llvm.org[], and the repository link of ccls is link:https://github.com/MaskRay/ccls/[]. @@ -197,7 +216,7 @@ Depending on the language server implementations, put one of the following JSON A Compilation database contains an array of compile command objects. Each object specifies a way of compiling a source file. -The compilation database file is usually [.filename]#compiler_commands.json#. +The compilation database file is usually [.filename]#compile_commands.json#. The database is used by language server implementations for indexing purpose. Please refer to link:https://clang.llvm.org/docs/JSONCompilationDatabase.html#format[] for details on the format of the compilation database file. @@ -244,7 +263,7 @@ In the top-level directory of the FreeBSD src tree, generate the compilation dat The `--append` flag tells the `intercept-build` to read an existing compilation database (if a compilation database exists) and append the results to the database. Entries with duplicated command keys are merged. -The generated compilation database by default is saved in the current working directory as [.filename]#compiler_commands.json#. +The generated compilation database by default is saved in the current working directory as [.filename]#compile_commands.json#. [[generators-bear]] ==== Using devel/bear @@ -255,12 +274,12 @@ In the top-level directory of the FreeBSD src tree, to generate compilation data [source,shell] .... -# bear --append make buildworld buildkernel -j`sysctl -n hw.ncpu` +# bear --append -- make buildworld buildkernel -j`sysctl -n hw.ncpu` .... The `--append` flag tells `bear` to read an existing compilation database if it is present, and append the results to the database. -Entries with duplicated command key are merged. -The generated compilation database by default is saved in the current working directory as [.filename]#compiler_commands.json#. +Entries with duplicated command keys are merged. +The generated compilation database by default is saved in the current working directory as [.filename]#compile_commands.json#. [[final]] == Final diff --git a/documentation/content/en/articles/freebsd-src-lsp/_index.po b/documentation/content/en/articles/freebsd-src-lsp/_index.po new file mode 100644 index 0000000000..20b6ba0feb --- /dev/null +++ b/documentation/content/en/articles/freebsd-src-lsp/_index.po @@ -0,0 +1,535 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-01-17 20:35-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:1 +#, no-wrap +msgid "Use Language Servers for development in the FreeBSD src tree to get precise go-to-definition and completion results." +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:1 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:13 +#, no-wrap +msgid "Use Language Servers for Development in the FreeBSD Src Tree" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:47 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:50 +msgid "" +"This guide is about setting up a FreeBSD src tree with language servers " +"performing source code indexing. The guide describes the steps for Vim/" +"NeoVim and VSCode. If you use a different text editor you can use this guide " +"as a reference and search the equivalent commands for your preferred editor." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:52 +#, no-wrap +msgid "Requirements" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:55 +msgid "" +"In order to follow this guide we need to install certain requirements. We " +"need a Language server, `ccls` or `clangd`, and optionally a compilation " +"database." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:57 +msgid "" +"The installation of the Language server can be performed via `pkg` or via " +"ports. If we chose `clangd` we need to install `llvm`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:59 +msgid "Using `pkg` to install `ccls`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:63 +#, no-wrap +msgid "# pkg install ccls\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:66 +msgid "" +"If we want to use `clangd` we need to install `llvm` (The example command " +"uses `llvm15` but choose the version you desire):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:70 +#, no-wrap +msgid "# pkg install llvm15\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:73 +msgid "" +"To install via ports choose a favorite combination of tools from each " +"category below:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:75 +msgid "Language server implementations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:76 +msgid "package:devel/ccls[]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:77 +msgid "" +"package:devel/llvm12[] (Other versions are okay, but newer is better. " +"Replace `clangd12` with clangdN in case other versions are used.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:78 +msgid "Editors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:79 +msgid "package:editors/vim[]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:80 +msgid "package:editors/neovim[]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:81 +msgid "package:editors/vscode[]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:82 +msgid "Compilation database generator" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:83 +msgid "package:devel/python[] (For llvm's scan-build-py implementation)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:84 +msgid "package:devel/py-pip[] (For rizsotto's scan-build implementation)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:85 +msgid "package:devel/bear[]" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:87 +#, no-wrap +msgid "Editor settings" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:90 +#, no-wrap +msgid "Vim/Neovim" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:92 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:178 +#, no-wrap +msgid "LSP client plugins" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:96 +msgid "" +"The built-in plugin manager is used for both editors in this example. The " +"LSP client plugin used is link:https://github.com/prabirshrestha/vim-" +"lsp[prabirshrestha/vim-lsp]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:98 +msgid "To set up the LSP client plugin for Neovim:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:103 +#, no-wrap +msgid "" +"# mkdir -p ~/.config/nvim/pack/lsp/start\n" +"# git clone https://github.com/prabirshrestha/vim-lsp ~/.config/nvim/pack/lsp/start/vim-lsp\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:106 +msgid "and for Vim:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:111 +#, no-wrap +msgid "" +"# mkdir -p ~/.vim/pack/lsp/start\n" +"# git clone https://github.com/prabirshrestha/vim-lsp ~/.vim/pack/lsp/start/vim-lsp\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:114 +msgid "" +"To enable the LSP client plugin in the editor, add the following snippet " +"into [.filepath]#~/.config/nvim/init.vim# when using Neovim, or [." +"filepath]#~/.vim/vimrc# when using Vim:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:115 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:203 +#, no-wrap +msgid "For ccls" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:127 +#, no-wrap +msgid "" +"au User lsp_setup call lsp#register_server({\n" +" \\ 'name': 'ccls',\n" +" \\ 'cmd': {server_info->['ccls']},\n" +" \\ 'allowlist': ['c', 'cpp', 'objc'],\n" +" \\ 'initialization_options': {\n" +" \\ 'cache': {\n" +" \\ 'hierarchicalPath': v:true\n" +" \\ }\n" +" \\ }})\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:129 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:188 +#, no-wrap +msgid "For clangd" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:138 +#, no-wrap +msgid "" +"au User lsp_setup call lsp#register_server({\n" +" \\ 'name': 'clangd',\n" +" \\ 'cmd': {server_info->['clangd15', '--background-index', '--header-insertion=never']},\n" +" \\ 'allowlist': ['c', 'cpp', 'objc'],\n" +" \\ 'initialization_options': {},\n" +" \\ })\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:141 +msgid "" +"Depending on the version that you installed for `clangd` you might need to " +"update the `server-info` to point to the correct binary." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:144 +msgid "" +"Please refer to link:https://github.com/prabirshrestha/vim-lsp/blob/master/" +"README.md#registering-servers[] to learn about setting up key bindings and " +"code completion. The official site of clangd is link:https://clangd.llvm." +"org[], and the repository link of ccls is link:https://github.com/MaskRay/" +"ccls/[]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:147 +msgid "" +"Below are the reference settings of keybindings and code completions. Put " +"the following snippet into [.filepath]#~/.config/nvim/init.vim#, or [." +"filepath]#~/.vim/vimrc# for Vim users to use it:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:154 +#, no-wrap +msgid "" +"function! s:on_lsp_buffer_enabled() abort\n" +" setlocal omnifunc=lsp#complete\n" +" setlocal completeopt-=preview\n" +" setlocal keywordprg=:LspHover\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:168 +#, no-wrap +msgid "" +" nmap <buffer> <C-]> <plug>(lsp-definition)\n" +" nmap <buffer> <C-W>] <plug>(lsp-peek-definition)\n" +" nmap <buffer> <C-W><C-]> <plug>(lsp-peek-definition)\n" +" nmap <buffer> gr <plug>(lsp-references)\n" +" nmap <buffer> <C-n> <plug>(lsp-next-reference)\n" +" nmap <buffer> <C-p> <plug>(lsp-previous-reference)\n" +" nmap <buffer> gI <plug>(lsp-implementation)\n" +" nmap <buffer> go <plug>(lsp-document-symbol)\n" +" nmap <buffer> gS <plug>(lsp-workspace-symbol)\n" +" nmap <buffer> ga <plug>(lsp-code-action)\n" +" nmap <buffer> gR <plug>(lsp-rename)\n" +" nmap <buffer> gm <plug>(lsp-signature-help)\n" +"endfunction\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:173 +#, no-wrap +msgid "" +"augroup lsp_install\n" +" au!\n" +" autocmd User lsp_buffer_enabled call s:on_lsp_buffer_enabled()\n" +"augroup END\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:176 +#, no-wrap +msgid "VSCode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:183 +msgid "" +"LSP client plugins are required to launch the language server daemon. Press " +"`Ctrl+Shift+X` to show the extension online search panel. Enter `llvm-vs-" +"code-extensions.vscode-clangd` when running clangd, or `ccls-project.ccls` " +"when running ccls." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:187 +msgid "" +"Then, press `Ctrl+Shift+P` to show the editor commands palette. Enter " +"`Preferences: Open Settings (JSON)` into the palette and hit `Enter` to open " +"[.filepath]#settings.json#. Depending on the language server " +"implementations, put one of the following JSON key/value pairs in [." +"filepath]#settings.json#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:201 +#, no-wrap +msgid "" +"[\n" +" /* Begin of your existing configurations */\n" +" ...\n" +" /* End of your existing configurations */\n" +" \"clangd.arguments\": [\n" +" \"--background-index\",\n" +" \"--header-insertion=never\"\n" +" ],\n" +" \"clangd.path\": \"clangd12\"\n" +"]\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:212 +#, no-wrap +msgid "" +"[\n" +" /* Begin of your existing configurations */\n" +" ...\n" +" /* End of your existing configurations */\n" +" \"ccls.cache.hierarchicalPath\": true\n" +"]\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:215 +#, no-wrap +msgid "Compilation database" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:221 +msgid "" +"A Compilation database contains an array of compile command objects. Each " +"object specifies a way of compiling a source file. The compilation database " +"file is usually [.filename]#compile_commands.json#. The database is used by " +"language server implementations for indexing purpose." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:223 +msgid "" +"Please refer to link:https://clang.llvm.org/docs/JSONCompilationDatabase." +"html#format[] for details on the format of the compilation database file." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:225 +#, no-wrap +msgid "Generators" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:228 +#, no-wrap +msgid "Using scan-build-py" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:230 +#, no-wrap +msgid "Installation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:234 +msgid "" +"`intercept-build` tool from scan-build-py is used to generate compilation " +"database." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:237 +msgid "" +"Install package:devel/python[] to get python interpreter first. To get " +"`intercept-build` from LLVM:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:241 +#, no-wrap +msgid "# git clone https://github.com/llvm/llvm-project /path/to/llvm-project\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:244 +msgid "" +"where [.filename]#/path/to/llvm-project/# is your desired path for the " +"repository. Make an alias in the shell configuration file for convenience:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:248 +#, no-wrap +msgid "alias intercept-build='/path/to/llvm-project/clang/tools/scan-build-py/bin/intercept-build'\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:254 +msgid "" +"link:https://github.com/rizsotto/scan-build[rizsotto/scan-build] can be used " +"instead of LLVM's scan-build-py. The LLVM's scan-build-py was rizsotto/scan-" +"build merged into the LLVM tree. This implementation can be installed by " +"`pip install --user scan-build`. The `intercept-build` script is in [." +"filename]#~/.local/bin# by default." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:255 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:271 +#, no-wrap +msgid "Usage" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:258 +msgid "" +"In the top-level directory of the FreeBSD src tree, generate the compilation " +"database with `intercept-build`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:262 +#, no-wrap +msgid "# intercept-build --append make buildworld buildkernel -j`sysctl -n hw.ncpu`\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:267 +msgid "" +"The `--append` flag tells the `intercept-build` to read an existing " +"compilation database (if a compilation database exists) and append the " +"results to the database. Entries with duplicated command keys are merged. " +"The generated compilation database by default is saved in the current " +"working directory as [.filename]#compile_commands.json#." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:269 +#, no-wrap +msgid "Using devel/bear" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:274 +msgid "" +"In the top-level directory of the FreeBSD src tree, to generate compilation " +"database with `bear`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:278 +#, no-wrap +msgid "# bear --append -- make buildworld buildkernel -j`sysctl -n hw.ncpu`\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:283 +msgid "" +"The `--append` flag tells `bear` to read an existing compilation database if " +"it is present, and append the results to the database. Entries with " +"duplicated command keys are merged. The generated compilation database by " +"default is saved in the current working directory as [." +"filename]#compile_commands.json#." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:285 +#, no-wrap +msgid "Final" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:289 +msgid "" +"Once the compilation database is generated, open any source files in the " +"FreeBSD src tree and LSP server daemon will be launched as well in " +"background. Opening source files in the src tree for the first time takes " +"significantly longer time before the LSP server is able to give a complete " +"result, due to initial background indexing by the LSP server compiling all " +"the listed entries in the compilation database. The language server daemon " +"however does not index the source files not appearing in the compilation " +"database, thus no complete results are shown on source files not being " +"compiled during the `make`." +msgstr "" diff --git a/documentation/content/en/articles/freebsd-status-report-process/_index.adoc b/documentation/content/en/articles/freebsd-status-report-process/_index.adoc new file mode 100644 index 0000000000..10f66607fb --- /dev/null +++ b/documentation/content/en/articles/freebsd-status-report-process/_index.adoc @@ -0,0 +1,290 @@ +--- +title: FreeBSD Status Report Process +authors: + - author: The FreeBSD Documentation Project +copyright: 2023-2025 The FreeBSD Documentation Project +description: Instructions for both writers and editors of status reports +trademarks: ["freebsd", "git", "github", "general"] +--- + += FreeBSD Status Report Process +:doctype: article +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:source-highlighter: rouge +:experimental: + +''' + +toc::[] + +FreeBSD status reports are published quarterly and provide the general public with a view of what is going on in the Project, and they are often augmented by special reports from Developer Summits. +As they are one of our most visible forms of communication, they are very important. + +Throughout this document and in other places related to FreeBSD status reports as well, the expression _status report_ is used both to indicate the document published on a quarterly basis and the single entries that are in it. + +== Instructions for writers + +This section provides some advice on writing status report entries. +Instructions on how to submit your entries are also given. + +_Do not worry if you are not a native English speaker. +The mailto:status@FreeBSD.org[status team] will check your entries for spelling and grammar, and fix it for you._ + +=== Introduce Your Work + +_Do not assume that the person reading the report knows about your project._ + +The status reports have a wide distribution. +They are often one of the top news items on the FreeBSD web site and are one of the first things that people will read if they want to know a bit about what FreeBSD is. +Consider this example: + +.... +abc(4) support was added, including frobnicator compatibility. +.... + +Someone reading this, if they are familiar with UNIX man pages, will know that `abc(4)` is some kind of device. +But why should the reader care? +What kind of device is it? +Compare with this version: + +.... +A new driver, abc(4), was added to the tree, bringing support for +Yoyodyne's range of Frobnicator network interfaces. +.... + +Now the reader knows that `abc` is a network interface driver. +Even if they do not use any Yoyodyne products, you have communicated that FreeBSD's support for network devices is improving. + +=== Show the Importance of Your Work + +_Status reports are not just about telling everyone that things were done, they also need to explain why they were done._ + +Carry on with the previous example. +Why is it interesting that we now support Yoyodyne Frobnicator cards? +Are they widespread? +Are they used in a specific popular device? +Are they used in a particular niche where FreeBSD has (or would like to have) a presence? +Are they the fastest network cards on the planet? +Status reports often say things like this: + +.... +We imported Cyberdyne Systems T800 into the tree. +.... + +And then they stop. +Maybe the reader is an avid Cyberdyne fan and knows what exciting new features the T800 brings. +This is unlikely. +It is far more likely that they have vaguely heard of whatever you have imported (especially into the ports tree: remember that there are over 35,000 other things there too...). +List some of the new features, or bug fixes. +Tell them why it is a good thing that we have the new version. + +=== Tell Us Something New + +_Do not recycle the same status report items._ + +Bear in mind that status reports are not just reports on the status of the project, they are reports on the change of status of the project. +If there is an ongoing project, spend a couple of sentences introducing it, but then spend the rest of the report talking about the new work. +What progress has been made since the last report? +What is left to do? +When is it likely to be finished (or, if "finished" does not really apply, when is it likely to be ready for wider use, for testing, for deployment in production, and so on)? + +=== Sponsorship + +_Do not forget about your sponsors._ + +If you or your project has received sponsorship, a scholarship from somebody or you have been already working as a contractor or an employee for a company, please include it. +Sponsors always certainly appreciate if you thank them for their funding, but it is also beneficial for them to show that they are actively supporting the Project this way. +Last, but not least, this helps FreeBSD to learn more about its important consumers. + +=== Open Items + +_If help is needed, make this explicit!_ + +Is there any help needed with something? +Are there tasks other people can do? +There are two ways in which you can use the open items part of the status report: to solicit help, or to give a quick overview of the amount of work left. +If there are already enough people working on the project, or it is in a state where adding more people would not speed it up, then the latter is better. +Give some big work items that are in progress, and maybe indicate who is focussing on each one. + +List tasks, with enough detail that people know if they are likely to be able to do them, and invite people to get in contact. + +=== Submit your report + +The following methods are available to submit your reports: + +* submit a link:https://reviews.freebsd.org/[Phabricator review] and add the group _status_ to the reviewers list. +You should put your reports in the appropriate subdirectory of `doc/website/content/en/status/` (create it if it is missing); + +* submit a pull request to the doc repository through link:https://github.com/freebsd/freebsd-doc[its GitHub mirror] . +You should put your reports in the appropriate subdirectory of `doc/website/content/en/status` (create it if it is missing); + +* send an email to status-submissions@FreeBSD.org including your report. + +An link:https://www.FreeBSD.org/status/report-sample.adoc[AsciiDoc sample report template] is available. + +== Instructions for editors + +This section describes how the reviewing and publication process works. + +[.informaltable] +[cols="1,1", frame="none"] +|=== + +|Status reports main webpage +|link:https://www.FreeBSD.org/status/[https://www.FreeBSD.org/status/] + +|Status reports archived GitHub repository (was used for reports from 2017Q4 to 2022Q4): +|link:https://www.github.com/freebsd/freebsd-quarterly[https://github.com/freebsd/freebsd-quarterly] + +|Main status team email address +|link:mailto:status@FreeBSD.org[status@FreeBSD.org] + +|Email address for reports submission +|link:mailto:status-submissions@FreeBSD.org[status-submissions@FreeBSD.org] + +|Mailing list for receiving calls for status reports +|link:https://lists.freebsd.org/subscription/freebsd-status-calls[freebsd-status-calls@FreeBSD.org] + +|Phabricator status team main page +|link:https://reviews.freebsd.org/project/profile/88/[https://reviews.freebsd.org/project/88/] +|=== + +=== Timeline + +Reports are always accepted by the status team, but the main collection process happens the last month of each quarter, hence in March, June, September and December. +Explicit calls for status reports will be sent in those months. +The months of January, April, July and October are dedicated to putting together the reports submitted during the precedent quarter; this can include waiting for late submissions. +Status reports publication is done during the same months as soon as the report are ready. + +All report submissions can have the deadline extended by link:mailto:status-submissions@FreeBSD.org[emailing the status team] up until the extended deadline, which is 8 days after the end of the quarter. +Entries from the link:https://www.freebsd.org/administration/#t-portmgr[ports management team] default to the extended headline, because of the overlap between status reports and quarterly ports branches. + +Reviewing of submitted reports by people not part of the status team should be essentially complete by mid-January/April/July/October (third-party review slush). +That is, barring typos or other light copyediting, the status team should be able to start assembling the submissions soon after the 15th. +Note that this is not a complete freeze, and the status team may still be able to accept reviews then. + +[cols="1,2,2,2,2"] +|=== +||First quarter|Second quarter|Third quarter|Fourth quarter + +|First call for reports +|March 1st +|June 1st +|September 1st +|December 1st + +|2 weeks left reminder +|March 15th +|June 15th +|September 15th +|December 15th + +|Last reminder +|March 24th +|June 24th +|September 24th +|December 24th + +|Standard deadline +|March 31st +|June 30th +|September 30th +|December 31st + +|Extended deadline +|April 8th +|July 8th +|October 8th +|January 8th + +|Third-party review slush +|April 15th +|July 15th +|October 15th +|January 15th +|=== + +=== Call for reports + +Calls for status reports are sent to the following recipients: + +* the link:https://lists.freebsd.org/subscription/freebsd-status-calls[freebsd-status-calls@FreeBSD.org mailing list]; +* to all submitters of last status reports (they may have updates or further improvements); +* and, depending on the season, + ** Various conference organizers: + *** link:mailto:secretary@asiabsdcon.org[AsiaBSDCon] in March (First Quarter); + *** link:mailto:info@bsdcan.org[BSDCan] in May (Second Quarter); + ** Various conference attendees: + *** EuroBSDcon in September - October (Third-Fourth Quarter); + EuroBSDcon as an organization is not interested in writing reports for FreeBSD - at least it was not in October 2019: its reason is that the conference is not FreeBSD specific. + Hence, reports about this event should be asked of members of the FreeBSD community that attended it. + ** Google Summer of Code link:mailto:soc-students@FreeBSD.org[students] and their link:mailto:soc-mentors@FreeBSD.org[mentors]. + +The easiest way to send calls for status reports is to use the link:https://cgit.freebsd.org/doc/tree/tools/sendcalls/sendcalls[[.filename]#sendcalls# perl script] in the [.filename]#tools/sendcalls# directory of the doc git repository. +The script automatically sends calls to all intended recipients. +It can also be used through a cron job, for example: + +.... +0 0 1,15,24 3,6,9,12 * cd ~/doc/tools/sendcalls && git pull && ./sendcalls -s 'Lorenzo Salvadore' +.... + +[IMPORTANT] +==== +If you are in charge of sending calls for status reports and you are indeed using a cron job, please run it on freefall and sign it with your name so that it is possible to infer who has configured the cronjob, in case something goes wrong. +Also please update the example above with your name, as an additional safety measure. +==== + +It may also be worth making a call for reports on the forums as link:https://forums.freebsd.org/threads/call-for-freebsd-2014q4-october-december-status-reports.49812/[was done in the past]. + +=== Building the report + +Submitted reports are reviewed and merged in the proper subdirectory of [.filename]#doc/website/content/en/status/# as they come in. +While the reports are being updated, people outside the status team may also review the individual entries and propose fixes. + +Usually the last step in the content review process is writing the introduction in a file named [.filename]#intro.adoc#: a good introduction can only be written once all the reports have been collected. +If possible, it is a good idea to ask different people to write the introduction to add variety: different people will bring different viewpoints and help keep it fresh. + +Once all the reports and the introduction are ready, the [.filename]#_index.adoc# file needs to be created: this is the file in which the reports are distributed into the various categories and sorted. + +=== Publishing the report + +When all the files of the status report are ready, it is time to publish it. + +First [.filename]#doc/website/content/en/status/_index.adoc# is edited: the next due date is updated and a link to the new report is added. +The change is then pushed on the repository and the status team checks that everythings works as expected. + +Then the news entry for the main website page is added to [.filename]#doc/website/data/en/news/news.toml#. + +Here is a sample for the news entry: +.... +[[news]] +date = "2021-01-16" +title = "October-December 2020 Status Report" +description = "The <a href=\"https://www.FreeBSD.org/status/report-2020-10-2020-12.html\">October to December 2020 Status Report</a> is now available with 42 entries." +.... + +Once the HTML version of the report has been built and is online, man:w3m[1] is used to dump the website as plain-text, e.g: +.... +% w3m -cols 80 -dump https://www.FreeBSD.org/status/report-2021-01-2021-03/ > /tmp/report-2021-01-2021-03.txt +.... + +man:w3m[1] has full proper unicode support. `-dump` simply outputs text rendering of the HTML code that can then have a few elements snipped, while `-cols` ensures that everything is wrapped to 80 columns. + +A link to the rendered report is added between the introduction and the first entry. + +The report is finally ready to be sent, toggling disposition (the report should be inlined), and ensuring it is encoded as UTF-8. + +Two emails are sent, both with subject in the format `FreeBSD Status Report - <First/Second/Third/Fourth> Quarter <year>`: + +* one to link:https://lists.freebsd.org/subscription/freebsd-announce[freebsd-announce@FreeBSD.org]; + +[IMPORTANT] +==== +This one must be approved, so if you are in charge of sending this email, ensure that someone does it (mail link:mailto:postmaster@FreeBSD.org[postmaster] if it is taking long). +==== + +* one to link:https://lists.freebsd.org/subscription/freebsd-hackers[freebsd-hackers@FreeBSD.org], which also has link:https://lists.freebsd.org/subscription/freebsd-current[freebsd-current@FreeBSD.org] and link:https://lists.freebsd.org/subscription/freebsd-stable[freebsd-stable@FreeBSD.org] in CC and `developers@FreeBSD.org` in BCC. diff --git a/documentation/content/en/articles/freebsd-status-report-process/_index.po b/documentation/content/en/articles/freebsd-status-report-process/_index.po new file mode 100644 index 0000000000..c012594326 --- /dev/null +++ b/documentation/content/en/articles/freebsd-status-report-process/_index.po @@ -0,0 +1,854 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-05-01 19:56-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:1 +#, no-wrap +msgid "Instructions for both writers and editors of status reports" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:1 +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:10 +#, no-wrap +msgid "FreeBSD Status Report Process" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:21 +msgid "'''" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:26 +msgid "" +"FreeBSD status reports are published quarterly and provide the general " +"public with a view of what is going on in the Project, and they are often " +"augmented by special reports from Developer Summits. As they are one of our " +"most visible forms of communication, they are very important." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:28 +msgid "" +"Throughout this document and in other places related to FreeBSD status " +"reports as well, the expression _status report_ is used both to indicate the " +"document published on a quarterly basis and the single entries that are in " +"it." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:29 +#, no-wrap +msgid "Instructions for writers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:33 +msgid "" +"This section provides some advice on writing status report entries. " +"Instructions on how to submit your entries are also given." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:36 +msgid "" +"_Do not worry if you are not a native English speaker. The " +"mailto:status@FreeBSD.org[status team] will check your entries for spelling " +"and grammar, and fix it for you._" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:37 +#, no-wrap +msgid "Introduce Your Work" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:40 +msgid "" +"_Do not assume that the person reading the report knows about your project._" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:44 +msgid "" +"The status reports have a wide distribution. They are often one of the top " +"news items on the FreeBSD web site and are one of the first things that " +"people will read if they want to know a bit about what FreeBSD is. Consider " +"this example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:47 +#, no-wrap +msgid "abc(4) support was added, including frobnicator compatibility.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:53 +msgid "" +"Someone reading this, if they are familiar with UNIX man pages, will know " +"that `abc(4)` is some kind of device. But why should the reader care? What " +"kind of device is it? Compare with this version:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:57 +#, no-wrap +msgid "" +"A new driver, abc(4), was added to the tree, bringing support for\n" +"Yoyodyne's range of Frobnicator network interfaces.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:61 +msgid "" +"Now the reader knows that `abc` is a network interface driver. Even if they " +"do not use any Yoyodyne products, you have communicated that FreeBSD's " +"support for network devices is improving." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:62 +#, no-wrap +msgid "Show the Importance of Your Work" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:65 +msgid "" +"_Status reports are not just about telling everyone that things were done, " +"they also need to explain why they were done._" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:73 +msgid "" +"Carry on with the previous example. Why is it interesting that we now " +"support Yoyodyne Frobnicator cards? Are they widespread? Are they used in a " +"specific popular device? Are they used in a particular niche where FreeBSD " +"has (or would like to have) a presence? Are they the fastest network cards " +"on the planet? Status reports often say things like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:76 +#, no-wrap +msgid "We imported Cyberdyne Systems T800 into the tree.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:84 +msgid "" +"And then they stop. Maybe the reader is an avid Cyberdyne fan and knows " +"what exciting new features the T800 brings. This is unlikely. It is far " +"more likely that they have vaguely heard of whatever you have imported " +"(especially into the ports tree: remember that there are over 35,000 other " +"things there too...). List some of the new features, or bug fixes. Tell " +"them why it is a good thing that we have the new version." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:85 +#, no-wrap +msgid "Tell Us Something New" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:88 +msgid "_Do not recycle the same status report items._" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:94 +msgid "" +"Bear in mind that status reports are not just reports on the status of the " +"project, they are reports on the change of status of the project. If there " +"is an ongoing project, spend a couple of sentences introducing it, but then " +"spend the rest of the report talking about the new work. What progress has " +"been made since the last report? What is left to do? When is it likely to be " +"finished (or, if \"finished\" does not really apply, when is it likely to be " +"ready for wider use, for testing, for deployment in production, and so on)?" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:95 +#, no-wrap +msgid "Sponsorship" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:98 +msgid "_Do not forget about your sponsors._" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:102 +msgid "" +"If you or your project has received sponsorship, a scholarship from somebody " +"or you have been already working as a contractor or an employee for a " +"company, please include it. Sponsors always certainly appreciate if you " +"thank them for their funding, but it is also beneficial for them to show " +"that they are actively supporting the Project this way. Last, but not " +"least, this helps FreeBSD to learn more about its important consumers." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:103 +#, no-wrap +msgid "Open Items" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:106 +msgid "_If help is needed, make this explicit!_" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:112 +msgid "" +"Is there any help needed with something? Are there tasks other people can " +"do? There are two ways in which you can use the open items part of the " +"status report: to solicit help, or to give a quick overview of the amount of " +"work left. If there are already enough people working on the project, or it " +"is in a state where adding more people would not speed it up, then the " +"latter is better. Give some big work items that are in progress, and maybe " +"indicate who is focussing on each one." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:114 +msgid "" +"List tasks, with enough detail that people know if they are likely to be " +"able to do them, and invite people to get in contact." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:115 +#, no-wrap +msgid "Submit your report" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:118 +msgid "The following methods are available to submit your reports:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:121 +msgid "" +"submit a link:https://reviews.freebsd.org/[Phabricator review] and add the " +"group _status_ to the reviewers list. You should put your reports in the " +"appropriate subdirectory of `doc/website/content/en/status/` (create it if " +"it is missing);" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:124 +msgid "" +"submit a pull request to the doc repository through link:https://github.com/" +"freebsd/freebsd-doc[its GitHub mirror] . You should put your reports in the " +"appropriate subdirectory of `doc/website/content/en/status` (create it if it " +"is missing);" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:126 +msgid "send an email to status-submissions@FreeBSD.org including your report." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:128 +msgid "" +"An link:https://www.FreeBSD.org/status/report-sample.adoc[AsciiDoc sample " +"report template] is available." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:129 +#, no-wrap +msgid "Instructions for editors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:132 +msgid "This section describes how the reviewing and publication process works." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:138 +#, no-wrap +msgid "Status reports main webpage" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:140 +#, no-wrap +msgid "link:https://www.FreeBSD.org/status/[https://www.FreeBSD.org/status/]" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:141 +#, no-wrap +msgid "Status reports archived GitHub repository (was used for reports from 2017Q4 to 2022Q4):" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:143 +#, no-wrap +msgid "link:https://www.github.com/freebsd/freebsd-quarterly[https://github.com/freebsd/freebsd-quarterly]" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:144 +#, no-wrap +msgid "Main status team email address" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:146 +#, no-wrap +msgid "link:mailto:status@FreeBSD.org[status@FreeBSD.org]" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:147 +#, no-wrap +msgid "Email address for reports submission" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:149 +#, no-wrap +msgid "link:mailto:status-submissions@FreeBSD.org[status-submissions@FreeBSD.org]" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:150 +#, no-wrap +msgid "Mailing list for receiving calls for status reports" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:152 +#, no-wrap +msgid "link:https://lists.freebsd.org/subscription/freebsd-status-calls[freebsd-status-calls@FreeBSD.org]" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:153 +#, no-wrap +msgid "Phabricator status team main page" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:154 +#, no-wrap +msgid "link:https://reviews.freebsd.org/project/profile/88/[https://reviews.freebsd.org/project/88/]" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:156 +#, no-wrap +msgid "Timeline" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:162 +msgid "" +"Reports are always accepted by the status team, but the main collection " +"process happens the last month of each quarter, hence in March, June, " +"September and December. Explicit calls for status reports will be sent in " +"those months. The months of January, April, July and October are dedicated " +"to putting together the reports submitted during the precedent quarter; this " +"can include waiting for late submissions. Status reports publication is " +"done during the same months as soon as the report are ready." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:165 +msgid "" +"All report submissions can have the deadline extended by link:mailto:status-" +"submissions@FreeBSD.org[emailing the status team] up until the extended " +"deadline, which is 8 days after the end of the quarter. Entries from the " +"link:https://www.freebsd.org/administration/#t-portmgr[ports management " +"team] default to the extended headline, because of the overlap between " +"status reports and quarterly ports branches." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:169 +msgid "" +"Reviewing of submitted reports by people not part of the status team should " +"be essentially complete by mid-January/April/July/October (third-party " +"review slush). That is, barring typos or other light copyediting, the " +"status team should be able to start assembling the submissions soon after " +"the 15th. Note that this is not a complete freeze, and the status team may " +"still be able to accept reviews then." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:172 +#, no-wrap +msgid "First quarter" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:172 +#, no-wrap +msgid "Second quarter" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:172 +#, no-wrap +msgid "Third quarter" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:174 +#, no-wrap +msgid "Fourth quarter" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:175 +#, no-wrap +msgid "First call for reports" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:176 +#, no-wrap +msgid "March 1st" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:177 +#, no-wrap +msgid "June 1st" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:178 +#, no-wrap +msgid "September 1st" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:180 +#, no-wrap +msgid "December 1st" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:181 +#, no-wrap +msgid "2 weeks left reminder" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:182 +#, no-wrap +msgid "March 15th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:183 +#, no-wrap +msgid "June 15th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:184 +#, no-wrap +msgid "September 15th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:186 +#, no-wrap +msgid "December 15th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:187 +#, no-wrap +msgid "Last reminder" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:188 +#, no-wrap +msgid "March 24th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:189 +#, no-wrap +msgid "June 24th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:190 +#, no-wrap +msgid "September 24th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:192 +#, no-wrap +msgid "December 24th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:193 +#, no-wrap +msgid "Standard deadline" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:194 +#, no-wrap +msgid "March 31st" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:195 +#, no-wrap +msgid "June 30th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:196 +#, no-wrap +msgid "September 30th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:198 +#, no-wrap +msgid "December 31st" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:199 +#, no-wrap +msgid "Extended deadline" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:200 +#, no-wrap +msgid "April 8th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:201 +#, no-wrap +msgid "July 8th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:202 +#, no-wrap +msgid "October 8th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:204 +#, no-wrap +msgid "January 8th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:205 +#, no-wrap +msgid "Third-party review slush" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:206 +#, no-wrap +msgid "April 15th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:207 +#, no-wrap +msgid "July 15th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:208 +#, no-wrap +msgid "October 15th" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:209 +#, no-wrap +msgid "January 15th" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:211 +#, no-wrap +msgid "Call for reports" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:214 +msgid "Calls for status reports are sent to the following recipients:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:216 +msgid "" +"the link:https://lists.freebsd.org/subscription/freebsd-status-calls[freebsd-" +"status-calls@FreeBSD.org mailing list];" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:217 +msgid "" +"to all submitters of last status reports (they may have updates or further " +"improvements);" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:218 +msgid "and, depending on the season," +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:219 +msgid "Various conference organizers:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:220 +msgid "" +"link:mailto:secretary@asiabsdcon.org[AsiaBSDCon] in March (First Quarter);" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:221 +msgid "link:mailto:info@bsdcan.org[BSDCan] in May (Second Quarter);" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:222 +msgid "Various conference attendees:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:225 +msgid "" +"EuroBSDcon in September - October (Third-Fourth Quarter); EuroBSDcon as an " +"organization is not interested in writing reports for FreeBSD - at least it " +"was not in October 2019: its reason is that the conference is not FreeBSD " +"specific. Hence, reports about this event should be asked of members of the " +"FreeBSD community that attended it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:226 +msgid "" +"Google Summer of Code link:mailto:soc-students@FreeBSD.org[students] and " +"their link:mailto:soc-mentors@FreeBSD.org[mentors]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:230 +msgid "" +"The easiest way to send calls for status reports is to use the link:https://" +"cgit.freebsd.org/doc/tree/tools/sendcalls/sendcalls[[.filename]#sendcalls# " +"perl script] in the [.filename]#tools/sendcalls# directory of the doc git " +"repository. The script automatically sends calls to all intended " +"recipients. It can also be used through a cron job, for example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:233 +#, no-wrap +msgid "0 0 1,15,24 3,6,9,12 * cd ~/doc/tools/sendcalls && git pull && ./sendcalls -s 'Lorenzo Salvadore'\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:239 +msgid "" +"If you are in charge of sending calls for status reports and you are indeed " +"using a cron job, please run it on freefall and sign it with your name so " +"that it is possible to infer who has configured the cronjob, in case " +"something goes wrong. Also please update the example above with your name, " +"as an additional safety measure." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:242 +msgid "" +"It may also be worth making a call for reports on the forums as link:https://" +"forums.freebsd.org/threads/call-for-freebsd-2014q4-october-december-status-" +"reports.49812/[was done in the past]." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:243 +#, no-wrap +msgid "Building the report" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:247 +msgid "" +"Submitted reports are reviewed and merged in the proper subdirectory of " +"[.filename]#doc/website/content/en/status/# as they come in. While the " +"reports are being updated, people outside the status team may also review " +"the individual entries and propose fixes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:250 +msgid "" +"Usually the last step in the content review process is writing the " +"introduction in a file named [.filename]#intro.adoc#: a good introduction " +"can only be written once all the reports have been collected. If possible, " +"it is a good idea to ask different people to write the introduction to add " +"variety: different people will bring different viewpoints and help keep it " +"fresh." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:252 +msgid "" +"Once all the reports and the introduction are ready, the " +"[.filename]#_index.adoc# file needs to be created: this is the file in which " +"the reports are distributed into the various categories and sorted." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:253 +#, no-wrap +msgid "Publishing the report" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:256 +msgid "" +"When all the files of the status report are ready, it is time to publish it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:259 +msgid "" +"First [.filename]#doc/website/content/en/status/_index.adoc# is edited: the " +"next due date is updated and a link to the new report is added. The change " +"is then pushed on the repository and the status team checks that everythings " +"works as expected." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:261 +msgid "" +"Then the news entry for the main website page is added to [.filename]#doc/" +"website/data/en/news/news.toml#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:263 +msgid "Here is a sample for the news entry:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:268 +#, no-wrap +msgid "" +"[[news]]\n" +"date = \"2021-01-16\"\n" +"title = \"October-December 2020 Status Report\"\n" +"description = \"The <a href=\\\"https://www.FreeBSD.org/status/report-2020-10-2020-12.html\\\">October to December 2020 Status Report</a> is now available with 42 entries.\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:271 +msgid "" +"Once the HTML version of the report has been built and is online, man:w3m[1] " +"is used to dump the website as plain-text, e.g:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:273 +#, no-wrap +msgid "% w3m -cols 80 -dump https://www.FreeBSD.org/status/report-2021-01-2021-03/ > /tmp/report-2021-01-2021-03.txt\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:276 +msgid "" +"man:w3m[1] has full proper unicode support. `-dump` simply outputs text " +"rendering of the HTML code that can then have a few elements snipped, while " +"`-cols` ensures that everything is wrapped to 80 columns." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:278 +msgid "" +"A link to the rendered report is added between the introduction and the " +"first entry." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:280 +msgid "" +"The report is finally ready to be sent, toggling disposition (the report " +"should be inlined), and ensuring it is encoded as UTF-8." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:282 +msgid "" +"Two emails are sent, both with subject in the format `FreeBSD Status Report " +"- <First/Second/Third/Fourth> Quarter <year>`:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:284 +msgid "" +"one to link:https://lists.freebsd.org/subscription/freebsd-announce[freebsd-" +"announce@FreeBSD.org];" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:288 +msgid "" +"This one must be approved, so if you are in charge of sending this email, " +"ensure that someone does it (mail " +"link:mailto:postmaster@FreeBSD.org[postmaster] if it is taking long)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-status-report-process/_index.adoc:290 +msgid "" +"one to link:https://lists.freebsd.org/subscription/freebsd-hackers[freebsd-" +"hackers@FreeBSD.org], which also has link:https://lists.freebsd.org/" +"subscription/freebsd-current[freebsd-current@FreeBSD.org] and link:https://" +"lists.freebsd.org/subscription/freebsd-stable[freebsd-stable@FreeBSD.org] in " +"CC and `developers@FreeBSD.org` in BCC." +msgstr "" diff --git a/documentation/content/en/articles/freebsd-update-server/_index.adoc b/documentation/content/en/articles/freebsd-update-server/_index.adoc index caaf17a3d7..fd7c066605 100644 --- a/documentation/content/en/articles/freebsd-update-server/_index.adoc +++ b/documentation/content/en/articles/freebsd-update-server/_index.adoc @@ -40,11 +40,21 @@ ifndef::env-beastie[] include::../../../../../shared/asciidoctor.adoc[] endif::[] + +[WARNING] +==== +The instructions in this article refer to an older version of FreeBSD and may +not work properly on recent versions of the OS. With the availability of +pkgbase, the freebsd-update utility is scheduled to be removed from FreeBSD in +the future. When that happens, this article is either updated to reflect the +new procedures or removed entirely. +==== + [.abstract-title] Abstract This article describes building an internal FreeBSD Update Server. -The https://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/[freebsd-update-server] is written by `{cperciva}`, Security Officer Emeritus of FreeBSD. +The https://github.com/freebsd/freebsd-update-build/[freebsd-update-server] is written by `{cperciva}`, Security Officer Emeritus of FreeBSD. For users that think it is convenient to update their systems against an official update server, building their own FreeBSD Update Server may help to extend its functionality by supporting manually-tweaked FreeBSD releases or by providing a local mirror that will allow faster updates for a number of machines. ''' @@ -78,17 +88,17 @@ At a minimum, updates require building on a FreeBSD release greater than or equa ==== * A user account with at least 4 GB of available space. This will allow the creation of updates for 7.1 and 7.2, but the exact space requirements may change from version to version. * An man:ssh[1] account on a remote machine to upload distributed updates. -* A web server, like extref:{handbook}[Apache, network-apache], with over half of the space required for the build. For instance, test builds for 7.1 and 7.2 consume a total amount of 4 GB, and the webserver space needed to distribute these updates is 2.6 GB. +* A web server, like extref:{handbook}network-servers[Apache, network-apache], with over half of the space required for the build. For instance, test builds for 7.1 and 7.2 consume a total amount of 4 GB, and the webserver space needed to distribute these updates is 2.6 GB. * Basic knowledge of shell scripting with Bourne shell, man:sh[1]. [[Configuration]] == Configuration: Installation & Setup -Download the https://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/[freebsd-update-server] software by installing package:devel/subversion[] and package:security/ca_root_nss[], and execute: +Download the https://github.com/freebsd/freebsd-update-build/[freebsd-update-server] software by installing package:devel/git[] and package:security/ca_root_nss[], and execute: [source,shell] .... -% svn co https://svn.freebsd.org/base/user/cperciva/freebsd-update-build freebsd-update-server +% git clone https://github.com/freebsd/freebsd-update-build.git freebsd-update-server .... Update [.filename]#scripts/build.conf# appropriately. @@ -271,7 +281,7 @@ A more detailed explanation may be found in [.filename]#scripts/build.subr#. [WARNING] ==== During this second build cycle, the network time protocol daemon, man:ntpd[8], is turned off. -Per `{cperciva}`, Security Officer Emeritus of FreeBSD, "the https://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/[freebsd-update-server] build code needs to identify timestamps which are stored in files so that they can be ignored when comparing builds to determine which files need to be updated. +Per `{cperciva}`, Security Officer Emeritus of FreeBSD, "the https://github.com/freebsd/freebsd-update-build/[freebsd-update-server] build code needs to identify timestamps which are stored in files so that they can be ignored when comparing builds to determine which files need to be updated. This timestamp-finding works by doing two builds 400 days apart and comparing the results." ==== @@ -392,9 +402,9 @@ In the event update code needs to be re-uploaded, this may be done by changing t The uploaded files will need to be in the document root of the webserver in order for updates to be distributed. The exact configuration will vary depending on the web server used. -For the Apache web server, please refer to the extref:{handbook}[Configuration of Apache servers, network-apache] section in the Handbook. +For the Apache web server, please refer to the extref:{handbook}network-servers[Configuration of Apache servers, network-apache] section in the Handbook. -Update client's `KeyPrint` and `ServerName` in [.filename]#/etc/freebsd-update.conf#, and perform updates as instructed in the extref:{handbook}[FreeBSD Update, updating-upgrading-freebsdupdate] section of the Handbook. +Update client's `KeyPrint` and `ServerName` in [.filename]#/etc/freebsd-update.conf#, and perform updates as instructed in the extref:{handbook}cutting-edge[FreeBSD Update, updating-upgrading-freebsdupdate] section of the Handbook. [IMPORTANT] ==== @@ -427,7 +437,7 @@ Create the patch directory of the respective release under [.filename]#/usr/loca As an example, take the patch for man:named[8]. Read the advisory, and grab the necessary file from link:https://www.FreeBSD.org/security/advisories/[FreeBSD Security Advisories]. -More information on interpreting the advisory, can be found in the extref:{handbook}[FreeBSD Handbook, security-advisories]. +More information on interpreting the advisory, can be found in the extref:{handbook}security[FreeBSD Handbook, security-advisories]. In the https://security.freebsd.org/advisories/FreeBSD-SA-09:12.bind.asc[security brief], this advisory is called `SA-09:12.bind`. After downloading the file, it is required to rename the file to an appropriate patch level. @@ -602,7 +612,7 @@ For reference, the entire run of link:../../source/articles/freebsd-update-serve findextradocs () { } # Add extra docs to ${WORKDIR}/$1 -addextradocs () { +addextradocs () { } .... @@ -621,7 +631,7 @@ addextradocs () { make ${COMPATFLAGS} release.1 release.2 2>&1 .... -* Create an appropriate extref:{handbook}[DNS, network-dns] SRV record for the update server, and put others behind it with variable weights. Using this facility will provide update mirrors, however this tip is not necessary unless you wish to provide a redundant service. +* Create an appropriate extref:{handbook}network-servers[DNS, network-dns] SRV record for the update server, and put others behind it with variable weights. Using this facility will provide update mirrors, however this tip is not necessary unless you wish to provide a redundant service. + [.programlisting] .... diff --git a/documentation/content/en/articles/freebsd-update-server/_index.po b/documentation/content/en/articles/freebsd-update-server/_index.po new file mode 100644 index 0000000000..5424e29877 --- /dev/null +++ b/documentation/content/en/articles/freebsd-update-server/_index.po @@ -0,0 +1,1039 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-01-17 20:35-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:1 +#, no-wrap +msgid "Building your own freebsd-update server allows a system administrator to perform fast updates for a number of machines from a local mirror" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:1 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:12 +#, no-wrap +msgid "Build Your Own FreeBSD Update Server" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:51 +msgid "" +"The instructions in this article refer to an older version of FreeBSD and " +"may not work properly on recent versions of the OS. With the availability of " +"pkgbase, the freebsd-update utility is scheduled to be removed from FreeBSD " +"in the future. When that happens, this article is either updated to reflect " +"the new procedures or removed entirely." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:55 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:59 +msgid "" +"This article describes building an internal FreeBSD Update Server. The " +"https://github.com/freebsd/freebsd-update-build/[freebsd-update-server] is " +"written by `{cperciva}`, Security Officer Emeritus of FreeBSD. For users " +"that think it is convenient to update their systems against an official " +"update server, building their own FreeBSD Update Server may help to extend " +"its functionality by supporting manually-tweaked FreeBSD releases or by " +"providing a local mirror that will allow faster updates for a number of " +"machines." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:61 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:65 +#, no-wrap +msgid "Acknowledgments" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:68 +msgid "" +"This article was subsequently printed at https://people.freebsd.org/~jgh/" +"files/fus/BSD_03_2010_EN.pdf[BSD Magazine]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:70 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:77 +msgid "" +"Experienced users or administrators are often responsible for several " +"machines or environments. They understand the difficult demands and " +"challenges of maintaining such an infrastructure. Running a FreeBSD Update " +"Server makes it easier to deploy security and software patches to selected " +"test machines before rolling them out to production. It also means a number " +"of systems can be updated from the local network rather than a potentially " +"slower Internet connection. This article outlines the steps involved in " +"creating an internal FreeBSD Update Server." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:79 +#, no-wrap +msgid "Prerequisites" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:82 +msgid "" +"To build an internal FreeBSD Update Server some requirements should be met." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:84 +msgid "A running FreeBSD system." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:88 +msgid "" +"At a minimum, updates require building on a FreeBSD release greater than or " +"equal to the target release version for distribution." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:90 +msgid "" +"A user account with at least 4 GB of available space. This will allow the " +"creation of updates for 7.1 and 7.2, but the exact space requirements may " +"change from version to version." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:91 +msgid "" +"An man:ssh[1] account on a remote machine to upload distributed updates." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:92 +msgid "" +"A web server, like extref:{handbook}[Apache, network-apache], with over half " +"of the space required for the build. For instance, test builds for 7.1 and " +"7.2 consume a total amount of 4 GB, and the webserver space needed to " +"distribute these updates is 2.6 GB." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:93 +msgid "Basic knowledge of shell scripting with Bourne shell, man:sh[1]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:95 +#, no-wrap +msgid "Configuration: Installation & Setup" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:98 +msgid "" +"Download the https://github.com/freebsd/freebsd-update-build/[freebsd-update-" +"server] software by installing package:devel/git[] and package:security/" +"ca_root_nss[], and execute:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:102 +#, no-wrap +msgid "% git clone https://github.com/freebsd/freebsd-update-build.git freebsd-update-server\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:106 +msgid "" +"Update [.filename]#scripts/build.conf# appropriately. It is sourced during " +"all build operations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:108 +msgid "" +"Here is the default [.filename]#build.conf#, which should be modified to " +"suit your environment." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:114 +#, no-wrap +msgid "" +"# Main configuration file for FreeBSD Update builds. The\n" +"# release-specific configuration data is lower down in\n" +"# the scripts tree.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:117 +#, no-wrap +msgid "" +"# Location from which to fetch releases\n" +"export FTP=ftp://ftp2.freebsd.org/pub/FreeBSD/releases <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:120 +#, no-wrap +msgid "" +"# Host platform\n" +"export HOSTPLATFORM=`uname -m`\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:123 +#, no-wrap +msgid "" +"# Host name to use inside jails\n" +"export BUILDHOSTNAME=${HOSTPLATFORM}-builder.daemonology.net <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:126 +#, no-wrap +msgid "" +"# Location of SSH key\n" +"export SSHKEY=/root/.ssh/id_dsa <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:129 +#, no-wrap +msgid "" +"# SSH account into which files are uploaded\n" +"MASTERACCT=builder@wadham.daemonology.net <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:132 +#, no-wrap +msgid "" +"# Directory into which files are uploaded\n" +"MASTERDIR=update-master.freebsd.org <.>\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:135 +msgid "Parameters for consideration would be:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:138 +msgid "" +"This is the location where ISO images are downloaded from (by the " +"`fetchiso()` subroutine of [.filename]#scripts/build.subr#). The location " +"configured is not limited to FTP URIs. Any URI scheme supported by standard " +"man:fetch[1] utility should work fine. Customizations to the `fetchiso()` " +"code can be installed by copying the default [.filename]#build.subr# script " +"to the release and architecture-specific area at [.filename]#scripts/RELEASE/" +"ARCHITECTURE/build.subr# and applying local changes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:140 +msgid "" +"The name of the build host. This information will be displayed on updated " +"systems when issuing:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:144 +#, no-wrap +msgid "% uname -v\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:148 +msgid "" +"The SSH key for uploading files to the update server. A key pair can be " +"created by typing `ssh-keygen -t dsa`. This parameter is optional; standard " +"password authentication will be used as a fallback authentication method " +"when `SSHKEY` is not defined. The man:ssh-keygen[1] manual page has more " +"detailed information about SSH and the appropriate steps for creating and " +"using one." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:150 +msgid "Account for uploading files to the update server." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:152 +msgid "Directory on the update server where files are uploaded to." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:154 +msgid "" +"The default [.filename]#build.conf# shipped with the freebsd-update-server " +"sources is suitable for building i386 releases of FreeBSD. As an example of " +"building an update server for other architectures, the following steps " +"outline the configuration changes needed for amd64:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:158 +msgid "Create a build environment for amd64:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:162 +#, no-wrap +msgid "% mkdir -p /usr/local/freebsd-update-server/scripts/7.2-RELEASE/amd64\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:165 +msgid "" +"Install a [.filename]#build.conf# in the newly created build directory. The " +"build configuration options for FreeBSD 7.2-RELEASE on amd64 should be " +"similar to:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:176 +#, no-wrap +msgid "" +"# SHA256 hash of RELEASE disc1.iso image.\n" +"export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5 <.>\n" +"# Components of the world, source, and kernels\n" +"export WORLDPARTS=\"base catpages dict doc games info manpages proflibs lib32\"\n" +"export SOURCEPARTS=\"base bin contrib crypto etc games gnu include krb5 \\\n" +" lib libexec release rescue sbin secure share sys tools \\\n" +" ubin usbin cddl\"\n" +"export KERNELPARTS=\"generic\"\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:179 +#, no-wrap +msgid "" +"# EOL date\n" +"export EOL=1275289200 <.>\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:182 +msgid "" +"The man:sha256[1] hash key for the desired release, is published within the " +"respective link:https://www.FreeBSD.org/releases/[release announcement]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:183 +msgid "" +"To generate the \"End of Life\" number for [.filename]#build.conf#, refer to " +"the \"Estimated EOL\" posted on the link:https://www.FreeBSD.org/security/" +"security/[FreeBSD Security Website]. The value of `EOL` can be derived from " +"the date listed on the web site, using the man:date[1] utility, for example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:187 +#, no-wrap +msgid "% date -j -f '%Y%m%d-%H%M%S' '20090401-000000' '+%s'\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:191 +#, no-wrap +msgid "Building Update Code" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:196 +msgid "" +"The first step is to run [.filename]#scripts/make.sh#. This will build some " +"binaries, create directories, and generate an RSA signing key used for " +"approving builds. In this step, a passphrase will have to be supplied for " +"the final creation of the signing key." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:211 +#, no-wrap +msgid "" +"# sh scripts/make.sh\n" +"cc -O2 -fno-strict-aliasing -pipe findstamps.c -o findstamps\n" +"findstamps.c: In function 'usage':\n" +"findstamps.c:45: warning: incompatible implicit declaration of built-in function 'exit'\n" +"cc -O2 -fno-strict-aliasing -pipe unstamp.c -o unstamp\n" +"install findstamps ../bin\n" +"install unstamp ../bin\n" +"rm -f findstamps unstamp\n" +"Generating RSA private key, 4096 bit long modulus\n" +"................................................................................++\n" +"...................++\n" +"e is 65537 (0x10001)\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:214 +#, no-wrap +msgid "" +"Public key fingerprint:\n" +"27ef53e48dc869eea6c3136091cc6ab8589f967559824779e855d58a2294de9e\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:218 +#, no-wrap +msgid "" +"Encrypting signing key for root\n" +"enter aes-256-cbc encryption password:\n" +"Verifying - enter aes-256-cbc encryption password:\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:224 +msgid "" +"Keep a note of the generated key fingerprint. This value is required in [." +"filename]#/etc/freebsd-update.conf# for binary updates." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:227 +msgid "At this point, we are ready to stage a build." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:232 +#, no-wrap +msgid "" +"# cd /usr/local/freebsd-update-server\n" +"# sh scripts/init.sh amd64 7.2-RELEASE\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:235 +msgid "What follows is a sample of an _initial_ build run." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:255 +#, no-wrap +msgid "" +"# sh scripts/init.sh amd64 7.2-RELEASE\n" +"Mon Aug 24 16:04:36 PDT 2009 Starting fetch for FreeBSD/amd64 7.2-RELEASE\n" +"/usr/local/freebsd-update-server/work/7.2-RELE100 of 588 MB 359 kBps 00m00s\n" +"Mon Aug 24 16:32:38 PDT 2009 Verifying disc1 hash for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 16:32:44 PDT 2009 Extracting components for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 16:34:05 PDT 2009 Constructing world+src image for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 16:35:57 PDT 2009 Extracting world+src for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 23:36:24 UTC 2009 Building world for FreeBSD/amd64 7.2-RELEASE\n" +"Tue Aug 25 00:31:29 UTC 2009 Distributing world for FreeBSD/amd64 7.2-RELEASE\n" +"Tue Aug 25 00:32:36 UTC 2009 Building and distributing kernels for FreeBSD/amd64 7.2-RELEASE\n" +"Tue Aug 25 00:44:44 UTC 2009 Constructing world components for FreeBSD/amd64 7.2-RELEASE\n" +"Tue Aug 25 00:44:56 UTC 2009 Distributing source for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 17:46:18 PDT 2009 Moving components into staging area for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 17:46:33 PDT 2009 Identifying extra documentation for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 17:47:13 PDT 2009 Extracting extra docs for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 17:47:18 PDT 2009 Indexing release for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 17:50:44 PDT 2009 Indexing world0 for FreeBSD/amd64 7.2-RELEASE\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:276 +#, no-wrap +msgid "" +"Files built but not released:\n" +"Files released but not built:\n" +"Files which differ by more than contents:\n" +"Files which differ between release and build:\n" +"kernel|generic|/GENERIC/hptrr.ko\n" +"kernel|generic|/GENERIC/kernel\n" +"src|sys|/sys/conf/newvers.sh\n" +"world|base|/boot/loader\n" +"world|base|/boot/pxeboot\n" +"world|base|/etc/mail/freebsd.cf\n" +"world|base|/etc/mail/freebsd.submit.cf\n" +"world|base|/etc/mail/sendmail.cf\n" +"world|base|/etc/mail/submit.cf\n" +"world|base|/lib/libcrypto.so.5\n" +"world|base|/usr/bin/ntpq\n" +"world|base|/usr/lib/libalias.a\n" +"world|base|/usr/lib/libalias_cuseeme.a\n" +"world|base|/usr/lib/libalias_dummy.a\n" +"world|base|/usr/lib/libalias_ftp.a\n" +"...\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:280 +msgid "" +"Then the build of the world is performed again, with world patches. A more " +"detailed explanation may be found in [.filename]#scripts/build.subr#." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:286 +msgid "" +"During this second build cycle, the network time protocol daemon, man:" +"ntpd[8], is turned off. Per `{cperciva}`, Security Officer Emeritus of " +"FreeBSD, \"the https://github.com/freebsd/freebsd-update-build/[freebsd-" +"update-server] build code needs to identify timestamps which are stored in " +"files so that they can be ignored when comparing builds to determine which " +"files need to be updated. This timestamp-finding works by doing two builds " +"400 days apart and comparing the results.\"" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:305 +#, no-wrap +msgid "" +"Mon Aug 24 17:54:07 PDT 2009 Extracting world+src for FreeBSD/amd64 7.2-RELEASE\n" +"Wed Sep 29 00:54:34 UTC 2010 Building world for FreeBSD/amd64 7.2-RELEASE\n" +"Wed Sep 29 01:49:42 UTC 2010 Distributing world for FreeBSD/amd64 7.2-RELEASE\n" +"Wed Sep 29 01:50:50 UTC 2010 Building and distributing kernels for FreeBSD/amd64 7.2-RELEASE\n" +"Wed Sep 29 02:02:56 UTC 2010 Constructing world components for FreeBSD/amd64 7.2-RELEASE\n" +"Wed Sep 29 02:03:08 UTC 2010 Distributing source for FreeBSD/amd64 7.2-RELEASE\n" +"Tue Sep 28 19:04:31 PDT 2010 Moving components into staging area for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 19:04:46 PDT 2009 Extracting extra docs for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 19:04:51 PDT 2009 Indexing world1 for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 19:08:04 PDT 2009 Locating build stamps for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 19:10:19 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 19:10:19 PDT 2009 Preparing to copy files into staging area for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 19:10:20 PDT 2009 Copying data files into staging area for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 12:16:57 PDT 2009 Copying metadata files into staging area for FreeBSD/amd64 7.2-RELEASE\n" +"Mon Aug 24 12:16:59 PDT 2009 Constructing metadata index and tag for FreeBSD/amd64 7.2-RELEASE\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:323 +#, no-wrap +msgid "" +"Files found which include build stamps:\n" +"kernel|generic|/GENERIC/hptrr.ko\n" +"kernel|generic|/GENERIC/kernel\n" +"world|base|/boot/loader\n" +"world|base|/boot/pxeboot\n" +"world|base|/etc/mail/freebsd.cf\n" +"world|base|/etc/mail/freebsd.submit.cf\n" +"world|base|/etc/mail/sendmail.cf\n" +"world|base|/etc/mail/submit.cf\n" +"world|base|/lib/libcrypto.so.5\n" +"world|base|/usr/bin/ntpq\n" +"world|base|/usr/include/osreldate.h\n" +"world|base|/usr/lib/libalias.a\n" +"world|base|/usr/lib/libalias_cuseeme.a\n" +"world|base|/usr/lib/libalias_dummy.a\n" +"world|base|/usr/lib/libalias_ftp.a\n" +"...\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:326 +msgid "Finally, the build completes." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:355 +#, no-wrap +msgid "" +"Values of build stamps, excluding library archive headers:\n" +"v1.2 (Aug 25 2009 00:40:36)\n" +"v1.2 (Aug 25 2009 00:38:22)\n" +"@()FreeBSD 7.2-RELEASE 0: Tue Aug 25 00:38:29 UTC 2009\n" +"FreeBSD 7.2-RELEASE 0: Tue Aug 25 00:38:29 UTC 2009\n" +" root@server.myhost.com:/usr/obj/usr/src/sys/GENERIC\n" +"7.2-RELEASE\n" +"Mon Aug 24 23:55:25 UTC 2009\n" +"Mon Aug 24 23:55:25 UTC 2009\n" +" built by root@server.myhost.com on Tue Aug 25 00:16:15 UTC 2009\n" +" built by root@server.myhost.com on Tue Aug 25 00:16:15 UTC 2009\n" +" built by root@server.myhost.com on Tue Aug 25 00:16:15 UTC 2009\n" +" built by root@server.myhost.com on Tue Aug 25 00:16:15 UTC 2009\n" +"Mon Aug 24 23:46:47 UTC 2009\n" +"ntpq 4.2.4p5-a Mon Aug 24 23:55:53 UTC 2009 (1)\n" +" * Copyright (c) 1992-2009 The FreeBSD Project.\n" +"Mon Aug 24 23:46:47 UTC 2009\n" +"Mon Aug 24 23:55:40 UTC 2009\n" +"Aug 25 2009\n" +"ntpd 4.2.4p5-a Mon Aug 24 23:55:52 UTC 2009 (1)\n" +"ntpdate 4.2.4p5-a Mon Aug 24 23:55:53 UTC 2009 (1)\n" +"ntpdc 4.2.4p5-a Mon Aug 24 23:55:53 UTC 2009 (1)\n" +"Tue Aug 25 00:21:21 UTC 2009\n" +"Tue Aug 25 00:21:21 UTC 2009\n" +"Tue Aug 25 00:21:21 UTC 2009\n" +"Mon Aug 24 23:46:47 UTC 2009\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:361 +#, no-wrap +msgid "" +"FreeBSD/amd64 7.2-RELEASE initialization build complete. Please\n" +"review the list of build stamps printed above to confirm that\n" +"they look sensible, then run\n" +" sh -e approve.sh amd64 7.2-RELEASE\n" +"to sign the release.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:366 +msgid "" +"Approve the build if everything is correct. More information on determining " +"this can be found in the distributed source file named [.filename]#USAGE#. " +"Execute [.filename]#scripts/approve.sh#, as directed. This will sign the " +"release, and move components into a staging area suitable for uploading." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:371 +#, no-wrap +msgid "" +"# cd /usr/local/freebsd-update-server\n" +"# sh scripts/mountkey.sh\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:381 +#, no-wrap +msgid "" +"# sh -e scripts/approve.sh amd64 7.2-RELEASE\n" +"Wed Aug 26 12:50:06 PDT 2009 Signing build for FreeBSD/amd64 7.2-RELEASE\n" +"Wed Aug 26 12:50:06 PDT 2009 Copying files to patch source directories for FreeBSD/amd64 7.2-RELEASE\n" +"Wed Aug 26 12:50:06 PDT 2009 Copying files to upload staging area for FreeBSD/amd64 7.2-RELEASE\n" +"Wed Aug 26 12:50:07 PDT 2009 Updating databases for FreeBSD/amd64 7.2-RELEASE\n" +"Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:384 +msgid "" +"After the approval process is complete, the upload procedure may be started." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:389 +#, no-wrap +msgid "" +"# cd /usr/local/freebsd-update-server\n" +"# sh scripts/upload.sh amd64 7.2-RELEASE\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:394 +msgid "" +"In the event update code needs to be re-uploaded, this may be done by " +"changing to the public distributions directory for the target release and " +"updating attributes of the _uploaded_ file." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:399 +#, no-wrap +msgid "" +"# cd /usr/local/freebsd-update-server/pub/7.2-RELEASE/amd64\n" +"# touch -t 200801010101.01 uploaded\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:406 +msgid "" +"The uploaded files will need to be in the document root of the webserver in " +"order for updates to be distributed. The exact configuration will vary " +"depending on the web server used. For the Apache web server, please refer " +"to the extref:{handbook}[Configuration of Apache servers, network-apache] " +"section in the Handbook." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:408 +msgid "" +"Update client's `KeyPrint` and `ServerName` in [.filename]#/etc/freebsd-" +"update.conf#, and perform updates as instructed in the extref:{handbook}" +"[FreeBSD Update, updating-upgrading-freebsdupdate] section of the Handbook." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:414 +msgid "" +"In order for FreeBSD Update Server to work properly, updates for both the " +"_current_ release and the release _one wants to upgrade to_ need to be " +"built. This is necessary for determining the differences of files between " +"releases. For example, when upgrading a FreeBSD system from 7.1-RELEASE to " +"7.2-RELEASE, updates will need to be built and uploaded to your distribution " +"server for both versions." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:417 +msgid "" +"For reference, the entire run of link:../../source/articles/freebsd-update-" +"server/init.txt[init.sh] is attached." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:419 +#, no-wrap +msgid "Building a Patch" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:422 +msgid "" +"Every time a link:https://www.FreeBSD.org/security/advisories/[security " +"advisory] or link:https://www.FreeBSD.org/security/notices/[security notice] " +"is announced, a patch update can be built." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:424 +msgid "For this example, 7.1-RELEASE will be used." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:426 +msgid "A couple of assumptions are made for a different release build:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:428 +msgid "Setup the correct directory structure for the initial build." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:429 +msgid "Perform an initial build for 7.1-RELEASE." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:431 +msgid "" +"Create the patch directory of the respective release under [.filename]#/usr/" +"local/freebsd-update-server/patches/#." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:436 +#, no-wrap +msgid "" +"% mkdir -p /usr/local/freebsd-update-server/patches/7.1-RELEASE/\n" +"% cd /usr/local/freebsd-update-server/patches/7.1-RELEASE\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:441 +msgid "" +"As an example, take the patch for man:named[8]. Read the advisory, and grab " +"the necessary file from link:https://www.FreeBSD.org/security/advisories/" +"[FreeBSD Security Advisories]. More information on interpreting the " +"advisory, can be found in the extref:{handbook}[FreeBSD Handbook, security-" +"advisories]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:446 +msgid "" +"In the https://security.freebsd.org/advisories/FreeBSD-SA-09:12.bind." +"asc[security brief], this advisory is called `SA-09:12.bind`. After " +"downloading the file, it is required to rename the file to an appropriate " +"patch level. It is suggested to keep this consistent with official FreeBSD " +"patch levels, but its name may be freely chosen. For this build, let us " +"follow the currently established practice of FreeBSD and call this `p7`. " +"Rename the file:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:450 +#, no-wrap +msgid "% cd /usr/local/freebsd-update-server/patches/7.1-RELEASE/; mv bind.patch 7-SA-09:12.bind\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:456 +msgid "" +"When running a patch level build, it is assumed that previous patches are in " +"place. When a patch build is run, it will run all patches contained in the " +"patch directory." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:458 +msgid "" +"There can be custom patches added to any build. Use the number zero, or any " +"other number." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:464 +msgid "" +"It is up to the administrator of the FreeBSD Update Server to take " +"appropriate measures to verify the authenticity of every patch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:468 +msgid "" +"At this point, a _diff_ is ready to be built. The software checks first to " +"see if a [.filename]#scripts/init.sh# has been run on the respective release " +"prior to running the diff build." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:473 +#, no-wrap +msgid "" +"# cd /usr/local/freebsd-update-server\n" +"# sh scripts/diff.sh amd64 7.1-RELEASE 7\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:476 +msgid "What follows is a sample of a _differential_ build run." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:550 +#, no-wrap +msgid "" +"# sh -e scripts/diff.sh amd64 7.1-RELEASE 7\n" +"Wed Aug 26 10:09:59 PDT 2009 Extracting world+src for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 17:10:25 UTC 2009 Building world for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 18:05:11 UTC 2009 Distributing world for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 18:06:16 UTC 2009 Building and distributing kernels for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 18:17:50 UTC 2009 Constructing world components for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 18:18:02 UTC 2009 Distributing source for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 11:19:23 PDT 2009 Moving components into staging area for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 11:19:37 PDT 2009 Extracting extra docs for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 11:19:42 PDT 2009 Indexing world0 for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 11:23:02 PDT 2009 Extracting world+src for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Thu Sep 30 18:23:29 UTC 2010 Building world for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Thu Sep 30 19:18:15 UTC 2010 Distributing world for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Thu Sep 30 19:19:18 UTC 2010 Building and distributing kernels for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Thu Sep 30 19:30:52 UTC 2010 Constructing world components for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Thu Sep 30 19:31:03 UTC 2010 Distributing source for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Thu Sep 30 12:32:25 PDT 2010 Moving components into staging area for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 12:32:39 PDT 2009 Extracting extra docs for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 12:32:43 PDT 2009 Indexing world1 for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 12:35:54 PDT 2009 Locating build stamps for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 12:36:58 PDT 2009 Reverting changes due to build stamps for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 12:37:14 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 12:37:14 PDT 2009 Preparing to copy files into staging area for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 12:37:15 PDT 2009 Copying data files into staging area for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 12:43:23 PDT 2009 Copying metadata files into staging area for FreeBSD/amd64 7.1-RELEASE-p7\n" +"Wed Aug 26 12:43:25 PDT 2009 Constructing metadata index and tag for FreeBSD/amd64 7.1-RELEASE-p7\n" +"...\n" +"Files found which include build stamps:\n" +"kernel|generic|/GENERIC/hptrr.ko\n" +"kernel|generic|/GENERIC/kernel\n" +"world|base|/boot/loader\n" +"world|base|/boot/pxeboot\n" +"world|base|/etc/mail/freebsd.cf\n" +"world|base|/etc/mail/freebsd.submit.cf\n" +"world|base|/etc/mail/sendmail.cf\n" +"world|base|/etc/mail/submit.cf\n" +"world|base|/lib/libcrypto.so.5\n" +"world|base|/usr/bin/ntpq\n" +"world|base|/usr/include/osreldate.h\n" +"world|base|/usr/lib/libalias.a\n" +"world|base|/usr/lib/libalias_cuseeme.a\n" +"world|base|/usr/lib/libalias_dummy.a\n" +"world|base|/usr/lib/libalias_ftp.a\n" +"...\n" +"Values of build stamps, excluding library archive headers:\n" +"v1.2 (Aug 26 2009 18:13:46)\n" +"v1.2 (Aug 26 2009 18:11:44)\n" +"@()FreeBSD 7.1-RELEASE-p7 0: Wed Aug 26 18:11:50 UTC 2009\n" +"FreeBSD 7.1-RELEASE-p7 0: Wed Aug 26 18:11:50 UTC 2009\n" +" root@server.myhost.com:/usr/obj/usr/src/sys/GENERIC\n" +"7.1-RELEASE-p7\n" +"Wed Aug 26 17:29:15 UTC 2009\n" +"Wed Aug 26 17:29:15 UTC 2009\n" +" built by root@server.myhost.com on Wed Aug 26 17:49:58 UTC 2009\n" +" built by root@server.myhost.com on Wed Aug 26 17:49:58 UTC 2009\n" +" built by root@server.myhost.com on Wed Aug 26 17:49:58 UTC 2009\n" +" built by root@server.myhost.com on Wed Aug 26 17:49:58 UTC 2009\n" +"Wed Aug 26 17:20:39 UTC 2009\n" +"ntpq 4.2.4p5-a Wed Aug 26 17:29:42 UTC 2009 (1)\n" +" * Copyright (c) 1992-2009 The FreeBSD Project.\n" +"Wed Aug 26 17:20:39 UTC 2009\n" +"Wed Aug 26 17:29:30 UTC 2009\n" +"Aug 26 2009\n" +"ntpd 4.2.4p5-a Wed Aug 26 17:29:41 UTC 2009 (1)\n" +"ntpdate 4.2.4p5-a Wed Aug 26 17:29:42 UTC 2009 (1)\n" +"ntpdc 4.2.4p5-a Wed Aug 26 17:29:42 UTC 2009 (1)\n" +"Wed Aug 26 17:55:02 UTC 2009\n" +"Wed Aug 26 17:55:02 UTC 2009\n" +"Wed Aug 26 17:55:02 UTC 2009\n" +"Wed Aug 26 17:20:39 UTC 2009\n" +"...\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:553 +msgid "Updates are printed, and approval is requested." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:572 +#, no-wrap +msgid "" +"New updates:\n" +"kernel|generic|/GENERIC/kernel.symbols|f|0|0|0555|0|7c8dc176763f96ced0a57fc04e7c1b8d793f27e006dd13e0b499e1474ac47e10|\n" +"kernel|generic|/GENERIC/kernel|f|0|0|0555|0|33197e8cf15bbbac263d17f39c153c9d489348c2c534f7ca1120a1183dec67b1|\n" +"kernel|generic|/|d|0|0|0755|0||\n" +"src|base|/|d|0|0|0755|0||\n" +"src|bin|/|d|0|0|0755|0||\n" +"src|cddl|/|d|0|0|0755|0||\n" +"src|contrib|/contrib/bind9/bin/named/update.c|f|0|10000|0644|0|4d434abf0983df9bc47435670d307fa882ef4b348ed8ca90928d250f42ea0757|\n" +"src|contrib|/contrib/bind9/lib/dns/openssldsa_link.c|f|0|10000|0644|0|c6805c39f3da2a06dd3f163f26c314a4692d4cd9a2d929c0acc88d736324f550|\n" +"src|contrib|/contrib/bind9/lib/dns/opensslrsa_link.c|f|0|10000|0644|0|fa0f7417ee9da42cc8d0fd96ad24e7a34125e05b5ae075bd6e3238f1c022a712|\n" +"...\n" +"FreeBSD/amd64 7.1-RELEASE update build complete. Please review\n" +"the list of build stamps printed above and the list of updated\n" +"files to confirm that they look sensible, then run\n" +" sh -e approve.sh amd64 7.1-RELEASE\n" +"to sign the build.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:575 +msgid "Follow the same process as noted before for approving a build:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:584 +#, no-wrap +msgid "" +"# sh -e scripts/approve.sh amd64 7.1-RELEASE\n" +"Wed Aug 26 12:50:06 PDT 2009 Signing build for FreeBSD/amd64 7.1-RELEASE\n" +"Wed Aug 26 12:50:06 PDT 2009 Copying files to patch source directories for FreeBSD/amd64 7.1-RELEASE\n" +"Wed Aug 26 12:50:06 PDT 2009 Copying files to upload staging area for FreeBSD/amd64 7.1-RELEASE\n" +"Wed Aug 26 12:50:07 PDT 2009 Updating databases for FreeBSD/amd64 7.1-RELEASE\n" +"Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.1-RELEASE\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:590 +#, no-wrap +msgid "" +"The FreeBSD/amd64 7.1-RELEASE update build has been signed and is\n" +"ready to be uploaded. Remember to run\n" +" sh -e umountkey.sh\n" +"to unmount the decrypted key once you have finished signing all\n" +"the new builds.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:593 +msgid "After approving the build, upload the software:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:598 +#, no-wrap +msgid "" +"# cd /usr/local/freebsd-update-server\n" +"# sh scripts/upload.sh amd64 7.1-RELEASE\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:601 +msgid "" +"For reference, the entire run of link:../../source/articles/freebsd-update-" +"server/diff.txt[diff.sh] is attached." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:603 +#, no-wrap +msgid "Tips" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:606 +msgid "" +"If a custom release is built using the native `make release` extref:{releng}" +"[procedure, release-build], freebsd-update-server code will work from your " +"release. As an example, a release without ports or documentation can be " +"built by clearing functionality pertaining to documentation subroutines " +"`findextradocs ()`, `addextradocs ()` and altering the download location in " +"`fetchiso ()`, respectively, in [.filename]#scripts/build.subr#. As a last " +"step, change the man:sha256[1] hash in [.filename]#build.conf# under your " +"respective release and architecture and you are ready to build off your " +"custom release." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:617 +#, no-wrap +msgid "" +"# Compare ${WORKDIR}/release and ${WORKDIR}/$1, identify which parts\n" +"# of the world|doc subcomponent are missing from the latter, and\n" +"# build a tarball out of them.\n" +"findextradocs () {\n" +"}\n" +"# Add extra docs to ${WORKDIR}/$1\n" +"addextradocs () {\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:620 +msgid "" +"Adding `-j _NUMBER_` flags to `buildworld` and `obj` targets in the [." +"filename]#scripts/build.subr# script may speed up processing depending on " +"the hardware used, however it is not necessary. Using these flags in other " +"targets is not recommended, as it may cause the build to become unreliable." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:632 +#, no-wrap +msgid "" +" # Build the world\n" +"\t\t log \"Building world\"\n" +"\t\t cd /usr/src &&\n" +"\t\t make -j 2 ${COMPATFLAGS} buildworld 2>&1\n" +"\t\t# Distribute the world\n" +"\t\t log \"Distributing world\"\n" +"\t\t cd /usr/src/release &&\n" +"\t\t make -j 2 obj &&\n" +"\t\t make ${COMPATFLAGS} release.1 release.2 2>&1\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:635 +msgid "" +"Create an appropriate extref:{handbook}[DNS, network-dns] SRV record for the " +"update server, and put others behind it with variable weights. Using this " +"facility will provide update mirrors, however this tip is not necessary " +"unless you wish to provide a redundant service." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/freebsd-update-server/_index.adoc:641 +#, no-wrap +msgid "" +"_http._tcp.update.myserver.com.\t\tIN SRV 0 2 80 host1.myserver.com.\n" +"\t\t\t\t\tIN SRV 0 1 80 host2.myserver.com.\n" +"\t\t\t\t\tIN SRV 0 0 80 host3.myserver.com.\n" +msgstr "" diff --git a/documentation/content/en/articles/geom-class/_index.adoc b/documentation/content/en/articles/geom-class/_index.adoc index cf10202e74..7613cb780a 100644 --- a/documentation/content/en/articles/geom-class/_index.adoc +++ b/documentation/content/en/articles/geom-class/_index.adoc @@ -152,7 +152,7 @@ This is controlled with two [.filename]#/etc/rc.conf# variables: [.programlisting] .... dumpdev="/dev/ad0s4b" -dumpdir="/usr/core +dumpdir="/usr/core" .... The `dumpdev` variable specifies the swap partition and `dumpdir` tells the system where in the filesystem to relocate the core dump on reboot. @@ -241,7 +241,7 @@ Structure `bio` is used for any and all Input/Output operations concerning GEOM. It basically contains information about what device ('provider') should satisfy the request, request type, offset, length, pointer to a buffer, and a bunch of "user-specific" flags and fields that can help implement various hacks. The important thing here is that ``bio``s are handled asynchronously. -That means that, in most parts of the code, there is no analogue to userland's man:read[2] and man:write[2] calls that do not return until a request is done. +That means that, in most parts of the code, there is no analogue to userland's man:read[2] and man:write[2] calls that do not return until a request is done. Rather, a developer-supplied function is called as a notification when the request gets completed (or results in error). The asynchronous programming model (also called "event-driven") is somewhat harder than the much more used imperative one used in userland (at least it takes a while to get used to it). diff --git a/documentation/content/en/articles/geom-class/_index.po b/documentation/content/en/articles/geom-class/_index.po new file mode 100644 index 0000000000..ef0c661432 --- /dev/null +++ b/documentation/content/en/articles/geom-class/_index.po @@ -0,0 +1,1059 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2022-02-01 09:21-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/geom-class/_index.adoc:1 +#, no-wrap +msgid "A guide to GEOM internals, and writing your own GEOM class" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/geom-class/_index.adoc:1 +#: documentation/content/en/articles/geom-class/_index.adoc:11 +#, no-wrap +msgid "Writing a GEOM Class" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:47 +msgid "" +"This text documents some starting points in developing GEOM classes, and " +"kernel modules in general. It is assumed that the reader is familiar with C " +"userland programming." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:49 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/geom-class/_index.adoc:53 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:56 +#, no-wrap +msgid "Documentation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:60 +msgid "" +"Documentation on kernel programming is scarce - it is one of few areas where " +"there is nearly nothing in the way of friendly tutorials, and the phrase " +"\"use the source!\" really holds true. However, there are some bits and " +"pieces (some of them seriously outdated) floating around that should be " +"studied before beginning to code:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:62 +msgid "" +"The extref:{developers-handbook}[FreeBSD Developer's Handbook] - part of the " +"documentation project, it does not contain anything specific to kernel " +"programming, but rather some general useful information." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:63 +msgid "" +"The extref:{arch-handbook}[FreeBSD Architecture Handbook] - also from the " +"documentation project, contains descriptions of several low-level facilities " +"and procedures. The most important chapter is 13, extref:{arch-handbook}" +"[Writing FreeBSD device drivers, driverbasics]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:64 +msgid "" +"The Blueprints section of http://www.freebsddiary.org[FreeBSD Diary] web " +"site - contains several interesting articles on kernel facilities." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:65 +msgid "" +"The man pages in section 9 - for important documentation on kernel functions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:66 +msgid "" +"The man:geom[4] man page and http://phk.freebsd.dk/pubs/[PHK's GEOM slides] " +"- for general introduction of the GEOM subsystem." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:67 +msgid "" +"Man pages man:g_bio[9], man:g_event[9], man:g_data[9], man:g_geom[9], man:" +"g_provider[9], man:g_consumer[9], man:g_access[9] & others linked from " +"those, for documentation on specific functionalities." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:68 +msgid "" +"The man:style[9] man page - for documentation on the coding-style " +"conventions which must be followed for any code which is to be committed to " +"the FreeBSD tree." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/geom-class/_index.adoc:70 +#, no-wrap +msgid "Preliminaries" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:77 +msgid "" +"The best way to do kernel development is to have (at least) two separate " +"computers. One of these would contain the development environment and " +"sources, and the other would be used to test the newly written code by " +"network-booting and network-mounting filesystems from the first one. This " +"way if the new code contains bugs and crashes the machine, it will not mess " +"up the sources (and other \"live\" data). The second system does not even " +"require a proper display. Instead, it could be connected with a serial " +"cable or KVM to the first one." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:80 +msgid "" +"But, since not everybody has two or more computers handy, there are a few " +"things that can be done to prepare an otherwise \"live\" system for " +"developing kernel code. This setup is also applicable for developing in a " +"http://www.vmware.com/[VMWare] or http://www.qemu.org/[QEmu] virtual machine " +"(the next best thing after a dedicated development machine)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:82 +#, no-wrap +msgid "Modifying a System for Development" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:85 +msgid "" +"For any kernel programming a kernel with `INVARIANTS` enabled is a must-" +"have. So enter these in your kernel configuration file:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:90 +#, no-wrap +msgid "" +"options INVARIANT_SUPPORT\n" +"options INVARIANTS\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:93 +msgid "" +"For more debugging you should also include WITNESS support, which will alert " +"you of mistakes in locking:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:98 +#, no-wrap +msgid "" +"options WITNESS_SUPPORT\n" +"options WITNESS\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:101 +msgid "For debugging crash dumps, a kernel with debug symbols is needed:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:105 +#, no-wrap +msgid " makeoptions DEBUG=-g\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:110 +msgid "" +"With the usual way of installing the kernel (`make installkernel`) the debug " +"kernel will not be automatically installed. It is called [.filename]#kernel." +"debug# and located in [.filename]#/usr/obj/usr/src/sys/KERNELNAME/#. For " +"convenience it should be copied to [.filename]#/boot/kernel/#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:113 +msgid "" +"Another convenience is enabling the kernel debugger so you can examine a " +"kernel panic when it happens. For this, enter the following lines in your " +"kernel configuration file:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:119 +#, no-wrap +msgid "" +"options KDB\n" +"options DDB\n" +"options KDB_TRACE\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:122 +msgid "" +"For this to work you might need to set a sysctl (if it is not on by default):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:126 +#, no-wrap +msgid " debug.debugger_on_panic=1\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:134 +msgid "" +"Kernel panics will happen, so care should be taken with the filesystem " +"cache. In particular, having softupdates might mean the latest file version " +"could be lost if a panic occurs before it is committed to storage. " +"Disabling softupdates yields a great performance hit, and still does not " +"guarantee data consistency. Mounting filesystem with the \"sync\" option is " +"needed for that. For a compromise, the softupdates cache delays can be " +"shortened. There are three sysctl's that are useful for this (best to be " +"set in [.filename]#/etc/sysctl.conf#):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:140 +#, no-wrap +msgid "" +"kern.filedelay=5\n" +"kern.dirdelay=4\n" +"kern.metadelay=3\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:143 +msgid "The numbers represent seconds." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:151 +msgid "" +"For debugging kernel panics, kernel core dumps are required. Since a kernel " +"panic might make filesystems unusable, this crash dump is first written to a " +"raw partition. Usually, this is the swap partition. This partition must be " +"at least as large as the physical RAM in the machine. On the next boot, the " +"dump is copied to a regular file. This happens after filesystems are " +"checked and mounted, and before swap is enabled. This is controlled with " +"two [.filename]#/etc/rc.conf# variables:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:156 +#, no-wrap +msgid "" +"dumpdev=\"/dev/ad0s4b\"\n" +"dumpdir=\"/usr/core\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:159 +msgid "" +"The `dumpdev` variable specifies the swap partition and `dumpdir` tells the " +"system where in the filesystem to relocate the core dump on reboot." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:162 +msgid "" +"Writing kernel core dumps is slow and takes a long time so if you have lots " +"of memory (>256M) and lots of panics it could be frustrating to sit and wait " +"while it is done (twice - first to write it to swap, then to relocate it to " +"filesystem). It is convenient then to limit the amount of RAM the system " +"will use via a [.filename]#/boot/loader.conf# tunable:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:166 +#, no-wrap +msgid " hw.physmem=\"256M\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:169 +msgid "" +"If the panics are frequent and filesystems large (or you simply do not trust " +"softupdates+background fsck) it is advisable to turn background fsck off via " +"[.filename]#/etc/rc.conf# variable:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:173 +#, no-wrap +msgid " background_fsck=\"NO\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:178 +msgid "" +"This way, the filesystems will always get checked when needed. Note that " +"with background fsck, a new panic could happen while it is checking the " +"disks. Again, the safest way is not to have many local filesystems by using " +"another computer as an NFS server." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:180 +#, no-wrap +msgid "Starting the Project" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:184 +msgid "" +"For the purpose of creating a new GEOM class, an empty subdirectory has to " +"be created under an arbitrary user-accessible directory. You do not have to " +"create the module directory under [.filename]#/usr/src#." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:186 +#, no-wrap +msgid "The Makefile" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:189 +msgid "" +"It is good practice to create [.filename]#Makefiles# for every nontrivial " +"coding project, which of course includes kernel modules." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:192 +msgid "" +"Creating the [.filename]#Makefile# is simple thanks to an extensive set of " +"helper routines provided by the system. In short, here is how a minimal [." +"filename]#Makefile# looks for a kernel module:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:197 +#, no-wrap +msgid "" +"SRCS=g_journal.c\n" +"KMOD=geom_journal\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:199 +#, no-wrap +msgid ".include <bsd.kmod.mk>\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:203 +msgid "" +"This [.filename]#Makefile# (with changed filenames) will do for any kernel " +"module, and a GEOM class can reside in just one kernel module. If more than " +"one file is required, list it in the `SRCS` variable, separated with " +"whitespace from other filenames." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/geom-class/_index.adoc:205 +#, no-wrap +msgid "On FreeBSD Kernel Programming" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:208 +#, no-wrap +msgid "Memory Allocation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:213 +msgid "" +"See man:malloc[9]. Basic memory allocation is only slightly different than " +"its userland equivalent. Most notably, `malloc`() and `free`() accept " +"additional parameters as is described in the man page." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:215 +msgid "" +"A \"malloc type\" must be declared in the declaration section of a source " +"file, like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:219 +#, no-wrap +msgid " static MALLOC_DEFINE(M_GJOURNAL, \"gjournal data\", \"GEOM_JOURNAL Data\");\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:222 +msgid "" +"To use this macro, [.filename]#sys/param.h#, [.filename]#sys/kernel.h# and [." +"filename]#sys/malloc.h# headers must be included." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:225 +msgid "" +"There is another mechanism for allocating memory, the UMA (Universal Memory " +"Allocator). See man:uma[9] for details, but it is a special type of " +"allocator mainly used for speedy allocation of lists comprised of same-sized " +"items (for example, dynamic arrays of structs)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:227 +#, no-wrap +msgid "Lists and Queues" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:234 +msgid "" +"See man:queue[3]. There are a LOT of cases when a list of things needs to " +"be maintained. Fortunately, this data structure is implemented (in several " +"ways) by C macros included in the system. The most used list type is TAILQ " +"because it is the most flexible. It is also the one with largest memory " +"requirements (its elements are doubly-linked) and also the slowest (although " +"the speed variation is on the order of several CPU instructions more, so it " +"should not be taken seriously)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:236 +msgid "" +"If data retrieval speed is very important, see man:tree[3] and man:" +"hashinit[9]." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:238 +#, no-wrap +msgid "BIOs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:242 +msgid "" +"Structure `bio` is used for any and all Input/Output operations concerning " +"GEOM. It basically contains information about what device ('provider') " +"should satisfy the request, request type, offset, length, pointer to a " +"buffer, and a bunch of \"user-specific\" flags and fields that can help " +"implement various hacks." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:246 +msgid "" +"The important thing here is that ``bio``s are handled asynchronously. That " +"means that, in most parts of the code, there is no analogue to userland's " +"man:read[2] and man:write[2] calls that do not return until a request is " +"done. Rather, a developer-supplied function is called as a notification " +"when the request gets completed (or results in error)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:250 +msgid "" +"The asynchronous programming model (also called \"event-driven\") is " +"somewhat harder than the much more used imperative one used in userland (at " +"least it takes a while to get used to it). In some cases the helper " +"routines `g_write_data`() and `g_read_data`() can be used, but __not " +"always__. In particular, they cannot be used when a mutex is held; for " +"example, the GEOM topology mutex or the internal mutex held during the `." +"start`() and `.stop`() functions." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/geom-class/_index.adoc:252 +#, no-wrap +msgid "On GEOM Programming" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:255 +#, no-wrap +msgid "Ggate" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:259 +msgid "" +"If maximum performance is not needed, a much simpler way of making a data " +"transformation is to implement it in userland via the ggate (GEOM gate) " +"facility. Unfortunately, there is no easy way to convert between, or even " +"share code between the two approaches." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:261 +#, no-wrap +msgid "GEOM Class" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:266 +msgid "" +"GEOM classes are transformations on the data. These transformations can be " +"combined in a tree-like fashion. Instances of GEOM classes are called " +"__geoms__." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:268 +msgid "" +"Each GEOM class has several \"class methods\" that get called when there is " +"no geom instance available (or they are simply not bound to a single " +"instance):" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:270 +msgid "" +"`.init` is called when GEOM becomes aware of a GEOM class (when the kernel " +"module gets loaded.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:271 +msgid "" +"`.fini` gets called when GEOM abandons the class (when the module gets " +"unloaded)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:272 +msgid "" +"`.taste` is called next, once for each provider the system has available. If " +"applicable, this function will usually create and start a geom instance." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:273 +msgid "`.destroy_geom` is called when the geom should be disbanded" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:274 +msgid "" +"`.ctlconf` is called when user requests reconfiguration of existing geom" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:276 +msgid "" +"Also defined are the GEOM event functions, which will get copied to the geom " +"instance." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:278 +msgid "" +"Field `.geom` in the `g_class` structure is a LIST of geoms instantiated " +"from the class." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:280 +msgid "These functions are called from the g_event kernel thread." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:282 +#, no-wrap +msgid "Softc" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:288 +msgid "" +"The name \"softc\" is a legacy term for \"driver private data\". The name " +"most probably comes from the archaic term \"software control block\". In " +"GEOM, it is a structure (more precise: pointer to a structure) that can be " +"attached to a geom instance to hold whatever data is private to the geom " +"instance. Most GEOM classes have the following members:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:290 +msgid "`struct g_provider *provider` : The \"provider\" this geom instantiates" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:291 +msgid "`uint16_t n_disks` : Number of consumer this geom consumes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:292 +msgid "" +"`struct g_consumer \\**disks` : Array of `struct g_consumer*`. (It is not " +"possible to use just single indirection because struct g_consumer* are " +"created on our behalf by GEOM)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:295 +msgid "" +"The `softc` structure contains all the state of geom instance. Every geom " +"instance has its own softc." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:297 +#, no-wrap +msgid "Metadata" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:300 +msgid "" +"Format of metadata is more-or-less class-dependent, but MUST start with:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:302 +msgid "16 byte buffer for null-terminated signature (usually the class name)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:303 +msgid "uint32 version ID" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:305 +msgid "" +"It is assumed that geom classes know how to handle metadata with version " +"ID's lower than theirs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:307 +msgid "" +"Metadata is located in the last sector of the provider (and thus must fit in " +"it)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:309 +msgid "" +"(All this is implementation-dependent but all existing code works like that, " +"and it is supported by libraries.)" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:311 +#, no-wrap +msgid "Labeling/creating a GEOM" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:314 +msgid "The sequence of events is:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:316 +msgid "user calls man:geom[8] utility (or one of its hardlinked friends)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:317 +msgid "" +"the utility figures out which geom class it is supposed to handle and " +"searches for [.filename]#geom_CLASSNAME.so# library (usually in [.filename]#/" +"lib/geom#)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:318 +msgid "" +"it man:dlopen[3]-s the library, extracts the definitions of command-line " +"parameters and helper functions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:320 +msgid "In the case of creating/labeling a new geom, this is what happens:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:322 +msgid "" +"man:geom[8] looks in the command-line argument for the command (usually " +"`label`), and calls a helper function." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:323 +msgid "" +"The helper function checks parameters and gathers metadata, which it " +"proceeds to write to all concerned providers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:324 +msgid "" +"This \"spoils\" existing geoms (if any) and initializes a new round of " +"\"tasting\" of the providers. The intended geom class recognizes the " +"metadata and brings the geom up." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:326 +msgid "" +"(The above sequence of events is implementation-dependent but all existing " +"code works like that, and it is supported by libraries.)" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:328 +#, no-wrap +msgid "GEOM Command Structure" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:332 +msgid "" +"The helper [.filename]#geom_CLASSNAME.so# library exports `class_commands` " +"structure, which is an array of `struct g_command` elements. Commands are " +"of uniform format and look like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/geom-class/_index.adoc:336 +#, no-wrap +msgid " verb [-options] geomname [other]\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:339 +msgid "Common verbs are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:341 +msgid "" +"label - to write metadata to devices so they can be recognized at tasting " +"and brought up in geoms" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:342 +msgid "destroy - to destroy metadata, so the geoms get destroyed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:344 +msgid "Common options are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:346 +msgid "`-v` : be verbose" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:347 +msgid "`-f` : force" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:351 +msgid "" +"Many actions, such as labeling and destroying metadata can be performed in " +"userland. For this, `struct g_command` provides field `gc_func` that can be " +"set to a function (in the same [.filename]#.so#) that will be called to " +"process a verb. If `gc_func` is NULL, the command will be passed to kernel " +"module, to `.ctlreq` function of the geom class." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:353 +#, no-wrap +msgid "Geoms" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:357 +msgid "" +"Geoms are instances of GEOM classes. They have internal data (a softc " +"structure) and some functions with which they respond to external events." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:359 +msgid "The event functions are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:361 +msgid "`.access` : calculates permissions (read/write/exclusive)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:362 +msgid "`.dumpconf` : returns XML-formatted information about the geom" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:363 +msgid "`.orphan` : called when some underlying provider gets disconnected" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:364 +msgid "`.spoiled` : called when some underlying provider gets written to" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:365 +msgid "`.start` : handles I/O" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:367 +msgid "" +"These functions are called from the `g_down` kernel thread and there can be " +"no sleeping in this context, (see definition of sleeping elsewhere) which " +"limits what can be done quite a bit, but forces the handling to be fast." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:369 +msgid "" +"Of these, the most important function for doing actual useful work is the `." +"start`() function, which is called when a BIO request arrives for a provider " +"managed by a instance of geom class." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:371 +#, no-wrap +msgid "GEOM Threads" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:374 +msgid "There are three kernel threads created and run by the GEOM framework:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:376 +msgid "" +"`g_down` : Handles requests coming from high-level entities (such as a " +"userland request) on the way to physical devices" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:377 +msgid "" +"`g_up` : Handles responses from device drivers to requests made by higher-" +"level entities" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:378 +msgid "" +"`g_event` : Handles all other cases: creation of geom instances, access " +"counting, \"spoil\" events, etc." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:380 +msgid "" +"When a user process issues \"read data X at offset Y of a file\" request, " +"this is what happens:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:382 +msgid "" +"The filesystem converts the request into a struct bio instance and passes it " +"to the GEOM subsystem. It knows what geom instance should handle it because " +"filesystems are hosted directly on a geom instance." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:383 +msgid "" +"The request ends up as a call to the `.start`() function made on the g_down " +"thread and reaches the top-level geom instance." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:384 +msgid "" +"This top-level geom instance (for example the partition slicer) determines " +"that the request should be routed to a lower-level instance (for example the " +"disk driver). It makes a copy of the bio request (bio requests _ALWAYS_ need " +"to be copied between instances, with `g_clone_bio`()!), modifies the data " +"offset and target provider fields and executes the copy with `g_io_request`()" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:385 +msgid "" +"The disk driver gets the bio request also as a call to `.start`() on the " +"`g_down` thread. It talks to hardware, gets the data back, and calls " +"`g_io_deliver`() on the bio." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:386 +msgid "" +"Now, the notification of bio completion \"bubbles up\" in the `g_up` thread. " +"First the partition slicer gets `.done`() called in the `g_up` thread, it " +"uses information stored in the bio to free the cloned `bio` structure (with " +"`g_destroy_bio`()) and calls `g_io_deliver`() on the original request." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:387 +msgid "The filesystem gets the data and transfers it to userland." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:389 +msgid "" +"See man:g_bio[9] man page for information how the data is passed back and " +"forth in the `bio` structure (note in particular the `bio_parent` and " +"`bio_children` fields and how they are handled)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:392 +msgid "" +"One important feature is: __THERE CAN BE NO SLEEPING IN G_UP AND G_DOWN " +"THREADS__. This means that none of the following things can be done in " +"those threads (the list is of course not complete, but only informative):" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:394 +msgid "Calls to `msleep`() and `tsleep`(), obviously." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:395 +msgid "" +"Calls to `g_write_data`() and `g_read_data`(), because these sleep between " +"passing the data to consumers and returning." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:396 +msgid "Waiting for I/O." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:397 +msgid "Calls to man:malloc[9] and `uma_zalloc`() with `M_WAITOK` flag set" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:398 +msgid "sx and other sleepable locks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:402 +msgid "" +"This restriction is here to stop GEOM code clogging the I/O request path, " +"since sleeping is usually not time-bound and there can be no guarantees on " +"how long will it take (there are some other, more technical reasons also). " +"It also means that there is not much that can be done in those threads; for " +"example, almost any complex thing requires memory allocation. Fortunately, " +"there is a way out: creating additional kernel threads." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/geom-class/_index.adoc:404 +#, no-wrap +msgid "Kernel Threads for Use in GEOM Code" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:407 +msgid "" +"Kernel threads are created with man:kthread_create[9] function, and they are " +"sort of similar to userland threads in behavior, only they cannot return to " +"caller to signify termination, but must call man:kthread_exit[9]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:410 +msgid "" +"In GEOM code, the usual use of threads is to offload processing of requests " +"from `g_down` thread (the `.start`() function). These threads look like " +"\"event handlers\": they have a linked list of event associated with them " +"(on which events can be posted by various functions in various threads so it " +"must be protected by a mutex), take the events from the list one by one and " +"process them in a big `switch`() statement." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:415 +msgid "" +"The main benefit of using a thread to handle I/O requests is that it can " +"sleep when needed. Now, this sounds good, but should be carefully thought " +"out. Sleeping is well and very convenient but can very effectively destroy " +"performance of the geom transformation. Extremely performance-sensitive " +"classes probably should do all the work in `.start`() function call, taking " +"great care to handle out-of-memory and similar errors." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:419 +msgid "" +"The other benefit of having a event-handler thread like that is to serialize " +"all the requests and responses coming from different geom threads into one " +"thread. This is also very convenient but can be slow. In most cases, " +"handling of `.done`() requests can be left to the `g_up` thread." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/geom-class/_index.adoc:422 +msgid "" +"Mutexes in FreeBSD kernel (see man:mutex[9]) have one distinction from their " +"more common userland cousins - the code cannot sleep while holding a " +"mutex). If the code needs to sleep a lot, man:sx[9] locks may be more " +"appropriate. On the other hand, if you do almost everything in a single " +"thread, you may get away with no mutexes at all." +msgstr "" diff --git a/documentation/content/en/articles/gjournal-desktop/_index.adoc b/documentation/content/en/articles/gjournal-desktop/_index.adoc index 71ce2b3084..164c92985b 100644 --- a/documentation/content/en/articles/gjournal-desktop/_index.adoc +++ b/documentation/content/en/articles/gjournal-desktop/_index.adoc @@ -61,7 +61,7 @@ On rare occasions, file system corruption reaches a point where user interventio The new journaling capability provided by GEOM can greatly assist in such scenarios, by virtually eliminating the time required for file system checking, and ensuring that the file system is quickly restored to a consistent state. -This article describes a procedure for implementing UFS journaling on a typical desktop PC scenario (one hard disk used for both operating system and data). +This article describes a procedure for implementing UFS journaling on a typical desktop PC scenario (one hard disk used for both operating system and data). It should be followed during a fresh installation of FreeBSD. The steps are simple enough and do not require overly complex interaction with the command line. @@ -106,14 +106,14 @@ For example: * You reserved some free disk space in a partition in [.filename]#/dev/ad0s1g#. * Using `gjournal`, a new [.filename]#/dev/ad0s1f.journal# device is created where [.filename]#/dev/ad0s1f# is the data provider, and [.filename]#/dev/ad0s1g# is the journal provider. This new device is then used for all subsequent file operations. -The amount of disk space you need to reserve for the journal provider depends on the usage load of the file system and not on the size of the data provider. +The amount of disk space you need to reserve for the journal provider depends on the usage load of the file system and not on the size of the data provider. For example on a typical office desktop, a 1 GB journal provider for the [.filename]#/usr# file system will suffice, while a machine that deals with heavy disk I/O (i.e. video editing) may need more. A kernel panic will occur if the journal space is exhausted before it has a chance to be committed. [NOTE] ==== The journal sizes suggested here, are highly unlikely to cause problems in typical desktop use (such as web browsing, word processing and playback of media files). -If your workload includes intense disk activity, use the following rule for maximum reliability: Your RAM size should fit in 30% of the journal provider's space. +If your workload includes intense disk activity, use the following rule for maximum reliability: Your RAM size should fit in 30% of the journal provider's space. For example, if your system has 1 GB RAM, create an approximately 3.3 GB journal provider. (Multiply your RAM size with 3.3 to obtain the size of the journal). ==== @@ -197,7 +197,7 @@ We would however suggest you postpone installation of third party software (pack [[first-boot]] === Booting for the first time -Your system will come up normally, but you will need to edit [.filename]#/etc/fstab# and remove the extra swap partitions you created for the journals. +Your system will come up normally, but you will need to edit [.filename]#/etc/fstab# and remove the extra swap partitions you created for the journals. Normally, the swap partition you will actually use is the one with the "b" suffix (i.e. ad0s1b in our example). Remove all other swap space entries and reboot so that FreeBSD will stop using them. @@ -371,7 +371,7 @@ options UFS_GJOURNAL # Note: This is already in GENERIC options GEOM_JOURNAL # You will have to add this one .... -Rebuild and reinstall your kernel following the relevant extref:{handbook}[instructions in the FreeBSD Handbook., kernelconfig] +Rebuild and reinstall your kernel following the relevant extref:{handbook}kernelconfig[instructions in the FreeBSD Handbook., kernelconfig] Do not forget to remove the relevant "load" entry from [.filename]#/boot/loader.conf# if you have previously used it. @@ -385,7 +385,7 @@ The following section covers frequently asked questions regarding problems relat The journal probably fills up before it has a chance to get committed (flushed) to disk. Keep in mind the size of the journal depends on the usage load, and not the size of the data provider. If your disk activity is high, you need a larger partition for the journal. -See the note in the <<understanding-journaling>> section. +See the note in the crossref:gjournal-desktop[understanding-journaling, Understanding Journaling in FreeBSD] section. === I made some mistake during configuration, and I cannot boot normally now. Can this be fixed some way? @@ -504,7 +504,7 @@ Finally, edit [.filename]#/boot/loader.conf#, remove the entry that loads the `g Journaling is a fairly new feature of FreeBSD, and as such, it is not very well documented yet. You may however find the following additional references useful: -* A extref:{handbook}[new section on journaling, geom-gjournal] is now part of the FreeBSD Handbook. +* A extref:{handbook}geom[new section on journaling, geom-gjournal] is now part of the FreeBSD Handbook. * https://lists.freebsd.org/pipermail/freebsd-current/2006-June/064043.html[This post] in {freebsd-current} by man:gjournal[8]'s developer, `{pjd}`. * https://lists.freebsd.org/pipermail/freebsd-questions/2008-April/173501.html[This post] in {freebsd-questions} by `{ivoras}`. * The manual pages of man:gjournal[8] and man:geom[8]. diff --git a/documentation/content/en/articles/gjournal-desktop/_index.po b/documentation/content/en/articles/gjournal-desktop/_index.po new file mode 100644 index 0000000000..260c965b75 --- /dev/null +++ b/documentation/content/en/articles/gjournal-desktop/_index.po @@ -0,0 +1,1029 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-12-29 08:30-0500\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: Title = +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:1 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:11 +#, no-wrap +msgid "Implementing UFS Journaling on a Desktop PC" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:50 +msgid "" +"A journaling file system uses a log to record all transactions that take " +"place in the file system, and preserves its integrity in the event of a " +"system crash or power failure. Although it is still possible to lose " +"unsaved changes to files, journaling almost completely eliminates the " +"possibility of file system corruption caused by an unclean shutdown. It " +"also shortens to a minimum the time required for after-failure file system " +"checking. Although the UFS file system employed by FreeBSD does not " +"implement journaling itself, the new journal class of the GEOM framework in " +"FreeBSD 7._X_ can be used to provide file system independent journaling. " +"This article explains how to implement UFS journaling on a typical desktop " +"PC scenario." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:52 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:56 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:61 +msgid "" +"While professional servers are usually well protected from unforeseen " +"shutdowns, the typical desktop is at the mercy of power failures, accidental " +"resets, and other user related incidents that can lead to unclean " +"shutdowns. Soft Updates usually protect the file system efficiently in such " +"cases, although most of the times a lengthy background check is required. " +"On rare occasions, file system corruption reaches a point where user " +"intervention is required and data may be lost." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:63 +msgid "" +"The new journaling capability provided by GEOM can greatly assist in such " +"scenarios, by virtually eliminating the time required for file system " +"checking, and ensuring that the file system is quickly restored to a " +"consistent state." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:67 +msgid "" +"This article describes a procedure for implementing UFS journaling on a " +"typical desktop PC scenario (one hard disk used for both operating system " +"and data). It should be followed during a fresh installation of FreeBSD. " +"The steps are simple enough and do not require overly complex interaction " +"with the command line." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:69 +msgid "After reading this article, you will know:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:71 +msgid "" +"How to reserve space for journaling during a new installation of FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:72 +msgid "" +"How to load and enable the `geom_journal` module (or build support for it in " +"your custom kernel)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:73 +msgid "" +"How to convert your existing file systems to utilize journaling, and what " +"options to use in [.filename]#/etc/fstab# to mount them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:74 +msgid "How to implement journaling in new (empty) partitions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:75 +msgid "How to troubleshoot common problems associated with journaling." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:77 +msgid "Before reading this article, you should be able to:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:79 +msgid "Understand basic UNIX(R) and FreeBSD concepts." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:80 +msgid "" +"Be familiar with the installation procedure of FreeBSD and the sysinstall " +"utility." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:86 +msgid "" +"The procedure described here is intended for preparing a new installation " +"where no actual user data is stored on the disk yet. While it is possible " +"to modify and extend this procedure for systems already in production, you " +"should _backup_ all important data before doing so. Messing around with " +"disks and partitions at a low level can lead to fatal mistakes and data loss." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:89 +#, no-wrap +msgid "Understanding Journaling in FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:93 +msgid "" +"The journaling provided by GEOM in FreeBSD 7._X_ is not file system specific " +"(unlike for example the ext3 file system in Linux(R)) but is functioning at " +"the block level. Though this means it can be applied to different file " +"systems, for FreeBSD 7.0-RELEASE, it can only be used on UFS2." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:97 +msgid "" +"This functionality is provided by loading the [.filename]#geom_journal.ko# " +"module into the kernel (or building it into a custom kernel) and using the " +"`gjournal` command to configure the file systems. In general, you would " +"like to journal large file systems, like [.filename]#/usr#. You will need " +"however (see the following section) to reserve some free disk space." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:104 +msgid "" +"When a file system is journaled, some disk space is needed to keep the " +"journal itself. The disk space that holds the actual data is referred to as " +"the __data provider__, while the one that holds the journal is referred to " +"as the __journal provider__. The data and journal providers need to be on " +"different partitions when journaling an existing (non-empty) partition. " +"When journaling a new partition, you have the option to use a single " +"provider for both data and journal. In any case, the `gjournal` command " +"combines both providers to create the final journaled file system. For " +"example:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:106 +msgid "" +"You wish to journal your [.filename]#/usr# file system, stored in [." +"filename]#/dev/ad0s1f# (which already contains data)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:107 +msgid "" +"You reserved some free disk space in a partition in [.filename]#/dev/ad0s1g#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:108 +msgid "" +"Using `gjournal`, a new [.filename]#/dev/ad0s1f.journal# device is created " +"where [.filename]#/dev/ad0s1f# is the data provider, and [.filename]#/dev/" +"ad0s1g# is the journal provider. This new device is then used for all " +"subsequent file operations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:112 +msgid "" +"The amount of disk space you need to reserve for the journal provider " +"depends on the usage load of the file system and not on the size of the data " +"provider. For example on a typical office desktop, a 1 GB journal provider " +"for the [.filename]#/usr# file system will suffice, while a machine that " +"deals with heavy disk I/O (i.e. video editing) may need more. A kernel " +"panic will occur if the journal space is exhausted before it has a chance to " +"be committed." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:119 +msgid "" +"The journal sizes suggested here, are highly unlikely to cause problems in " +"typical desktop use (such as web browsing, word processing and playback of " +"media files). If your workload includes intense disk activity, use the " +"following rule for maximum reliability: Your RAM size should fit in 30% of " +"the journal provider's space. For example, if your system has 1 GB RAM, " +"create an approximately 3.3 GB journal provider. (Multiply your RAM size " +"with 3.3 to obtain the size of the journal)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:122 +msgid "" +"For more information about journaling, please read the manual page of man:" +"gjournal[8]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:124 +#, no-wrap +msgid "Steps During the Installation of FreeBSD" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:126 +#, no-wrap +msgid "Reserving Space for Journaling" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:130 +msgid "" +"A typical desktop machine usually has one hard disk that stores both the OS " +"and user data. Arguably, the default partitioning scheme selected by " +"sysinstall is more or less suitable: A desktop machine does not need a large " +"[.filename]#/var# partition, while [.filename]#/usr# is allocated the bulk " +"of the disk space, since user data and a lot of packages are installed into " +"its subdirectories." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:134 +msgid "" +"The default partitioning (the one obtained by pressing kbd:[A] at the " +"FreeBSD partition editor, called Disklabel) does not leave any unallocated " +"space. Each partition that will be journaled, requires another partition " +"for the journal. Since the [.filename]#/usr# partition is the largest, it " +"makes sense to shrink this partition slightly, to obtain the space required " +"for journaling." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:137 +msgid "" +"In our example, an 80 GB disk is used. The following screenshot shows the " +"default partitions created by Disklabel during installation:" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:138 +#, no-wrap +msgid "disklabel1.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:142 +msgid "" +"If this is more or less what you need, it is very easy to adjust for " +"journaling. Simply use the arrow keys to move the highlight to the [." +"filename]#/usr# partition and press kbd:[D] to delete it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:146 +msgid "" +"Now, move the highlight to the disk name at the top of the screen and press " +"kbd:[C] to create a new partition for [.filename]#/usr#. This new partition " +"should be smaller by 1 GB (if you intend to journal [.filename]#/usr# only), " +"or 2 GB (if you intend to journal both [.filename]#/usr# and [.filename]#/" +"var#). From the pop-up that appears, opt to create a file system, and type " +"[.filename]#/usr# as the mount point." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:152 +msgid "" +"Should you journal the [.filename]#/var# partition? Normally, journaling " +"makes sense on quite large partitions. You may decide not to journal [." +"filename]#/var#, although doing so on a typical desktop will cause no harm. " +"If the file system is lightly used (quite probable for a desktop) you may " +"wish to allocate less disk space for its journal." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:155 +msgid "" +"In our example, we journal both [.filename]#/usr# and [.filename]#/var#. " +"You may of course adjust the procedure to your own needs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:161 +msgid "" +"To keep things as easy going as possible, we are going to use sysinstall to " +"create the partitions required for journaling. However, during " +"installation, sysinstall insists on asking a mount point for each partition " +"you create. At this point, you do not have any mount points for the " +"partitions that will hold the journals, and in reality you __do not even " +"need them__. These are not partitions that we are ever going to mount " +"somewhere." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:165 +msgid "" +"To avoid these problems with sysinstall, we are going to create the journal " +"partitions as swap space. Swap is never mounted, and sysinstall has no " +"problem creating as many swap partitions as needed. After the first reboot, " +"[.filename]#/etc/fstab# will have to be edited, and the extra swap space " +"entries removed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:171 +msgid "" +"To create the swap, again use the arrow keys to move the highlight to the " +"top of Disklabel screen, so that the disk name itself is highlighted. Then " +"press kbd:[N], enter the desired size (_1024M_), and select \"swap space\" " +"from the pop-up menu that appears. Repeat for every journal you wish to " +"create. In our example, we create two partitions to provide for the " +"journals of [.filename]#/usr# and [.filename]#/var#. The final result is " +"shown in the following screenshot:" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:172 +#, no-wrap +msgid "disklabel2.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:177 +msgid "" +"When you have completed creating the partitions, we suggest you write down " +"the partition names, and mount points, so you can easily refer to this " +"information during the configuration phase. This will help alleviate " +"mistakes that may damage your installation. The following table shows our " +"notes for the sample configuration:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:178 +#, no-wrap +msgid "Partitions and Journals" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:182 +#, no-wrap +msgid "Partition" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:183 +#, no-wrap +msgid "Mount Point" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:185 +#, no-wrap +msgid "Journal" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:186 +#, no-wrap +msgid "ad0s1d" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:187 +#, no-wrap +msgid "/var" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:189 +#, no-wrap +msgid "ad0s1h" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:190 +#, no-wrap +msgid "ad0s1f" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:191 +#, no-wrap +msgid "/usr" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:192 +#, no-wrap +msgid "ad0s1g" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:196 +msgid "" +"Continue the installation as you would normally do. We would however " +"suggest you postpone installation of third party software (packages) until " +"you have completely setup journaling." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:198 +#, no-wrap +msgid "Booting for the first time" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:203 +msgid "" +"Your system will come up normally, but you will need to edit [.filename]#/" +"etc/fstab# and remove the extra swap partitions you created for the " +"journals. Normally, the swap partition you will actually use is the one " +"with the \"b\" suffix (i.e. ad0s1b in our example). Remove all other swap " +"space entries and reboot so that FreeBSD will stop using them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:205 +msgid "" +"When the system comes up again, we will be ready to configure journaling." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:207 +#, no-wrap +msgid "Setting Up Journaling" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:210 +#, no-wrap +msgid "Executing `gjournal`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:214 +msgid "" +"Having prepared all the required partitions, it is quite easy to configure " +"journaling. We will need to switch to single user mode, so login as `root` " +"and type:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:218 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:436 +#, no-wrap +msgid "# shutdown now\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:222 +msgid "" +"Press kbd:[Enter] to get the default shell. We will need to unmount the " +"partitions that will be journaled, in our example [.filename]#/usr# and [." +"filename]#/var#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:226 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:443 +#, no-wrap +msgid "# umount /usr /var\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:229 +msgid "Load the module required for journaling:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:233 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:408 +#, no-wrap +msgid "# gjournal load\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:238 +msgid "" +"Now, use your notes to determine which partition will be used for each " +"journal. In our example, [.filename]#/usr# is [.filename]#ad0s1f# and its " +"journal will be [.filename]#ad0s1g#, while [.filename]#/var# is [." +"filename]#ad0s1d# and will be journaled to [.filename]#ad0s1h#. The " +"following commands are required:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:244 +#, no-wrap +msgid "" +"# gjournal label ad0s1f ad0s1g\n" +"GEOM_JOURNAL: Journal 2948326772: ad0s1f contains data.\n" +"GEOM_JOURNAL: Journal 2948326772: ad0s1g contains journal.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:248 +#, no-wrap +msgid "" +"# gjournal label ad0s1d ad0s1h\n" +"GEOM_JOURNAL: Journal 3193218002: ad0s1d contains data.\n" +"GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal.\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:254 +msgid "" +"If the last sector of either partition is used, `gjournal` will return an " +"error. You will have to run the command using the `-f` flag to force an " +"overwrite, i.e.:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:258 +#, no-wrap +msgid "# gjournal label -f ad0s1d ad0s1h\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:261 +msgid "" +"Since this is a new installation, it is highly unlikely that anything will " +"be actually overwritten." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:266 +msgid "" +"At this point, two new devices are created, namely [.filename]#ad0s1d." +"journal# and [.filename]#ad0s1f.journal#. These represent the [.filename]#/" +"var# and [.filename]#/usr# partitions we have to mount. Before mounting, we " +"must however set the journal flag on them and clear the Soft Updates flag:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:272 +#, no-wrap +msgid "" +"# tunefs -J enable -n disable ad0s1d.journal\n" +"tunefs: gjournal set\n" +"tunefs: soft updates cleared\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:276 +#, no-wrap +msgid "" +"# tunefs -J enable -n disable ad0s1f.journal\n" +"tunefs: gjournal set\n" +"tunefs: soft updates cleared\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:279 +msgid "" +"Now, mount the new devices manually at their respective places (note that we " +"can now use the `async` mount option):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:284 +#, no-wrap +msgid "" +"# mount -o async /dev/ad0s1d.journal /var\n" +"# mount -o async /dev/ad0s1f.journal /usr\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:287 +msgid "" +"Edit [.filename]#/etc/fstab# and update the entries for [.filename]#/usr# " +"and [.filename]#/var#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:292 +#, no-wrap +msgid "" +"/dev/ad0s1f.journal /usr ufs rw,async 2 2\n" +"/dev/ad0s1d.journal /var ufs rw,async 2 2\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:297 +msgid "" +"Make sure the above entries are correct, or you will have trouble starting " +"up normally after you reboot!" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:300 +msgid "" +"Finally, edit [.filename]#/boot/loader.conf# and add the following line so " +"the man:gjournal[8] module is loaded at every boot:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:304 +#, no-wrap +msgid "geom_journal_load=\"YES\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:309 +msgid "" +"Congratulations! Your system is now set for journaling. You can either type " +"`exit` to return to multi-user mode, or reboot to test your configuration " +"(recommended). During the boot you will see messages like the following:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:319 +#, no-wrap +msgid "" +"ad0: 76293MB XEC XE800JD-00HBC0 08.02D08 at ata0-master SATA150\n" +"GEOM_JOURNAL: Journal 2948326772: ad0s1g contains journal.\n" +"GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal.\n" +"GEOM_JOURNAL: Journal 3193218002: ad0s1d contains data.\n" +"GEOM_JOURNAL: Journal ad0s1d clean.\n" +"GEOM_JOURNAL: Journal 2948326772: ad0s1f contains data.\n" +"GEOM_JOURNAL: Journal ad0s1f clean.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:322 +msgid "After an unclean shutdown, the messages will vary slightly, i.e.:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:326 +#, no-wrap +msgid "GEOM_JOURNAL: Journal ad0s1d consistent.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:329 +msgid "" +"This usually means that man:gjournal[8] used the information in the journal " +"provider to return the file system to a consistent state." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:331 +#, no-wrap +msgid "Journaling Newly Created Partitions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:336 +msgid "" +"While the above procedure is necessary for journaling partitions that " +"already contain data, journaling an empty partition is somewhat easier, " +"since both the data and the journal provider can be stored in the same " +"partition. For example, assume a new disk was installed, and a new " +"partition [.filename]#/dev/ad1s1d# was created. Creating the journal would " +"be as simple as:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:340 +#, no-wrap +msgid "# gjournal label ad1s1d\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:346 +msgid "" +"The journal size will be 1 GB by default. You may adjust it by using the `-" +"s` option. The value can be given in bytes, or appended by `K`, `M` or `G` " +"to denote Kilobytes, Megabytes or Gigabytes respectively. Note that " +"`gjournal` will not allow you to create unsuitably small journal sizes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:348 +msgid "" +"For example, to create a 2 GB journal, you could use the following command:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:352 +#, no-wrap +msgid "# gjournal label -s 2G ad1s1d\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:355 +msgid "" +"You can then create a file system on your new partition, and enable " +"journaling using the `-J` option:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:359 +#, no-wrap +msgid "# newfs -J /dev/ad1s1d.journal\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:362 +#, no-wrap +msgid "Building Journaling into Your Custom Kernel" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:366 +msgid "" +"If you do not wish to load `geom_journal` as a module, you can build its " +"functions right into your kernel. Edit your custom kernel configuration " +"file, and make sure it includes these two lines:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:370 +#, no-wrap +msgid "options UFS_GJOURNAL # Note: This is already in GENERIC\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:372 +#, no-wrap +msgid "options GEOM_JOURNAL # You will have to add this one\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:375 +msgid "" +"Rebuild and reinstall your kernel following the relevant extref:{handbook}" +"[instructions in the FreeBSD Handbook., kernelconfig]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:377 +msgid "" +"Do not forget to remove the relevant \"load\" entry from [.filename]#/boot/" +"loader.conf# if you have previously used it." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:379 +#, no-wrap +msgid "Troubleshooting Journaling" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:382 +msgid "" +"The following section covers frequently asked questions regarding problems " +"related to journaling." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:383 +#, no-wrap +msgid "I am getting kernel panics during periods of high disk activity. How is this related to journaling?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:389 +msgid "" +"The journal probably fills up before it has a chance to get committed " +"(flushed) to disk. Keep in mind the size of the journal depends on the " +"usage load, and not the size of the data provider. If your disk activity is " +"high, you need a larger partition for the journal. See the note in the " +"crossref:gjournal-desktop[understanding-journaling, Understanding Journaling " +"in FreeBSD] section." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:390 +#, no-wrap +msgid "I made some mistake during configuration, and I cannot boot normally now. Can this be fixed some way?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:396 +msgid "" +"You either forgot (or misspelled) the entry in [.filename]#/boot/loader." +"conf#, or there are errors in your [.filename]#/etc/fstab# file. These are " +"usually easy to fix. Press kbd:[Enter] to get to the default single user " +"shell. Then locate the root of the problem:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:400 +#, no-wrap +msgid "# cat /boot/loader.conf\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:404 +msgid "" +"If the `geom_journal_load` entry is missing or misspelled, the journaled " +"devices are never created. Load the module manually, mount all partitions, " +"and continue with multi-user boot:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:415 +#, no-wrap +msgid "" +"GEOM_JOURNAL: Journal 2948326772: ad0s1g contains journal.\n" +"GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal.\n" +"GEOM_JOURNAL: Journal 3193218002: ad0s1d contains data.\n" +"GEOM_JOURNAL: Journal ad0s1d clean.\n" +"GEOM_JOURNAL: Journal 2948326772: ad0s1f contains data.\n" +"GEOM_JOURNAL: Journal ad0s1f clean.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:419 +#, no-wrap +msgid "" +"# mount -a\n" +"# exit\n" +"(boot continues)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:424 +msgid "" +"If, on the other hand, this entry is correct, have a look at [.filename]#/" +"etc/fstab#. You will probably find a misspelled or missing entry. In this " +"case, mount all remaining partitions by hand and continue with the multi-" +"user boot." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:425 +#, no-wrap +msgid "Can I remove journaling and return to my standard file system with Soft Updates?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:430 +msgid "" +"Sure. Use the following procedure, which reverses the changes. The " +"partitions you created for the journal providers can then be used for other " +"purposes, if you so wish." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:432 +msgid "Login as `root` and switch to single user mode:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:439 +msgid "Unmount the journaled partitions:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:446 +msgid "Synchronize the journals:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:450 +#, no-wrap +msgid "# gjournal sync\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:453 +msgid "Stop the journaling providers:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:458 +#, no-wrap +msgid "" +"# gjournal stop ad0s1d.journal\n" +"# gjournal stop ad0s1f.journal\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:461 +msgid "Clear journaling metadata from all the devices used:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:468 +#, no-wrap +msgid "" +"# gjournal clear ad0s1d\n" +"# gjournal clear ad0s1f\n" +"# gjournal clear ad0s1g\n" +"# gjournal clear ad0s1h\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:471 +msgid "" +"Clear the file system journaling flag, and restore the Soft Updates flag:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:477 +#, no-wrap +msgid "" +"# tunefs -J disable -n enable ad0s1d\n" +"tunefs: gjournal cleared\n" +"tunefs: soft updates set\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:481 +#, no-wrap +msgid "" +"# tunefs -J disable -n enable ad0s1f\n" +"tunefs: gjournal cleared\n" +"tunefs: soft updates set\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:484 +msgid "Remount the old devices by hand:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:489 +#, no-wrap +msgid "" +"# mount -o rw /dev/ad0s1d /var\n" +"# mount -o rw /dev/ad0s1f /usr\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:492 +msgid "Edit [.filename]#/etc/fstab# and restore it to its original state:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:497 +#, no-wrap +msgid "" +"/dev/ad0s1f /usr ufs rw 2 2\n" +"/dev/ad0s1d /var ufs rw 2 2\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:500 +msgid "" +"Finally, edit [.filename]#/boot/loader.conf#, remove the entry that loads " +"the `geom_journal` module and reboot." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:502 +#, no-wrap +msgid "Further Reading" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:506 +msgid "" +"Journaling is a fairly new feature of FreeBSD, and as such, it is not very " +"well documented yet. You may however find the following additional " +"references useful:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:508 +msgid "" +"A extref:{handbook}[new section on journaling, geom-gjournal] is now part of " +"the FreeBSD Handbook." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:509 +msgid "" +"https://lists.freebsd.org/pipermail/freebsd-current/2006-June/064043." +"html[This post] in {freebsd-current} by man:gjournal[8]'s developer, `{pjd}`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:510 +msgid "" +"https://lists.freebsd.org/pipermail/freebsd-questions/2008-April/173501." +"html[This post] in {freebsd-questions} by `{ivoras}`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/gjournal-desktop/_index.adoc:510 +msgid "The manual pages of man:gjournal[8] and man:geom[8]." +msgstr "" diff --git a/documentation/content/en/articles/hubs/_index.adoc b/documentation/content/en/articles/hubs/_index.adoc index 1e2c9da25a..8445423a5d 100644 --- a/documentation/content/en/articles/hubs/_index.adoc +++ b/documentation/content/en/articles/hubs/_index.adoc @@ -56,7 +56,7 @@ toc::[] [NOTE] ==== -We are not accepting new mirrors at this time. +We are not accepting new community mirrors at this time. ==== [[mirror-contact]] @@ -191,7 +191,7 @@ All of course for various FreeBSD versions, and various architectures. The best way to mirror the FTP area is rsync. You can install the port package:net/rsync[] and then use rsync to sync with your upstream host. -rsync is already mentioned in <<mirror-serv-rsync>>. +rsync is already mentioned in crossref:hubs[mirror-serv-rsync, Rsync (optional for FTP Fileset)]. Since rsync access is not required, your preferred upstream site may not allow it. You may need to hunt around a little bit to find a site that allows rsync access. @@ -214,19 +214,38 @@ If you sync the whole module (unlike subdirectories), be aware that the module-d [[mirror-www]] === Mirroring the WWW Pages -The FreeBSD website should only be mirrored via rsync. +[WARNING] +==== +Since doc migration to Hugo/Asciidoctor on 2021-01-25, mirroring the website with rsync no longer works. +==== + +There are ongoing studies to implement a website mirror with the extref:{handbook}mirrors/[official infrastructure]. + +For the former website mirrors, a way to achieve mirroring the website today is building the website locally with the corresponding address it will be hosted. + +[source,shell] +.... +% cd website && env HUGO_baseURL="https://www.XX.freebsd.org/" make +.... -A command line to mirror the FreeBSD web site might look like: +Check for more details about the build tools on extref:{fdp-primer}overview/[FreeBSD Documentation Project Primer for New Contributors, overview-quick-start] book. +//// [source,shell] .... % rsync -vaHz --delete rsync://bit0.us-west.freebsd.org/FreeBSD-www-data/ /usr/local/www/ .... +//// + +[NOTE] +==== +Notice the website was split into www.FreeBSD.org and docs.FreeBSD.org, and there are links between them; plus, at this moment, `HUGO_baseURL` variable won't cover all links, this way, mirroring the website is discouraged. +==== [[mirror-pkgs]] === Mirroring Packages -Due to very high requirements of bandwidth, storage and adminstration the FreeBSD Project has decided not to allow public mirrors of packages. +Due to very high requirements of bandwidth, storage and administration the FreeBSD Project has decided not to allow public mirrors of packages. For sites with lots of machines, it might be advantagous to run a caching HTTP proxy for the man:pkg[8] process. Alternatively specific packages and their dependencies can be fetched by running something like the following: @@ -289,7 +308,9 @@ Lots of online documentation leads "interactive"users to `ftp.FreeBSD.org` so au Additionally there exists a hierarchy of mirrors, which is described in terms of __tiers__. The master sites are not referred to but can be described as __Tier-0__. Mirrors that mirror from these sites can be considered __Tier-1__, mirrors of __Tier-1__-mirrors, are __Tier-2__, etc. -Official sites are encouraged to be of a low __tier__, but the lower the tier the higher the requirements in terms as described in <<mirror-requirements>>. +Official sites are encouraged to be of a low __tier__, but the lower the tier +the higher the requirements in terms as described in +crossref:hubs[mirror-requirements, Requirements for FreeBSD Mirrors]. Also access to low-tier-mirrors may be restricted, and access to master sites is definitely restricted. The __tier__-hierarchy is not reflected by DNS and generally not documented anywhere except for the master sites. However, official mirrors with low numbers like 1-4, are usually _Tier-1_ (this is just a rough hint, and there is no rule). @@ -303,7 +324,8 @@ The short answer is: from the site that is closest to you in Internet terms, or [[mirror-where-simple]] ==== I Just Want to Mirror from Somewhere! -If you have no special intentions or requirements, the statement in <<mirror-where-where>> applies. +If you have no special intentions or requirements, the statement in +crossref:hubs[mirror-where-where, Ok, but Where Should I get the Stuff Now?] applies. This means: [.procedure] @@ -314,11 +336,12 @@ This means: ==== [[mirror-where-official]] -==== I am an Official Mirror, What is the Right Rite for Me? +==== I am an Official Mirror, What is the Right Site for Me? -In general the description in <<mirror-where-simple>> still applies. +In general the description in crossref:hubs[mirror-where-simple, I Just Want to Mirror from Somewhere!] still applies. Of course you may want to put some weight on the fact that your upstream should be of a low tier. -There are some other considerations about _official_ mirrors that are described in <<mirror-official>>. +There are some other considerations about _official_ mirrors that are described +in crossref:hubs[mirror-official, Official Mirrors]. [[mirror-where-master]] ==== I Want to Access the Master Sites! @@ -340,7 +363,7 @@ There is one master site for the FTP fileset. This is the master site for the FTP fileset. `ftp-master.FreeBSD.org` provides rsync access, in addition to FTP. -Refer to <<mirror-ftp-rsync>>. +Refer to crossref:hubs[mirror-ftp-rsync, Mirroring the FTP Site]. Mirrors are also encouraged to allow rsync access for the FTP contents, since they are __Tier-1__-mirrors. @@ -369,7 +392,7 @@ Tier-1 mirrors are required to: * provide FTP and rsync access Furthermore, admins should be subscribed to the {freebsd-hubs}. -See extref:{handbook}[this link, eresources-mail] for details, how to subscribe. +See extref:{handbook}eresources[this link, eresources-mail] for details, how to subscribe. [IMPORTANT] ==== @@ -383,7 +406,7 @@ If Mirror1 does not update for a while, lower tier mirrors will begin to mirror [[mirror-official-become]] === How to Become Official Then? -We are not accepting any new mirrors at this time. +Please contact the Cluster Administrators as documented at https://www.FreeBSD.org/administration/#t-clusteradm. [[mirror-statpages]] == Some Statistics from Mirror Sites diff --git a/documentation/content/en/articles/hubs/_index.po b/documentation/content/en/articles/hubs/_index.po new file mode 100644 index 0000000000..0d084bc187 --- /dev/null +++ b/documentation/content/en/articles/hubs/_index.po @@ -0,0 +1,921 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-12-29 08:30-0500\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/hubs/_index.adoc:1 +#, no-wrap +msgid "The all in one guide for mirroring the FreeBSD website, FTP servers, and more" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/hubs/_index.adoc:1 +#: documentation/content/en/articles/hubs/_index.adoc:17 +#, no-wrap +msgid "Mirroring FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:50 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:52 +msgid "" +"An in-progress article on how to mirror FreeBSD, aimed at hub administrators." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:54 +msgid "'''" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:60 +msgid "We are not accepting new community mirrors at this time." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/hubs/_index.adoc:63 +#, no-wrap +msgid "Contact Information" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:67 +msgid "" +"The Mirror System Coordinators can be reached through email at mailto:mirror-" +"admin@FreeBSD.org[mirror-admin@FreeBSD.org]. There is also a {freebsd-hubs}." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/hubs/_index.adoc:69 +#, no-wrap +msgid "Requirements for FreeBSD Mirrors" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:72 +#, no-wrap +msgid "Disk Space" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:82 +msgid "" +"Disk space is one of the most important requirements. Depending on the set " +"of releases, architectures, and degree of completeness you want to mirror, a " +"huge amount of disk space may be consumed. Also keep in mind that " +"_official_ mirrors are probably required to be complete. The web pages " +"should always be mirrored completely. Also note that the numbers stated " +"here are reflecting the current state (at {rel120-current}-RELEASE/{rel113-" +"current}-RELEASE). Further development and releases will only increase the " +"required amount. Also make sure to keep some (ca. 10-20%) extra space " +"around just to be sure. Here are some approximate figures:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:84 +msgid "Full FTP Distribution: 1.4 TB" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:85 +msgid "CTM deltas: 10 GB" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:86 +msgid "Web pages: 1GB" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:88 +msgid "" +"The current disk usage of FTP Distribution can be found at link:ftp://ftp." +"FreeBSD.org/pub/FreeBSD/dir.sizes[ftp://ftp.FreeBSD.org/pub/FreeBSD/dir." +"sizes]." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:90 +#, no-wrap +msgid "Network Connection/Bandwidth" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:97 +msgid "" +"Of course, you need to be connected to the Internet. The required bandwidth " +"depends on your intended use of the mirror. If you just want to mirror some " +"parts of FreeBSD for local use at your site/intranet, the demand may be much " +"smaller than if you want to make the files publicly available. If you " +"intend to become an official mirror, the bandwidth required will be even " +"higher. We can only give rough estimates here:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:99 +msgid "" +"Local site, no public access: basically no minimum, but < 2 Mbps could make " +"syncing too slow." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:100 +msgid "Unofficial public site: 34 Mbps is probably a good start." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:101 +msgid "" +"Official site: > 100 Mbps is recommended, and your host should be connected " +"as close as possible to your border router." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:103 +#, no-wrap +msgid "System Requirements, CPU, RAM" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:111 +msgid "" +"One thing this depends on the expected number of clients, which is " +"determined by the server's policy. It is also affected by the types of " +"services you want to offer. Plain FTP or HTTP services may not require a " +"huge amount of resources. Watch out if you provide rsync. This can have a " +"huge impact on CPU and memory requirements as it is considered a memory " +"hog. The following are just examples to give you a very rough hint." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:114 +msgid "" +"For a moderately visited site that offers rsync, you might consider a " +"current CPU with around 800MHz - 1 GHz, and at least 512MB RAM. This is " +"probably the minimum you want for an _official_ site." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:116 +msgid "" +"For a frequently used site you definitely need more RAM (consider 2GB as a " +"good start) and possibly more CPU, which could also mean that you need to go " +"for a SMP system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:120 +msgid "" +"You also want to consider a fast disk subsystem. Operations on the SVN " +"repository require a fast disk subsystem (RAID is highly advised). A SCSI " +"controller that has a cache of its own can also speed up things since most " +"of these services incur a large number of small modifications to the disk." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:122 +#, no-wrap +msgid "Services to Offer" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:127 +msgid "" +"Every mirror site is required to have a set of core services available. In " +"addition to these required services, there are a number of optional services " +"that server administrators may choose to offer. This section explains which " +"services you can provide and how to go about implementing them." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/hubs/_index.adoc:129 +#, no-wrap +msgid "FTP (required for FTP Fileset)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:135 +msgid "" +"This is one of the most basic services, and it is required for each mirror " +"offering public FTP distributions. FTP access must be anonymous, and no " +"upload/download ratios are allowed (a ridiculous thing anyway). Upload " +"capability is not required (and _must_ never be allowed for the FreeBSD file " +"space). Also the FreeBSD archive should be available under the path [." +"filename]#/pub/FreeBSD#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:137 +msgid "" +"There is a lot of software available which can be set up to allow anonymous " +"FTP (in alphabetical order)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:139 +msgid "" +"`/usr/libexec/ftpd`: FreeBSD's own ftpd can be used. Be sure to read man:" +"ftpd[8]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:140 +msgid "package:ftp/ncftpd[]: A commercial package, free for educational use." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:141 +msgid "package:ftp/oftpd[]: An ftpd designed with security as a main focus." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:142 +msgid "package:ftp/proftpd[]: A modular and very flexible ftpd." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:143 +msgid "package:ftp/pure-ftpd[]: Another ftpd developed with security in mind." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:144 +msgid "package:ftp/twoftpd[]: As above." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:145 +msgid "package:ftp/vsftpd[]: The \"very secure\" ftpd." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:149 +msgid "" +"FreeBSD's `ftpd`, `proftpd` and maybe `ncftpd` are among the most commonly " +"used FTPds. The others do not have a large userbase among mirror sites. " +"One thing to consider is that you may need flexibility in limiting how many " +"simultaneous connections are allowed, thus limiting how much network " +"bandwidth and system resources are consumed." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/hubs/_index.adoc:151 +#, no-wrap +msgid "Rsync (optional for FTP Fileset)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:161 +msgid "" +"Rsync is often offered for access to the contents of the FTP area of " +"FreeBSD, so other mirror sites can use your system as their source. The " +"protocol is different from FTP in many ways. It is much more bandwidth " +"friendly, as only differences between files are transferred instead of whole " +"files when they change. Rsync does require a significant amount of memory " +"for each instance. The size depends on the size of the synced module in " +"terms of the number of directories and files. Rsync can use `rsh` and `ssh` " +"(now default) as a transport, or use its own protocol for stand-alone access " +"(this is the preferred method for public rsync servers). Authentication, " +"connection limits, and other restrictions may be applied. There is just one " +"software package available:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:163 +msgid "package:net/rsync[]" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/hubs/_index.adoc:165 +#, no-wrap +msgid "HTTP (required for Web Pages, Optional for FTP Fileset)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:171 +msgid "" +"If you want to offer the FreeBSD web pages, you will need to install a web " +"server. You may optionally offer the FTP fileset via HTTP. The choice of " +"web server software is left up to the mirror administrator. Some of the " +"most popular choices are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:173 +msgid "" +"package:www/apache24[]: Apache is still one of the most widely deployed web " +"servers on the Internet. It is used extensively by the FreeBSD Project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:174 +msgid "" +"package:www/boa[]: Boa is a single-tasking HTTP server. Unlike traditional " +"web servers, it does not fork for each incoming connection, nor does it fork " +"many copies of itself to handle multiple connections. Although, it should " +"provide considerably great performance for purely static content." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:175 +msgid "" +"package:www/cherokee[]: Cherokee is a very fast, flexible and easy to " +"configure web server. It supports the widespread technologies nowadays: " +"FastCGI, SCGI, PHP, CGI, SSL/TLS encrypted connections, vhosts, users " +"authentication, on the fly encoding and load balancing. It also generates " +"Apache compatible log files." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:176 +msgid "" +"package:www/lighttpd[]: lighttpd is a secure, fast, compliant and very " +"flexible web server which has been optimized for high-performance " +"environments. It has a very low memory footprint compared to other web " +"servers and takes care of cpu-load." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:177 +msgid "" +"package:www/nginx[]: nginx is a high performance edge web server with a low " +"memory footprint and key features to build a modern and efficient web " +"infrastructure. Features include a HTTP server, HTTP and mail reverse proxy, " +"caching, load balancing, compression, request throttling, connection " +"multiplexing and reuse, SSL offload and HTTP media streaming." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:178 +msgid "" +"package:www/thttpd[]: If you are going to be serving a large amount of " +"static content you may find that using an application such as thttpd is more " +"efficient than others. It is also optimized for excellent performance on " +"FreeBSD." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/hubs/_index.adoc:180 +#, no-wrap +msgid "How to Mirror FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:184 +msgid "" +"Ok, now you know the requirements and how to offer the services, but not how " +"to get it. :-) This section explains how to actually mirror the various " +"parts of FreeBSD, what tools to use, and where to mirror from." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:186 +#, no-wrap +msgid "Mirroring the FTP Site" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:191 +msgid "" +"The FTP area is the largest amount of data that needs to be mirrored. It " +"includes the _distribution sets_ required for network installation, the " +"_branches_ which are actually snapshots of checked-out source trees, the " +"_ISO Images_ to write CD-ROMs with the installation distribution, a live " +"file system, and a snapshot of the ports tree. All of course for various " +"FreeBSD versions, and various architectures." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:197 +msgid "" +"The best way to mirror the FTP area is rsync. You can install the port " +"package:net/rsync[] and then use rsync to sync with your upstream host. " +"rsync is already mentioned in crossref:hubs[mirror-serv-rsync, Rsync " +"(optional for FTP Fileset)]. Since rsync access is not required, your " +"preferred upstream site may not allow it. You may need to hunt around a " +"little bit to find a site that allows rsync access." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:202 +msgid "" +"Since the number of rsync clients will have a significant impact on the " +"server machine, most admins impose limitations on their server. For a " +"mirror, you should ask the site maintainer you are syncing from about their " +"policy, and maybe an exception for your host (since you are a mirror)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:205 +msgid "A command line to mirror FreeBSD might look like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/hubs/_index.adoc:209 +#, no-wrap +msgid "% rsync -vaHz --delete rsync://ftp4.de.FreeBSD.org/FreeBSD/ /pub/FreeBSD/\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:213 +msgid "" +"Consult the documentation for rsync, which is also available at http://rsync." +"samba.org/[http://rsync.samba.org/], about the various options to be used " +"with rsync. If you sync the whole module (unlike subdirectories), be aware " +"that the module-directory (here \"FreeBSD\") will not be created, so you " +"cannot omit the target directory. Also you might want to set up a script " +"framework that calls such a command via man:cron[8]." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:215 +#, no-wrap +msgid "Mirroring the WWW Pages" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:220 +msgid "" +"Since doc migration to Hugo/Asciidoctor on 2021-01-25, mirroring the website " +"with rsync no longer works." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:223 +msgid "" +"There are ongoing studies to implement a website mirror with the extref:" +"{handbook}mirrors/[official infrastructure]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:225 +msgid "" +"For the former website mirrors, a way to achieve mirroring the website today " +"is building the website locally with the corresponding address it will be " +"hosted." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/hubs/_index.adoc:229 +#, no-wrap +msgid "% cd website && env HUGO_baseURL=\"https://www.XX.freebsd.org/\" make\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:232 +msgid "" +"Check for more details about the build tools on extref:{fdp-primer}overview/" +"[FreeBSD Documentation Project Primer for New Contributors, overview-quick-" +"start] book." +msgstr "" + +#. [source,shell] +#. .... +#. % rsync -vaHz --delete rsync://bit0.us-west.freebsd.org/FreeBSD-www-data/ /usr/local/www/ +#. .... +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:243 +msgid "" +"Notice the website was split into www.FreeBSD.org and docs.FreeBSD.org, and " +"there are links between them; plus, at this moment, `HUGO_baseURL` variable " +"won't cover all links, this way, mirroring the website is discouraged." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:246 +#, no-wrap +msgid "Mirroring Packages" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:251 +msgid "" +"Due to very high requirements of bandwidth, storage and administration the " +"FreeBSD Project has decided not to allow public mirrors of packages. For " +"sites with lots of machines, it might be advantagous to run a caching HTTP " +"proxy for the man:pkg[8] process. Alternatively specific packages and their " +"dependencies can be fetched by running something like the following:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/hubs/_index.adoc:255 +#, no-wrap +msgid "% pkg fetch -d -o /usr/local/mirror vim\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:258 +msgid "" +"Once those packages have been fetched, the repository metadata must be " +"generated by running:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/hubs/_index.adoc:262 +#, no-wrap +msgid "% pkg repo /usr/local/mirror\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:266 +msgid "" +"Once the packages have been fetched and the metadata for the repository has " +"been generated, serve the packages up to the client machines via HTTP. For " +"additional information see the man pages for man:pkg[8], specifically the " +"man:pkg-repo[8] page." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:268 +#, no-wrap +msgid "How Often Should I Mirror?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:274 +msgid "" +"Every mirror should be updated at a minimum of once per day. Certainly a " +"script with locking to prevent multiple runs happening at the same time will " +"be needed to run from man:cron[8]. Since nearly every admin does this in " +"their own way, specific instructions cannot be provided. It could work " +"something like this:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:278 +msgid "" +"Put the command to run your mirroring application in a script. Use of a " +"plain `/bin/sh` script is recommended." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:279 +msgid "" +"Add some output redirections so diagnostic messages are logged to a file." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:280 +msgid "Test if your script works. Check the logs." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:281 +msgid "" +"Use man:crontab[1] to add the script to the appropriate user's man:" +"crontab[5]. This should be a different user than what your FTP daemon runs " +"as so that if file permissions inside your FTP area are not world-readable " +"those files cannot be accessed by anonymous FTP. This is used to \"stage\" " +"releases - making sure all of the official mirror sites have all of the " +"necessary release files on release day." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:284 +msgid "Here are some recommended schedules:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:286 +msgid "FTP fileset: daily" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:287 +msgid "WWW pages: daily" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/hubs/_index.adoc:289 +#, no-wrap +msgid "Where to Mirror From" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:294 +msgid "" +"This is an important issue. So this section will spend some effort to " +"explain the backgrounds. We will say this several times: under no " +"circumstances should you mirror from `ftp.FreeBSD.org`." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:296 +#, no-wrap +msgid "A few Words About the Organization" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:307 +msgid "" +"Mirrors are organized by country. All official mirrors have a DNS entry of " +"the form `ftpN.CC.FreeBSD.org`. _CC_ (i.e., country code) is the _top level " +"domain_ (TLD) of the country where this mirror is located. _N_ is a number, " +"telling that the host would be the _Nth_ mirror in that country. (Same " +"applies to `wwwN.CC.FreeBSD.org`, etc.) There are mirrors with no _CC_ " +"part. These are the mirror sites that are very well connected and allow a " +"large number of concurrent users. `ftp.FreeBSD.org` is actually two " +"machines, one currently located in Denmark and the other in the United " +"States. It is _NOT_ a master site and should never be used to mirror from. " +"Lots of online documentation leads \"interactive\"users to `ftp.FreeBSD.org` " +"so automated mirroring systems should find a different machine to mirror " +"from." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:317 +msgid "" +"Additionally there exists a hierarchy of mirrors, which is described in " +"terms of __tiers__. The master sites are not referred to but can be " +"described as __Tier-0__. Mirrors that mirror from these sites can be " +"considered __Tier-1__, mirrors of __Tier-1__-mirrors, are __Tier-2__, etc. " +"Official sites are encouraged to be of a low __tier__, but the lower the " +"tier the higher the requirements in terms as described in crossref:" +"hubs[mirror-requirements, Requirements for FreeBSD Mirrors]. Also access to " +"low-tier-mirrors may be restricted, and access to master sites is definitely " +"restricted. The __tier__-hierarchy is not reflected by DNS and generally " +"not documented anywhere except for the master sites. However, official " +"mirrors with low numbers like 1-4, are usually _Tier-1_ (this is just a " +"rough hint, and there is no rule)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:319 +#, no-wrap +msgid "Ok, but Where Should I get the Stuff Now?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:323 +msgid "" +"Under no circumstances should you mirror from `ftp.FreeBSD.org`. The short " +"answer is: from the site that is closest to you in Internet terms, or gives " +"you the fastest access." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/hubs/_index.adoc:325 +#, no-wrap +msgid "I Just Want to Mirror from Somewhere!" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:330 +msgid "" +"If you have no special intentions or requirements, the statement in crossref:" +"hubs[mirror-where-where, Ok, but Where Should I get the Stuff Now?] " +"applies. This means:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:334 +msgid "" +"Check for those which provide fastest access (number of hops, round-trip-" +"times) and offer the services you intend to use (like rsync)." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:335 +msgid "" +"Contact the administrators of your chosen site stating your request, and " +"asking about their terms and policies." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:336 +msgid "Set up your mirror as described above." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/hubs/_index.adoc:339 +#, no-wrap +msgid "I am an Official Mirror, What is the Right Site for Me?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:345 +msgid "" +"In general the description in crossref:hubs[mirror-where-simple, I Just Want " +"to Mirror from Somewhere!] still applies. Of course you may want to put " +"some weight on the fact that your upstream should be of a low tier. There " +"are some other considerations about _official_ mirrors that are described in " +"crossref:hubs[mirror-official, Official Mirrors]." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/hubs/_index.adoc:347 +#, no-wrap +msgid "I Want to Access the Master Sites!" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:354 +msgid "" +"If you have good reasons and good prerequisites, you may want and get access " +"to one of the master sites. Access to these sites is generally restricted, " +"and there are special policies for access. If you are already an _official_ " +"mirror, this certainly helps you getting access. In any other case make " +"sure your country really needs another mirror. If it already has three or " +"more, ask the \"zone administrator\" (mailto:hostmaster@CC.FreeBSD." +"org[hostmaster@CC.FreeBSD.org]) or {freebsd-hubs} first." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:357 +msgid "" +"Whoever helped you become, an _official_ should have helped you gain access " +"to an appropriate upstream host, either one of the master sites or a " +"suitable Tier-1 site. If not, you can send email to mailto:mirror-" +"admin@FreeBSD.org[mirror-admin@FreeBSD.org] to request help with that." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:359 +msgid "There is one master site for the FTP fileset." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/hubs/_index.adoc:361 +#, no-wrap +msgid "ftp-master.FreeBSD.org" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:364 +msgid "This is the master site for the FTP fileset." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:367 +msgid "" +"`ftp-master.FreeBSD.org` provides rsync access, in addition to FTP. Refer " +"to crossref:hubs[mirror-ftp-rsync, Mirroring the FTP Site]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:369 +msgid "" +"Mirrors are also encouraged to allow rsync access for the FTP contents, " +"since they are __Tier-1__-mirrors." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/hubs/_index.adoc:371 +#, no-wrap +msgid "Official Mirrors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:374 +msgid "Official mirrors are mirrors that" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:376 +msgid "a) have a `FreeBSD.org` DNS entry (usually a CNAME)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:377 +msgid "" +"b) are listed as an official mirror in the FreeBSD documentation (like " +"handbook)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:380 +msgid "" +"So far to distinguish official mirrors. Official mirrors are not necessarily " +"__Tier-1__-mirrors. However you probably will not find a __Tier-1__-mirror, " +"that is not also official." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:382 +#, no-wrap +msgid "Special Requirements for Official (tier-1) Mirrors" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:387 +msgid "" +"It is not so easy to state requirements for all official mirrors, since the " +"project is sort of tolerant here. It is more easy to say, what _official " +"tier-1 mirrors_ are required to. All other official mirrors can consider " +"this a big __should__." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:389 +msgid "Tier-1 mirrors are required to:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:391 +msgid "carry the complete fileset" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:392 +msgid "allow access to other mirror sites" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:393 +msgid "provide FTP and rsync access" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:396 +msgid "" +"Furthermore, admins should be subscribed to the {freebsd-hubs}. See extref:" +"{handbook}[this link, eresources-mail] for details, how to subscribe." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:401 +msgid "" +"It is _very_ important for a hub administrator, especially Tier-1 hub " +"admins, to check the https://www.FreeBSD.org/releng/[release schedule] for " +"the next FreeBSD release. This is important because it will tell you when " +"the next release is scheduled to come out, and thus giving you time to " +"prepare for the big spike of traffic which follows it." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/hubs/_index.adoc:404 +msgid "" +"It is also important that hub administrators try to keep their mirrors as up-" +"to-date as possible (again, even more crucial for Tier-1 mirrors). If " +"Mirror1 does not update for a while, lower tier mirrors will begin to mirror " +"old data from Mirror1 and thus begins a downward spiral... Keep your mirrors " +"up to date!" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:407 +#, no-wrap +msgid "How to Become Official Then?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:410 +msgid "" +"Please contact the Cluster Administrators as documented at https://www." +"FreeBSD.org/administration/#t-clusteradm." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/hubs/_index.adoc:412 +#, no-wrap +msgid "Some Statistics from Mirror Sites" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:415 +msgid "" +"Here are links to the stat pages of your favorite mirrors (aka the only ones " +"who feel like providing stats)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/hubs/_index.adoc:417 +#, no-wrap +msgid "FTP Site Statistics" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:420 +msgid "" +"ftp.is.FreeBSD.org - mailto:hostmaster@is.FreeBSD.org[hostmaster@is.FreeBSD." +"org] - http://www.rhnet.is/status/draupnir/draupnir.html[ (Bandwidth)] " +"http://www.rhnet.is/status/ftp/ftp-notendur.html[(FTP processes)] http://www." +"rhnet.is/status/ftp/http-notendur.html[(HTTP processes)]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/hubs/_index.adoc:420 +msgid "" +"ftp2.ru.FreeBSD.org - mailto:mirror@macomnet.ru[mirror@macomnet.ru] - http://" +"mirror.macomnet.net/mrtg/mirror.macomnet.net_195.128.64.25.html[(Bandwidth)] " +"http://mirror.macomnet.net/mrtg/mirror.macomnet.net_proc.html[(HTTP and FTP " +"users)]" +msgstr "" diff --git a/documentation/content/en/articles/ipsec-must/_index.adoc b/documentation/content/en/articles/ipsec-must/_index.adoc index 361f70406f..262ffef368 100644 --- a/documentation/content/en/articles/ipsec-must/_index.adoc +++ b/documentation/content/en/articles/ipsec-must/_index.adoc @@ -52,8 +52,8 @@ toc::[] [[problem]] == The Problem -First, lets assume you have <<ipsec-install>>. -How do you know it is <<caveat>>? Sure, your connection will not work if it is misconfigured, and it will work when you finally get it right. +First, lets assume you have crossref::ipsec-must[ipsec-install, Installing IPsec]. +How do you know it is crossref::ipsec-must[caveat, Caveat]? Sure, your connection will not work if it is misconfigured, and it will work when you finally get it right. man:netstat[1] will list it. But can you independently confirm it? [[solution]] @@ -73,13 +73,14 @@ This would be true even if some of the data in "encrypted mode" was not encrypte Ueli Maurer's "Universal Statistical Test for Random Bit Generators"(https://web.archive.org/web/20011115002319/http://www.geocities.com/SiliconValley/Code/4704/universal.pdf[MUST]) quickly measures the entropy of a sample. It uses a compression-like algorithm. -<<code>> for a variant which measures successive (~quarter megabyte) chunks of a file. +crossref::ipsec-must[code, Maurer's Universal Statistical Test (for block size8 bits)] for a variant which measures successive (~quarter megabyte) chunks of a file. [[tcpdump]] === Tcpdump We also need a way to capture the raw network data. -A program called man:tcpdump[1] lets you do this, if you have enabled the _Berkeley Packet Filter_ interface in your <<kernel>>. +A program called man:tcpdump[1] lets you do this, if you have enabled the +_Berkeley Packet Filter_ interface in your crossref::ipsec-must[kernel,src/sys/i386/conf/KERNELNAME]. The command: @@ -99,9 +100,9 @@ Here is the experiment: [.procedure] ==== . Open a window to an IPsec host and another window to an insecure host. -. Now start <<tcpdump>>. +. Now start crossref::ipsec-must[tcpdump, Tcpdump]. . In the "secure" window, run the UNIX(R) command man:yes[1], which will stream the `y` character. After a while, stop this. Switch to the insecure window, and repeat. After a while, stop. -. Now run <<code>> on the captured packets. You should see something like the following. The important thing to note is that the secure connection has 93% (6.7) of the expected value (7.18), and the "normal" connection has 29% (2.1) of the expected value. +. Now run crossref::ipsec-must[code, Maurer's Universal Statistical Test (for block size8 bits)] on the captured packets. You should see something like the following. The important thing to note is that the secure connection has 93% (6.7) of the expected value (7.18), and the "normal" connection has 29% (2.1) of the expected value. + [source,shell] .... @@ -143,12 +144,12 @@ IPsec encrypts everything between two hosts. Most of the modern versions of FreeBSD have IPsec support in their base source. So you will need to include the `IPSEC` option in your kernel config and, after kernel rebuild and reinstall, configure IPsec connections using man:setkey[8] command. -A comprehensive guide on running IPsec on FreeBSD is provided in extref:{handbook}[FreeBSD Handbook, ipsec]. +A comprehensive guide on running IPsec on FreeBSD is provided in extref:{vpn-ipsec}[VPN over IPsec]. [[kernel]] == src/sys/i386/conf/KERNELNAME -This needs to be present in the kernel config file in order to capture network data with man:tcpdump[1]. +This needs to be present in the kernel config file to capture network data with man:tcpdump[1]. Be sure to run man:config[8] after adding this, and rebuild and reinstall. [.programlisting] diff --git a/documentation/content/en/articles/ipsec-must/_index.po b/documentation/content/en/articles/ipsec-must/_index.po new file mode 100644 index 0000000000..559dddbb99 --- /dev/null +++ b/documentation/content/en/articles/ipsec-must/_index.po @@ -0,0 +1,571 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-12-29 08:30-0500\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: Title = +#: documentation/content/en/articles/ipsec-must/_index.adoc:1 +#: documentation/content/en/articles/ipsec-must/_index.adoc:11 +#, no-wrap +msgid "Independent Verification of IPsec Functionality in FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:47 +msgid "" +"You installed IPsec and it seems to be working. How do you know? I describe " +"a method for experimentally verifying that IPsec is working." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:49 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ipsec-must/_index.adoc:53 +#, no-wrap +msgid "The Problem" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:58 +msgid "" +"First, lets assume you have crossref::ipsec-must[ipsec-install, Installing " +"IPsec]. How do you know it is crossref::ipsec-must[caveat, Caveat]? Sure, " +"your connection will not work if it is misconfigured, and it will work when " +"you finally get it right. man:netstat[1] will list it. But can you " +"independently confirm it?" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ipsec-must/_index.adoc:60 +#, no-wrap +msgid "The Solution" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:63 +msgid "First, some crypto-relevant info theory:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:65 +msgid "" +"Encrypted data is uniformly distributed, i.e., has maximal entropy per " +"symbol;" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:66 +msgid "" +"Raw, uncompressed data is typically redundant, i.e., has sub-maximal entropy." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:70 +msgid "" +"Suppose you could measure the entropy of the data to- and from- your network " +"interface. Then you could see the difference between unencrypted data and " +"encrypted data. This would be true even if some of the data in \"encrypted " +"mode\" was not encrypted---as the outermost IP header must be if the packet " +"is to be routable." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/ipsec-must/_index.adoc:72 +#, no-wrap +msgid "MUST" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:77 +msgid "" +"Ueli Maurer's \"Universal Statistical Test for Random Bit " +"Generators\"(https://web.archive.org/web/20011115002319/http://www.geocities." +"com/SiliconValley/Code/4704/universal.pdf[MUST]) quickly measures the " +"entropy of a sample. It uses a compression-like algorithm. crossref::ipsec-" +"must[code, Maurer's Universal Statistical Test (for block size8 bits)] for a " +"variant which measures successive (~quarter megabyte) chunks of a file." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/ipsec-must/_index.adoc:79 +#, no-wrap +msgid "Tcpdump" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:84 +msgid "" +"We also need a way to capture the raw network data. A program called man:" +"tcpdump[1] lets you do this, if you have enabled the _Berkeley Packet " +"Filter_ interface in your crossref::ipsec-must[kernel,src/sys/i386/conf/" +"KERNELNAME]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:86 +msgid "The command:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:90 +#, no-wrap +msgid " tcpdump -c 4000 -s 10000 -w dumpfile.bin\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:94 +msgid "" +"will capture 4000 raw packets to _dumpfile.bin_. Up to 10,000 bytes per " +"packet will be captured in this example." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ipsec-must/_index.adoc:96 +#, no-wrap +msgid "The Experiment" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:99 +msgid "Here is the experiment:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:103 +msgid "Open a window to an IPsec host and another window to an insecure host." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:104 +msgid "Now start crossref::ipsec-must[tcpdump, Tcpdump]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:105 +msgid "" +"In the \"secure\" window, run the UNIX(R) command man:yes[1], which will " +"stream the `y` character. After a while, stop this. Switch to the insecure " +"window, and repeat. After a while, stop." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:106 +msgid "" +"Now run crossref::ipsec-must[code, Maurer's Universal Statistical Test (for " +"block size8 bits)] on the captured packets. You should see something like " +"the following. The important thing to note is that the secure connection has " +"93% (6.7) of the expected value (7.18), and the \"normal\" connection has " +"29% (2.1) of the expected value." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:122 +#, no-wrap +msgid "" +"% tcpdump -c 4000 -s 10000 -w ipsecdemo.bin\n" +"% uliscan ipsecdemo.bin\n" +"Uliscan 21 Dec 98\n" +"L=8 256 258560\n" +"Measuring file ipsecdemo.bin\n" +"Init done\n" +"Expected value for L=8 is 7.1836656\n" +"6.9396 --------------------------------------------------------\n" +"6.6177 -----------------------------------------------------\n" +"6.4100 ---------------------------------------------------\n" +"2.1101 -----------------\n" +"2.0838 -----------------\n" +"2.0983 -----------------\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ipsec-must/_index.adoc:126 +#, no-wrap +msgid "Caveat" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:132 +msgid "" +"This experiment shows that IPsec _does_ seem to be distributing the payload " +"data __uniformly__, as encryption should. However, the experiment described " +"here _cannot_ detect many possible flaws in a system (none of which do I " +"have any evidence for). These include poor key generation or exchange, data " +"or keys being visible to others, use of weak algorithms, kernel subversion, " +"etc. Study the source; know the code." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ipsec-must/_index.adoc:134 +#, no-wrap +msgid "IPsec---Definition" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:140 +msgid "" +"Internet Protocol security extensions to IPv4; required for IPv6. A " +"protocol for negotiating encryption and authentication at the IP (host-to-" +"host) level. SSL secures only one application socket; SSH secures only a " +"login; PGP secures only a specified file or message. IPsec encrypts " +"everything between two hosts." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ipsec-must/_index.adoc:142 +#, no-wrap +msgid "Installing IPsec" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:146 +msgid "" +"Most of the modern versions of FreeBSD have IPsec support in their base " +"source. So you will need to include the `IPSEC` option in your kernel " +"config and, after kernel rebuild and reinstall, configure IPsec connections " +"using man:setkey[8] command." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:148 +msgid "" +"A comprehensive guide on running IPsec on FreeBSD is provided in extref:" +"{handbook}[FreeBSD Handbook, ipsec]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ipsec-must/_index.adoc:150 +#, no-wrap +msgid "src/sys/i386/conf/KERNELNAME" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:154 +msgid "" +"This needs to be present in the kernel config file to capture network data " +"with man:tcpdump[1]. Be sure to run man:config[8] after adding this, and " +"rebuild and reinstall." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:158 +#, no-wrap +msgid "device\tbpf\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ipsec-must/_index.adoc:161 +#, no-wrap +msgid "Maurer's Universal Statistical Test (for block size=8 bits)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ipsec-must/_index.adoc:164 +msgid "" +"You can find the same code at https://web.archive.org/web/20031204230654/" +"http://www.geocities.com:80/SiliconValley/Code/4704/uliscanc.txt[this link]." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:169 +#, no-wrap +msgid "" +"/*\n" +" ULISCAN.c ---blocksize of 8\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:173 +#, no-wrap +msgid "" +" 1 Oct 98\n" +" 1 Dec 98\n" +" 21 Dec 98 uliscan.c derived from ueli8.c\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:175 +#, no-wrap +msgid " This version has // comments removed for Sun cc\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:178 +#, no-wrap +msgid "" +" This implements Ueli M Maurer's \"Universal Statistical Test for Random\n" +" Bit Generators\" using L=8\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:181 +#, no-wrap +msgid "" +" Accepts a filename on the command line; writes its results, with other\n" +" info, to stdout.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:183 +#, no-wrap +msgid " Handles input file exhaustion gracefully.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:186 +#, no-wrap +msgid "" +" Ref: J. Cryptology v 5 no 2, 1992 pp 89-105\n" +" also on the web somewhere, which is where I found it.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:189 +#, no-wrap +msgid "" +" -David Honig\n" +" honig@sprynet.com\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:194 +#, no-wrap +msgid "" +" Usage:\n" +" ULISCAN filename\n" +" outputs to stdout\n" +"*/\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:200 +#, no-wrap +msgid "" +"#define L 8\n" +"#define V (1<<L)\n" +"#define Q (10*V)\n" +"#define K (100 *Q)\n" +"#define MAXSAMP (Q + K)\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:203 +#, no-wrap +msgid "" +"#include <stdio.h>\n" +"#include <math.h>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:215 +#, no-wrap +msgid "" +"int main(argc, argv)\n" +"int argc;\n" +"char **argv;\n" +"{\n" +" FILE *fptr;\n" +" int i,j;\n" +" int b, c;\n" +" int table[V];\n" +" double sum = 0.0;\n" +" int iproduct = 1;\n" +" int run;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:217 +#, no-wrap +msgid " extern double log(/* double x */);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:219 +#, no-wrap +msgid " printf(\"Uliscan 21 Dec 98 \\nL=%d %d %d \\n\", L, V, MAXSAMP);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:226 +#, no-wrap +msgid "" +" if (argc < 2) {\n" +" printf(\"Usage: Uliscan filename\\n\");\n" +" exit(-1);\n" +" } else {\n" +" printf(\"Measuring file %s\\n\", argv[1]);\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:228 +#, no-wrap +msgid " fptr = fopen(argv[1],\"rb\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:233 +#, no-wrap +msgid "" +" if (fptr == NULL) {\n" +" printf(\"Can't find %s\\n\", argv[1]);\n" +" exit(-1);\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:237 +#, no-wrap +msgid "" +" for (i = 0; i < V; i++) {\n" +" table[i] = 0;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:242 +#, no-wrap +msgid "" +" for (i = 0; i < Q; i++) {\n" +" b = fgetc(fptr);\n" +" table[b] = i;\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:244 +#, no-wrap +msgid " printf(\"Init done\\n\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:246 +#, no-wrap +msgid " printf(\"Expected value for L=8 is 7.1836656\\n\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:248 +#, no-wrap +msgid " run = 1;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:252 +#, no-wrap +msgid "" +" while (run) {\n" +" sum = 0.0;\n" +" iproduct = 1;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:257 +#, no-wrap +msgid "" +" if (run)\n" +" for (i = Q; run && i < Q + K; i++) {\n" +" j = i;\n" +" b = fgetc(fptr);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:260 +#, no-wrap +msgid "" +" if (b < 0)\n" +" run = 0;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:264 +#, no-wrap +msgid "" +" if (run) {\n" +" if (table[b] > j)\n" +" j += K;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:266 +#, no-wrap +msgid " sum += log((double)(j-table[b]));\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:270 +#, no-wrap +msgid "" +" table[b] = i;\n" +" }\n" +" }\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:273 +#, no-wrap +msgid "" +" if (!run)\n" +" printf(\"Premature end of file; read %d blocks.\\n\", i - Q);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:276 +#, no-wrap +msgid "" +" sum = (sum/((double)(i - Q))) / log(2.0);\n" +" printf(\"%4.4f \", sum);\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:279 +#, no-wrap +msgid "" +" for (i = 0; i < (int)(sum*8.0 + 0.50); i++)\n" +" printf(\"-\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:281 +#, no-wrap +msgid " printf(\"\\n\");\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ipsec-must/_index.adoc:295 +#, no-wrap +msgid "" +" /* refill initial table */\n" +" if (0) {\n" +" for (i = 0; i < Q; i++) {\n" +" b = fgetc(fptr);\n" +" if (b < 0) {\n" +" run = 0;\n" +" } else {\n" +" table[b] = i;\n" +" }\n" +" }\n" +" }\n" +" }\n" +"}\n" +msgstr "" diff --git a/documentation/content/en/articles/ldap-auth/_index.adoc b/documentation/content/en/articles/ldap-auth/_index.adoc index 66a05a8e4f..7fc7543484 100644 --- a/documentation/content/en/articles/ldap-auth/_index.adoc +++ b/documentation/content/en/articles/ldap-auth/_index.adoc @@ -70,8 +70,8 @@ Its most recent specifications are in http://www.ietf.org/rfc/rfc4510.txt[RFC451 Essentially it is a database that expects to be read from more often than it is written to. The LDAP server http://www.openldap.org/[OpenLDAP] will be used in the examples in this document; while the principles here should be generally applicable to many different servers, most of the concrete administration is OpenLDAP-specific. -There are several server versions in ports, for example package:net/openldap24-server[]. -Client servers will need the corresponding package:net/openldap24-client[] libraries. +There are several server versions in ports, for example package:net/openldap26-server[]. +Client servers will need the corresponding package:net/openldap26-client[] libraries. There are (basically) two areas of the LDAP service which need configuration. The first is setting up a server to receive connections properly, and the second is adding entries to the server's directory so that FreeBSD tools know how to interact with it. @@ -97,7 +97,7 @@ First, install OpenLDAP: [source,shell] .... -# cd /usr/ports/net/openldap24-server +# cd /usr/ports/net/openldap26-server # make install clean .... @@ -187,7 +187,8 @@ Getting Private key ==== This will create a self-signed certificate that can be used for the directives in [.filename]#slapd.conf#, where [.filename]#cert.crt# and [.filename]#cacert.crt# are the same file. -If you are going to use many OpenLDAP servers (for replication via `slurpd`) you will want to see <<ssl-ca>> to generate a CA key and use it to sign individual server certificates. +If you are going to use many OpenLDAP servers (for replication via `slurpd`) you +will want to see crossref:ldap-auth[ssl-ca, OpenSSL Certificates for LDAP] to generate a CA key and use it to sign individual server certificates. Once this is done, put the following in [.filename]#/etc/rc.conf#: @@ -209,7 +210,7 @@ ldap slapd 3261 7 tcp4 *:389 *:* [[ldap-connect-client]] ==== Configuring the Client -Install the package:net/openldap24-client[] port for the OpenLDAP libraries. +Install the package:net/openldap26-client[] port for the OpenLDAP libraries. The client machines will always have OpenLDAP libraries since that is all package:security/pam_ldap[] and package:net/nss_ldap[] support, at least for the moment. The configuration file for the OpenLDAP libraries is [.filename]#/usr/local/etc/openldap/ldap.conf#. @@ -272,7 +273,7 @@ In either case, the relevant schemas need to be loaded in [.filename]#slapd.conf For this example we will use the `person` object class. If you are using `inetOrgPerson`, the steps are basically identical, except that the `sn` attribute is required. -To add a user `testuser`, the ldif would be: +To add a test-user named `tuser`, the ldif would be: [.programlisting] .... @@ -317,7 +318,8 @@ If it does, your database is properly configured to be used as an LDAP authentic [[client]] == Client Configuration -The client should already have OpenLDAP libraries from <<ldap-connect-client>>, but if you are installing several client machines you will need to install package:net/openldap24-client[] on each of them. +The client should already have OpenLDAP libraries from +crossref:ldap-auth[ldap-connect-client,Configuring the Client], but if you are installing several client machines you will need to install package:net/openldap26-client[] on each of them. FreeBSD requires two ports to be installed to authenticate against an LDAP server, package:security/pam_ldap[] and package:net/nss_ldap[]. @@ -491,7 +493,8 @@ Congratulations! You should now have working LDAP authentication. Unfortunately, as of the time this was written FreeBSD did not support changing user passwords with man:passwd[1]. As a result of this, most administrators are left to implement a solution themselves. I provide some examples here. -Note that if you write your own password change script, there are some security issues you should be made aware of; see <<security-passwd>> +Note that if you write your own password change script, there are some security +issues you should be made aware of; see crossref:ldap-auth[security-passwd, Password Storage] [[chpw-shell]] .Shell Script for Changing Passwords @@ -734,10 +737,6 @@ There are a few other programs that might be useful, particularly if you have ma package:security/pam_mkhomedir[] is a PAM module that always succeeds; its purpose is to create home directories for users which do not have them. If you have dozens of client servers and hundreds of users, it is much easier to use this and set up skeleton directories than to prepare every home directory. -package:sysutils/cpu[] is a man:pw[8]-like utility that can be used to manage users in the LDAP directory. -You can call it directly, or wrap scripts around it. -It can handle both TLS (with the `-x` flag) and SSL (directly). - package:sysutils/ldapvi[] is a great utility for editing LDAP values in an LDIF-like syntax. The directory (or subsection of the directory) is presented in the editor chosen by the `EDITOR` environment variable. This makes it easy to enable large-scale changes in the directory without having to write a custom tool. diff --git a/documentation/content/en/articles/ldap-auth/_index.po b/documentation/content/en/articles/ldap-auth/_index.po new file mode 100644 index 0000000000..848c2f1120 --- /dev/null +++ b/documentation/content/en/articles/ldap-auth/_index.po @@ -0,0 +1,1424 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-12-29 08:30-0500\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/ldap-auth/_index.adoc:1 +#, no-wrap +msgid "Guide for the configuration of an LDAP server for authentication on FreeBSD" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/ldap-auth/_index.adoc:1 +#: documentation/content/en/articles/ldap-auth/_index.adoc:12 +#, no-wrap +msgid "LDAP Authentication" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:45 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:48 +msgid "" +"This document is intended as a guide for the configuration of an LDAP server " +"(principally an OpenLDAP server) for authentication on FreeBSD. This is " +"useful for situations where many servers need the same user accounts, for " +"example as a replacement for NIS." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:50 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ldap-auth/_index.adoc:54 +#, no-wrap +msgid "Preface" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:58 +msgid "" +"This document is intended to give the reader enough of an understanding of " +"LDAP to configure an LDAP server. This document will attempt to provide an " +"explanation of package:net/nss_ldap[] and package:security/pam_ldap[] for " +"use with client machines services for use with the LDAP server." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:60 +msgid "" +"When finished, the reader should be able to configure and deploy a FreeBSD " +"server that can host an LDAP directory, and to configure and deploy a " +"FreeBSD server which can authenticate against an LDAP directory." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:64 +msgid "" +"This article is not intended to be an exhaustive account of the security, " +"robustness, or best practice considerations for configuring LDAP or the " +"other services discussed herein. While the author takes care to do " +"everything correctly, they do not address security issues beyond a general " +"scope. This article should be considered to lay the theoretical groundwork " +"only, and any actual implementation should be accompanied by careful " +"requirement analysis." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ldap-auth/_index.adoc:66 +#, no-wrap +msgid "Configuring LDAP" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:71 +msgid "" +"LDAP stands for \"Lightweight Directory Access Protocol\" and is a subset of " +"the X.500 Directory Access Protocol. Its most recent specifications are in " +"http://www.ietf.org/rfc/rfc4510.txt[RFC4510] and friends. Essentially it is " +"a database that expects to be read from more often than it is written to." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:75 +msgid "" +"The LDAP server http://www.openldap.org/[OpenLDAP] will be used in the " +"examples in this document; while the principles here should be generally " +"applicable to many different servers, most of the concrete administration is " +"OpenLDAP-specific. There are several server versions in ports, for example " +"package:net/openldap26-server[]. Client servers will need the corresponding " +"package:net/openldap26-client[] libraries." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:78 +msgid "" +"There are (basically) two areas of the LDAP service which need " +"configuration. The first is setting up a server to receive connections " +"properly, and the second is adding entries to the server's directory so that " +"FreeBSD tools know how to interact with it." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/ldap-auth/_index.adoc:80 +#, no-wrap +msgid "Setting Up the Server for Connections" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:86 +msgid "" +"This section is specific to OpenLDAP. If you are using another server, you " +"will need to consult that server's documentation." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:89 +#: documentation/content/en/articles/ldap-auth/_index.adoc:94 +#, no-wrap +msgid "Installing OpenLDAP" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:92 +msgid "First, install OpenLDAP:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:102 +#, no-wrap +msgid "" +"# cd /usr/ports/net/openldap26-server\n" +"# make install clean\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:107 +msgid "" +"This installs the `slapd` and `slurpd` binaries, along with the required " +"OpenLDAP libraries." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/ldap-auth/_index.adoc:109 +#, no-wrap +msgid "Configuring OpenLDAP" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:112 +msgid "Next we must configure OpenLDAP." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:115 +msgid "" +"You will want to require encryption in your connections to the LDAP server; " +"otherwise your users' passwords will be transferred in plain text, which is " +"considered insecure. The tools we will be using support two very similar " +"kinds of encryption, SSL and TLS." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:118 +msgid "" +"TLS stands for \"Transportation Layer Security\". Services that employ TLS " +"tend to connect on the _same_ ports as the same services without TLS; thus " +"an SMTP server which supports TLS will listen for connections on port 25, " +"and an LDAP server will listen on 389." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:121 +msgid "" +"SSL stands for \"Secure Sockets Layer\", and services that implement SSL do " +"_not_ listen on the same ports as their non-SSL counterparts. Thus SMTPS " +"listens on port 465 (not 25), HTTPS listens on 443, and LDAPS on 636." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:125 +msgid "" +"The reason SSL uses a different port than TLS is because a TLS connection " +"begins as plain text, and switches to encrypted traffic after the `STARTTLS` " +"directive. SSL connections are encrypted from the beginning. Other than " +"that there are no substantial differences between the two." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:129 +msgid "We will adjust OpenLDAP to use TLS, as SSL is considered deprecated." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:132 +msgid "" +"Once OpenLDAP is installed via ports, the following configuration parameters " +"in [.filename]#/usr/local/etc/openldap/slapd.conf# will enable TLS:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:136 +#, no-wrap +msgid "security ssf=128\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:140 +#, no-wrap +msgid "" +"TLSCertificateFile /path/to/your/cert.crt\n" +"TLSCertificateKeyFile /path/to/your/cert.key\n" +"TLSCACertificateFile /path/to/your/cacert.crt\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:144 +msgid "" +"Here, `ssf=128` tells OpenLDAP to require 128-bit encryption for all " +"connections, both search and update. This parameter may be configured based " +"on the security needs of your site, but rarely you need to weaken it, as " +"most LDAP client libraries support strong encryption." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:147 +msgid "" +"The [.filename]#cert.crt#, [.filename]#cert.key#, and [.filename]#cacert." +"crt# files are necessary for clients to authenticate _you_ as the valid LDAP " +"server. If you simply want a server that runs, you can create a self-signed " +"certificate with OpenSSL:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:149 +#, no-wrap +msgid "Generating an RSA Key" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:160 +#, no-wrap +msgid "" +"% openssl genrsa -out cert.key 1024\n" +"Generating RSA private key, 1024 bit long modulus\n" +"....................++++++\n" +"...++++++\n" +"e is 65537 (0x10001)\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:162 +#, no-wrap +msgid "% openssl req -new -key cert.key -out cert.csr\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:171 +msgid "" +"At this point you should be prompted for some values. You may enter " +"whatever values you like; however, it is important the \"Common Name\" value " +"be the fully qualified domain name of the OpenLDAP server. In our case, and " +"the examples here, the server is _server.example.org_. Incorrectly setting " +"this value will cause clients to fail when making connections. This can the " +"cause of great frustration, so ensure that you follow these steps closely." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:173 +msgid "Finally, the certificate signing request needs to be signed:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:175 +#, no-wrap +msgid "Self-signing the Certificate" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:185 +#, no-wrap +msgid "" +"% openssl x509 -req -in cert.csr -days 365 -signkey cert.key -out cert.crt\n" +"Signature ok\n" +"subject=/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd\n" +"Getting Private key\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:192 +msgid "" +"This will create a self-signed certificate that can be used for the " +"directives in [.filename]#slapd.conf#, where [.filename]#cert.crt# and [." +"filename]#cacert.crt# are the same file. If you are going to use many " +"OpenLDAP servers (for replication via `slurpd`) you will want to see " +"crossref:ldap-auth[ssl-ca, OpenSSL Certificates for LDAP] to generate a CA " +"key and use it to sign individual server certificates." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:194 +msgid "Once this is done, put the following in [.filename]#/etc/rc.conf#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:198 +#, no-wrap +msgid "slapd_enable=\"YES\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:203 +msgid "" +"Then run `/usr/local/etc/rc.d/slapd start`. This should start OpenLDAP. " +"Confirm that it is listening on 389 with" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:208 +#, no-wrap +msgid "" +"% sockstat -4 -p 389\n" +"ldap slapd 3261 7 tcp4 *:389 *:*\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/ldap-auth/_index.adoc:211 +#, no-wrap +msgid "Configuring the Client" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:215 +msgid "" +"Install the package:net/openldap26-client[] port for the OpenLDAP " +"libraries. The client machines will always have OpenLDAP libraries since " +"that is all package:security/pam_ldap[] and package:net/nss_ldap[] support, " +"at least for the moment." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:218 +msgid "" +"The configuration file for the OpenLDAP libraries is [.filename]#/usr/local/" +"etc/openldap/ldap.conf#. Edit this file to contain the following values:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:225 +#, no-wrap +msgid "" +"base dc=example,dc=org\n" +"uri ldap://server.example.org/\n" +"ssl start_tls\n" +"tls_cacert /path/to/your/cacert.crt\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:230 +msgid "" +"It is important that your clients have access to [.filename]#cacert.crt#, " +"otherwise they will not be able to connect." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:237 +msgid "" +"There are two files called [.filename]#ldap.conf#. The first is this file, " +"which is for the OpenLDAP libraries and defines how to talk to the server. " +"The second is [.filename]#/usr/local/etc/ldap.conf#, and is for pam_ldap." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:242 +msgid "" +"At this point you should be able to run `ldapsearch -Z` on the client " +"machine; `-Z` means \"use TLS\". If you encounter an error, then something " +"is configured wrong; most likely it is your certificates. Use man:" +"openssl[1]'s `s_client` and `s_server` to ensure you have them configured " +"and signed properly." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/ldap-auth/_index.adoc:244 +#, no-wrap +msgid "Entries in the Database" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:249 +msgid "" +"Authentication against an LDAP directory is generally accomplished by " +"attempting to bind to the directory as the connecting user. This is done by " +"establishing a \"simple\" bind on the directory with the user name " +"supplied. If there is an entry with the `uid` equal to the user name and " +"that entry's `userPassword` attribute matches the password supplied, then " +"the bind is successful." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:251 +msgid "" +"The first thing we have to do is figure out is where in the directory our " +"users will live." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:255 +msgid "" +"The base entry for our database is `dc=example,dc=org`. The default " +"location for users that most clients seem to expect is something like " +"`ou=people,_base_`, so that is what will be used here. However keep in mind " +"that this is configurable." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:257 +msgid "So the ldif entry for the `people` organizational unit will look like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:264 +#, no-wrap +msgid "" +"dn: ou=people,dc=example,dc=org\n" +"objectClass: top\n" +"objectClass: organizationalUnit\n" +"ou: people\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:267 +msgid "All users will be created as subentries of this organizational unit." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:272 +msgid "" +"Some thought might be given to the object class your users will belong to. " +"Most tools by default will use `people`, which is fine if you simply want to " +"provide entries against which to authenticate. However, if you are going to " +"store user information in the LDAP database as well, you will probably want " +"to use `inetOrgPerson`, which has many useful attributes. In either case, " +"the relevant schemas need to be loaded in [.filename]#slapd.conf#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:275 +msgid "" +"For this example we will use the `person` object class. If you are using " +"`inetOrgPerson`, the steps are basically identical, except that the `sn` " +"attribute is required." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:277 +msgid "To add a test-user named `tuser`, the ldif would be:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:291 +#, no-wrap +msgid "" +"dn: uid=tuser,ou=people,dc=example,dc=org\n" +"objectClass: person\n" +"objectClass: posixAccount\n" +"objectClass: shadowAccount\n" +"objectClass: top\n" +"uidNumber: 10000\n" +"gidNumber: 10000\n" +"homeDirectory: /home/tuser\n" +"loginShell: /bin/csh\n" +"uid: tuser\n" +"cn: tuser\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:294 +msgid "" +"I start my LDAP users' UIDs at 10000 to avoid collisions with system " +"accounts; you can configure whatever number you wish here, as long as it is " +"less than 65536." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:297 +msgid "" +"We also need group entries. They are as configurable as user entries, but " +"we will use the defaults below:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:304 +#, no-wrap +msgid "" +"dn: ou=groups,dc=example,dc=org\n" +"objectClass: top\n" +"objectClass: organizationalUnit\n" +"ou: groups\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:310 +#, no-wrap +msgid "" +"dn: cn=tuser,ou=groups,dc=example,dc=org\n" +"objectClass: posixGroup\n" +"objectClass: top\n" +"gidNumber: 10000\n" +"cn: tuser\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:314 +msgid "" +"To enter these into your database, you can use `slapadd` or `ldapadd` on a " +"file containing these entries. Alternatively, you can use package:sysutils/" +"ldapvi[]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:317 +msgid "" +"The `ldapsearch` utility on the client machine should now return these " +"entries. If it does, your database is properly configured to be used as an " +"LDAP authentication server." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ldap-auth/_index.adoc:319 +#, no-wrap +msgid "Client Configuration" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:323 +msgid "" +"The client should already have OpenLDAP libraries from crossref:ldap-" +"auth[ldap-connect-client,Configuring the Client], but if you are installing " +"several client machines you will need to install package:net/openldap26-" +"client[] on each of them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:325 +msgid "" +"FreeBSD requires two ports to be installed to authenticate against an LDAP " +"server, package:security/pam_ldap[] and package:net/nss_ldap[]." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/ldap-auth/_index.adoc:327 +#, no-wrap +msgid "Authentication" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:330 +msgid "" +"package:security/pam_ldap[] is configured via [.filename]#/usr/local/etc/" +"ldap.conf#." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:335 +msgid "" +"This is a _different file_ than the OpenLDAP library functions' " +"configuration file, [.filename]#/usr/local/etc/openldap/ldap.conf#; however, " +"it takes many of the same options; in fact it is a superset of that file. " +"For the rest of this section, references to [.filename]#ldap.conf# will mean " +"[.filename]#/usr/local/etc/ldap.conf#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:339 +msgid "" +"Thus, we will want to copy all of our original configuration parameters from " +"[.filename]#openldap/ldap.conf# to the new [.filename]#ldap.conf#. Once " +"this is done, we want to tell package:security/pam_ldap[] what to look for " +"on the directory server." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:342 +msgid "" +"We are identifying our users with the `uid` attribute. To configure this " +"(though it is the default), set the `pam_login_attribute` directive in [." +"filename]#ldap.conf#:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:344 +#, no-wrap +msgid "Setting `pam_login_attribute`" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:351 +#, no-wrap +msgid "pam_login_attribute uid\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:359 +msgid "" +"With this set, package:security/pam_ldap[] will search the entire LDAP " +"directory under `base` for the value `uid=_username_`. If it finds one and " +"only one entry, it will attempt to bind as that user with the password it " +"was given. If it binds correctly, then it will allow access. Otherwise it " +"will fail." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:365 +msgid "" +"Users whose shell is not in [.filename]#/etc/shells# will not be able to log " +"in. This is particularly important when Bash is set as the user shell on " +"the LDAP server. Bash is not included with a default installation of " +"FreeBSD. When installed from a package or port, it is located at [." +"filename]#/usr/local/bin/bash#. Verify that the path to the shell on the " +"server is set correctly:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:369 +#, no-wrap +msgid "% getent passwd username\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:374 +msgid "" +"There are two choices when the output shows `/bin/bash` in the last column. " +"The first is to change the user's entry on the LDAP server to [.filename]#/" +"usr/local/bin/bash#. The second option is to create a symlink on the LDAP " +"client computer so Bash is found at the correct location:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:378 +#, no-wrap +msgid "# ln -s /usr/local/bin/bash /bin/bash\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:382 +msgid "" +"Make sure that [.filename]#/etc/shells# contains entries for both `/usr/" +"local/bin/bash` and `/bin/bash`. The user will then be able to log in to " +"the system with Bash as their shell." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/ldap-auth/_index.adoc:384 +#, no-wrap +msgid "PAM" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:388 +msgid "" +"PAM, which stands for \"Pluggable Authentication Modules\", is the method by " +"which FreeBSD authenticates most of its sessions. To tell FreeBSD we wish " +"to use an LDAP server, we will have to add a line to the appropriate PAM " +"file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:390 +msgid "" +"Most of the time the appropriate PAM file is [.filename]#/etc/pam.d/sshd#, " +"if you want to use SSH (remember to set the relevant options in [.filename]#/" +"etc/ssh/sshd_config#, otherwise SSH will not use PAM)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:392 +msgid "To use PAM for authentication, add the line" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:396 +#, no-wrap +msgid "auth sufficient /usr/local/lib/pam_ldap.so no_warn\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:399 +msgid "" +"Exactly where this line shows up in the file and which options appear in the " +"fourth column determine the exact behavior of the authentication mechanism; " +"see man:pam[d]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:402 +msgid "" +"With this configuration you should be able to authenticate a user against an " +"LDAP directory. PAM will perform a bind with your credentials, and if " +"successful will tell SSH to allow access." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:406 +msgid "" +"However it is not a good idea to allow _every_ user in the directory into " +"_every_ client machine. With the current configuration, all that a user " +"needs to log into a machine is an LDAP entry. Fortunately there are a few " +"ways to restrict user access." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:409 +msgid "" +"[.filename]#ldap.conf# supports a `pam_groupdn` directive; every account " +"that connects to this machine needs to be a member of the group specified " +"here. For example, if you have" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:413 +#, no-wrap +msgid "pam_groupdn cn=servername,ou=accessgroups,dc=example,dc=org\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:417 +msgid "" +"in [.filename]#ldap.conf#, then only members of that group will be able to " +"log in. There are a few things to bear in mind, however." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:420 +msgid "" +"Members of this group are specified in one or more `memberUid` attributes, " +"and each attribute must have the full distinguished name of the member. So " +"`memberUid: someuser` will not work; it must be:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:424 +#, no-wrap +msgid "memberUid: uid=someuser,ou=people,dc=example,dc=org\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:430 +msgid "" +"Additionally, this directive is not checked in PAM during authentication, it " +"is checked during account management, so you will need a second line in your " +"PAM files under `account`. This will require, in turn, _every_ user to be " +"listed in the group, which is not necessarily what we want. To avoid " +"blocking users that are not in LDAP, you should enable the " +"`ignore_unknown_user` attribute. Finally, you should set the " +"`ignore_authinfo_unavail` option so that you are not locked out of every " +"computer when the LDAP server is unavailable." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:432 +msgid "Your [.filename]#pam.d/sshd# might then end up looking like this:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:434 +#, no-wrap +msgid "Sample [.filename]#pam.d/sshd#" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:445 +#, no-wrap +msgid "" +"auth required pam_nologin.so no_warn\n" +"auth sufficient pam_opie.so no_warn no_fake_prompts\n" +"auth requisite pam_opieaccess.so no_warn allow_local\n" +"auth sufficient /usr/local/lib/pam_ldap.so no_warn\n" +"auth required pam_unix.so no_warn try_first_pass\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:448 +#, no-wrap +msgid "" +"account required pam_login_access.so\n" +"account required /usr/local/lib/pam_ldap.so no_warn ignore_authinfo_unavail ignore_unknown_user\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:457 +msgid "" +"Since we are adding these lines specifically to [.filename]#pam.d/sshd#, " +"this will only have an effect on SSH sessions. LDAP users will be unable to " +"log in at the console. To change this behavior, examine the other files in " +"[.filename]#/etc/pam.d# and modify them accordingly." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/ldap-auth/_index.adoc:460 +#, no-wrap +msgid "Name Service Switch" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:464 +msgid "" +"NSS is the service that maps attributes to names. So, for example, if a " +"file is owned by user `1001`, an application will query NSS for the name of " +"`1001`, and it might get `bob` or `ted` or whatever the user's name is." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:466 +msgid "" +"Now that our user information is kept in LDAP, we need to tell NSS to look " +"there when queried." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:471 +msgid "" +"The package:net/nss_ldap[] port does this. It uses the same configuration " +"file as package:security/pam_ldap[], and should not need any extra " +"parameters once it is installed. Instead, what is left is simply to edit [." +"filename]#/etc/nsswitch.conf# to take advantage of the directory. Simply " +"replace the following lines:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:476 +#, no-wrap +msgid "" +"group: compat\n" +"passwd: compat\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:479 +msgid "with" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:484 +#, no-wrap +msgid "" +"group: files ldap\n" +"passwd: files ldap\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:487 +msgid "This will allow you to map usernames to UIDs and UIDs to usernames." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:489 +msgid "Congratulations! You should now have working LDAP authentication." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/ldap-auth/_index.adoc:491 +#, no-wrap +msgid "Caveats" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:498 +msgid "" +"Unfortunately, as of the time this was written FreeBSD did not support " +"changing user passwords with man:passwd[1]. As a result of this, most " +"administrators are left to implement a solution themselves. I provide some " +"examples here. Note that if you write your own password change script, " +"there are some security issues you should be made aware of; see crossref:" +"ldap-auth[security-passwd, Password Storage]" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:500 +#, no-wrap +msgid "Shell Script for Changing Passwords" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:507 +#, no-wrap +msgid "#!/bin/sh\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:513 +#, no-wrap +msgid "" +"stty -echo\n" +"read -p \"Old Password: \" oldp; echo\n" +"read -p \"New Password: \" np1; echo\n" +"read -p \"Retype New Password: \" np2; echo\n" +"stty echo\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:518 +#, no-wrap +msgid "" +"if [ \"$np1\" != \"$np2\" ]; then\n" +" echo \"Passwords do not match.\"\n" +" exit 1\n" +"fi\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:523 +#, no-wrap +msgid "" +"ldappasswd -D uid=\"$USER\",ou=people,dc=example,dc=org \\\n" +" -w \"$oldp\" \\\n" +" -a \"$oldp\" \\\n" +" -s \"$np1\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:532 +msgid "" +"This script does hardly any error checking, but more important it is very " +"cavalier about how it stores your passwords. If you do anything like this, " +"at least adjust the `security.bsd.see_other_uids` sysctl value:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:536 +#, no-wrap +msgid "# sysctl security.bsd.see_other_uids=0\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:543 +msgid "" +"A more flexible (and probably more secure) approach can be used by writing a " +"custom program, or even a web interface. The following is part of a Ruby " +"library that can change LDAP passwords. It sees use both on the command " +"line, and on the web." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:545 +#, no-wrap +msgid "Ruby Script for Changing Passwords" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:555 +#, no-wrap +msgid "" +"require 'ldap'\n" +"require 'base64'\n" +"require 'digest'\n" +"require 'password' # ruby-password\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:558 +#, no-wrap +msgid "" +"ldap_server = \"ldap.example.org\"\n" +"luser = \"uid=#{ENV['USER']},ou=people,dc=example,dc=org\"\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:563 +#, no-wrap +msgid "" +"# get the new password, check it, and create a salted hash from it\n" +"def get_password\n" +" pwd1 = Password.get(\"New Password: \")\n" +" pwd2 = Password.get(\"Retype New Password: \")\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:566 +#, no-wrap +msgid "" +" raise if pwd1 != pwd2\n" +" pwd1.check # check password strength\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:572 +#, no-wrap +msgid "" +" salt = rand.to_s.gsub(/0\\./, '')\n" +" pass = pwd1.to_s\n" +" hash = \"{SSHA}\"+Base64.encode64(Digest::SHA1.digest(\"#{pass}#{salt}\")+salt).chomp!\n" +" return hash\n" +"end\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:575 +#, no-wrap +msgid "" +"oldp = Password.get(\"Old Password: \")\n" +"newp = get_password\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:578 +#, no-wrap +msgid "" +"# We'll just replace it. That we can bind proves that we either know\n" +"# the old password or are an admin.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:582 +#, no-wrap +msgid "" +"replace = LDAP::Mod.new(LDAP::LDAP_MOD_REPLACE | LDAP::LDAP_MOD_BVALUES,\n" +" \"userPassword\",\n" +" [newp])\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:587 +#, no-wrap +msgid "" +"conn = LDAP::SSLConn.new(ldap_server, 389, true)\n" +"conn.set_option(LDAP::LDAP_OPT_PROTOCOL_VERSION, 3)\n" +"conn.bind(luser, oldp)\n" +"conn.modify(luser, [replace])\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:592 +msgid "" +"Although not guaranteed to be free of security holes (the password is kept " +"in memory, for example) this is cleaner and more flexible than a simple `sh` " +"script." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ldap-auth/_index.adoc:594 +#, no-wrap +msgid "Security Considerations" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:597 +msgid "" +"Now that your machines (and possibly other services) are authenticating " +"against your LDAP server, this server needs to be protected at least as well " +"as [.filename]#/etc/master.passwd# would be on a regular server, and " +"possibly even more so since a broken or cracked LDAP server would break " +"every client service." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:600 +msgid "" +"Remember, this section is not exhaustive. You should continually review " +"your configuration and procedures for improvements." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/ldap-auth/_index.adoc:602 +#, no-wrap +msgid "Setting Attributes Read-only" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:606 +msgid "" +"Several attributes in LDAP should be read-only. If left writable by the " +"user, for example, a user could change his `uidNumber` attribute to `0` and " +"get `root` access!" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:610 +msgid "" +"To begin with, the `userPassword` attribute should not be world-readable. " +"By default, anyone who can connect to the LDAP server can read this " +"attribute. To disable this, put the following in [.filename]#slapd.conf#:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:612 +#, no-wrap +msgid "Hide Passwords" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:623 +#: documentation/content/en/articles/ldap-auth/_index.adoc:649 +#, no-wrap +msgid "" +"access to dn.subtree=\"ou=people,dc=example,dc=org\"\n" +" attrs=userPassword\n" +" by self write\n" +" by anonymous auth\n" +" by * none\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:627 +#: documentation/content/en/articles/ldap-auth/_index.adoc:656 +#, no-wrap +msgid "" +"access to *\n" +" by self write\n" +" by * read\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:632 +msgid "" +"This will disallow reading of the `userPassword` attribute, while still " +"allowing users to change their own passwords." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:636 +msgid "" +"Additionally, you'll want to keep users from changing some of their own " +"attributes. By default, users can change any attribute (except for those " +"which the LDAP schemas themselves deny changes), such as `uidNumber`. To " +"close this hole, modify the above to" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:638 +#, no-wrap +msgid "Read-only Attributes" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:652 +#, no-wrap +msgid "" +"access to attrs=homeDirectory,uidNumber,gidNumber\n" +" by * read\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:661 +msgid "This will stop users from being able to masquerade as other users." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/ldap-auth/_index.adoc:663 +#, no-wrap +msgid "`root` Account Definition" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:668 +msgid "" +"Often the `root` or manager account for the LDAP service will be defined in " +"the configuration file. OpenLDAP supports this, for example, and it works, " +"but it can lead to trouble if [.filename]#slapd.conf# is compromised. It " +"may be better to use this only to bootstrap yourself into LDAP, and then " +"define a `root` account there." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:672 +msgid "" +"Even better is to define accounts that have limited permissions, and omit a " +"`root` account entirely. For example, users that can add or remove user " +"accounts are added to one group, but they cannot themselves change the " +"membership of this group. Such a security policy would help mitigate the " +"effects of a leaked password." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:674 +#: documentation/content/en/articles/ldap-auth/_index.adoc:680 +#, no-wrap +msgid "Creating a Management Group" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:678 +msgid "" +"Say you want your IT department to be able to change home directories for " +"users, but you do not want all of them to be able to add or remove users. " +"The way to do this is to add a group for these admins:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:693 +#, no-wrap +msgid "" +"dn: cn=homemanagement,dc=example,dc=org\n" +"objectClass: top\n" +"objectClass: posixGroup\n" +"cn: homemanagement\n" +"gidNumber: 121 # required for posixGroup\n" +"memberUid: uid=tuser,ou=people,dc=example,dc=org\n" +"memberUid: uid=user2,ou=people,dc=example,dc=org\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:698 +msgid "And then change the permissions attributes in [.filename]#slapd.conf#:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:700 +#, no-wrap +msgid "ACLs for a Home Directory Management Group" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:710 +#, no-wrap +msgid "" +"access to dn.subtree=\"ou=people,dc=example,dc=org\"\n" +" attr=homeDirectory\n" +" by dn=\"cn=homemanagement,dc=example,dc=org\"\n" +" dnattr=memberUid write\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:715 +msgid "Now `tuser` and `user2` can change other users' home directories." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:719 +msgid "" +"In this example we have given a subset of administrative power to certain " +"users without giving them power in other domains. The idea is that soon no " +"single user account has the power of a `root` account, but every power root " +"had is had by at least one user. The `root` account then becomes " +"unnecessary and can be removed." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/ldap-auth/_index.adoc:721 +#, no-wrap +msgid "Password Storage" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:725 +msgid "" +"By default OpenLDAP will store the value of the `userPassword` attribute as " +"it stores any other data: in the clear. Most of the time it is base 64 " +"encoded, which provides enough protection to keep an honest administrator " +"from knowing your password, but little else." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:728 +msgid "" +"It is a good idea, then, to store passwords in a more secure format, such as " +"SSHA (salted SHA). This is done by whatever program you use to change " +"users' passwords." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ldap-auth/_index.adoc:733 +#, no-wrap +msgid "Useful Aids" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:736 +msgid "" +"There are a few other programs that might be useful, particularly if you " +"have many users and do not want to configure everything manually." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:739 +msgid "" +"package:security/pam_mkhomedir[] is a PAM module that always succeeds; its " +"purpose is to create home directories for users which do not have them. If " +"you have dozens of client servers and hundreds of users, it is much easier " +"to use this and set up skeleton directories than to prepare every home " +"directory." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:743 +msgid "" +"package:sysutils/ldapvi[] is a great utility for editing LDAP values in an " +"LDIF-like syntax. The directory (or subsection of the directory) is " +"presented in the editor chosen by the `EDITOR` environment variable. This " +"makes it easy to enable large-scale changes in the directory without having " +"to write a custom tool." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:746 +msgid "" +"package:security/openssh-portable[] has the ability to contact an LDAP " +"server to verify SSH keys. This is extremely nice if you have many servers " +"and do not want to copy your public keys across all of them." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/ldap-auth/_index.adoc:751 +#, no-wrap +msgid "OpenSSL Certificates for LDAP" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:755 +msgid "" +"If you are hosting two or more LDAP servers, you will probably not want to " +"use self-signed certificates, since each client will have to be configured " +"to work with each certificate. While this is possible, it is not nearly as " +"simple as creating your own certificate authority, and signing your servers' " +"certificates with that." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:757 +msgid "" +"The steps here are presented as they are with very little attempt at " +"explaining what is going on-further explanation can be found in man:" +"openssl[1] and its friends." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:760 +msgid "" +"To create a certificate authority, we simply need a self-signed certificate " +"and key. The steps for this again are" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:762 +#, no-wrap +msgid "Creating a Certificate" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:771 +#, no-wrap +msgid "" +"% openssl genrsa -out root.key 1024\n" +"% openssl req -new -key root.key -out root.csr\n" +"% openssl x509 -req -days 1024 -in root.csr -signkey root.key -out root.crt\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:777 +msgid "" +"These will be your root CA key and certificate. You will probably want to " +"encrypt the key and store it in a cool, dry place; anyone with access to it " +"can masquerade as one of your LDAP servers." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:780 +msgid "" +"Next, using the first two steps above create a key [.filename]#ldap-server-" +"one.key# and certificate signing request [.filename]#ldap-server-one.csr#. " +"Once you sign the signing request with [.filename]#root.key#, you will be " +"able to use [.filename]#ldap-server-one.*# on your LDAP servers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/ldap-auth/_index.adoc:784 +msgid "" +"Do not forget to use the fully qualified domain name for the \"common name\" " +"attribute when generating the certificate signing request; otherwise clients " +"will reject a connection with you, and it can be very tricky to diagnose." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:787 +msgid "To sign the key, use `-CA` and `-CAkey` instead of `-signkey`:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/ldap-auth/_index.adoc:789 +#, no-wrap +msgid "Signing as a Certificate Authority" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:798 +#, no-wrap +msgid "" +"% openssl x509 -req -days 1024 \\\n" +"-in ldap-server-one.csr -CA root.crt -CAkey root.key \\\n" +"-out ldap-server-one.crt\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:803 +msgid "" +"The resulting file will be the certificate that you can use on your LDAP " +"servers." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/ldap-auth/_index.adoc:804 +msgid "" +"Finally, for clients to trust all your servers, distribute [.filename]#root." +"crt# (the __certificate__, not the key!) to each client, and specify it in " +"the `TLSCACertificateFile` directive in [.filename]#ldap.conf#." +msgstr "" diff --git a/documentation/content/en/articles/leap-seconds/_index.adoc b/documentation/content/en/articles/leap-seconds/_index.adoc index d28629b005..55a1dfb5fc 100644 --- a/documentation/content/en/articles/leap-seconds/_index.adoc +++ b/documentation/content/en/articles/leap-seconds/_index.adoc @@ -56,7 +56,7 @@ Also see man:time2posix[3]. [[leapseconds-posix]] == Default Leap Second Handling on FreeBSD -The easiest way to handle leap seconds is with the POSIX time rules FreeBSD uses by default, combined with extref:{handbook}[NTP, network-ntp]. +The easiest way to handle leap seconds is with the POSIX time rules FreeBSD uses by default, combined with extref:{handbook}network-servers[NTP, network-ntp]. When man:ntpd[8] is running and the time is synchronized with upstream NTP servers that handle leap seconds correctly, the leap second will cause the system time to automatically repeat the last second of the day. No other adjustments are necessary. diff --git a/documentation/content/en/articles/leap-seconds/_index.po b/documentation/content/en/articles/leap-seconds/_index.po new file mode 100644 index 0000000000..ff08ec6a17 --- /dev/null +++ b/documentation/content/en/articles/leap-seconds/_index.po @@ -0,0 +1,200 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2022-02-01 09:21-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/leap-seconds/_index.adoc:1 +#, no-wrap +msgid "A short description of how leap seconds are handled on FreeBSD" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/leap-seconds/_index.adoc:1 +#: documentation/content/en/articles/leap-seconds/_index.adoc:7 +#, no-wrap +msgid "FreeBSD Support for Leap Seconds" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:39 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/leap-seconds/_index.adoc:43 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:47 +msgid "" +"A _leap second_ is an one second adjustment made at specific times of year " +"to UTC to synchronize atomic time scales with variations in the rotation of " +"the Earth. This article describes how FreeBSD interacts with leap seconds." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:50 +msgid "" +"As of this writing, the next leap second will occur at 2015-Jun-30 23:59:60 " +"UTC. This leap second will occur during a business day for North and South " +"America and the Asia/Pacific region." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:52 +msgid "" +"Leap seconds are announced by https://www.iers.org/IERS/EN/Home/home_node." +"html[IERS] on https://datacenter.iers.org/data/latestVersion/16_BULLETIN_C16." +"txt[Bulletin C]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:55 +msgid "" +"Standard leap second behavior is described in https://datatracker.ietf.org/" +"doc/html/rfc7164#section-3[RFC 7164]. Also see man:time2posix[3]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/leap-seconds/_index.adoc:57 +#, no-wrap +msgid "Default Leap Second Handling on FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:62 +msgid "" +"The easiest way to handle leap seconds is with the POSIX time rules FreeBSD " +"uses by default, combined with extref:{handbook}[NTP, network-ntp]. When " +"man:ntpd[8] is running and the time is synchronized with upstream NTP " +"servers that handle leap seconds correctly, the leap second will cause the " +"system time to automatically repeat the last second of the day. No other " +"adjustments are necessary." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:64 +msgid "" +"If the upstream NTP servers do not handle leap seconds correctly, man:" +"ntpd[8] will step the time by one second after the errant upstream server " +"has noticed and stepped itself." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:66 +msgid "" +"If NTP is not being used, manual adjustment of the system clock will be " +"required after the leap second has passed." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/leap-seconds/_index.adoc:68 +#, no-wrap +msgid "Cautions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:72 +msgid "" +"Leap seconds are inserted at the same instant all over the world: UTC " +"midnight. In Japan that is mid-morning, in the Pacific mid-day, in the " +"Americas late afternoon, and in Europe at night." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:74 +msgid "" +"We believe and expect that FreeBSD, if provided correct and stable NTP " +"service, will work as designed during this leap second, as it did during the " +"previous ones." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:77 +msgid "" +"However, we caution that practically no applications have ever asked the " +"kernel about leap seconds. Our experience is that, as designed, leap " +"seconds are essentially a replay of the second before the leap second, and " +"this is a surprise to most application programmers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:79 +msgid "" +"Other operating systems and other computers may or may not handle the leap-" +"second the same way as FreeBSD, and systems without correct and stable NTP " +"service will not know anything about leap seconds at all." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:81 +msgid "" +"It is not unheard of for computers to crash because of leap seconds, and " +"experience has shown that a large fraction of all public NTP servers might " +"handle and announce the leap second incorrectly." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:83 +msgid "" +"Please try to make sure nothing horrible happens because of the leap second." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/leap-seconds/_index.adoc:85 +#, no-wrap +msgid "Testing" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:91 +msgid "" +"It is possible to test whether a leap second will be used. Due to the " +"nature of NTP, the test might work up to 24 hours before the leap second. " +"Some major reference clock sources only announce leap seconds one hour ahead " +"of the event. Query the NTP daemon:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/leap-seconds/_index.adoc:95 +#, no-wrap +msgid "% ntpq -c 'rv 0 leap'\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:99 +msgid "" +"Output that includes `leap_add_sec` indicates proper support of the leap " +"second. Before the 24 hours leading up to the leap second, or after the " +"leap second has passed, `leap_none` will be shown." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/leap-seconds/_index.adoc:101 +#, no-wrap +msgid "Conclusion" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/leap-seconds/_index.adoc:104 +msgid "" +"In practice, leap seconds are usually not a problem on FreeBSD. We hope " +"that this overview helps clarify what to expect and how to make the leap " +"second event proceed more smoothly." +msgstr "" diff --git a/documentation/content/en/articles/license-guide/_index.adoc b/documentation/content/en/articles/license-guide/_index.adoc new file mode 100644 index 0000000000..de35c94860 --- /dev/null +++ b/documentation/content/en/articles/license-guide/_index.adoc @@ -0,0 +1,351 @@ +--- +title: FreeBSD Licensing Policy +authors: + - author: Warner Losh + email: imp@FreeBSD.org +trademarks: ["freebsd", "general"] +--- + += FreeBSD License Policies +:doctype: article +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:source-highlighter: rouge +:experimental: + +ifdef::env-beastie[] +ifdef::backend-html5[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +:imagesdir: ../../../images/{images-path} +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +''' + +toc::[] + +[[intro]] + +[[pref-license]] +== Preferred License for New Files + +The rest of this section is intended to help you get started. +As a rule, when in doubt, ask. +It is much easier to receive advice than to fix the source tree. +The FreeBSD Project makes use of both explicit licenses (where the verbatim text of the license is reproduced in each file) and detached licenses (where a tag in the file specifies the license, as described in this document). + +The FreeBSD Project uses this text as the preferred license: + +[.programlisting] +.... +/* + * Copyright (c) [year] [your name] + * + * SPDX-License-Identifier: BSD-2-Clause + */ +.... + +The FreeBSD project does not allow using the "advertising clause" in new code. +Due to the large number of contributors to the FreeBSD project, complying with this clause for many commercial vendors has become difficult. +If you have code in the tree with the advertising clause, please consider switching to a license without it. +New contributions to FreeBSD should use the BSD-2-Clause license. + +The FreeBSD project discourages completely new licenses and variations on the standard licenses. +New licenses require the approval of {core-email} to reside in the main repository. +In the past, non-standard licenses have generated more problems than standard ones. +Poor drafting of non-standard licenses often causes more unintended consequences, so they are unlikely to be approved by {core-email}. +The FreeBSD project is standardizing on the BSD-2-Clause license, as published by SPDX. + +In addition, project policy requires that code licensed under some non-BSD licenses must be placed in specific sections of the repository. +For some licenses, compilation must be conditional or disabled by default. +For example, code in the static part of the GENERIC kernel must be licensed under the BSD or substantially similar licenses. +GPL, APSL, CDDL, etc, licensed software must not be compiled into the static GENERIC kernel. +Code with these licenses may be used in pre-compiled modules, however. + +Developers are reminded that, in open source, getting "open" correct is just as important as getting "source" correct. +Improper handling of intellectual property has serious consequences. +Any questions or concerns should immediately be brought to the attention of {core-email}. + +[[license-policy]] +== Software License Policy + +The following sections outline the project's Software License Policies in detail. +For the most part we expect developers to read, understand and utilize the sections above this one to apply appropriate licenses to their contributions. +The rest of this document details the philosophical background to the policies as well as the policies in great detail. +As always, if the text below is confusing or you need help with applying these policies, please reach out to {core-email}. + +=== Guiding Principles + +The FreeBSD Project aims to produce a complete, BSD-licensed operating system allowing consumers of the system to produce derivative products without constraint or further license obligations. +We invite and greatly appreciate the contribution of both changes and additions under the two-clause BSD license, and encourage the adoption of this license by other open source projects. +Use of the BSD license is key to encouraging the adoption of advanced operating system technology, and on many notable occasions has been pivotal to widespread use of new technology. + +We accept however that compelling reasons exist to allow differently-licensed software to be included in the FreeBSD source tree. + +We require software licensed under some non-BSD licenses to be carefully isolated in the source tree so that it cannot contaminate BSD-only components. +Such cautious management encourages licensing clarity and facilitates the production of BSD-only derivative products. + +Unless a special exception is made, no existing BSD-licensed components may be replaced with more restrictively licensed software. +We encourage FreeBSD and third party developers to seek the relicensing, dual-licensing, or reimplementing of critical components under the BSD license instead. +Such would ease their more integral adoption into the FreeBSD operating system. + +=== Policy + +* The import of new software licensed under any licenses other than the BSD license and BSD-Like Licenses (as defined below) requires the prior approval of the FreeBSD Core Team. +Requests for import must include: +** A list of features or bug fixes that the new version or patches contain, along with evidence that our users need those features. +PRs or references to mailing list discussions are ideal forms of evidence. +** This process should be used for all software imports, not just those that require Core Team review. +The mere existence of a new version does not justify an import of software to source or ports. +** A list of FreeBSD branches that may be affected. +Expansions of scope require a new request to and approval from the FreeBSD Core Team. + +* The Apache License 2.0 is acceptable for use in some cases. +The Core Team must approve the import of new Apache License licensed components or the change of license of existing components to the Apache License. +** This license is approved for the following components: +*** LLVM toolchain and (with LLVM Exceptions) runtime components. + +* The BSD+Patent License is acceptable for use in some cases. +The Core Team must approve the import of new BSD+Patent License licensed components or the change of license of existing components to the BSD+Patent License. +** This license is approved for the following components: +*** EDK2 derived code related to UEFI functionality + +* The Common Development and Distribution License (CDDL) is acceptable for use in some cases. +The Core Team must approve the import of new CDDL licensed components or the change of license of existing components to the CDDL. +** This license is approved for the following components: +*** DTrace +*** ZFS filesystem, including kernel support and userland utilities + +* Historically, the phrase 'All Rights Reserved.' was included in all copyright notices. +All the BSD releases had it, to comply with the https://en.wikipedia.org/wiki/Buenos_Aires_Convention[Buenos Aires Convention of 1910] in the Americas. +With the ratification of the https://en.wikipedia.org/wiki/Berne_Convention[Berne Convention] in 2000 by Nicaragua, the Buenos Aires Convention -- and the phrase -- became obsolete. +As such, the FreeBSD project recommends that new code omit the phrase and encourages existing copyright holders to remove it. +In 2018, the project updated its templates to remove it. +* Initially, many items in the FreeBSD tree were marked with BSD-2-Clause-FreeBSD. +However, SPDX has obsoleted the license as a variant; and the SPDX text of the obsolete tag differs enough from the standard FreeBSD license that it shouldn't be used. +A review of its current use is ongoing. + +==== Acceptable licenses + +The following licenses are considered to be acceptable BSD-Like Licenses for the purpose of this Policy. +Deviations or the use of any other license must be approved by the FreeBSD Core Team: + +* The 2 clause version of the BSD license + +[.programlisting] +.... +/* + * Copyright (c) [year] [your name] + * + * SPDX-License-Identifier: BSD-2-Clause + */ +.... +* The 3 clause version of the BSD license + +[.programlisting] +.... +/* + * Copyright (c) [year] [your name] + * + * SPDX-License-Identifier: BSD-3-Clause + */ +.... +* The ISC License + +[.programlisting] +.... +/* + * Copyright (c) [year] [copyright holder] + * + * SPDX-License-Identifier: ISC + */ +.... +* The MIT License + +[.programlisting] +.... +/* + * Copyright (c) [year] [copyright holders] + * + * SPDX-License-Identifier: MIT + */ +.... +== Software Collection License + +The FreeBSD Project licenses its compilation of software as described in [.filename]#COPYRIGHT# under the BSD-2-Clause license. +This license does not supersede the license of individual files, which is described below. +Files that do not have an explicit license are licensed under the BSD-2-Clause license. + +== License File Location + +To comply with the https://reuse.software/[REUSE Software] standard as much as possible, all license files will be stored in the [.filename]#LICENSES/# directory of the repository. +There are three subdirectories under this top level directory. +The [.filename]#LICENSES/text/# subdirectory contains, in detached form, the text of all the licenses that are allowed in the FreeBSD software collection. +These files are stored using the SPDX-License-Identifier name followed by .txt. +The [.filename]#LICENSES/exceptions/# subdirectory has the text of all exceptions that are allowed in detached form in the FreeBSD software collection. +These files are stored using the exception identifier name followed by .txt. +The [.filename]#LICENSES/other/# contains, in detached form, the license files references in SPDX-License-Identifier expressions, but aren't otherwise allowed as detached licenses. +All such files must appear at least once in the FreeBSD software collection, and should be removed when the last file that references them is removed. +Licenses that have no adequate SPDX matching license must be in [.filename]#LICENSES/other/# and have a filename that starts with LicenseRef- followed by a unique idstring. +No such files have currently been identified, but if they are, a full list will appear here. + +The FreeBSD Project currently does not make use of the `DEP5` files described in the `REUSE Software` standard. +The FreeBSD Project has not marked all the files in the tree yet in accordance with this standard, as described later in this document. +The FreeBSD Project has not yet included these files in its repositories since this policy is still evolving. + +[[individual-files]] +== Individual Files License + +Each individual file in the FreeBSD software collection has its own copyright and license. +How they are marked varies and is described in this section. + +A copyright notice identifies who claims the legal copyright to a file. +These are provided on a best effort basis by the project. +Because copyrights may be legally transferred, the current copyright holder may differ from what is listed in the file. + +A license is a legal document between the contributor and the users of the software granting permission to use the copyrighted portions of the software, subject to certain terms and conditions set forth in the license. +Licenses can be expressed in one of two ways in the FreeBSD software collection. +Licenses can be explicit in a file. +When a license grant is explicit in the file, that file may be used, copied, and modified in accordance with that license. +Licenses can also be expressed indirectly, where the text of the license is elsewhere. +The project uses the Software Package Data Exchange (SPDX) license identifiers for this purpose, as described in the following subsections. +SPDX license identifiers are managed by the SPDX Workgroup at the Linux Foundation, and have been agreed on by partners throughout the industry, tool vendors, and legal teams. +For further information see https://spdx.org/ and the following sections for how the FreeBSD Project uses them. + +Entities that contribute fixes and enhancements to the software collection without an explicit license agree to license those changes under the terms that apply to the modified file(s). +Project policy, in line with industry practice, only includes a copyright notice from significant contributors to the files in the collection. + +There are four types of files in the FreeBSD software collection: + +. Files that have only an explicit copyright notice and license. +. Files that have both an explicit copyright notice and license, and a SPDX-License-Identifier tag. +. Files that have only a copyright notice and an SPDX-License-Identifier tag, but no explicit license. +. Files that lack any copyright or license at all. + +=== Only Copyright and License + +Many files in the FreeBSD software collection have both a copyright notice and an explicit license contained in the file. +In these cases, the license contained in the file governs. + +=== Copyright and License with SPDX-License-Identifier expression + +Some files in the FreeBSD software collection contain a copyright statement, an SPDX-License-Identifier tag and an explicit license. +The explicit license takes precedence over the SPDX-License-Identifier tag. +The SPDX-License-Identifier tag is the project's best effort attempt to characterize the license, but is only informative for automated tools. +See crossref:license-guide[expressions,SPDX-License-Identifier Expressions] for how to interpret the expression. + +=== Only Copyright and SPDX-License-Identifier expression. + +Some files in the tree contain detached licenses. +These files contain only a copyright notice and an SPDX-License-Identifier expression, but no explicit license. +See crossref:license-guide[expressions,SPDX-License-Identifier Expressions] for how to interpret the expression. +Note: the expressions allowed for detached licenses by the project are a subset of the expressions used informationally or that are defined by the standard. + +The license for files containing only the SPDX-License-Identifier should be construed to be + +. Start the license with the copyright notice from the file. +Include all the copyright holders. +. For each sub-expression, copy the license text from [.filename]#LICENSE/text/`id`.txt#. +When exceptions are present, append them from [.filename]#src/share/license/exceptions/`id`.txt#. +SPDX-License-Identifier expressions should be construed as described in the SPDX standard. + +Where `id` is the SPDX short license identifier from the `Identifier` column of https://spdx.org/licenses/[SPDX Identifiers] or https://spdx.org/licenses/exceptions-index.html[license exception]. +If there is no file in [.filename]#LICENSE/#, then that license or exception cannot be specified as a detached license under this section. + +When reading the license text that is detached from a file, a number of considerations must be taken to make the detached license make sense. + +. Any reference to a copyright notice shall refer to the copyright notice constructed from the licensed file, not from any copyright notice in the license text file itself. +Many SPDX files have sample copyright notices that are understood to be examples only. +. When names of entities are referred to in the license text, they shall be construed to apply to the list of all copyright holders listed in the copyright notices of the licensed file. +For example, the BSD-4-clause license contains the phrase "This product includes software developed by the organization". +The phrase 'the organization' should be replaced by the copyright holders. +. When the SPDX offers variations of the license, it is understood the license in the [.filename]#LICENSE/# file represents the exact version of the license selected. +The SPDX standard exists to match families of licenses and these variations help match similar licenses that the SPDX organization believes to be legally identical. + +For licenses that have slight variations in text, the SPDX has guidelines to match them. +These guidelines are not relevant here. +Contributors wishing to license under a variant of a SPDX license not contained verbatim in [.filename]#LICENSE/# cannot use the detached option and must specify the license explicitly. + +=== Files without Copyright or any License Marking + +Some files cannot have suitable comments added to them. +In such cases, a license may be found in [.filename]#file.ext.license#. +For example, a file named [.filename]#foo.jpg# may have a license in [.filename]#foo.jpg.license#, following the REUSE Software conventions. + +Files created by the project that lack a copyright notice are understood to fall under the blanket copyright and licensing in [.filename]#COPYRIGHT#. +Either the file is a mere recitation of facts, not protectable by Copyright Law, or the content is so trivial as to not warrant the overhead of an explicit license. + +Files that lack marking and have more than a trivial amount of copyrightable material, or whose author believes them to be improperly marked, should be brought to the attention of the FreeBSD core team. +It is the strong policy of the FreeBSD Project to comply with all appropriate licenses. + +In the future, all such files will be marked explicitly, or follow the REUSE Software [.filename]#.license# convention. + +[[expressions]] +=== SPDX-License-Identifier Expressions + +An 'SPDX License expression' is used in two contexts in the FreeBSD software collection. +First, its full form is used for files that have explicit license statements contained within the file as well as a summarizing SPDX-License-Identifier expression. +In this context, the full power of these expressions may be used. +Second, in a restricted form described above, it is used to denote the actual license for a given file. +In the second context, only a subset of this expression is allowed by the project. + +An `SPDX License sub-expression` is either an SPDX short form license identifier from the https://spdx.org/licenses/[SPDX License List], or the combination of two SPDX short form license identifiers separated by "WITH" when a https://spdx.org/licenses/exceptions-index.html[license exception] applies. +When multiple licenses apply, an expression consists of keywords "AND", "OR" separating sub-expressions and surrounded by "(", ")" . +The https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/[full specification of expressions] spells out all the details and takes precedence when it conflicts with the simplified treatment of this section. + +Some license identifiers, like [L]GPL, have the option to use only that version, or any later version. +SPDX defines the suffix `-or-later` to mean that version of the license or a later version. +It defines `-only` to mean only that specific version of the file. +There is an old convention to have no suffix (which means what the new '-only' suffix means, but which people confuse for `-or-later`). +In addition, affixing a `+` suffix was meant to mean `-or-later`. +New files in FreeBSD should not use these two conventions. +Old files that use this convention should be converted as appropriate. + +[.programlisting] +.... + // SPDX-License-Identifier: GPL-2.0-only + // SPDX-License-Identifier: LGPL-2.1-or-later +.... + +`WITH` should be used when a license modifier is needed. +In the FreeBSD project, a number of files from LLVM have an exception to the Apache 2.0 license: + +[.programlisting] +.... + // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +.... + +https://spdx.org/licenses/exceptions-index.html[Exception tags] are managed by SPDX. +License exceptions can only be applied to certain licenses, as specified in the exception. + +`OR` should be used if the file has a choice of license and one license is selected. +For example, some dtsi files are available under dual licenses: + +[.programlisting] +.... + // SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause +.... + +`AND` should be used if the file has multiple licenses whose terms all apply to use the file. +For example, if code has been incorporated by several projects, each with their own license: + +[.programlisting] +.... + // SPDX-License-Identifier: BSD-2-Clause AND MIT +.... diff --git a/documentation/content/en/articles/license-guide/_index.po b/documentation/content/en/articles/license-guide/_index.po new file mode 100644 index 0000000000..c7dc8447e2 --- /dev/null +++ b/documentation/content/en/articles/license-guide/_index.po @@ -0,0 +1,762 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-05-01 19:56-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: title +#: documentation/content/en/articles/license-guide/_index.adoc:1 +#, no-wrap +msgid "FreeBSD Licensing Policy" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/license-guide/_index.adoc:9 +#, no-wrap +msgid "FreeBSD License Policies" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:40 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/license-guide/_index.adoc:46 +#, no-wrap +msgid "Preferred License for New Files" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:52 +msgid "" +"The rest of this section is intended to help you get started. As a rule, " +"when in doubt, ask. It is much easier to receive advice than to fix the " +"source tree. The FreeBSD Project makes use of both explicit licenses (where " +"the verbatim text of the license is reproduced in each file) and detached " +"licenses (where a tag in the file specifies the license, as described in " +"this document)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:54 +msgid "The FreeBSD Project uses this text as the preferred license:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/license-guide/_index.adoc:62 +#: documentation/content/en/articles/license-guide/_index.adoc:158 +#, no-wrap +msgid "" +"/*\n" +" * Copyright (c) [year] [your name]\n" +" *\n" +" * SPDX-License-Identifier: BSD-2-Clause\n" +" */\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:68 +msgid "" +"The FreeBSD project does not allow using the \"advertising clause\" in new " +"code. Due to the large number of contributors to the FreeBSD project, " +"complying with this clause for many commercial vendors has become " +"difficult. If you have code in the tree with the advertising clause, please " +"consider switching to a license without it. New contributions to FreeBSD " +"should use the BSD-2-Clause license." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:74 +msgid "" +"The FreeBSD project discourages completely new licenses and variations on " +"the standard licenses. New licenses require the approval of {core-email} to " +"reside in the main repository. In the past, non-standard licenses have " +"generated more problems than standard ones. Poor drafting of non-standard " +"licenses often causes more unintended consequences, so they are unlikely to " +"be approved by {core-email}. The FreeBSD project is standardizing on the " +"BSD-2-Clause license, as published by SPDX." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:80 +msgid "" +"In addition, project policy requires that code licensed under some non-BSD " +"licenses must be placed in specific sections of the repository. For some " +"licenses, compilation must be conditional or disabled by default. For " +"example, code in the static part of the GENERIC kernel must be licensed " +"under the BSD or substantially similar licenses. GPL, APSL, CDDL, etc, " +"licensed software must not be compiled into the static GENERIC kernel. Code " +"with these licenses may be used in pre-compiled modules, however." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:84 +msgid "" +"Developers are reminded that, in open source, getting \"open\" correct is " +"just as important as getting \"source\" correct. Improper handling of " +"intellectual property has serious consequences. Any questions or concerns " +"should immediately be brought to the attention of {core-email}." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/license-guide/_index.adoc:86 +#, no-wrap +msgid "Software License Policy" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:92 +msgid "" +"The following sections outline the project's Software License Policies in " +"detail. For the most part we expect developers to read, understand and " +"utilize the sections above this one to apply appropriate licenses to their " +"contributions. The rest of this document details the philosophical " +"background to the policies as well as the policies in great detail. As " +"always, if the text below is confusing or you need help with applying these " +"policies, please reach out to {core-email}." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/license-guide/_index.adoc:93 +#, no-wrap +msgid "Guiding Principles" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:98 +msgid "" +"The FreeBSD Project aims to produce a complete, BSD-licensed operating " +"system allowing consumers of the system to produce derivative products " +"without constraint or further license obligations. We invite and greatly " +"appreciate the contribution of both changes and additions under the two-" +"clause BSD license, and encourage the adoption of this license by other open " +"source projects. Use of the BSD license is key to encouraging the adoption " +"of advanced operating system technology, and on many notable occasions has " +"been pivotal to widespread use of new technology." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:100 +msgid "" +"We accept however that compelling reasons exist to allow differently-" +"licensed software to be included in the FreeBSD source tree." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:103 +msgid "" +"We require software licensed under some non-BSD licenses to be carefully " +"isolated in the source tree so that it cannot contaminate BSD-only " +"components. Such cautious management encourages licensing clarity and " +"facilitates the production of BSD-only derivative products." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:107 +msgid "" +"Unless a special exception is made, no existing BSD-licensed components may " +"be replaced with more restrictively licensed software. We encourage FreeBSD " +"and third party developers to seek the relicensing, dual-licensing, or " +"reimplementing of critical components under the BSD license instead. Such " +"would ease their more integral adoption into the FreeBSD operating system." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/license-guide/_index.adoc:108 +#, no-wrap +msgid "Policy" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:112 +msgid "" +"The import of new software licensed under any licenses other than the BSD " +"license and BSD-Like Licenses (as defined below) requires the prior approval " +"of the FreeBSD Core Team. Requests for import must include:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:114 +msgid "" +"A list of features or bug fixes that the new version or patches contain, " +"along with evidence that our users need those features. PRs or references " +"to mailing list discussions are ideal forms of evidence." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:116 +msgid "" +"This process should be used for all software imports, not just those that " +"require Core Team review. The mere existence of a new version does not " +"justify an import of software to source or ports." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:118 +msgid "" +"A list of FreeBSD branches that may be affected. Expansions of scope " +"require a new request to and approval from the FreeBSD Core Team." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:121 +msgid "" +"The Apache License 2.0 is acceptable for use in some cases. The Core Team " +"must approve the import of new Apache License licensed components or the " +"change of license of existing components to the Apache License." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:122 +#: documentation/content/en/articles/license-guide/_index.adoc:127 +#: documentation/content/en/articles/license-guide/_index.adoc:132 +msgid "This license is approved for the following components:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:123 +msgid "LLVM toolchain and (with LLVM Exceptions) runtime components." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:126 +msgid "" +"The BSD+Patent License is acceptable for use in some cases. The Core Team " +"must approve the import of new BSD+Patent License licensed components or the " +"change of license of existing components to the BSD+Patent License." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:128 +msgid "EDK2 derived code related to UEFI functionality" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:131 +msgid "" +"The Common Development and Distribution License (CDDL) is acceptable for use " +"in some cases. The Core Team must approve the import of new CDDL licensed " +"components or the change of license of existing components to the CDDL." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:133 +msgid "DTrace" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:134 +msgid "ZFS filesystem, including kernel support and userland utilities" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:140 +msgid "" +"Historically, the phrase 'All Rights Reserved.' was included in all " +"copyright notices. All the BSD releases had it, to comply with the https://" +"en.wikipedia.org/wiki/Buenos_Aires_Convention[Buenos Aires Convention of " +"1910] in the Americas. With the ratification of the https://" +"en.wikipedia.org/wiki/Berne_Convention[Berne Convention] in 2000 by " +"Nicaragua, the Buenos Aires Convention -- and the phrase -- became " +"obsolete. As such, the FreeBSD project recommends that new code omit the " +"phrase and encourages existing copyright holders to remove it. In 2018, the " +"project updated its templates to remove it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:143 +msgid "" +"Initially, many items in the FreeBSD tree were marked with BSD-2-Clause-" +"FreeBSD. However, SPDX has obsoleted the license as a variant; and the SPDX " +"text of the obsolete tag differs enough from the standard FreeBSD license " +"that it shouldn't be used. A review of its current use is ongoing." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/license-guide/_index.adoc:144 +#, no-wrap +msgid "Acceptable licenses" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:148 +msgid "" +"The following licenses are considered to be acceptable BSD-Like Licenses for " +"the purpose of this Policy. Deviations or the use of any other license must " +"be approved by the FreeBSD Core Team:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:150 +msgid "The 2 clause version of the BSD license" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:160 +msgid "The 3 clause version of the BSD license" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/license-guide/_index.adoc:168 +#, no-wrap +msgid "" +"/*\n" +" * Copyright (c) [year] [your name]\n" +" *\n" +" * SPDX-License-Identifier: BSD-3-Clause\n" +" */\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:170 +msgid "The ISC License" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/license-guide/_index.adoc:178 +#, no-wrap +msgid "" +"/*\n" +" * Copyright (c) [year] [copyright holder]\n" +" *\n" +" * SPDX-License-Identifier: ISC\n" +" */\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:180 +msgid "The MIT License" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/license-guide/_index.adoc:188 +#, no-wrap +msgid "" +"/*\n" +" * Copyright (c) [year] [copyright holders]\n" +" *\n" +" * SPDX-License-Identifier: MIT\n" +" */\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/license-guide/_index.adoc:189 +#, no-wrap +msgid "Software Collection License" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:194 +msgid "" +"The FreeBSD Project licenses its compilation of software as described in " +"[.filename]#COPYRIGHT# under the BSD-2-Clause license. This license does " +"not supersede the license of individual files, which is described below. " +"Files that do not have an explicit license are licensed under the BSD-2-" +"Clause license." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/license-guide/_index.adoc:195 +#, no-wrap +msgid "License File Location" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:207 +msgid "" +"To comply with the https://reuse.software/[REUSE Software] standard as much " +"as possible, all license files will be stored in the [.filename]#LICENSES/# " +"directory of the repository. There are three subdirectories under this top " +"level directory. The [.filename]#LICENSES/text/# subdirectory contains, in " +"detached form, the text of all the licenses that are allowed in the FreeBSD " +"software collection. These files are stored using the SPDX-License-" +"Identifier name followed by .txt. The [.filename]#LICENSES/exceptions/# " +"subdirectory has the text of all exceptions that are allowed in detached " +"form in the FreeBSD software collection. These files are stored using the " +"exception identifier name followed by .txt. The [.filename]#LICENSES/other/" +"# contains, in detached form, the license files references in SPDX-License-" +"Identifier expressions, but aren't otherwise allowed as detached licenses. " +"All such files must appear at least once in the FreeBSD software collection, " +"and should be removed when the last file that references them is removed. " +"Licenses that have no adequate SPDX matching license must be in " +"[.filename]#LICENSES/other/# and have a filename that starts with " +"LicenseRef- followed by a unique idstring. No such files have currently " +"been identified, but if they are, a full list will appear here." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:211 +msgid "" +"The FreeBSD Project currently does not make use of the `DEP5` files " +"described in the `REUSE Software` standard. The FreeBSD Project has not " +"marked all the files in the tree yet in accordance with this standard, as " +"described later in this document. The FreeBSD Project has not yet included " +"these files in its repositories since this policy is still evolving." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/license-guide/_index.adoc:213 +#, no-wrap +msgid "Individual Files License" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:217 +msgid "" +"Each individual file in the FreeBSD software collection has its own " +"copyright and license. How they are marked varies and is described in this " +"section." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:221 +msgid "" +"A copyright notice identifies who claims the legal copyright to a file. " +"These are provided on a best effort basis by the project. Because " +"copyrights may be legally transferred, the current copyright holder may " +"differ from what is listed in the file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:230 +msgid "" +"A license is a legal document between the contributor and the users of the " +"software granting permission to use the copyrighted portions of the " +"software, subject to certain terms and conditions set forth in the license. " +"Licenses can be expressed in one of two ways in the FreeBSD software " +"collection. Licenses can be explicit in a file. When a license grant is " +"explicit in the file, that file may be used, copied, and modified in " +"accordance with that license. Licenses can also be expressed indirectly, " +"where the text of the license is elsewhere. The project uses the Software " +"Package Data Exchange (SPDX) license identifiers for this purpose, as " +"described in the following subsections. SPDX license identifiers are " +"managed by the SPDX Workgroup at the Linux Foundation, and have been agreed " +"on by partners throughout the industry, tool vendors, and legal teams. For " +"further information see https://spdx.org/ and the following sections for how " +"the FreeBSD Project uses them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:233 +msgid "" +"Entities that contribute fixes and enhancements to the software collection " +"without an explicit license agree to license those changes under the terms " +"that apply to the modified file(s). Project policy, in line with industry " +"practice, only includes a copyright notice from significant contributors to " +"the files in the collection." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:235 +msgid "There are four types of files in the FreeBSD software collection:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:237 +msgid "Files that have only an explicit copyright notice and license." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:238 +msgid "" +"Files that have both an explicit copyright notice and license, and a SPDX-" +"License-Identifier tag." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:239 +msgid "" +"Files that have only a copyright notice and an SPDX-License-Identifier tag, " +"but no explicit license." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:240 +msgid "Files that lack any copyright or license at all." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/license-guide/_index.adoc:241 +#, no-wrap +msgid "Only Copyright and License" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:245 +msgid "" +"Many files in the FreeBSD software collection have both a copyright notice " +"and an explicit license contained in the file. In these cases, the license " +"contained in the file governs." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/license-guide/_index.adoc:246 +#, no-wrap +msgid "Copyright and License with SPDX-License-Identifier expression" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:252 +msgid "" +"Some files in the FreeBSD software collection contain a copyright statement, " +"an SPDX-License-Identifier tag and an explicit license. The explicit " +"license takes precedence over the SPDX-License-Identifier tag. The SPDX-" +"License-Identifier tag is the project's best effort attempt to characterize " +"the license, but is only informative for automated tools. See " +"crossref:license-guide[expressions,SPDX-License-Identifier Expressions] for " +"how to interpret the expression." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/license-guide/_index.adoc:253 +#, no-wrap +msgid "Only Copyright and SPDX-License-Identifier expression." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:259 +msgid "" +"Some files in the tree contain detached licenses. These files contain only " +"a copyright notice and an SPDX-License-Identifier expression, but no " +"explicit license. See crossref:license-guide[expressions,SPDX-License-" +"Identifier Expressions] for how to interpret the expression. Note: the " +"expressions allowed for detached licenses by the project are a subset of the " +"expressions used informationally or that are defined by the standard." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:261 +msgid "" +"The license for files containing only the SPDX-License-Identifier should be " +"construed to be" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:264 +msgid "" +"Start the license with the copyright notice from the file. Include all the " +"copyright holders." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:267 +msgid "" +"For each sub-expression, copy the license text from [.filename]#LICENSE/text/" +"`id`.txt#. When exceptions are present, append them from [.filename]#src/" +"share/license/exceptions/`id`.txt#. SPDX-License-Identifier expressions " +"should be construed as described in the SPDX standard." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:270 +msgid "" +"Where `id` is the SPDX short license identifier from the `Identifier` column " +"of https://spdx.org/licenses/[SPDX Identifiers] or https://spdx.org/licenses/" +"exceptions-index.html[license exception]. If there is no file in " +"[.filename]#LICENSE/#, then that license or exception cannot be specified as " +"a detached license under this section." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:272 +msgid "" +"When reading the license text that is detached from a file, a number of " +"considerations must be taken to make the detached license make sense." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:275 +msgid "" +"Any reference to a copyright notice shall refer to the copyright notice " +"constructed from the licensed file, not from any copyright notice in the " +"license text file itself. Many SPDX files have sample copyright notices " +"that are understood to be examples only." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:278 +msgid "" +"When names of entities are referred to in the license text, they shall be " +"construed to apply to the list of all copyright holders listed in the " +"copyright notices of the licensed file. For example, the BSD-4-clause " +"license contains the phrase \"This product includes software developed by " +"the organization\". The phrase 'the organization' should be replaced by the " +"copyright holders." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:280 +msgid "" +"When the SPDX offers variations of the license, it is understood the license " +"in the [.filename]#LICENSE/# file represents the exact version of the " +"license selected. The SPDX standard exists to match families of licenses " +"and these variations help match similar licenses that the SPDX organization " +"believes to be legally identical." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:284 +msgid "" +"For licenses that have slight variations in text, the SPDX has guidelines to " +"match them. These guidelines are not relevant here. Contributors wishing " +"to license under a variant of a SPDX license not contained verbatim in " +"[.filename]#LICENSE/# cannot use the detached option and must specify the " +"license explicitly." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/license-guide/_index.adoc:285 +#, no-wrap +msgid "Files without Copyright or any License Marking" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:290 +msgid "" +"Some files cannot have suitable comments added to them. In such cases, a " +"license may be found in [.filename]#file.ext.license#. For example, a file " +"named [.filename]#foo.jpg# may have a license in " +"[.filename]#foo.jpg.license#, following the REUSE Software conventions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:293 +msgid "" +"Files created by the project that lack a copyright notice are understood to " +"fall under the blanket copyright and licensing in [.filename]#COPYRIGHT#. " +"Either the file is a mere recitation of facts, not protectable by Copyright " +"Law, or the content is so trivial as to not warrant the overhead of an " +"explicit license." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:296 +msgid "" +"Files that lack marking and have more than a trivial amount of copyrightable " +"material, or whose author believes them to be improperly marked, should be " +"brought to the attention of the FreeBSD core team. It is the strong policy " +"of the FreeBSD Project to comply with all appropriate licenses." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:298 +msgid "" +"In the future, all such files will be marked explicitly, or follow the REUSE " +"Software [.filename]#.license# convention." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/license-guide/_index.adoc:300 +#, no-wrap +msgid "SPDX-License-Identifier Expressions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:307 +msgid "" +"An 'SPDX License expression' is used in two contexts in the FreeBSD software " +"collection. First, its full form is used for files that have explicit " +"license statements contained within the file as well as a summarizing SPDX-" +"License-Identifier expression. In this context, the full power of these " +"expressions may be used. Second, in a restricted form described above, it " +"is used to denote the actual license for a given file. In the second " +"context, only a subset of this expression is allowed by the project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:311 +msgid "" +"An `SPDX License sub-expression` is either an SPDX short form license " +"identifier from the https://spdx.org/licenses/[SPDX License List], or the " +"combination of two SPDX short form license identifiers separated by \"WITH\" " +"when a https://spdx.org/licenses/exceptions-index.html[license exception] " +"applies. When multiple licenses apply, an expression consists of keywords " +"\"AND\", \"OR\" separating sub-expressions and surrounded by \"(\", \")\" . " +"The https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/" +"[full specification of expressions] spells out all the details and takes " +"precedence when it conflicts with the simplified treatment of this section." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:319 +msgid "" +"Some license identifiers, like [L]GPL, have the option to use only that " +"version, or any later version. SPDX defines the suffix `-or-later` to mean " +"that version of the license or a later version. It defines `-only` to mean " +"only that specific version of the file. There is an old convention to have " +"no suffix (which means what the new '-only' suffix means, but which people " +"confuse for `-or-later`). In addition, affixing a `+` suffix was meant to " +"mean `-or-later`. New files in FreeBSD should not use these two " +"conventions. Old files that use this convention should be converted as " +"appropriate." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/license-guide/_index.adoc:324 +#, no-wrap +msgid "" +" // SPDX-License-Identifier: GPL-2.0-only\n" +" // SPDX-License-Identifier: LGPL-2.1-or-later\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:328 +msgid "" +"`WITH` should be used when a license modifier is needed. In the FreeBSD " +"project, a number of files from LLVM have an exception to the Apache 2.0 " +"license:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/license-guide/_index.adoc:332 +#, no-wrap +msgid " // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:336 +msgid "" +"https://spdx.org/licenses/exceptions-index.html[Exception tags] are managed " +"by SPDX. License exceptions can only be applied to certain licenses, as " +"specified in the exception." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:339 +msgid "" +"`OR` should be used if the file has a choice of license and one license is " +"selected. For example, some dtsi files are available under dual licenses:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/license-guide/_index.adoc:343 +#, no-wrap +msgid " // SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/license-guide/_index.adoc:347 +msgid "" +"`AND` should be used if the file has multiple licenses whose terms all apply " +"to use the file. For example, if code has been incorporated by several " +"projects, each with their own license:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/license-guide/_index.adoc:351 +#, no-wrap +msgid " // SPDX-License-Identifier: BSD-2-Clause AND MIT\n" +msgstr "" diff --git a/documentation/content/en/articles/linux-emulation/_index.adoc b/documentation/content/en/articles/linux-emulation/_index.adoc index b695d7bc81..f225c23fe4 100644 --- a/documentation/content/en/articles/linux-emulation/_index.adoc +++ b/documentation/content/en/articles/linux-emulation/_index.adoc @@ -61,7 +61,7 @@ toc::[] In the last few years the open source UNIX(R) based operating systems started to be widely deployed on server and client machines. Among these operating systems I would like to point out two: FreeBSD, for its BSD heritage, time proven code base and many interesting features and Linux(R) for its wide user base, enthusiastic open developer community and support from large companies. -FreeBSD tends to be used on server class machines serving heavy duty networking tasks with less usage on desktop class machines for ordinary users. +FreeBSD tends to be used on server class machines serving heavy duty networking tasks with less usage on desktop class machines for ordinary users. While Linux(R) has the same usage on servers, but it is used much more by home based users. This leads to a situation where there are many binary only programs available for Linux(R) that lack support for FreeBSD. @@ -109,7 +109,7 @@ Common UNIX(R) API defines a syscall as a way to issue commands from a user spac The most common implementation is either by using an interrupt or specialized instruction (think of `SYSENTER`/`SYSCALL` instructions for ia32). Syscalls are defined by a number. For example in FreeBSD, the syscall number 85 is the man:swapon[2] syscall and the syscall number 132 is man:mkfifo[2]. -Some syscalls need parameters, which are passed from the user-space to the kernel-space in various ways (implementation dependant). +Some syscalls need parameters, which are passed from the user-space to the kernel-space in various ways (implementation dependent). Syscalls are synchronous. Another possible way to communicate is by using a _trap_. @@ -219,7 +219,7 @@ The parameters to the actual syscall handler are passed in the form of `struct t Handling of traps in FreeBSD is similar to the handling of syscalls. Whenever a trap occurs, an assembler handler is called. It is chosen between alltraps, alltraps with regs pushed or calltrap depending on the type of the trap. -This handler prepares arguments for a call to a C function `trap()` (defined in [.filename]#sys/i386/i386/trap.c#), which then processes the occurred trap. +This handler prepares arguments for a call to a C function `trap()` (defined in [.filename]#sys/i386/i386/trap.c#), which then processes the occurred trap. After the processing it might send a signal to the process and/or exit to userland using `userret()`. [[freebsd-exits]] @@ -510,14 +510,14 @@ numbers are not casual Spin locks let waiters to spin until they cannot acquire the lock. An important matter do deal with is when a thread contests on a spin lock if it is not descheduled. -Since the FreeBSD kernel is preemptive, this exposes spin lock at the risk of deadlocks that can be solved just disabling interrupts while they are acquired. +Since the FreeBSD kernel is preemptive, this exposes spin lock at the risk of deadlocks that can be solved just disabling interrupts while they are acquired. For this and other reasons (like lack of priority propagation support, poorness in load balancing schemes between CPUs, etc.), spin locks are intended to protect very small paths of code, or ideally not to be used at all if not explicitly requested (explained later). [[freebsd-blocking]] ===== Blocking Block locks let waiters to be descheduled and blocked until the lock owner does not drop it and wakes up one or more contenders. -In order to avoid starvation issues, blocking locks do priority propagation from the waiters to the owner. +To avoid starvation issues, blocking locks do priority propagation from the waiters to the owner. Block locks must be implemented through the turnstile interface and are intended to be the most used kind of locks in the kernel, if no particular conditions are met. [[freebsd-sleeping]] @@ -548,7 +548,7 @@ Among these locks only mutexes, sxlocks, rwlocks and lockmgrs are intended to ha [[freebsd-scheduling]] ===== Scheduling barriers -Scheduling barriers are intended to be used in order to drive scheduling of threading. +Scheduling barriers are intended to be used to drive scheduling of threading. They consist mainly of three different stubs: * critical sections (and preemption) @@ -561,11 +561,11 @@ Generally, these should be used only in a particular context and even if they ca ===== Critical sections The FreeBSD kernel has been made preemptive basically to deal with interrupt threads. -In fact, in order to avoid high interrupt latency, time-sharing priority threads can be preempted by interrupt threads (in this way, they do not need to wait to be scheduled as the normal path previews). +In fact, to avoid high interrupt latency, time-sharing priority threads can be preempted by interrupt threads (in this way, they do not need to wait to be scheduled as the normal path previews). Preemption, however, introduces new racing points that need to be handled, as well. -Often, in order to deal with preemption, the simplest thing to do is to completely disable it. +Often, to deal with preemption, the simplest thing to do is to completely disable it. A critical section defines a piece of code (borderlined by the pair of functions man:critical_enter[9] and man:critical_exit[9], where preemption is guaranteed to not happen (until the protected code is fully executed). -This can often replace a lock effectively but should be used carefully in order to not lose the whole advantage that preemption brings. +This can often replace a lock effectively but should be used carefully to not lose the whole advantage that preemption brings. [[freebsd-schedpin]] ===== sched_pin/sched_unpin @@ -578,7 +578,7 @@ The latter condition will determine a critical section as a too strong condition [[freebsd-schedbind]] ===== sched_bind/sched_unbind -`sched_bind` is an API used in order to bind a thread to a particular CPU for all the time it executes the code, until a `sched_unbind` function call does not unbind it. +`sched_bind` is an API used to bind a thread to a particular CPU for all the time it executes the code, until a `sched_unbind` function call does not unbind it. This feature has a key role in situations where you cannot trust the current state of CPUs (for example, at very early stages of boot), as you want to avoid your thread to migrate on inactive CPUs. Since `sched_bind` and `sched_unbind` manipulate internal scheduler structures, they need to be enclosed in `sched_lock` acquisition/releasing when used. @@ -741,7 +741,7 @@ On the other hand `close` is just an alias for real FreeBSD man:close[2] so it h The Linux(R) emulation layer is not complete, as some syscalls are not implemented properly and some are not implemented at all. The emulation layer employs a facility to mark unimplemented syscalls with the `DUMMY` macro. These dummy definitions reside in [.filename]#linux_dummy.c# in a form of `DUMMY(syscall);`, which is then translated to various syscall auxiliary files and the implementation consists of printing a message saying that this syscall is not implemented. -The `UNIMPL` prototype is not used because we want to be able to identify the name of the syscall that was called in order to know what syscalls are more important to implement. +The `UNIMPL` prototype is not used because we want to be able to identify the name of the syscall that was called to know what syscalls are more important to implement. [[signal-handling]] === Signal handling @@ -775,7 +775,7 @@ It also unmasks the signal in process signal mask. [[ptrace]] === Ptrace -Many UNIX(R) derivates implement the man:ptrace[2] syscall in order to allow various tracking and debugging features. +Many UNIX(R) derivates implement the man:ptrace[2] syscall to allow various tracking and debugging features. This facility enables the tracing process to obtain various information about the traced process, like register dumps, any memory from the process address space, etc. and also to trace the process like in stepping an instruction or between system entries (syscalls and traps). man:ptrace[2] also lets you set various information in the traced process (registers etc.). man:ptrace[2] is a UNIX(R)-wide standard implemented in most UNIX(R)es around the world. @@ -793,7 +793,7 @@ Also `PT_SYSCALL` is not implemented. [[traps]] === Traps -Whenever a Linux(R) process running in the emulation layer traps the trap itself is handled transparently with the only exception of the trap translation. +Whenever a Linux(R) process running in the emulation layer traps the trap itself is handled transparently with the only exception of the trap translation. Linux(R) and FreeBSD differs in opinion on what a trap is so this is dealt with here. The code is actually very short: @@ -851,7 +851,7 @@ Then we talk briefly about some syscalls. One of the major areas of progress in development of Linux(R) 2.6 was threading. Prior to 2.6, the Linux(R) threading support was implemented in the linuxthreads library. The library was a partial implementation of POSIX(R) threading. -The threading was implemented using separate processes for each thread using the `clone` syscall to let them share the address space (and other things). +The threading was implemented using separate processes for each thread using the `clone` syscall to let them share the address space (and other things). The main weaknesses of this approach was that every thread had a different PID, signal handling was broken (from the pthreads perspective), etc. Also the performance was not very good (use of `SIGUSR` signals for threads synchronization, kernel resource consumption, etc.) so to overcome these problems a new threading system was developed and named NPTL. @@ -954,7 +954,7 @@ More about locking later. [[pid-mangling]] ==== PID mangling -As there is a difference in view as what to the idea of a process ID and thread ID is between FreeBSD and Linux(R) we have to translate the view somehow. +As there is a difference in view as what to the idea of a process ID and thread ID is between FreeBSD and Linux(R) we have to translate the view somehow. We do it by PID mangling. This means that we fake what a PID (=TGID) and TID (=PID) is between kernel and userland. The rule of thumb is that in kernel (in Linuxulator) PID = PID and TGID = shared -> group pid and to userland we present `PID = shared -> group_pid` and `TID = proc -> p_pid`. @@ -1006,9 +1006,9 @@ Newer glibc in a case of 2.6 kernel uses `clone` to implement man:fork[2] and ma ==== Locking The locking is implemented to be per-subsystem because we do not expect a lot of contention on these. -There are two locks: `emul_lock` used to protect manipulating of `linux_emuldata` and `emul_shared_lock` used to manipulate `linux_emuldata_shared`. +There are two locks: `emul_lock` used to protect manipulating of `linux_emuldata` and `emul_shared_lock` used to manipulate `linux_emuldata_shared`. The `emul_lock` is a nonsleepable blocking mutex while `emul_shared_lock` is a sleepable blocking `sx_lock`. -Due to of the per-subsystem locking we can coalesce some locks and that is why the em find offers the non-locking access. +Due to of the per-subsystem locking we can coalesce some locks and that is why the em_find offers the non-locking access. [[tls]] === TLS @@ -1392,7 +1392,7 @@ We are able to run the most used applications like package:www/linux-firefox[], Some of the programs exhibit bad behavior under 2.6 emulation but this is currently under investigation and hopefully will be fixed soon. The only big application that is known not to work is the Linux(R) Java(TM) Development Kit and this is because of the requirement of `epoll` facility which is not directly related to the Linux(R) kernel 2.6. -We hope to enable 2.6.16 emulation by default some time after FreeBSD 7.0 is released at least to expose the 2.6 emulation parts for some wider testing. +We hope to enable 2.6.16 emulation by default some time after FreeBSD 7.0 is released at least to expose the 2.6 emulation parts for some wider testing. Once this is done we can switch to Fedora Core 6 linux_base, which is the ultimate plan. [[future-work]] @@ -1431,6 +1431,6 @@ I would like to thank all those people for their advice, code reviews and genera [[literatures]] == Literatures -. Marshall Kirk McKusick - George V. Nevile-Neil. Design and Implementation of the FreeBSD operating system. Addison-Wesley, 2005. +. Marshall Kirk McKusick - George V. Neville-Neil. Design and Implementation of the FreeBSD operating system. Addison-Wesley, 2005. . https://tldp.org[https://tldp.org] . https://www.kernel.org[https://www.kernel.org] diff --git a/documentation/content/en/articles/linux-emulation/_index.po b/documentation/content/en/articles/linux-emulation/_index.po new file mode 100644 index 0000000000..4483660ee5 --- /dev/null +++ b/documentation/content/en/articles/linux-emulation/_index.po @@ -0,0 +1,3230 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-01-17 20:35-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/linux-emulation/_index.adoc:1 +#, no-wrap +msgid "A technical description about the internals of the Linux emulation layer in FreeBSD" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/articles/linux-emulation/_index.adoc:1 +#, no-wrap +msgid "Linux® emulation in FreeBSD" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/linux-emulation/_index.adoc:11 +#, no-wrap +msgid "Linux(R) emulation in FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:54 +msgid "" +"This masters thesis deals with updating the Linux(R) emulation layer (the so " +"called _Linuxulator_). The task was to update the layer to match the " +"functionality of Linux(R) 2.6. As a reference implementation, the Linux(R) " +"2.6.16 kernel was chosen. The concept is loosely based on the NetBSD " +"implementation. Most of the work was done in the summer of 2006 as a part " +"of the Google Summer of Code students program. The focus was on bringing " +"the _NPTL_ (new POSIX(R) thread library) support into the emulation layer, " +"including _TLS_ (thread local storage), _futexes_ (fast user space mutexes), " +"_PID mangling_, and some other minor things. Many small problems were " +"identified and fixed in the process. My work was integrated into the main " +"FreeBSD source repository and will be shipped in the upcoming 7.0R release. " +"We, the emulation development team, are working on making the Linux(R) 2.6 " +"emulation the default emulation layer in FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:56 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-emulation/_index.adoc:60 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:67 +msgid "" +"In the last few years the open source UNIX(R) based operating systems " +"started to be widely deployed on server and client machines. Among these " +"operating systems I would like to point out two: FreeBSD, for its BSD " +"heritage, time proven code base and many interesting features and Linux(R) " +"for its wide user base, enthusiastic open developer community and support " +"from large companies. FreeBSD tends to be used on server class machines " +"serving heavy duty networking tasks with less usage on desktop class " +"machines for ordinary users. While Linux(R) has the same usage on servers, " +"but it is used much more by home based users. This leads to a situation " +"where there are many binary only programs available for Linux(R) that lack " +"support for FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:69 +msgid "" +"Naturally, a need for the ability to run Linux(R) binaries on a FreeBSD " +"system arises and this is what this thesis deals with: the emulation of the " +"Linux(R) kernel in the FreeBSD operating system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:72 +msgid "" +"During the Summer of 2006 Google Inc. sponsored a project which focused on " +"extending the Linux(R) emulation layer (the so called Linuxulator) in " +"FreeBSD to include Linux(R) 2.6 facilities. This thesis is written as a " +"part of this project." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-emulation/_index.adoc:74 +#, no-wrap +msgid "A look inside..." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:80 +msgid "" +"In this section we are going to describe every operating system in " +"question. How they deal with syscalls, trapframes etc., all the low-level " +"stuff. We also describe the way they understand common UNIX(R) primitives " +"like what a PID is, what a thread is, etc. In the third subsection we talk " +"about how UNIX(R) on UNIX(R) emulation could be done in general." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:82 +#, no-wrap +msgid "What is UNIX(R)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:94 +msgid "" +"UNIX(R) is an operating system with a long history that has influenced " +"almost every other operating system currently in use. Starting in the " +"1960s, its development continues to this day (although in different " +"projects). UNIX(R) development soon forked into two main ways: the BSDs and " +"System III/V families. They mutually influenced themselves by growing a " +"common UNIX(R) standard. Among the contributions originated in BSD we can " +"name virtual memory, TCP/IP networking, FFS, and many others. The System V " +"branch contributed to SysV interprocess communication primitives, copy-on-" +"write, etc. UNIX(R) itself does not exist any more but its ideas have been " +"used by many other operating systems world wide thus forming the so called " +"UNIX(R)-like operating systems. These days the most influential ones are " +"Linux(R), Solaris, and possibly (to some extent) FreeBSD. There are in-" +"company UNIX(R) derivatives (AIX, HP-UX etc.), but these have been more and " +"more migrated to the aforementioned systems. Let us summarize typical " +"UNIX(R) characteristics." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:96 +#: documentation/content/en/articles/linux-emulation/_index.adoc:187 +#: documentation/content/en/articles/linux-emulation/_index.adoc:279 +#, no-wrap +msgid "Technical details" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:104 +msgid "" +"Every running program constitutes a process that represents a state of the " +"computation. Running process is divided between kernel-space and user-" +"space. Some operations can be done only from kernel space (dealing with " +"hardware etc.), but the process should spend most of its lifetime in the " +"user space. The kernel is where the management of the processes, hardware, " +"and low-level details take place. The kernel provides a standard unified " +"UNIX(R) API to the user space. The most important ones are covered below." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:106 +#, no-wrap +msgid "Communication between kernel and user space process" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:114 +msgid "" +"Common UNIX(R) API defines a syscall as a way to issue commands from a user " +"space process to the kernel. The most common implementation is either by " +"using an interrupt or specialized instruction (think of `SYSENTER`/`SYSCALL` " +"instructions for ia32). Syscalls are defined by a number. For example in " +"FreeBSD, the syscall number 85 is the man:swapon[2] syscall and the syscall " +"number 132 is man:mkfifo[2]. Some syscalls need parameters, which are " +"passed from the user-space to the kernel-space in various ways " +"(implementation dependent). Syscalls are synchronous." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:118 +msgid "" +"Another possible way to communicate is by using a _trap_. Traps occur " +"asynchronously after some event occurs (division by zero, page fault etc.). " +"A trap can be transparent for a process (page fault) or can result in a " +"reaction like sending a _signal_ (division by zero)." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:120 +#, no-wrap +msgid "Communication between processes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:125 +msgid "" +"There are other APIs (System V IPC, shared memory etc.) but the single most " +"important API is signal. Signals are sent by processes or by the kernel and " +"received by processes. Some signals can be ignored or handled by a user " +"supplied routine, some result in a predefined action that cannot be altered " +"or ignored." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:127 +#, no-wrap +msgid "Process management" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:137 +msgid "" +"Kernel instances are processed first in the system (so called init). Every " +"running process can create its identical copy using the man:fork[2] " +"syscall. Some slightly modified versions of this syscall were introduced " +"but the basic semantic is the same. Every running process can morph into " +"some other process using the man:exec[3] syscall. Some modifications of " +"this syscall were introduced but all serve the same basic purpose. " +"Processes end their lives by calling the man:exit[2] syscall. Every process " +"is identified by a unique number called PID. Every process has a defined " +"parent (identified by its PID)." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:139 +#, no-wrap +msgid "Thread management" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:145 +msgid "" +"Traditional UNIX(R) does not define any API nor implementation for " +"threading, while POSIX(R) defines its threading API but the implementation " +"is undefined. Traditionally there were two ways of implementing threads. " +"Handling them as separate processes (1:1 threading) or envelope the whole " +"thread group in one process and managing the threading in userspace (1:N " +"threading). Comparing main features of each approach:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:147 +msgid "1:1 threading" +msgstr "" + +#. type: Bullet: '- ' +#: documentation/content/en/articles/linux-emulation/_index.adoc:149 +msgid "heavyweight threads" +msgstr "" + +#. type: Bullet: '- ' +#: documentation/content/en/articles/linux-emulation/_index.adoc:150 +msgid "" +"the scheduling cannot be altered by the user (slightly mitigated by the " +"POSIX(R) API)" +msgstr "" + +#. type: Bullet: '+ ' +#: documentation/content/en/articles/linux-emulation/_index.adoc:151 +msgid "no syscall wrapping necessary" +msgstr "" + +#. type: Bullet: '+ ' +#: documentation/content/en/articles/linux-emulation/_index.adoc:152 +msgid "can utilize multiple CPUs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:154 +msgid "1:N threading" +msgstr "" + +#. type: Bullet: '+ ' +#: documentation/content/en/articles/linux-emulation/_index.adoc:156 +msgid "lightweight threads" +msgstr "" + +#. type: Bullet: '+ ' +#: documentation/content/en/articles/linux-emulation/_index.adoc:157 +msgid "scheduling can be easily altered by the user" +msgstr "" + +#. type: Bullet: '- ' +#: documentation/content/en/articles/linux-emulation/_index.adoc:158 +msgid "syscalls must be wrapped" +msgstr "" + +#. type: Bullet: '- ' +#: documentation/content/en/articles/linux-emulation/_index.adoc:159 +msgid "cannot utilize more than one CPU" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:161 +#, no-wrap +msgid "What is FreeBSD?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:169 +msgid "" +"The FreeBSD project is one of the oldest open source operating systems " +"currently available for daily use. It is a direct descendant of the genuine " +"UNIX(R) so it could be claimed that it is a true UNIX(R) although licensing " +"issues do not permit that. The start of the project dates back to the early " +"1990's when a crew of fellow BSD users patched the 386BSD operating system. " +"Based on this patchkit a new operating system arose named FreeBSD for its " +"liberal license. Another group created the NetBSD operating system with " +"different goals in mind. We will focus on FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:174 +msgid "" +"FreeBSD is a modern UNIX(R)-based operating system with all the features of " +"UNIX(R). Preemptive multitasking, multiuser facilities, TCP/IP networking, " +"memory protection, symmetric multiprocessing support, virtual memory with " +"merged VM and buffer cache, they are all there. One of the interesting and " +"extremely useful features is the ability to emulate other UNIX(R)-like " +"operating systems. As of December 2006 and 7-CURRENT development, the " +"following emulation functionalities are supported:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:176 +msgid "FreeBSD/i386 emulation on FreeBSD/amd64" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:177 +msgid "FreeBSD/i386 emulation on FreeBSD/ia64" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:178 +msgid "Linux(R)-emulation of Linux(R) operating system on FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:179 +msgid "NDIS-emulation of Windows networking drivers interface" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:180 +msgid "NetBSD-emulation of NetBSD operating system" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:181 +msgid "PECoff-support for PECoff FreeBSD executables" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:182 +msgid "SVR4-emulation of System V revision 4 UNIX(R)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:185 +msgid "" +"Actively developed emulations are the Linux(R) layer and various FreeBSD-on-" +"FreeBSD layers. Others are not supposed to work properly nor be usable " +"these days." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:195 +msgid "" +"FreeBSD is traditional flavor of UNIX(R) in the sense of dividing the run of " +"processes into two halves: kernel space and user space run. There are two " +"types of process entry to the kernel: a syscall and a trap. There is only " +"one way to return. In the subsequent sections we will describe the three " +"gates to/from the kernel. The whole description applies to the i386 " +"architecture as the Linuxulator only exists there but the concept is similar " +"on other architectures. The information was taken from [1] and the source " +"code." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:197 +#, no-wrap +msgid "System entries" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:204 +msgid "" +"FreeBSD has an abstraction called an execution class loader, which is a " +"wedge into the man:execve[2] syscall. This employs a structure `sysentvec`, " +"which describes an executable ABI. It contains things like errno " +"translation table, signal translation table, various functions to serve " +"syscall needs (stack fixup, coredumping, etc.). Every ABI the FreeBSD " +"kernel wants to support must define this structure, as it is used later in " +"the syscall processing code and at some other places. System entries are " +"handled by trap handlers, where we can access both the kernel-space and the " +"user-space at once." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:206 +#: documentation/content/en/articles/linux-emulation/_index.adoc:288 +#, no-wrap +msgid "Syscalls" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:209 +msgid "" +"Syscalls on FreeBSD are issued by executing interrupt `0x80` with register " +"`%eax` set to a desired syscall number with arguments passed on the stack." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:215 +msgid "" +"When a process issues an interrupt `0x80`, the `int0x80` syscall trap " +"handler is issued (defined in [.filename]#sys/i386/i386/exception.s#), which " +"prepares arguments (i.e. copies them on to the stack) for a call to a C " +"function man:syscall[2] (defined in [.filename]#sys/i386/i386/trap.c#), " +"which processes the passed in trapframe. The processing consists of " +"preparing the syscall (depending on the `sysvec` entry), determining if the " +"syscall is 32-bit or 64-bit one (changes size of the parameters), then the " +"parameters are copied, including the syscall. Next, the actual syscall " +"function is executed with processing of the return code (special cases for " +"`ERESTART` and `EJUSTRETURN` errors). Finally an `userret()` is scheduled, " +"switching the process back to the users-pace. The parameters to the actual " +"syscall handler are passed in the form of `struct thread *td`, `struct " +"syscall args *` arguments where the second parameter is a pointer to the " +"copied in structure of parameters." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:217 +#: documentation/content/en/articles/linux-emulation/_index.adoc:307 +#: documentation/content/en/articles/linux-emulation/_index.adoc:794 +#, no-wrap +msgid "Traps" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:224 +msgid "" +"Handling of traps in FreeBSD is similar to the handling of syscalls. " +"Whenever a trap occurs, an assembler handler is called. It is chosen " +"between alltraps, alltraps with regs pushed or calltrap depending on the " +"type of the trap. This handler prepares arguments for a call to a C " +"function `trap()` (defined in [.filename]#sys/i386/i386/trap.c#), which then " +"processes the occurred trap. After the processing it might send a signal to " +"the process and/or exit to userland using `userret()`." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:226 +#: documentation/content/en/articles/linux-emulation/_index.adoc:312 +#, no-wrap +msgid "Exits" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:230 +msgid "" +"Exits from kernel to userspace happen using the assembler routine `doreti` " +"regardless of whether the kernel was entered via a trap or via a syscall. " +"This restores the program status from the stack and returns to the userspace." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:232 +#: documentation/content/en/articles/linux-emulation/_index.adoc:318 +#, no-wrap +msgid "UNIX(R) primitives" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:238 +msgid "" +"FreeBSD operating system adheres to the traditional UNIX(R) scheme, where " +"every process has a unique identification number, the so called _PID_ " +"(Process ID). PID numbers are allocated either linearly or randomly ranging " +"from `0` to `PID_MAX`. The allocation of PID numbers is done using linear " +"searching of PID space. Every thread in a process receives the same PID " +"number as result of the man:getpid[2] call." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:249 +msgid "" +"There are currently two ways to implement threading in FreeBSD. The first " +"way is M:N threading followed by the 1:1 threading model. The default " +"library used is M:N threading (`libpthread`) and you can switch at runtime " +"to 1:1 threading (`libthr`). The plan is to switch to 1:1 library by " +"default soon. Although those two libraries use the same kernel primitives, " +"they are accessed through different API(es). The M:N library uses the " +"`kse_*` family of syscalls while the 1:1 library uses the `thr_*` family of " +"syscalls. Due to this, there is no general concept of thread ID shared " +"between kernel and userspace. Of course, both threading libraries implement " +"the pthread thread ID API. Every kernel thread (as described by `struct " +"thread`) has td tid identifier but this is not directly accessible from " +"userland and solely serves the kernel's needs. It is also used for 1:1 " +"threading library as pthread's thread ID but handling of this is internal to " +"the library and cannot be relied on." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:257 +msgid "" +"As stated previously there are two implementations of threading in FreeBSD. " +"The M:N library divides the work between kernel space and userspace. Thread " +"is an entity that gets scheduled in the kernel but it can represent various " +"number of userspace threads. M userspace threads get mapped to N kernel " +"threads thus saving resources while keeping the ability to exploit " +"multiprocessor parallelism. Further information about the implementation " +"can be obtained from the man page or [1]. The 1:1 library directly maps a " +"userland thread to a kernel thread thus greatly simplifying the scheme. " +"None of these designs implement a fairness mechanism (such a mechanism was " +"implemented but it was removed recently because it caused serious slowdown " +"and made the code more difficult to deal with)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:259 +#, no-wrap +msgid "What is Linux(R)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:263 +msgid "" +"Linux(R) is a UNIX(R)-like kernel originally developed by Linus Torvalds, " +"and now being contributed to by a massive crowd of programmers all around " +"the world. From its mere beginnings to today, with wide support from " +"companies such as IBM or Google, Linux(R) is being associated with its fast " +"development pace, full hardware support and benevolent dictator model of " +"organization." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:267 +msgid "" +"Linux(R) development started in 1991 as a hobbyist project at University of " +"Helsinki in Finland. Since then it has obtained all the features of a " +"modern UNIX(R)-like OS: multiprocessing, multiuser support, virtual memory, " +"networking, basically everything is there. There are also highly advanced " +"features like virtualization etc." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:270 +msgid "" +"As of 2006 Linux(R) seems to be the most widely used open source operating " +"system with support from independent software vendors like Oracle, " +"RealNetworks, Adobe, etc. Most of the commercial software distributed for " +"Linux(R) can only be obtained in a binary form so recompilation for other " +"operating systems is impossible." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:275 +msgid "" +"Most of the Linux(R) development happens in a Git version control system. " +"Git is a distributed system so there is no central source of the Linux(R) " +"code, but some branches are considered prominent and official. The version " +"number scheme implemented by Linux(R) consists of four numbers A.B.C.D. " +"Currently development happens in 2.6.C.D, where C represents major version, " +"where new features are added or changed while D is a minor version for " +"bugfixes only." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:277 +msgid "More information can be obtained from [3]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:286 +msgid "" +"Linux(R) follows the traditional UNIX(R) scheme of dividing the run of a " +"process in two halves: the kernel and user space. The kernel can be entered " +"in two ways: via a trap or via a syscall. The return is handled only in one " +"way. The further description applies to Linux(R) 2.6 on the i386(TM) " +"architecture. This information was taken from [2]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:296 +msgid "" +"Syscalls in Linux(R) are performed (in userspace) using `syscallX` macros " +"where X substitutes a number representing the number of parameters of the " +"given syscall. This macro translates to a code that loads `%eax` register " +"with a number of the syscall and executes interrupt `0x80`. After this " +"syscall return is called, which translates negative return values to " +"positive `errno` values and sets `res` to `-1` in case of an error. " +"Whenever the interrupt `0x80` is called the process enters the kernel in " +"system call trap handler. This routine saves all registers on the stack and " +"calls the selected syscall entry. Note that the Linux(R) calling convention " +"expects parameters to the syscall to be passed via registers as shown here:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:298 +msgid "parameter -> `%ebx`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:299 +msgid "parameter -> `%ecx`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:300 +msgid "parameter -> `%edx`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:301 +msgid "parameter -> `%esi`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:302 +msgid "parameter -> `%edi`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:303 +msgid "parameter -> `%ebp`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:305 +msgid "" +"There are some exceptions to this, where Linux(R) uses different calling " +"convention (most notably the `clone` syscall)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:310 +msgid "" +"The trap handlers are introduced in [.filename]#arch/i386/kernel/traps.c# " +"and most of these handlers live in [.filename]#arch/i386/kernel/entry.S#, " +"where handling of the traps happens." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:316 +msgid "" +"Return from the syscall is managed by syscall man:exit[3], which checks for " +"the process having unfinished work, then checks whether we used user-" +"supplied selectors. If this happens stack fixing is applied and finally the " +"registers are restored from the stack and the process returns to the " +"userspace." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:327 +msgid "" +"In the 2.6 version, the Linux(R) operating system redefined some of the " +"traditional UNIX(R) primitives, notably PID, TID and thread. PID is defined " +"not to be unique for every process, so for some processes (threads) man:" +"getppid[2] returns the same value. Unique identification of process is " +"provided by TID. This is because _NPTL_ (New POSIX(R) Thread Library) " +"defines threads to be normal processes (so called 1:1 threading). Spawning " +"a new process in Linux(R) 2.6 happens using the `clone` syscall (fork " +"variants are reimplemented using it). This clone syscall defines a set of " +"flags that affect behavior of the cloning process regarding thread " +"implementation. The semantic is a bit fuzzy as there is no single flag " +"telling the syscall to create a thread." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:329 +msgid "Implemented clone flags are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:331 +msgid "`CLONE_VM` - processes share their memory space" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:332 +msgid "`CLONE_FS` - share umask, cwd and namespace" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:333 +msgid "`CLONE_FILES` - share open files" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:334 +msgid "`CLONE_SIGHAND` - share signal handlers and blocked signals" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:335 +msgid "`CLONE_PARENT` - share parent" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:336 +msgid "`CLONE_THREAD` - be thread (further explanation below)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:337 +msgid "`CLONE_NEWNS` - new namespace" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:338 +msgid "`CLONE_SYSVSEM` - share SysV undo structures" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:339 +msgid "`CLONE_SETTLS` - setup TLS at supplied address" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:340 +msgid "`CLONE_PARENT_SETTID` - set TID in the parent" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:341 +msgid "`CLONE_CHILD_CLEARTID` - clear TID in the child" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:342 +msgid "`CLONE_CHILD_SETTID` - set TID in the child" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:348 +msgid "" +"`CLONE_PARENT` sets the real parent to the parent of the caller. This is " +"useful for threads because if thread A creates thread B we want thread B to " +"be parented to the parent of the whole thread group. `CLONE_THREAD` does " +"exactly the same thing as `CLONE_PARENT`, `CLONE_VM` and `CLONE_SIGHAND`, " +"rewrites PID to be the same as PID of the caller, sets exit signal to be " +"none and enters the thread group. `CLONE_SETTLS` sets up GDT entries for " +"TLS handling. The `CLONE_*_*TID` set of flags sets/clears user supplied " +"address to TID or 0." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:352 +msgid "" +"As you can see the `CLONE_THREAD` does most of the work and does not seem to " +"fit the scheme very well. The original intention is unclear (even for " +"authors, according to comments in the code) but I think originally there was " +"one threading flag, which was then parcelled among many other flags but this " +"separation was never fully finished. It is also unclear what this partition " +"is good for as glibc does not use that so only hand-written use of the clone " +"permits a programmer to access this features." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:355 +msgid "" +"For non-threaded programs the PID and TID are the same. For threaded " +"programs the first thread PID and TID are the same and every created thread " +"shares the same PID and gets assigned a unique TID (because `CLONE_THREAD` " +"is passed in) also parent is shared for all processes forming this threaded " +"program." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:357 +msgid "" +"The code that implements man:pthread_create[3] in NPTL defines the clone " +"flags like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:361 +#, no-wrap +msgid "int clone_flags = (CLONE_VM | CLONE_FS | CLONE_FILES | CLONE_SIGNAL\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:363 +#, no-wrap +msgid " | CLONE_SETTLS | CLONE_PARENT_SETTID\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:366 +#, no-wrap +msgid "" +"| CLONE_CHILD_CLEARTID | CLONE_SYSVSEM\n" +"#if __ASSUME_NO_CLONE_DETACHED == 0\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:369 +#, no-wrap +msgid "" +"| CLONE_DETACHED\n" +"#endif\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:371 +#, no-wrap +msgid "| 0);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:374 +msgid "The `CLONE_SIGNAL` is defined like" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:378 +#, no-wrap +msgid "#define CLONE_SIGNAL (CLONE_SIGHAND | CLONE_THREAD)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:381 +msgid "the last 0 means no signal is sent when any of the threads exits." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:383 +#, no-wrap +msgid "What is emulation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:388 +msgid "" +"According to a dictionary definition, emulation is the ability of a program " +"or device to imitate another program or device. This is achieved by " +"providing the same reaction to a given stimulus as the emulated object. In " +"practice, the software world mostly sees three types of emulation - a " +"program used to emulate a machine (QEMU, various game console emulators " +"etc.), software emulation of a hardware facility (OpenGL emulators, floating " +"point units emulation etc.) and operating system emulation (either in kernel " +"of the operating system or as a userspace program)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:395 +msgid "" +"Emulation is usually used in a place, where using the original component is " +"not feasible nor possible at all. For example someone might want to use a " +"program developed for a different operating system than they use. Then " +"emulation comes in handy. Sometimes there is no other way but to use " +"emulation - e.g. when the hardware device you try to use does not exist (yet/" +"anymore) then there is no other way but emulation. This happens often when " +"porting an operating system to a new (non-existent) platform. Sometimes it " +"is just cheaper to emulate." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:407 +msgid "" +"Looking from an implementation point of view, there are two main approaches " +"to the implementation of emulation. You can either emulate the whole thing " +"- accepting possible inputs of the original object, maintaining inner state " +"and emitting correct output based on the state and/or input. This kind of " +"emulation does not require any special conditions and basically can be " +"implemented anywhere for any device/program. The drawback is that " +"implementing such emulation is quite difficult, time-consuming and error-" +"prone. In some cases we can use a simpler approach. Imagine you want to " +"emulate a printer that prints from left to right on a printer that prints " +"from right to left. It is obvious that there is no need for a complex " +"emulation layer but simply reversing of the printed text is sufficient. " +"Sometimes the emulating environment is very similar to the emulated one so " +"just a thin layer of some translation is necessary to provide fully working " +"emulation! As you can see this is much less demanding to implement, so less " +"time-consuming and error-prone than the previous approach. But the " +"necessary condition is that the two environments must be similar enough. " +"The third approach combines the two previous. Most of the time the objects " +"do not provide the same capabilities so in a case of emulating the more " +"powerful one on the less powerful we have to emulate the missing features " +"with full emulation described above." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:410 +msgid "" +"This master thesis deals with emulation of UNIX(R) on UNIX(R), which is " +"exactly the case, where only a thin layer of translation is sufficient to " +"provide full emulation. The UNIX(R) API consists of a set of syscalls, " +"which are usually self contained and do not affect some global kernel state." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:412 +msgid "" +"There are a few syscalls that affect inner state but this can be dealt with " +"by providing some structures that maintain the extra state." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:416 +msgid "" +"No emulation is perfect and emulations tend to lack some parts but this " +"usually does not cause any serious drawbacks. Imagine a game console " +"emulator that emulates everything but music output. No doubt that the games " +"are playable and one can use the emulator. It might not be that comfortable " +"as the original game console but its an acceptable compromise between price " +"and comfort." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:420 +msgid "" +"The same goes with the UNIX(R) API. Most programs can live with a very " +"limited set of syscalls working. Those syscalls tend to be the oldest ones " +"(man:read[2]/man:write[2], man:fork[2] family, man:signal[3] handling, man:" +"exit[3], man:socket[2] API) hence it is easy to emulate because their " +"semantics is shared among all UNIX(R)es, which exist todays." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-emulation/_index.adoc:422 +#, no-wrap +msgid "Emulation" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:424 +#, no-wrap +msgid "How emulation works in FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:429 +msgid "" +"As stated earlier, FreeBSD supports running binaries from several other " +"UNIX(R)es. This works because FreeBSD has an abstraction called the " +"execution class loader. This wedges into the man:execve[2] syscall, so when " +"man:execve[2] is about to execute a binary it examines its type." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:435 +msgid "" +"There are basically two types of binaries in FreeBSD. Shell-like text " +"scripts which are identified by `#!` as their first two characters and " +"normal (typically _ELF_) binaries, which are a representation of a compiled " +"executable object. The vast majority (one could say all of them) of " +"binaries in FreeBSD are from type ELF. ELF files contain a header, which " +"specifies the OS ABI for this ELF file. By reading this information, the " +"operating system can accurately determine what type of binary the given file " +"is." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:441 +msgid "" +"Every OS ABI must be registered in the FreeBSD kernel. This applies to the " +"FreeBSD native OS ABI, as well. So when man:execve[2] executes a binary it " +"iterates through the list of registered APIs and when it finds the right one " +"it starts to use the information contained in the OS ABI description (its " +"syscall table, `errno` translation table, etc.). So every time the process " +"calls a syscall, it uses its own set of syscalls instead of some global " +"one. This effectively provides a very elegant and easy way of supporting " +"execution of various binary formats." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:446 +msgid "" +"The nature of emulation of different OSes (and also some other subsystems) " +"led developers to invite a handler event mechanism. There are various " +"places in the kernel, where a list of event handlers are called. Every " +"subsystem can register an event handler and they are called accordingly. " +"For example, when a process exits there is a handler called that possibly " +"cleans up whatever the subsystem needs to be cleaned." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:448 +msgid "" +"Those simple facilities provide basically everything that is needed for the " +"emulation infrastructure and in fact these are basically the only things " +"necessary to implement the Linux(R) emulation layer." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:450 +#, no-wrap +msgid "Common primitives in the FreeBSD kernel" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:454 +msgid "" +"Emulation layers need some support from the operating system. I am going to " +"describe some of the supported primitives in the FreeBSD operating system." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:456 +#, no-wrap +msgid "Locking primitives" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:459 +msgid "Contributed by: `{attilio}`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:461 +msgid "" +"The FreeBSD synchronization primitive set is based on the idea to supply a " +"rather huge number of different primitives in a way that the better one can " +"be used for every particular, appropriate situation." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:463 +msgid "" +"To a high level point of view you can consider three kinds of " +"synchronization primitives in the FreeBSD kernel:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:465 +msgid "atomic operations and memory barriers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:466 +msgid "locks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:467 +msgid "scheduling barriers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:470 +msgid "" +"Below there are descriptions for the 3 families. For every lock, you should " +"really check the linked manpage (where possible) for more detailed " +"explanations." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:472 +#, no-wrap +msgid "Atomic operations and memory barriers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:483 +msgid "" +"Atomic operations are implemented through a set of functions performing " +"simple arithmetics on memory operands in an atomic way with respect to " +"external events (interrupts, preemption, etc.). Atomic operations can " +"guarantee atomicity just on small data types (in the magnitude order of the " +"`.long.` architecture C data type), so should be rarely used directly in the " +"end-level code, if not only for very simple operations (like flag setting in " +"a bitmap, for example). In fact, it is rather simple and common to write " +"down a wrong semantic based on just atomic operations (usually referred as " +"lock-less). The FreeBSD kernel offers a way to perform atomic operations in " +"conjunction with a memory barrier. The memory barriers will guarantee that " +"an atomic operation will happen following some specified ordering with " +"respect to other memory accesses. For example, if we need that an atomic " +"operation happen just after all other pending writes (in terms of " +"instructions reordering buffers activities) are completed, we need to " +"explicitly use a memory barrier in conjunction to this atomic operation. So " +"it is simple to understand why memory barriers play a key role for higher-" +"level locks building (just as refcounts, mutexes, etc.). For a detailed " +"explanatory on atomic operations, please refer to man:atomic[9]. It is far, " +"however, noting that atomic operations (and memory barriers as well) should " +"ideally only be used for building front-ending locks (as mutexes)." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:485 +#, no-wrap +msgid "Refcounts" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:491 +msgid "" +"Refcounts are interfaces for handling reference counters. They are " +"implemented through atomic operations and are intended to be used just for " +"cases, where the reference counter is the only one thing to be protected, so " +"even something like a spin-mutex is deprecated. Using the refcount " +"interface for structures, where a mutex is already used is often wrong since " +"we should probably close the reference counter in some already protected " +"paths. A manpage discussing refcount does not exist currently, just check [." +"filename]#sys/refcount.h# for an overview of the existing API." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:493 +#, no-wrap +msgid "Locks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:498 +msgid "" +"FreeBSD kernel has huge classes of locks. Every lock is defined by some " +"peculiar properties, but probably the most important is the event linked to " +"contesting holders (or in other terms, the behavior of threads unable to " +"acquire the lock). FreeBSD's locking scheme presents three different " +"behaviors for contenders:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:500 +msgid "spinning" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:501 +msgid "blocking" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:502 +msgid "sleeping" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:506 +msgid "numbers are not casual" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:509 +#, no-wrap +msgid "Spinning locks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:515 +msgid "" +"Spin locks let waiters to spin until they cannot acquire the lock. An " +"important matter do deal with is when a thread contests on a spin lock if it " +"is not descheduled. Since the FreeBSD kernel is preemptive, this exposes " +"spin lock at the risk of deadlocks that can be solved just disabling " +"interrupts while they are acquired. For this and other reasons (like lack " +"of priority propagation support, poorness in load balancing schemes between " +"CPUs, etc.), spin locks are intended to protect very small paths of code, or " +"ideally not to be used at all if not explicitly requested (explained later)." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:517 +#, no-wrap +msgid "Blocking" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:522 +msgid "" +"Block locks let waiters to be descheduled and blocked until the lock owner " +"does not drop it and wakes up one or more contenders. To avoid starvation " +"issues, blocking locks do priority propagation from the waiters to the " +"owner. Block locks must be implemented through the turnstile interface and " +"are intended to be the most used kind of locks in the kernel, if no " +"particular conditions are met." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:524 +#, no-wrap +msgid "Sleeping" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:529 +msgid "" +"Sleep locks let waiters to be descheduled and fall asleep until the lock " +"holder does not drop it and wakes up one or more waiters. Since sleep locks " +"are intended to protect large paths of code and to cater asynchronous " +"events, they do not do any form of priority propagation. They must be " +"implemented through the man:sleepqueue[9] interface." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:533 +msgid "" +"The order used to acquire locks is very important, not only for the " +"possibility to deadlock due at lock order reversals, but even because lock " +"acquisition should follow specific rules linked to locks natures. If you " +"give a look at the table above, the practical rule is that if a thread holds " +"a lock of level n (where the level is the number listed close to the kind of " +"lock) it is not allowed to acquire a lock of superior levels, since this " +"would break the specified semantic for a path. For example, if a thread " +"holds a block lock (level 2), it is allowed to acquire a spin lock (level 1) " +"but not a sleep lock (level 3), since block locks are intended to protect " +"smaller paths than sleep lock (these rules are not about atomic operations " +"or scheduling barriers, however)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:535 +msgid "This is a list of lock with their respective behaviors:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:537 +msgid "spin mutex - spinning - man:mutex[9]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:538 +msgid "sleep mutex - blocking - man:mutex[9]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:539 +msgid "pool mutex - blocking - man:mtx[pool]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:540 +msgid "" +"sleep family - sleeping - man:sleep[9] pause tsleep msleep msleep spin " +"msleep rw msleep sx" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:541 +msgid "condvar - sleeping - man:condvar[9]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:542 +msgid "rwlock - blocking - man:rwlock[9]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:543 +msgid "sxlock - sleeping - man:sx[9]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:544 +msgid "lockmgr - sleeping - man:lockmgr[9]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:545 +msgid "semaphores - sleeping - man:sema[9]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:547 +msgid "" +"Among these locks only mutexes, sxlocks, rwlocks and lockmgrs are intended " +"to handle recursion, but currently recursion is only supported by mutexes " +"and lockmgrs." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:549 +#, no-wrap +msgid "Scheduling barriers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:553 +msgid "" +"Scheduling barriers are intended to be used to drive scheduling of " +"threading. They consist mainly of three different stubs:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:555 +msgid "critical sections (and preemption)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:556 +msgid "sched_bind" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:557 +msgid "sched_pin" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:559 +msgid "" +"Generally, these should be used only in a particular context and even if " +"they can often replace locks, they should be avoided because they do not let " +"the diagnose of simple eventual problems with locking debugging tools (as " +"man:witness[4])." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:561 +#, no-wrap +msgid "Critical sections" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:569 +msgid "" +"The FreeBSD kernel has been made preemptive basically to deal with interrupt " +"threads. In fact, to avoid high interrupt latency, time-sharing priority " +"threads can be preempted by interrupt threads (in this way, they do not need " +"to wait to be scheduled as the normal path previews). Preemption, however, " +"introduces new racing points that need to be handled, as well. Often, to " +"deal with preemption, the simplest thing to do is to completely disable it. " +"A critical section defines a piece of code (borderlined by the pair of " +"functions man:critical_enter[9] and man:critical_exit[9], where preemption " +"is guaranteed to not happen (until the protected code is fully executed). " +"This can often replace a lock effectively but should be used carefully to " +"not lose the whole advantage that preemption brings." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:571 +#, no-wrap +msgid "sched_pin/sched_unpin" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:577 +msgid "" +"Another way to deal with preemption is the `sched_pin()` interface. If a " +"piece of code is closed in the `sched_pin()` and `sched_unpin()` pair of " +"functions it is guaranteed that the respective thread, even if it can be " +"preempted, it will always be executed on the same CPU. Pinning is very " +"effective in the particular case when we have to access at per-cpu datas and " +"we assume other threads will not change those data. The latter condition " +"will determine a critical section as a too strong condition for our code." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:579 +#, no-wrap +msgid "sched_bind/sched_unbind" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:584 +msgid "" +"`sched_bind` is an API used to bind a thread to a particular CPU for all the " +"time it executes the code, until a `sched_unbind` function call does not " +"unbind it. This feature has a key role in situations where you cannot trust " +"the current state of CPUs (for example, at very early stages of boot), as " +"you want to avoid your thread to migrate on inactive CPUs. Since " +"`sched_bind` and `sched_unbind` manipulate internal scheduler structures, " +"they need to be enclosed in `sched_lock` acquisition/releasing when used." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:586 +#, no-wrap +msgid "Proc structure" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:592 +msgid "" +"Various emulation layers sometimes require some additional per-process " +"data. It can manage separate structures (a list, a tree etc.) containing " +"these data for every process but this tends to be slow and memory " +"consuming. To solve this problem the FreeBSD `proc` structure contains " +"`p_emuldata`, which is a void pointer to some emulation layer specific " +"data. This `proc` entry is protected by the proc mutex." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:597 +msgid "" +"The FreeBSD `proc` structure contains a `p_sysent` entry that identifies, " +"which ABI this process is running. In fact, it is a pointer to the " +"`sysentvec` described above. So by comparing this pointer to the address " +"where the `sysentvec` structure for the given ABI is stored we can " +"effectively determine whether the process belongs to our emulation layer. " +"The code typically looks like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:602 +#, no-wrap +msgid "" +"if (__predict_true(p->p_sysent != &elf_Linux(R)_sysvec))\n" +"\t return;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:606 +msgid "" +"As you can see, we effectively use the `__predict_true` modifier to collapse " +"the most common case (FreeBSD process) to a simple return operation thus " +"preserving high performance. This code should be turned into a macro " +"because currently it is not very flexible, i.e. we do not support Linux(R)64 " +"emulation nor A.OUT Linux(R) processes on i386." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:608 +#, no-wrap +msgid "VFS" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:617 +msgid "" +"The FreeBSD VFS subsystem is very complex but the Linux(R) emulation layer " +"uses just a small subset via a well defined API. It can either operate on " +"vnodes or file handlers. Vnode represents a virtual vnode, i.e. " +"representation of a node in VFS. Another representation is a file handler, " +"which represents an opened file from the perspective of a process. A file " +"handler can represent a socket or an ordinary file. A file handler contains " +"a pointer to its vnode. More then one file handler can point to the same " +"vnode." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:619 +#, no-wrap +msgid "namei" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:626 +msgid "" +"The man:namei[9] routine is a central entry point to pathname lookup and " +"translation. It traverses the path point by point from the starting point " +"to the end point using lookup function, which is internal to VFS. The man:" +"namei[9] syscall can cope with symlinks, absolute and relative paths. When " +"a path is looked up using man:namei[9] it is inputed to the name cache. This " +"behavior can be suppressed. This routine is used all over the kernel and " +"its performance is very critical." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:628 +#, no-wrap +msgid "vn_fullpath" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:634 +msgid "" +"The man:vn_fullpath[9] function takes the best effort to traverse VFS name " +"cache and returns a path for a given (locked) vnode. This process is " +"unreliable but works just fine for the most common cases. The unreliability " +"is because it relies on VFS cache (it does not traverse the on medium " +"structures), it does not work with hardlinks, etc. This routine is used in " +"several places in the Linuxulator." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:636 +#, no-wrap +msgid "Vnode operations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:639 +msgid "" +"`fgetvp` - given a thread and a file descriptor number it returns the " +"associated vnode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:640 +msgid "man:vn_lock[9] - locks a vnode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:641 +msgid "`vn_unlock` - unlocks a vnode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:642 +msgid "man:VOP_READDIR[9] - reads a directory referenced by a vnode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:643 +msgid "" +"man:VOP_GETATTR[9] - gets attributes of a file or a directory referenced by " +"a vnode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:644 +msgid "man:VOP_LOOKUP[9] - looks up a path to a given directory" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:645 +msgid "man:VOP_OPEN[9] - opens a file referenced by a vnode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:646 +msgid "man:VOP_CLOSE[9] - closes a file referenced by a vnode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:647 +msgid "man:vput[9] - decrements the use count for a vnode and unlocks it" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:648 +msgid "man:vrele[9] - decrements the use count for a vnode" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:649 +msgid "man:vref[9] - increments the use count for a vnode" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:651 +#, no-wrap +msgid "File handler operations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:654 +msgid "" +"`fget` - given a thread and a file descriptor number it returns associated " +"file handler and references it" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:655 +msgid "`fdrop` - drops a reference to a file handler" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:656 +msgid "`fhold` - references a file handler" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-emulation/_index.adoc:658 +#, no-wrap +msgid "Linux(R) emulation layer -MD part" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:666 +msgid "" +"This section deals with implementation of Linux(R) emulation layer in " +"FreeBSD operating system. It first describes the machine dependent part " +"talking about how and where interaction between userland and kernel is " +"implemented. It talks about syscalls, signals, ptrace, traps, stack fixup. " +"This part discusses i386 but it is written generally so other architectures " +"should not differ very much. The next part is the machine independent part " +"of the Linuxulator. This section only covers i386 and ELF handling. A.OUT " +"is obsolete and untested." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:668 +#, no-wrap +msgid "Syscall handling" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:672 +msgid "" +"Syscall handling is mostly written in [.filename]#linux_sysvec.c#, which " +"covers most of the routines pointed out in the `sysentvec` structure. When " +"a Linux(R) process running on FreeBSD issues a syscall, the general syscall " +"routine calls linux prepsyscall routine for the Linux(R) ABI." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:674 +#, no-wrap +msgid "Linux(R) prepsyscall" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:681 +msgid "" +"Linux(R) passes arguments to syscalls via registers (that is why it is " +"limited to 6 parameters on i386) while FreeBSD uses the stack. The Linux(R) " +"prepsyscall routine must copy parameters from registers to the stack. The " +"order of the registers is: `%ebx`, `%ecx`, `%edx`, `%esi`, `%edi`, `%ebp`. " +"The catch is that this is true for only _most_ of the syscalls. Some (most " +"notably `clone`) uses a different order but it is luckily easy to fix by " +"inserting a dummy parameter in the `linux_clone` prototype." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:683 +#, no-wrap +msgid "Syscall writing" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:687 +msgid "" +"Every syscall implemented in the Linuxulator must have its prototype with " +"various flags in [.filename]#syscalls.master#. The form of the file is:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:695 +#, no-wrap +msgid "" +"...\n" +"\tAUE_FORK STD\t\t{ int linux_fork(void); }\n" +"...\n" +"\tAUE_CLOSE NOPROTO\t{ int close(int fd); }\n" +"...\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:705 +msgid "" +"The first column represents the syscall number. The second column is for " +"auditing support. The third column represents the syscall type. It is " +"either `STD`, `OBSOL`, `NOPROTO` and `UNIMPL`. `STD` is a standard syscall " +"with full prototype and implementation. `OBSOL` is obsolete and defines " +"just the prototype. `NOPROTO` means that the syscall is implemented " +"elsewhere so do not prepend ABI prefix, etc. `UNIMPL` means that the " +"syscall will be substituted with the `nosys` syscall (a syscall just " +"printing out a message about the syscall not being implemented and returning " +"`ENOSYS`)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:708 +msgid "" +"From [.filename]#syscalls.master# a script generates three files: [." +"filename]#linux_syscall.h#, [.filename]#linux_proto.h# and [." +"filename]#linux_sysent.c#. The [.filename]#linux_syscall.h# contains " +"definitions of syscall names and their numerical value, e.g.:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:716 +#, no-wrap +msgid "" +"...\n" +"#define LINUX_SYS_linux_fork 2\n" +"...\n" +"#define LINUX_SYS_close 6\n" +"...\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:719 +msgid "" +"The [.filename]#linux_proto.h# contains structure definitions of arguments " +"to every syscall, e.g.:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:725 +#, no-wrap +msgid "" +"struct linux_fork_args {\n" +" register_t dummy;\n" +"};\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:728 +msgid "" +"And finally, [.filename]#linux_sysent.c# contains structure describing the " +"system entry table, used to actually dispatch a syscall, e.g.:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:733 +#, no-wrap +msgid "" +"{ 0, (sy_call_t *)linux_fork, AUE_FORK, NULL, 0, 0 }, /* 2 = linux_fork */\n" +"{ AS(close_args), (sy_call_t *)close, AUE_CLOSE, NULL, 0, 0 }, /* 6 = close */\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:737 +msgid "" +"As you can see `linux_fork` is implemented in Linuxulator itself so the " +"definition is of `STD` type and has no argument, which is exhibited by the " +"dummy argument structure. On the other hand `close` is just an alias for " +"real FreeBSD man:close[2] so it has no linux arguments structure associated " +"and in the system entry table it is not prefixed with linux as it calls the " +"real man:close[2] in the kernel." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:739 +#, no-wrap +msgid "Dummy syscalls" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:745 +msgid "" +"The Linux(R) emulation layer is not complete, as some syscalls are not " +"implemented properly and some are not implemented at all. The emulation " +"layer employs a facility to mark unimplemented syscalls with the `DUMMY` " +"macro. These dummy definitions reside in [.filename]#linux_dummy.c# in a " +"form of `DUMMY(syscall);`, which is then translated to various syscall " +"auxiliary files and the implementation consists of printing a message saying " +"that this syscall is not implemented. The `UNIMPL` prototype is not used " +"because we want to be able to identify the name of the syscall that was " +"called to know what syscalls are more important to implement." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:747 +#, no-wrap +msgid "Signal handling" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:751 +msgid "" +"Signal handling is done generally in the FreeBSD kernel for all binary " +"compatibilities with a call to a compat-dependent layer. Linux(R) " +"compatibility layer defines `linux_sendsig` routine for this purpose." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:753 +#, no-wrap +msgid "Linux(R) sendsig" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:760 +msgid "" +"This routine first checks whether the signal has been installed with a " +"`SA_SIGINFO` in which case it calls `linux_rt_sendsig` routine instead. " +"Furthermore, it allocates (or reuses an already existing) signal handle " +"context, then it builds a list of arguments for the signal handler. It " +"translates the signal number based on the signal translation table, assigns " +"a handler, translates sigset. Then it saves context for the `sigreturn` " +"routine (various registers, translated trap number and signal mask). " +"Finally, it copies out the signal context to the userspace and prepares " +"context for the actual signal handler to run." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:762 +#, no-wrap +msgid "linux_rt_sendsig" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:767 +msgid "" +"This routine is similar to `linux_sendsig` just the signal context " +"preparation is different. It adds `siginfo`, `ucontext`, and some POSIX(R) " +"parts. It might be worth considering whether those two functions could not " +"be merged with a benefit of less code duplication and possibly even faster " +"execution." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:769 +#, no-wrap +msgid "linux_sigreturn" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:774 +msgid "" +"This syscall is used for return from the signal handler. It does some " +"security checks and restores the original process context. It also unmasks " +"the signal in process signal mask." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:776 +#, no-wrap +msgid "Ptrace" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:782 +msgid "" +"Many UNIX(R) derivates implement the man:ptrace[2] syscall to allow various " +"tracking and debugging features. This facility enables the tracing process " +"to obtain various information about the traced process, like register dumps, " +"any memory from the process address space, etc. and also to trace the " +"process like in stepping an instruction or between system entries (syscalls " +"and traps). man:ptrace[2] also lets you set various information in the " +"traced process (registers etc.). man:ptrace[2] is a UNIX(R)-wide standard " +"implemented in most UNIX(R)es around the world." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:788 +msgid "" +"Linux(R) emulation in FreeBSD implements the man:ptrace[2] facility in [." +"filename]#linux_ptrace.c#. The routines for converting registers between " +"Linux(R) and FreeBSD and the actual man:ptrace[2] syscall emulation " +"syscall. The syscall is a long switch block that implements its counterpart " +"in FreeBSD for every man:ptrace[2] command. The man:ptrace[2] commands are " +"mostly equal between Linux(R) and FreeBSD so usually just a small " +"modification is needed. For example, `PT_GETREGS` in Linux(R) operates on " +"direct data while FreeBSD uses a pointer to the data so after performing a " +"(native) man:ptrace[2] syscall, a copyout must be done to preserve Linux(R) " +"semantics." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:792 +msgid "" +"The man:ptrace[2] implementation in Linuxulator has some known weaknesses. " +"There have been panics seen when using `strace` (which is a man:ptrace[2] " +"consumer) in the Linuxulator environment. Also `PT_SYSCALL` is not " +"implemented." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:799 +msgid "" +"Whenever a Linux(R) process running in the emulation layer traps the trap " +"itself is handled transparently with the only exception of the trap " +"translation. Linux(R) and FreeBSD differs in opinion on what a trap is so " +"this is dealt with here. The code is actually very short:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:805 +#, no-wrap +msgid "" +"static int\n" +"translate_traps(int signal, int trap_code)\n" +"{\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:808 +#, no-wrap +msgid "" +" if (signal != SIGBUS)\n" +" return signal;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:810 +#, no-wrap +msgid " switch (trap_code) {\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:816 +#, no-wrap +msgid "" +" case T_PROTFLT:\n" +" case T_TSSFLT:\n" +" case T_DOUBLEFLT:\n" +" case T_PAGEFLT:\n" +" return SIGSEGV;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:821 +#, no-wrap +msgid "" +" default:\n" +" return signal;\n" +" }\n" +"}\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:824 +#, no-wrap +msgid "Stack fixup" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:831 +msgid "" +"The RTLD run-time link-editor expects so called AUX tags on stack during an " +"`execve` so a fixup must be done to ensure this. Of course, every RTLD " +"system is different so the emulation layer must provide its own stack fixup " +"routine to do this. So does Linuxulator. The `elf_linux_fixup` simply " +"copies out AUX tags to the stack and adjusts the stack of the user space " +"process to point right after those tags. So RTLD works in a smart way." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:833 +#, no-wrap +msgid "A.OUT support" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:840 +msgid "" +"The Linux(R) emulation layer on i386 also supports Linux(R) A.OUT binaries. " +"Pretty much everything described in the previous sections must be " +"implemented for A.OUT support (beside traps translation and signals " +"sending). The support for A.OUT binaries is no longer maintained, " +"especially the 2.6 emulation does not work with it but this does not cause " +"any problem, as the linux-base in ports probably do not support A.OUT " +"binaries at all. This support will probably be removed in future. Most of " +"the stuff necessary for loading Linux(R) A.OUT binaries is in [." +"filename]#imgact_linux.c# file." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-emulation/_index.adoc:842 +#, no-wrap +msgid "Linux(R) emulation layer -MI part" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:847 +msgid "" +"This section talks about machine independent part of the Linuxulator. It " +"covers the emulation infrastructure needed for Linux(R) 2.6 emulation, the " +"thread local storage (TLS) implementation (on i386) and futexes. Then we " +"talk briefly about some syscalls." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:849 +#, no-wrap +msgid "Description of NPTL" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:857 +msgid "" +"One of the major areas of progress in development of Linux(R) 2.6 was " +"threading. Prior to 2.6, the Linux(R) threading support was implemented in " +"the linuxthreads library. The library was a partial implementation of " +"POSIX(R) threading. The threading was implemented using separate processes " +"for each thread using the `clone` syscall to let them share the address " +"space (and other things). The main weaknesses of this approach was that " +"every thread had a different PID, signal handling was broken (from the " +"pthreads perspective), etc. Also the performance was not very good (use of " +"`SIGUSR` signals for threads synchronization, kernel resource consumption, " +"etc.) so to overcome these problems a new threading system was developed and " +"named NPTL." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:863 +msgid "" +"The NPTL library focused on two things but a third thing came along so it is " +"usually considered a part of NPTL. Those two things were embedding of " +"threads into a process structure and futexes. The additional third thing " +"was TLS, which is not directly required by NPTL but the whole NPTL userland " +"library depends on it. Those improvements yielded in much improved " +"performance and standards conformance. NPTL is a standard threading library " +"in Linux(R) systems these days." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:867 +msgid "" +"The FreeBSD Linuxulator implementation approaches the NPTL in three main " +"areas. The TLS, futexes and PID mangling, which is meant to simulate the " +"Linux(R) threads. Further sections describe each of these areas." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:869 +#, no-wrap +msgid "Linux(R) 2.6 emulation infrastructure" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:872 +msgid "" +"These sections deal with the way Linux(R) threads are managed and how we " +"simulate that in FreeBSD." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:874 +#, no-wrap +msgid "Runtime determining of 2.6 emulation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:883 +msgid "" +"The Linux(R) emulation layer in FreeBSD supports runtime setting of the " +"emulated version. This is done via man:sysctl[8], namely `compat.linux." +"osrelease`. Setting this man:sysctl[8] affects runtime behavior of the " +"emulation layer. When set to 2.6.x it sets the value of `linux_use_linux26` " +"while setting to something else keeps it unset. This variable (plus per-" +"prison variables of the very same kind) determines whether 2.6 " +"infrastructure (mainly PID mangling) is used in the code or not. The " +"version setting is done system-wide and this affects all Linux(R) " +"processes. The man:sysctl[8] should not be changed when running any " +"Linux(R) binary as it might harm things." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:885 +#, no-wrap +msgid "Linux(R) processes and thread identifiers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:892 +msgid "" +"The semantics of Linux(R) threading are a little confusing and uses entirely " +"different nomenclature to FreeBSD. A process in Linux(R) consists of a " +"`struct task` embedding two identifier fields - PID and TGID. PID is _not_ " +"a process ID but it is a thread ID. The TGID identifies a thread group in " +"other words a process. For single-threaded process the PID equals the TGID." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:898 +msgid "" +"The thread in NPTL is just an ordinary process that happens to have TGID not " +"equal to PID and have a group leader not equal to itself (and shared VM etc. " +"of course). Everything else happens in the same way as to an ordinary " +"process. There is no separation of a shared status to some external " +"structure like in FreeBSD. This creates some duplication of information and " +"possible data inconsistency. The Linux(R) kernel seems to use task -> group " +"information in some places and task information elsewhere and it is really " +"not very consistent and looks error-prone." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:901 +msgid "" +"Every NPTL thread is created by a call to the `clone` syscall with a " +"specific set of flags (more in the next subsection). The NPTL implements " +"strict 1:1 threading." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:903 +msgid "" +"In FreeBSD we emulate NPTL threads with ordinary FreeBSD processes that " +"share VM space, etc. and the PID gymnastic is just mimicked in the emulation " +"specific structure attached to the process. The structure attached to the " +"process looks like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:908 +#, no-wrap +msgid "" +"struct linux_emuldata {\n" +" pid_t pid;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:911 +#, no-wrap +msgid "" +" int *child_set_tid; /* in clone(): Child.s TID to set on clone */\n" +" int *child_clear_tid;/* in clone(): Child.s TID to clear on exit */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:913 +#, no-wrap +msgid " struct linux_emuldata_shared *shared;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:915 +#, no-wrap +msgid " int pdeath_signal; /* parent death signal */\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:918 +#, no-wrap +msgid "" +" LIST_ENTRY(linux_emuldata) threads; /* list of linux threads */\n" +"};\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:925 +msgid "" +"The PID is used to identify the FreeBSD process that attaches this " +"structure. The `child_se_tid` and `child_clear_tid` are used for TID " +"address copyout when a process exits and is created. The `shared` pointer " +"points to a structure shared among threads. The `pdeath_signal` variable " +"identifies the parent death signal and the `threads` pointer is used to link " +"this structure to the list of threads. The `linux_emuldata_shared` " +"structure looks like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:929 +#, no-wrap +msgid "struct linux_emuldata_shared {\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:931 +#, no-wrap +msgid " int refs;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:933 +#, no-wrap +msgid " pid_t group_pid;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:936 +#, no-wrap +msgid "" +" LIST_HEAD(, linux_emuldata) threads; /* head of list of linux threads */\n" +"};\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:941 +msgid "" +"The `refs` is a reference counter being used to determine when we can free " +"the structure to avoid memory leaks. The `group_pid` is to identify PID ( = " +"TGID) of the whole process ( = thread group). The `threads` pointer is the " +"head of the list of threads in the process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:944 +msgid "" +"The `linux_emuldata` structure can be obtained from the process using " +"`em_find`. The prototype of the function is:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:948 +#, no-wrap +msgid "struct linux_emuldata *em_find(struct proc *, int locked);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:953 +msgid "" +"Here, `proc` is the process we want the emuldata structure from and the " +"locked parameter determines whether we want to lock or not. The accepted " +"values are `EMUL_DOLOCK` and `EMUL_DOUNLOCK`. More about locking later." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:955 +#, no-wrap +msgid "PID mangling" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:962 +msgid "" +"As there is a difference in view as what to the idea of a process ID and " +"thread ID is between FreeBSD and Linux(R) we have to translate the view " +"somehow. We do it by PID mangling. This means that we fake what a PID " +"(=TGID) and TID (=PID) is between kernel and userland. The rule of thumb is " +"that in kernel (in Linuxulator) PID = PID and TGID = shared -> group pid and " +"to userland we present `PID = shared -> group_pid` and `TID = proc -> " +"p_pid`. The PID member of `linux_emuldata structure` is a FreeBSD PID." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:966 +msgid "" +"The above affects mainly getpid, getppid, gettid syscalls. Where we use PID/" +"TGID respectively. In copyout of TIDs in `child_clear_tid` and " +"`child_set_tid` we copy out FreeBSD PID." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:968 +#, no-wrap +msgid "Clone syscall" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:972 +msgid "" +"The `clone` syscall is the way threads are created in Linux(R). The syscall " +"prototype looks like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:977 +#, no-wrap +msgid "" +"int linux_clone(l_int flags, void *stack, void *parent_tidptr, int dummy,\n" +"void * child_tidptr);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:987 +msgid "" +"The `flags` parameter tells the syscall how exactly the processes should be " +"cloned. As described above, Linux(R) can create processes sharing various " +"things independently, for example two processes can share file descriptors " +"but not VM, etc. Last byte of the `flags` parameter is the exit signal of " +"the newly created process. The `stack` parameter if non-`NULL` tells, where " +"the thread stack is and if it is `NULL` we are supposed to copy-on-write the " +"calling process stack (i.e. do what normal man:fork[2] routine does). The " +"`parent_tidptr` parameter is used as an address for copying out process PID " +"(i.e. thread id) once the process is sufficiently instantiated but is not " +"runnable yet. The `dummy` parameter is here because of the very strange " +"calling convention of this syscall on i386. It uses the registers directly " +"and does not let the compiler do it what results in the need of a dummy " +"syscall. The `child_tidptr` parameter is used as an address for copying out " +"PID once the process has finished forking and when the process exits." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1001 +msgid "" +"The syscall itself proceeds by setting corresponding flags depending on the " +"flags passed in. For example, `CLONE_VM` maps to RFMEM (sharing of VM), " +"etc. The only nit here is `CLONE_FS` and `CLONE_FILES` because FreeBSD does " +"not allow setting this separately so we fake it by not setting RFFDG " +"(copying of fd table and other fs information) if either of these is " +"defined. This does not cause any problems, because those flags are always " +"set together. After setting the flags the process is forked using the " +"internal `fork1` routine, the process is instrumented not to be put on a run " +"queue, i.e. not to be set runnable. After the forking is done we possibly " +"reparent the newly created process to emulate `CLONE_PARENT` semantics. " +"Next part is creating the emulation data. Threads in Linux(R) does not " +"signal their parents so we set exit signal to be 0 to disable this. After " +"that setting of `child_set_tid` and `child_clear_tid` is performed enabling " +"the functionality later in the code. At this point we copy out the PID to " +"the address specified by `parent_tidptr`. The setting of process stack is " +"done by simply rewriting thread frame `%esp` register (`%rsp` on amd64). " +"Next part is setting up TLS for the newly created process. After this man:" +"vfork[2] semantics might be emulated and finally the newly created process " +"is put on a run queue and copying out its PID to the parent process via " +"`clone` return value is done." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1004 +msgid "" +"The `clone` syscall is able and in fact is used for emulating classic man:" +"fork[2] and man:vfork[2] syscalls. Newer glibc in a case of 2.6 kernel uses " +"`clone` to implement man:fork[2] and man:vfork[2] syscalls." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1006 +#, no-wrap +msgid "Locking" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1012 +msgid "" +"The locking is implemented to be per-subsystem because we do not expect a " +"lot of contention on these. There are two locks: `emul_lock` used to " +"protect manipulating of `linux_emuldata` and `emul_shared_lock` used to " +"manipulate `linux_emuldata_shared`. The `emul_lock` is a nonsleepable " +"blocking mutex while `emul_shared_lock` is a sleepable blocking `sx_lock`. " +"Due to of the per-subsystem locking we can coalesce some locks and that is " +"why the em find offers the non-locking access." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:1014 +#, no-wrap +msgid "TLS" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1017 +msgid "This section deals with TLS also known as thread local storage." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1019 +#, no-wrap +msgid "Introduction to threading" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1040 +msgid "" +"Threads in computer science are entities within a process that can be " +"scheduled independently from each other. The threads in the process share " +"process wide data (file descriptors, etc.) but also have their own stack for " +"their own data. Sometimes there is a need for process-wide data specific to " +"a given thread. Imagine a name of the thread in execution or something like " +"that. The traditional UNIX(R) threading API, pthreads provides a way to do " +"it via man:pthread_key_create[3], man:pthread_setspecific[3] and man:" +"pthread_getspecific[3] where a thread can create a key to the thread local " +"data and using man:pthread_getspecific[3] or man:pthread_getspecific[3] to " +"manipulate those data. You can easily see that this is not the most " +"comfortable way this could be accomplished. So various producers of C/C++ " +"compilers introduced a better way. They defined a new modifier keyword " +"thread that specifies that a variable is thread specific. A new method of " +"accessing such variables was developed as well (at least on i386). The " +"pthreads method tends to be implemented in userspace as a trivial lookup " +"table. The performance of such a solution is not very good. So the new " +"method uses (on i386) segment registers to address a segment, where TLS area " +"is stored so the actual accessing of a thread variable is just appending the " +"segment register to the address thus addressing via it. The segment " +"registers are usually `%gs` and `%fs` acting like segment selectors. Every " +"thread has its own area where the thread local data are stored and the " +"segment must be loaded on every context switch. This method is very fast " +"and used almost exclusively in the whole i386 UNIX(R) world. Both FreeBSD " +"and Linux(R) implement this approach and it yields very good results. The " +"only drawback is the need to reload the segment on every context switch " +"which can slowdown context switches. FreeBSD tries to avoid this overhead " +"by using only 1 segment descriptor for this while Linux(R) uses 3. " +"Interesting thing is that almost nothing uses more than 1 descriptor (only " +"Wine seems to use 2) so Linux(R) pays this unnecessary price for context " +"switches." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1042 +#, no-wrap +msgid "Segments on i386" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1049 +msgid "" +"The i386 architecture implements the so called segments. A segment is a " +"description of an area of memory. The base address (bottom) of the memory " +"area, the end of it (ceiling), type, protection, etc. The memory described " +"by a segment can be accessed using segment selector registers (`%cs`, `%ds`, " +"`%ss`, `%es`, `%fs`, `%gs`). For example let us suppose we have a segment " +"which base address is 0x1234 and length and this code:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1053 +#, no-wrap +msgid "mov %edx,%gs:0x10\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1062 +msgid "" +"This will load the content of the `%edx` register into memory location " +"0x1244. Some segment registers have a special use, for example `%cs` is " +"used for code segment and `%ss` is used for stack segment but `%fs` and " +"`%gs` are generally unused. Segments are either stored in a global GDT " +"table or in a local LDT table. LDT is accessed via an entry in the GDT. " +"The LDT can store more types of segments. LDT can be per process. Both " +"tables define up to 8191 entries." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1064 +#, no-wrap +msgid "Implementation on Linux(R) i386" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1072 +msgid "" +"There are two main ways of setting up TLS in Linux(R). It can be set when " +"cloning a process using the `clone` syscall or it can call " +"`set_thread_area`. When a process passes `CLONE_SETTLS` flag to `clone`, " +"the kernel expects the memory pointed to by the `%esi` register a Linux(R) " +"user space representation of a segment, which gets translated to the machine " +"representation of a segment and loaded into a GDT slot. The GDT slot can be " +"specified with a number or -1 can be used meaning that the system itself " +"should choose the first free slot. In practice, the vast majority of " +"programs use only one TLS entry and does not care about the number of the " +"entry. We exploit this in the emulation and in fact depend on it." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1074 +#, no-wrap +msgid "Emulation of Linux(R) TLS" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1077 +#, no-wrap +msgid "i386" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1095 +msgid "" +"Loading of TLS for the current thread happens by calling `set_thread_area` " +"while loading TLS for a second process in `clone` is done in the separate " +"block in `clone`. Those two functions are very similar. The only " +"difference being the actual loading of the GDT segment, which happens on the " +"next context switch for the newly created process while `set_thread_area` " +"must load this directly. The code basically does this. It copies the " +"Linux(R) form segment descriptor from the userland. The code checks for the " +"number of the descriptor but because this differs between FreeBSD and " +"Linux(R) we fake it a little. We only support indexes of 6, 3 and -1. The " +"6 is genuine Linux(R) number, 3 is genuine FreeBSD one and -1 means " +"autoselection. Then we set the descriptor number to constant 3 and copy out " +"this to the userspace. We rely on the userspace process using the number " +"from the descriptor but this works most of the time (have never seen a case " +"where this did not work) as the userspace process typically passes in 1. " +"Then we convert the descriptor from the Linux(R) form to a machine dependant " +"form (i.e. operating system independent form) and copy this to the FreeBSD " +"defined segment descriptor. Finally we can load it. We assign the " +"descriptor to threads PCB (process control block) and load the `%gs` segment " +"using `load_gs`. This loading must be done in a critical section so that " +"nothing can interrupt us. The `CLONE_SETTLS` case works exactly like this " +"just the loading using `load_gs` is not performed. The segment used for " +"this (segment number 3) is shared for this use between FreeBSD processes and " +"Linux(R) processes so the Linux(R) emulation layer does not add any overhead " +"over plain FreeBSD." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1097 +#, no-wrap +msgid "amd64" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1101 +msgid "" +"The amd64 implementation is similar to the i386 one but there was initially " +"no 32bit segment descriptor used for this purpose (hence not even native " +"32bit TLS users worked) so we had to add such a segment and implement its " +"loading on every context switch (when a flag signaling use of 32bit is " +"set). Apart from this the TLS loading is exactly the same just the segment " +"numbers are different and the descriptor format and the loading differs " +"slightly." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:1103 +#, no-wrap +msgid "Futexes" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1106 +#, no-wrap +msgid "Introduction to synchronization" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1116 +msgid "" +"Threads need some kind of synchronization and POSIX(R) provides some of " +"them: mutexes for mutual exclusion, read-write locks for mutual exclusion " +"with biased ratio of reads and writes and condition variables for signaling " +"a status change. It is interesting to note that POSIX(R) threading API " +"lacks support for semaphores. Those synchronization routines " +"implementations are heavily dependant on the type threading support we " +"have. In pure 1:M (userspace) model the implementation can be solely done " +"in userspace and thus be very fast (the condition variables will probably " +"end up being implemented using signals, i.e. not fast) and simple. In 1:1 " +"model, the situation is also quite clear - the threads must be synchronized " +"using kernel facilities (which is very slow because a syscall must be " +"performed). The mixed M:N scenario just combines the first and second " +"approach or rely solely on kernel. Threads synchronization is a vital part " +"of thread-enabled programming and its performance can affect resulting " +"program a lot. Recent benchmarks on FreeBSD operating system showed that an " +"improved sx_lock implementation yielded 40% speedup in _ZFS_ (a heavy sx " +"user), this is in-kernel stuff but it shows clearly how important the " +"performance of synchronization primitives is." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1120 +msgid "" +"Threaded programs should be written with as little contention on locks as " +"possible. Otherwise, instead of doing useful work the thread just waits on " +"a lock. As a result of this, the most well written threaded programs show " +"little locks contention." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1122 +#, no-wrap +msgid "Futexes introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1127 +msgid "" +"Linux(R) implements 1:1 threading, i.e. it has to use in-kernel " +"synchronization primitives. As stated earlier, well written threaded " +"programs have little lock contention. So a typical sequence could be " +"performed as two atomic increase/decrease mutex reference counter, which is " +"very fast, as presented by the following example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1133 +#, no-wrap +msgid "" +"pthread_mutex_lock(&mutex);\n" +"...\n" +"pthread_mutex_unlock(&mutex);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1136 +msgid "" +"1:1 threading forces us to perform two syscalls for those mutex calls, which " +"is very slow." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1141 +msgid "" +"The solution Linux(R) 2.6 implements is called futexes. Futexes implement " +"the check for contention in userspace and call kernel primitives only in a " +"case of contention. Thus the typical case takes place without any kernel " +"intervention. This yields reasonably fast and flexible synchronization " +"primitives implementation." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1143 +#, no-wrap +msgid "Futex API" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1146 +msgid "The futex syscall looks like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1150 +#, no-wrap +msgid "int futex(void *uaddr, int op, int val, struct timespec *timeout, void *uaddr2, int val3);\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1153 +msgid "" +"In this example `uaddr` is an address of the mutex in userspace, `op` is an " +"operation we are about to perform and the other parameters have per-" +"operation meaning." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1155 +msgid "Futexes implement the following operations:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1157 +msgid "`FUTEX_WAIT`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1158 +msgid "`FUTEX_WAKE`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1159 +msgid "`FUTEX_FD`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1160 +msgid "`FUTEX_REQUEUE`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1161 +msgid "`FUTEX_CMP_REQUEUE`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1162 +msgid "`FUTEX_WAKE_OP`" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1164 +#, no-wrap +msgid "FUTEX_WAIT" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1169 +msgid "" +"This operation verifies that on address `uaddr` the value `val` is written. " +"If not, `EWOULDBLOCK` is returned, otherwise the thread is queued on the " +"futex and gets suspended. If the argument `timeout` is non-zero it " +"specifies the maximum time for the sleeping, otherwise the sleeping is " +"infinite." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1171 +#, no-wrap +msgid "FUTEX_WAKE" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1174 +msgid "" +"This operation takes a futex at `uaddr` and wakes up `val` first futexes " +"queued on this futex." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1176 +#, no-wrap +msgid "FUTEX_FD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1179 +msgid "This operations associates a file descriptor with a given futex." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1181 +#, no-wrap +msgid "FUTEX_REQUEUE" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1184 +msgid "" +"This operation takes `val` threads queued on futex at `uaddr`, wakes them " +"up, and takes `val2` next threads and requeues them on futex at `uaddr2`." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1186 +#, no-wrap +msgid "FUTEX_CMP_REQUEUE" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1189 +msgid "" +"This operation does the same as `FUTEX_REQUEUE` but it checks that `val3` " +"equals to `val` first." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1191 +#, no-wrap +msgid "FUTEX_WAKE_OP" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1195 +msgid "" +"This operation performs an atomic operation on `val3` (which contains coded " +"some other value) and `uaddr`. Then it wakes up `val` threads on futex at " +"`uaddr` and if the atomic operation returned a positive number it wakes up " +"`val2` threads on futex at `uaddr2`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1197 +msgid "The operations implemented in `FUTEX_WAKE_OP`:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1199 +msgid "`FUTEX_OP_SET`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1200 +msgid "`FUTEX_OP_ADD`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1201 +msgid "`FUTEX_OP_OR`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1202 +msgid "`FUTEX_OP_AND`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1203 +msgid "`FUTEX_OP_XOR`" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1208 +msgid "" +"There is no `val2` parameter in the futex prototype. The `val2` is taken " +"from the `struct timespec *timeout` parameter for operations " +"`FUTEX_REQUEUE`, `FUTEX_CMP_REQUEUE` and `FUTEX_WAKE_OP`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1211 +#, no-wrap +msgid "Futex emulation in FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1216 +msgid "" +"The futex emulation in FreeBSD is taken from NetBSD and further extended by " +"us. It is placed in `linux_futex.c` and [.filename]#linux_futex.h# files. " +"The `futex` structure looks like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1222 +#, no-wrap +msgid "" +"struct futex {\n" +" void *f_uaddr;\n" +" int f_refcount;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1224 +#, no-wrap +msgid " LIST_ENTRY(futex) f_list;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1227 +#, no-wrap +msgid "" +" TAILQ_HEAD(lf_waiting_paroc, waiting_proc) f_waiting_proc;\n" +"};\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1230 +msgid "And the structure `waiting_proc` is:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1234 +#, no-wrap +msgid "struct waiting_proc {\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1236 +#, no-wrap +msgid " struct thread *wp_t;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1238 +#, no-wrap +msgid " struct futex *wp_new_futex;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1241 +#, no-wrap +msgid "" +" TAILQ_ENTRY(waiting_proc) wp_list;\n" +"};\n" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1244 +#, no-wrap +msgid "futex_get / futex_put" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1248 +msgid "" +"A futex is obtained using the `futex_get` function, which searches a linear " +"list of futexes and returns the found one or creates a new futex. When " +"releasing a futex from the use we call the `futex_put` function, which " +"decreases a reference counter of the futex and if the refcount reaches zero " +"it is released." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1250 +#, no-wrap +msgid "futex_sleep" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1258 +msgid "" +"When a futex queues a thread for sleeping it creates a `working_proc` " +"structure and puts this structure to the list inside the futex structure " +"then it just performs a man:tsleep[9] to suspend the thread. The sleep can " +"be timed out. After man:tsleep[9] returns (the thread was woken up or it " +"timed out) the `working_proc` structure is removed from the list and is " +"destroyed. All this is done in the `futex_sleep` function. If we got woken " +"up from `futex_wake` we have `wp_new_futex` set so we sleep on it. This way " +"the actual requeueing is done in this function." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1260 +#, no-wrap +msgid "futex_wake" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1268 +msgid "" +"Waking up a thread sleeping on a futex is performed in the `futex_wake` " +"function. First in this function we mimic the strange Linux(R) behavior, " +"where it wakes up N threads for all operations, the only exception is that " +"the REQUEUE operations are performed on N+1 threads. But this usually does " +"not make any difference as we are waking up all threads. Next in the " +"function in the loop we wake up n threads, after this we check if there is a " +"new futex for requeueing. If so, we requeue up to n2 threads on the new " +"futex. This cooperates with `futex_sleep`." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1270 +#, no-wrap +msgid "futex_wake_op" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1275 +msgid "" +"The `FUTEX_WAKE_OP` operation is quite complicated. First we obtain two " +"futexes at addresses `uaddr` and `uaddr2` then we perform the atomic " +"operation using `val3` and `uaddr2`. Then `val` waiters on the first futex " +"is woken up and if the atomic operation condition holds we wake up `val2` (i." +"e. `timeout`) waiter on the second futex." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1277 +#, no-wrap +msgid "futex atomic operation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1282 +msgid "" +"The atomic operation takes two parameters `encoded_op` and `uaddr`. The " +"encoded operation encodes the operation itself, comparing value, operation " +"argument, and comparing argument. The pseudocode for the operation is like " +"this one:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1287 +#, no-wrap +msgid "" +"oldval = *uaddr2\n" +"*uaddr2 = oldval OP oparg\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1291 +msgid "" +"And this is done atomically. First a copying in of the number at `uaddr` is " +"performed and the operation is done. The code handles page faults and if no " +"page fault occurs `oldval` is compared to `cmparg` argument with cmp " +"comparator." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1293 +#, no-wrap +msgid "Futex locking" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1297 +msgid "" +"Futex implementation uses two lock lists protecting `sx_lock` and global " +"locks (either Giant or another `sx_lock`). Every operation is performed " +"locked from the start to the very end." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:1299 +#, no-wrap +msgid "Various syscalls implementation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1302 +msgid "" +"In this section I am going to describe some smaller syscalls that are worth " +"mentioning because their implementation is not obvious or those syscalls are " +"interesting from other point of view." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1304 +#, no-wrap +msgid "*at family of syscalls" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1313 +msgid "" +"During development of Linux(R) 2.6.16 kernel, the *at syscalls were added. " +"Those syscalls (`openat` for example) work exactly like their at-less " +"counterparts with the slight exception of the `dirfd` parameter. This " +"parameter changes where the given file, on which the syscall is to be " +"performed, is. When the `filename` parameter is absolute `dirfd` is ignored " +"but when the path to the file is relative, it comes to the play. The " +"`dirfd` parameter is a directory relative to which the relative pathname is " +"checked. The `dirfd` parameter is a file descriptor of some directory or " +"`AT_FDCWD`. So for example the `openat` syscall can be like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1317 +#, no-wrap +msgid "file descriptor 123 = /tmp/foo/, current working directory = /tmp/\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1322 +#, no-wrap +msgid "" +"openat(123, /tmp/bah\\, flags, mode)\t/* opens /tmp/bah */\n" +"openat(123, bah\\, flags, mode)\t\t/* opens /tmp/foo/bah */\n" +"openat(AT_FDWCWD, bah\\, flags, mode)\t/* opens /tmp/bah */\n" +"openat(stdio, bah\\, flags, mode)\t/* returns error because stdio is not a directory */\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1331 +msgid "" +"This infrastructure is necessary to avoid races when opening files outside " +"the working directory. Imagine that a process consists of two threads, " +"thread A and thread B. Thread A issues `open(./tmp/foo/bah., flags, mode)` " +"and before returning it gets preempted and thread B runs. Thread B does not " +"care about the needs of thread A and renames or removes [.filename]#/tmp/foo/" +"#. We got a race. To avoid this we can open [.filename]#/tmp/foo# and use " +"it as `dirfd` for `openat` syscall. This also enables user to implement per-" +"thread working directories." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1334 +msgid "" +"Linux(R) family of *at syscalls contains: `linux_openat`, `linux_mkdirat`, " +"`linux_mknodat`, `linux_fchownat`, `linux_futimesat`, `linux_fstatat64`, " +"`linux_unlinkat`, `linux_renameat`, `linux_linkat`, `linux_symlinkat`, " +"`linux_readlinkat`, `linux_fchmodat` and `linux_faccessat`. All these are " +"implemented using the modified man:namei[9] routine and simple wrapping " +"layer." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1336 +#, no-wrap +msgid "Implementation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1344 +msgid "" +"The implementation is done by altering the man:namei[9] routine (described " +"above) to take additional parameter `dirfd` in its `nameidata` structure, " +"which specifies the starting point of the pathname lookup instead of using " +"the current working directory every time. The resolution of `dirfd` from " +"file descriptor number to a vnode is done in native *at syscalls. When " +"`dirfd` is `AT_FDCWD` the `dvp` entry in `nameidata` structure is `NULL` but " +"when `dirfd` is a different number we obtain a file for this file " +"descriptor, check whether this file is valid and if there is vnode attached " +"to it then we get a vnode. Then we check this vnode for being a directory. " +"In the actual man:namei[9] routine we simply substitute the `dvp` vnode for " +"`dp` variable in the man:namei[9] function, which determines the starting " +"point. The man:namei[9] is not used directly but via a trace of different " +"functions on various levels. For example the `openat` goes like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-emulation/_index.adoc:1348 +#, no-wrap +msgid "openat() --> kern_openat() --> vn_open() -> namei()\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1354 +msgid "" +"For this reason `kern_open` and `vn_open` must be altered to incorporate the " +"additional `dirfd` parameter. No compat layer is created for those because " +"there are not many users of this and the users can be easily converted. " +"This general implementation enables FreeBSD to implement their own *at " +"syscalls. This is being discussed right now." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1356 +#, no-wrap +msgid "Ioctl" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1370 +msgid "" +"The ioctl interface is quite fragile due to its generality. We have to bear " +"in mind that devices differ between Linux(R) and FreeBSD so some care must " +"be applied to do ioctl emulation work right. The ioctl handling is " +"implemented in [.filename]#linux_ioctl.c#, where `linux_ioctl` function is " +"defined. This function simply iterates over sets of ioctl handlers to find " +"a handler that implements a given command. The ioctl syscall has three " +"parameters, the file descriptor, command and an argument. The command is a " +"16-bit number, which in theory is divided into high 8 bits determining class " +"of the ioctl command and low 8 bits, which are the actual command within the " +"given set. The emulation takes advantage of this division. We implement " +"handlers for each set, like `sound_handler` or `disk_handler`. Each handler " +"has a maximum command and a minimum command defined, which is used for " +"determining what handler is used. There are slight problems with this " +"approach because Linux(R) does not use the set division consistently so " +"sometimes ioctls for a different set are inside a set they should not belong " +"to (SCSI generic ioctls inside cdrom set, etc.). FreeBSD currently does not " +"implement many Linux(R) ioctls (compared to NetBSD, for example) but the " +"plan is to port those from NetBSD. The trend is to use Linux(R) ioctls even " +"in the native FreeBSD drivers because of the easy porting of applications." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/linux-emulation/_index.adoc:1372 +#, no-wrap +msgid "Debugging" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1379 +msgid "" +"Every syscall should be debuggable. For this purpose we introduce a small " +"infrastructure. We have the ldebug facility, which tells whether a given " +"syscall should be debugged (settable via a sysctl). For printing we have " +"LMSG and ARGS macros. Those are used for altering a printable string for " +"uniform debugging messages." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-emulation/_index.adoc:1381 +#, no-wrap +msgid "Conclusion" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:1384 +#, no-wrap +msgid "Results" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1390 +msgid "" +"As of April 2007 the Linux(R) emulation layer is capable of emulating the " +"Linux(R) 2.6.16 kernel quite well. The remaining problems concern futexes, " +"unfinished *at family of syscalls, problematic signals delivery, missing " +"`epoll` and `inotify` and probably some bugs we have not discovered yet. " +"Despite this we are capable of running basically all the Linux(R) programs " +"included in FreeBSD Ports Collection with Fedora Core 4 at 2.6.16 and there " +"are some rudimentary reports of success with Fedora Core 6 at 2.6.16. The " +"Fedora Core 6 linux_base was recently committed enabling some further " +"testing of the emulation layer and giving us some more hints where we should " +"put our effort in implementing missing stuff." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1394 +msgid "" +"We are able to run the most used applications like package:www/linux-" +"firefox[], package:net-im/skype[] and some games from the Ports Collection. " +"Some of the programs exhibit bad behavior under 2.6 emulation but this is " +"currently under investigation and hopefully will be fixed soon. The only " +"big application that is known not to work is the Linux(R) Java(TM) " +"Development Kit and this is because of the requirement of `epoll` facility " +"which is not directly related to the Linux(R) kernel 2.6." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1397 +msgid "" +"We hope to enable 2.6.16 emulation by default some time after FreeBSD 7.0 is " +"released at least to expose the 2.6 emulation parts for some wider testing. " +"Once this is done we can switch to Fedora Core 6 linux_base, which is the " +"ultimate plan." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:1399 +#, no-wrap +msgid "Future work" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1402 +msgid "" +"Future work should focus on fixing the remaining issues with futexes, " +"implement the rest of the *at family of syscalls, fix the signal delivery " +"and possibly implement the `epoll` and `inotify` facilities." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1404 +msgid "" +"We hope to be able to run the most important programs flawlessly soon, so we " +"will be able to switch to the 2.6 emulation by default and make the Fedora " +"Core 6 the default linux_base because our currently used Fedora Core 4 is " +"not supported any more." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1408 +msgid "" +"The other possible goal is to share our code with NetBSD and DragonflyBSD. " +"NetBSD has some support for 2.6 emulation but its far from finished and not " +"really tested. DragonflyBSD has expressed some interest in porting the 2.6 " +"improvements." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1413 +msgid "" +"Generally, as Linux(R) develops we would like to keep up with their " +"development, implementing newly added syscalls. Splice comes to mind " +"first. Some already implemented syscalls are also suboptimal, for example " +"`mremap` and others. Some performance improvements can also be made, finer " +"grained locking and others." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-emulation/_index.adoc:1415 +#, no-wrap +msgid "Team" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1418 +msgid "I cooperated on this project with (in alphabetical order):" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1420 +msgid "`{jhb}`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1421 +msgid "`{kib}`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1422 +msgid "Emmanuel Dreyfus" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1423 +msgid "Scot Hetzel" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1424 +msgid "`{jkim}`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1425 +msgid "`{netchild}`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1426 +msgid "`{ssouhlal}`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1427 +msgid "Li Xiao" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1428 +msgid "`{davidxu}`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1430 +msgid "" +"I would like to thank all those people for their advice, code reviews and " +"general support." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-emulation/_index.adoc:1432 +#, no-wrap +msgid "Literatures" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1435 +msgid "" +"Marshall Kirk McKusick - George V. Nevile-Neil. Design and Implementation of " +"the FreeBSD operating system. Addison-Wesley, 2005." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1436 +msgid "https://tldp.org[https://tldp.org]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-emulation/_index.adoc:1436 +msgid "https://www.kernel.org[https://www.kernel.org]" +msgstr "" diff --git a/documentation/content/en/articles/linux-users/_index.adoc b/documentation/content/en/articles/linux-users/_index.adoc index 37f9a4126d..343b523c6b 100644 --- a/documentation/content/en/articles/linux-users/_index.adoc +++ b/documentation/content/en/articles/linux-users/_index.adoc @@ -54,18 +54,19 @@ toc::[] This document highlights some of the technical differences between FreeBSD and Linux(R) so that intermediate to advanced Linux(R) users can quickly familiarize themselves with the basics of FreeBSD. This document assumes that FreeBSD is already installed. -Refer to the extref:{handbook}[Installing FreeBSD, bsdinstall] chapter of the FreeBSD Handbook for help with the installation process. +Refer to the extref:{handbook}bsdinstall[Installing FreeBSD, bsdinstall] chapter of the FreeBSD Handbook for help with the installation process. [[shells]] == Default Shell Linux(R) users are often surprised to find that Bash is not the default shell in FreeBSD. In fact, Bash is not included in the default installation. -Instead, FreeBSD uses man:tcsh[1] as the default root shell, and the Bourne shell-compatible man:sh[1] as the default user shell. +Instead, the Bourne shell-compatible man:sh[1] as the default user shell. +The root shell is man:tcsh[1] by default on FreeBSD 13 and earlier and man:sh[1] on FreeBSD 14 and later. man:sh[1] is very similar to Bash but with a much smaller feature-set. Generally shell scripts written for man:sh[1] will run in Bash, but the reverse is not always true. -However, Bash and other shells are available for installation using the FreeBSD extref:{handbook}[Packages and Ports Collection, ports]. +However, Bash and other shells are available for installation using the FreeBSD extref:{handbook}ports[Packages and Ports Collection, ports]. After installing another shell, use man:chsh[1] to change a user's default shell. It is recommended that the `root` user's default shell remain unchanged since shells which are not included in the base distribution are installed to [.filename]#/usr/local/bin#. @@ -91,7 +92,7 @@ If an application installation does not require any customization, installing th Compile the port instead whenever an application requires customization of the default options. If needed, a custom package can be compiled from ports using `make package`. -A complete list of all available ports and packages can be found https://www.freebsd.org/ports/[here]. +A complete list of all available ports and packages can be found https://ports.freebsd.org[here]. [[packages]] === Packages @@ -105,7 +106,7 @@ For example, the following command installs Apache 2.4: # pkg install apache24 .... -For more information on packages refer to section 5.4 of the FreeBSD Handbook: extref:{handbook}[Using pkgng for Binary Package Management, pkgng-intro]. +For more information on packages refer to section 4.4 of the FreeBSD Handbook: extref:{handbook}ports[Using pkgng for Binary Package Management, pkgng-intro]. [[ports]] === Ports @@ -113,8 +114,8 @@ For more information on packages refer to section 5.4 of the FreeBSD Handbook: e The FreeBSD Ports Collection is a framework of [.filename]#Makefiles# and patches specifically customized for installing applications from source on FreeBSD. When installing a port, the system will fetch the source code, apply any required patches, compile the code, and install the application and any required dependencies. -The Ports Collection, sometimes referred to as the ports tree, can be installed to [.filename]#/usr/ports# using man:portsnap[8]. -Detailed instructions for installing the Ports Collection can be found in extref:{handbook}[section 5.5, ports-using] of the FreeBSD Handbook. +The Ports Collection, sometimes referred to as the ports tree, can be installed to [.filename]#/usr/ports# using link:{handbook}mirrors/#git[Git]. +Detailed instructions for installing the Ports Collection can be found in extref:{handbook}ports[section 4.5.1, ports-using-installation-methods] of the FreeBSD Handbook. To compile a port, change to the port's directory and start the build process. The following example installs Apache 2.4 from the Ports Collection: @@ -133,7 +134,7 @@ This example specifies that the mod_ldap module should also be installed: # make WITH_LDAP="YES" install clean .... -Refer to extref:{handbook}[Using the Ports Collection, ports-using] for more information. +Refer to extref:{handbook}ports[Using the Ports Collection, ports-using] for more information. [[startup]] == System Startup @@ -141,14 +142,14 @@ Refer to extref:{handbook}[Using the Ports Collection, ports-using] for more inf Many Linux(R) distributions use the SysV init system, whereas FreeBSD uses the traditional BSD-style man:init[8]. Under the BSD-style man:init[8], there are no run-levels and [.filename]#/etc/inittab# does not exist. Instead, startup is controlled by man:rc[8] scripts. -At system boot, [.filename]#/etc/rc# reads [.filename]#/etc/rc.conf# and [.filename]#/etc/defaults/rc.conf# to determine which services are to be started. +At system boot, [.filename]#/etc/rc# reads [.filename]#/etc/rc.conf# and [.filename]#/etc/defaults/rc.conf# to determine which services are to be started. The specified services are then started by running the corresponding service initialization scripts located in [.filename]#/etc/rc.d/# and [.filename]#/usr/local/etc/rc.d/#. These scripts are similar to the scripts located in [.filename]#/etc/init.d/# on Linux(R) systems. -The scripts found in [.filename]#/etc/rc.d/# are for applications that are part of the "base" system, such as man:cron[8], man:sshd[8], and man:syslog[3]. +The scripts found in [.filename]#/etc/rc.d/# are for applications that are part of the "base" system, such as man:cron[8], man:sshd[8], and man:syslog[3]. The scripts in [.filename]#/usr/local/etc/rc.d/# are for user-installed applications such as Apache and Squid. Since FreeBSD is developed as a complete operating system, user-installed applications are not considered to be part of the "base" system. -User-installed applications are generally installed using extref:{handbook}[Packages or Ports, ports-using]. +User-installed applications are generally installed using extref:{handbook}ports[Packages or Ports, ports-using]. In order to keep them separate from the base system, user-installed applications are installed under [.filename]#/usr/local/#. Therefore, user-installed binaries reside in [.filename]#/usr/local/bin/#, configuration files are in [.filename]#/usr/local/etc/#, and so on. @@ -231,9 +232,9 @@ ifconfig_em0="DHCP" FreeBSD does not use Linux(R) IPTABLES for its firewall. Instead, FreeBSD offers a choice of three kernel level firewalls: -* extref:{handbook}[PF, firewalls-pf] -* extref:{handbook}[IPFILTER, firewalls-ipf] -* extref:{handbook}[IPFW, firewalls-ipfw] +* extref:{handbook}firewalls[PF, firewalls-pf] +* extref:{handbook}firewalls[IPFILTER, firewalls-ipf] +* extref:{handbook}firewalls[IPFW, firewalls-ipfw] PF is developed by the OpenBSD project and ported to FreeBSD. PF was created as a replacement for IPFILTER and its syntax is similar to that of IPFILTER. @@ -272,7 +273,7 @@ ipfw add allow tcp from any to me 22 in via $ext_if There are two methods for updating a FreeBSD system: from source or binary updates. Updating from source is the most involved update method, but offers the greatest amount of flexibility. -The process involves synchronizing a local copy of the FreeBSD source code with the FreeBSD Subversion servers. +The process involves synchronizing a local copy of the FreeBSD source code with the FreeBSD Git repository. Once the local source code is up-to-date, a new version of the kernel and userland can be compiled. Binary updates are similar to using `yum` or `apt-get` to update a Linux(R) system. @@ -290,7 +291,7 @@ When using man:cron[8] to schedule updates, use `freebsd-update cron` in the man ==== -For more information on source and binary updates, refer to extref:{handbook}[the chapter on updating, updating-upgrading] in the FreeBSD Handbook. +For more information on source and binary updates, refer to extref:{handbook}cutting-edge[the chapter on updating, updating-upgrading-freebsdupdate] in the FreeBSD Handbook. [[procfs]] == procfs: Gone But Not Forgotten diff --git a/documentation/content/en/articles/linux-users/_index.po b/documentation/content/en/articles/linux-users/_index.po new file mode 100644 index 0000000000..5a22174032 --- /dev/null +++ b/documentation/content/en/articles/linux-users/_index.po @@ -0,0 +1,809 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-09-14 14:59-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/linux-users/_index.adoc:1 +#, no-wrap +msgid "This document is intended to quickly familiarize intermediate to advanced Linux® users with the basics of FreeBSD." +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/articles/linux-users/_index.adoc:1 +#, no-wrap +msgid "FreeBSD Quickstart Guide for Linux® Users" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/linux-users/_index.adoc:11 +#, no-wrap +msgid "FreeBSD Quickstart Guide for Linux(R) Users" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:46 +msgid "" +"This document is intended to quickly familiarize intermediate to advanced " +"Linux(R) users with the basics of FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:48 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-users/_index.adoc:52 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:55 +msgid "" +"This document highlights some of the technical differences between FreeBSD " +"and Linux(R) so that intermediate to advanced Linux(R) users can quickly " +"familiarize themselves with the basics of FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:58 +msgid "" +"This document assumes that FreeBSD is already installed. Refer to the " +"extref:{handbook}[Installing FreeBSD, bsdinstall] chapter of the FreeBSD " +"Handbook for help with the installation process." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-users/_index.adoc:60 +#, no-wrap +msgid "Default Shell" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:68 +msgid "" +"Linux(R) users are often surprised to find that Bash is not the default " +"shell in FreeBSD. In fact, Bash is not included in the default " +"installation. Instead, the Bourne shell-compatible man:sh[1] as the default " +"user shell. The root shell is man:tcsh[1] by default on FreeBSD 13 and " +"earlier and man:sh[1] on FreeBSD 14 and later. man:sh[1] is very similar to " +"Bash but with a much smaller feature-set. Generally shell scripts written " +"for man:sh[1] will run in Bash, but the reverse is not always true." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:70 +msgid "" +"However, Bash and other shells are available for installation using the " +"FreeBSD extref:{handbook}[Packages and Ports Collection, ports]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:75 +msgid "" +"After installing another shell, use man:chsh[1] to change a user's default " +"shell. It is recommended that the `root` user's default shell remain " +"unchanged since shells which are not included in the base distribution are " +"installed to [.filename]#/usr/local/bin#. In the event of a problem, the " +"file system where [.filename]#/usr/local/bin# is located may not be " +"mounted. In this case, `root` would not have access to its default shell, " +"preventing `root` from logging in and fixing the problem." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-users/_index.adoc:77 +#, no-wrap +msgid "Packages and Ports: Adding Software in FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:81 +msgid "" +"FreeBSD provides two methods for installing applications: binary packages " +"and compiled ports. Each method has its own benefits:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/linux-users/_index.adoc:82 +#, no-wrap +msgid "Binary Packages" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:84 +msgid "Faster installation as compared to compiling large applications." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:85 +msgid "Does not require an understanding of how to compile software." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:86 +msgid "No need to install a compiler." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-users/_index.adoc:87 +#: documentation/content/en/articles/linux-users/_index.adoc:112 +#, no-wrap +msgid "Ports" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:89 +msgid "Ability to customize installation options." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:90 +msgid "Custom patches can be applied." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:94 +msgid "" +"If an application installation does not require any customization, " +"installing the package is sufficient. Compile the port instead whenever an " +"application requires customization of the default options. If needed, a " +"custom package can be compiled from ports using `make package`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:96 +msgid "" +"A complete list of all available ports and packages can be found https://" +"ports.freebsd.org[here]." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/linux-users/_index.adoc:98 +#, no-wrap +msgid "Packages" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:103 +msgid "" +"Packages are pre-compiled applications, the FreeBSD equivalents of [." +"filename]#.deb# files on Debian/Ubuntu based systems and [.filename]#.rpm# " +"files on Red Hat/Fedora based systems. Packages are installed using `pkg`. " +"For example, the following command installs Apache 2.4:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:107 +#, no-wrap +msgid "# pkg install apache24\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:110 +msgid "" +"For more information on packages refer to section 5.4 of the FreeBSD " +"Handbook: extref:{handbook}[Using pkgng for Binary Package Management, pkgng-" +"intro]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:116 +msgid "" +"The FreeBSD Ports Collection is a framework of [.filename]#Makefiles# and " +"patches specifically customized for installing applications from source on " +"FreeBSD. When installing a port, the system will fetch the source code, " +"apply any required patches, compile the code, and install the application " +"and any required dependencies." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:119 +msgid "" +"The Ports Collection, sometimes referred to as the ports tree, can be " +"installed to [.filename]#/usr/ports# using link:{handbook}mirrors/" +"#git[Git]. Detailed instructions for installing the Ports Collection can be " +"found in extref:{handbook}[section 4.5.1, ports-using-installation-methods] " +"of the FreeBSD Handbook." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:121 +msgid "" +"To compile a port, change to the port's directory and start the build " +"process. The following example installs Apache 2.4 from the Ports Collection:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:126 +#, no-wrap +msgid "" +"# cd /usr/ports/www/apache24\n" +"# make install clean\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:130 +msgid "" +"A benefit of using ports to install software is the ability to customize the " +"installation options. This example specifies that the mod_ldap module " +"should also be installed:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:135 +#, no-wrap +msgid "" +"# cd /usr/ports/www/apache24\n" +"# make WITH_LDAP=\"YES\" install clean\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:138 +msgid "" +"Refer to extref:{handbook}[Using the Ports Collection, ports-using] for more " +"information." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-users/_index.adoc:140 +#, no-wrap +msgid "System Startup" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:147 +msgid "" +"Many Linux(R) distributions use the SysV init system, whereas FreeBSD uses " +"the traditional BSD-style man:init[8]. Under the BSD-style man:init[8], " +"there are no run-levels and [.filename]#/etc/inittab# does not exist. " +"Instead, startup is controlled by man:rc[8] scripts. At system boot, [." +"filename]#/etc/rc# reads [.filename]#/etc/rc.conf# and [.filename]#/etc/" +"defaults/rc.conf# to determine which services are to be started. The " +"specified services are then started by running the corresponding service " +"initialization scripts located in [.filename]#/etc/rc.d/# and [.filename]#/" +"usr/local/etc/rc.d/#. These scripts are similar to the scripts located in [." +"filename]#/etc/init.d/# on Linux(R) systems." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:150 +msgid "" +"The scripts found in [.filename]#/etc/rc.d/# are for applications that are " +"part of the \"base\" system, such as man:cron[8], man:sshd[8], and man:" +"syslog[3]. The scripts in [.filename]#/usr/local/etc/rc.d/# are for user-" +"installed applications such as Apache and Squid." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:155 +msgid "" +"Since FreeBSD is developed as a complete operating system, user-installed " +"applications are not considered to be part of the \"base\" system. User-" +"installed applications are generally installed using extref:{handbook}" +"[Packages or Ports, ports-using]. In order to keep them separate from the " +"base system, user-installed applications are installed under [.filename]#/" +"usr/local/#. Therefore, user-installed binaries reside in [.filename]#/usr/" +"local/bin/#, configuration files are in [.filename]#/usr/local/etc/#, and so " +"on." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:160 +msgid "" +"Services are enabled by adding an entry for the service in [.filename]#/etc/" +"rc.conf#. The system defaults are found in [.filename]#/etc/defaults/rc." +"conf# and these default settings are overridden by settings in [.filename]#/" +"etc/rc.conf#. Refer to man:rc.conf[5] for more information about the " +"available entries. When installing additional applications, review the " +"application's install message to determine how to enable any associated " +"services." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:162 +msgid "" +"The following entries in [.filename]#/etc/rc.conf# enable man:sshd[8], " +"enable Apache 2.4, and specify that Apache should be started with SSL." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:170 +#, no-wrap +msgid "" +"# enable SSHD\n" +"sshd_enable=\"YES\"\n" +"# enable Apache with SSL\n" +"apache24_enable=\"YES\"\n" +"apache24_flags=\"-DSSL\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:173 +msgid "" +"Once a service has been enabled in [.filename]#/etc/rc.conf#, it can be " +"started without rebooting the system:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:178 +#, no-wrap +msgid "" +"# service sshd start\n" +"# service apache24 start\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:181 +msgid "" +"If a service has not been enabled, it can be started from the command line " +"using `onestart`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:185 +#, no-wrap +msgid "# service sshd onestart\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-users/_index.adoc:188 +#, no-wrap +msgid "Network Configuration" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:192 +msgid "" +"Instead of a generic _ethX_ identifier that Linux(R) uses to identify a " +"network interface, FreeBSD uses the driver name followed by a number. The " +"following output from man:ifconfig[8] shows two Intel(R) Pro 1000 network " +"interfaces ([.filename]#em0# and [.filename]#em1#):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:208 +#, no-wrap +msgid "" +"% ifconfig\n" +"em0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500\n" +" options=b<RXCSUM,TXCSUM,VLAN_MTU>\n" +" inet 10.10.10.100 netmask 0xffffff00 broadcast 10.10.10.255\n" +" ether 00:50:56:a7:70:b2\n" +" media: Ethernet autoselect (1000baseTX <full-duplex>)\n" +" status: active\n" +"em1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500\n" +" options=b<RXCSUM,TXCSUM,VLAN_MTU>\n" +" inet 192.168.10.222 netmask 0xffffff00 broadcast 192.168.10.255\n" +" ether 00:50:56:a7:03:2b\n" +" media: Ethernet autoselect (1000baseTX <full-duplex>)\n" +" status: active\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:213 +msgid "" +"An IP address can be assigned to an interface using man:ifconfig[8]. To " +"remain persistent across reboots, the IP configuration must be included in [." +"filename]#/etc/rc.conf#. The following [.filename]#/etc/rc.conf# entries " +"specify the hostname, IP address, and default gateway:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:219 +#, no-wrap +msgid "" +"hostname=\"server1.example.com\"\n" +"ifconfig_em0=\"inet 10.10.10.100 netmask 255.255.255.0\"\n" +"defaultrouter=\"10.10.10.1\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:222 +msgid "Use the following entries to instead configure an interface for DHCP:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:227 +#, no-wrap +msgid "" +"hostname=\"server1.example.com\"\n" +"ifconfig_em0=\"DHCP\"\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-users/_index.adoc:230 +#, no-wrap +msgid "Firewall" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:234 +msgid "" +"FreeBSD does not use Linux(R) IPTABLES for its firewall. Instead, FreeBSD " +"offers a choice of three kernel level firewalls:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:236 +msgid "extref:{handbook}[PF, firewalls-pf]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:237 +msgid "extref:{handbook}[IPFILTER, firewalls-ipf]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:238 +msgid "extref:{handbook}[IPFW, firewalls-ipfw]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:242 +msgid "" +"PF is developed by the OpenBSD project and ported to FreeBSD. PF was " +"created as a replacement for IPFILTER and its syntax is similar to that of " +"IPFILTER. PF can be paired with man:altq[4] to provide QoS features." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:244 +msgid "This sample PF entry allows inbound SSH:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:248 +#, no-wrap +msgid "pass in on $ext_if inet proto tcp from any to ($ext_if) port 22\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:252 +msgid "" +"IPFILTER is the firewall application developed by Darren Reed. It is not " +"specific to FreeBSD and has been ported to several operating systems " +"including NetBSD, OpenBSD, SunOS, HP/UX, and Solaris." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:254 +msgid "The IPFILTER syntax to allow inbound SSH is:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:258 +#, no-wrap +msgid "pass in on $ext_if proto tcp from any to any port = 22\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:262 +msgid "" +"IPFW is the firewall developed and maintained by FreeBSD. It can be paired " +"with man:dummynet[4] to provide traffic shaping capabilities and simulate " +"different types of network connections." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:264 +msgid "The IPFW syntax to allow inbound SSH would be:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:268 +#, no-wrap +msgid "ipfw add allow tcp from any to me 22 in via $ext_if\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-users/_index.adoc:271 +#, no-wrap +msgid "Updating FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:274 +msgid "" +"There are two methods for updating a FreeBSD system: from source or binary " +"updates." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:278 +msgid "" +"Updating from source is the most involved update method, but offers the " +"greatest amount of flexibility. The process involves synchronizing a local " +"copy of the FreeBSD source code with the FreeBSD Git repository. Once the " +"local source code is up-to-date, a new version of the kernel and userland " +"can be compiled." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:282 +msgid "" +"Binary updates are similar to using `yum` or `apt-get` to update a Linux(R) " +"system. In FreeBSD, man:freebsd-update[8] can be used fetch new binary " +"updates and install them. These updates can be scheduled using man:cron[8]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/linux-users/_index.adoc:286 +msgid "" +"When using man:cron[8] to schedule updates, use `freebsd-update cron` in the " +"man:crontab[1] to reduce the possibility of a large number of machines all " +"pulling updates at the same time:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:290 +#, no-wrap +msgid "0 3 * * * root /usr/sbin/freebsd-update cron\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/linux-users/_index.adoc:295 +msgid "" +"For more information on source and binary updates, refer to extref:{handbook}" +"[the chapter on updating, updating-upgrading-freebsdupdate] in the FreeBSD " +"Handbook." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-users/_index.adoc:297 +#, no-wrap +msgid "procfs: Gone But Not Forgotten" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/linux-users/_index.adoc:301 +msgid "" +"In some Linux(R) distributions, one could look at [.filename]#/proc/sys/net/" +"ipv4/ip_forward# to determine if IP forwarding is enabled. In FreeBSD, man:" +"sysctl[8] is instead used to view this and other system settings." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/linux-users/_index.adoc:303 +msgid "" +"For example, use the following to determine if IP forwarding is enabled on a " +"FreeBSD system:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:308 +#, no-wrap +msgid "" +"% sysctl net.inet.ip.forwarding\n" +"net.inet.ip.forwarding: 0\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:311 +msgid "Use `-a` to list all the system settings:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:315 +#, no-wrap +msgid "% sysctl -a | more\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:318 +msgid "" +"If an application requires procfs, add the following entry to [.filename]#/" +"etc/fstab#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:322 +#, no-wrap +msgid "proc /proc procfs rw,noauto 0 0\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:325 +msgid "" +"Including `noauto` will prevent [.filename]#/proc# from being automatically " +"mounted at boot." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:327 +msgid "To mount the file system without rebooting:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/linux-users/_index.adoc:331 +#, no-wrap +msgid "# mount /proc\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-users/_index.adoc:334 +#, no-wrap +msgid "Common Commands" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:337 +msgid "Some common command equivalents are as follows:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:342 +#, no-wrap +msgid "Linux(R) command (Red Hat/Debian)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:343 +#, no-wrap +msgid "FreeBSD equivalent" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:345 +#, no-wrap +msgid "Purpose" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:346 +#, no-wrap +msgid "`yum install _package_` / `apt-get install _package_`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:347 +#, no-wrap +msgid "`pkg install _package_`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:349 +#, no-wrap +msgid "Install package from remote repository" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:350 +#, no-wrap +msgid "`rpm -ivh _package_` / `dpkg -i _package_`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:351 +#, no-wrap +msgid "`pkg add _package_`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:353 +#, no-wrap +msgid "Install local package" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:354 +#, no-wrap +msgid "`rpm -qa` / `dpkg -l`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:355 +#, no-wrap +msgid "`pkg info`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:357 +#, no-wrap +msgid "List installed packages" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:358 +#, no-wrap +msgid "`lspci`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:359 +#, no-wrap +msgid "`pciconf`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:361 +#, no-wrap +msgid "List PCI devices" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:362 +#, no-wrap +msgid "`lsmod`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:363 +#, no-wrap +msgid "`kldstat`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:365 +#, no-wrap +msgid "List loaded kernel modules" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:366 +#, no-wrap +msgid "`modprobe`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:367 +#, no-wrap +msgid "`kldload` / `kldunload`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:369 +#, no-wrap +msgid "Load/Unload kernel modules" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:370 +#, no-wrap +msgid "`strace`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:371 +#, no-wrap +msgid "`truss`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/linux-users/_index.adoc:372 +#, no-wrap +msgid "Trace system calls" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/linux-users/_index.adoc:375 +#, no-wrap +msgid "Conclusion" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/linux-users/_index.adoc:378 +msgid "" +"This document has provided an overview of FreeBSD. Refer to the extref:" +"{handbook}[FreeBSD Handbook] for more in-depth coverage of these topics as " +"well as the many topics not covered by this document." +msgstr "" diff --git a/documentation/content/en/articles/mailing-list-faq/_index.adoc b/documentation/content/en/articles/mailing-list-faq/_index.adoc index 99b123e332..64595b6bb0 100644 --- a/documentation/content/en/articles/mailing-list-faq/_index.adoc +++ b/documentation/content/en/articles/mailing-list-faq/_index.adoc @@ -43,8 +43,8 @@ Abstract This is the FAQ for the FreeBSD mailing lists. If you are interested in helping with this project, send email to the {freebsd-doc}. -The latest version of this document is always available from the link:.[FreeBSD World Wide Web server]. -It may also be downloaded as one large link:.[HTML] file with HTTP or as plain text, PostScript, PDF, etc. from the https://download.freebsd.org/doc/[FreeBSD FTP server]. +The latest version of this document is always available from the extref:{mailing-list-faq}[FreeBSD World Wide Web server]. +It may also be downloaded as one large extref:{mailing-list-faq}[HTML] file with HTTP or as plain text, PostScript, PDF, etc. from the https://download.freebsd.org/doc/[FreeBSD FTP server]. You may also want to link:https://www.FreeBSD.org/search/[Search the FAQ]. ''' @@ -54,7 +54,7 @@ toc::[] [[introduction]] == Introduction -As is usual with FAQs, this document aims to cover the most frequently asked questions concerning the FreeBSD mailing lists (and of course answer them!). +As is usual with FAQs, this document aims to cover the most frequently asked questions concerning the FreeBSD mailing lists (and of course answer them!). Although originally intended to reduce bandwidth and avoid the same old questions being asked over and over again, FAQs have become recognized as valuable information resources. This document attempts to represent a community consensus, and as such it can never really be __authoritative__. @@ -71,6 +71,8 @@ This depends on charter of each individual list. Some lists are more oriented to developers; some are more oriented towards the FreeBSD community as a whole. Please see link:https://lists.FreeBSD.org/[this list] for the current summary. +Lists are English language, unless stated otherwise. + === Are the FreeBSD mailing lists open for anyone to participate? Again, this depends on charter of each individual list. @@ -79,9 +81,8 @@ This will help everyone to have a better experience with the lists. If after reading the above lists, you still do not know which mailing list to post a question to, you will probably want to post to freebsd-questions (but see below, first). -Also note that the mailing lists have traditionally been open to postings from non-subscribers. -This has been a deliberate choice, to help make joining the FreeBSD community an easier process, and to encourage open sharing of ideas. -However, due to past abuse by some individuals, certain lists now have a policy where postings from non-subscribers must be manually screened to ensure that they are appropriate. +Note that you must subscribe to a mailing list before you can post. +You can elect to subscribe without receiving messages posted to the mailing list. === How can I subscribe? @@ -97,7 +98,7 @@ This is a classical mistake when using mailing lists; please try to avoid it. === Are archives available? -Yes. Threaded archives are available link:https://docs.FreeBSD.org/mail/[here]. +Yes. Threaded archives with all e-mails since 1994 are available link:https://mail-archive.freebsd.org/mail/[here]. You can also access https://lists.freebsd.org/pipermail[mailman archive] and link:https://lists.freebsd.org/archives[mlmmj archive] directly. === Are mailing lists available in a digest format? @@ -195,7 +196,7 @@ Literally, a `bikeshed` is a small outdoor shelter into which one may store one' However, in FreeBSD parlance, the term refers to topics that are simple enough that (nearly) anyone can offer an opinion about, and often (nearly) everyone does. The genesis of this term is explained in more detail extref:{faq}[in this document, bikeshed-painting]. You simply must have a working knowledge of this concept before posting to any FreeBSD mailing list. -More generally, a bikeshed is a topic that will tend to generate immediate meta-discussions and flames if you have not read up on their past history. +More generally, a bikeshed is a topic that will tend to generate immediate meta-discussions and flames if you have not read up on their history. Please help us to keep the mailing lists as useful for as many people as possible by avoiding bikesheds whenever you can. Thanks. diff --git a/documentation/content/en/articles/mailing-list-faq/_index.po b/documentation/content/en/articles/mailing-list-faq/_index.po new file mode 100644 index 0000000000..1970b15513 --- /dev/null +++ b/documentation/content/en/articles/mailing-list-faq/_index.po @@ -0,0 +1,578 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-05-01 19:57-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:1 +#, no-wrap +msgid "How to best use the mailing lists, such as how to help avoid frequently-repeated discussions" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:1 +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:10 +#, no-wrap +msgid "Frequently Asked Questions About The FreeBSD Mailing Lists" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:43 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:49 +msgid "" +"This is the FAQ for the FreeBSD mailing lists. If you are interested in " +"helping with this project, send email to the {freebsd-doc}. The latest " +"version of this document is always available from the link:.[FreeBSD World " +"Wide Web server]. It may also be downloaded as one large link:.[HTML] file " +"with HTTP or as plain text, PostScript, PDF, etc. from the https://" +"download.freebsd.org/doc/[FreeBSD FTP server]. You may also want to " +"link:https://www.FreeBSD.org/search/[Search the FAQ]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:51 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:55 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:59 +msgid "" +"As is usual with FAQs, this document aims to cover the most frequently asked " +"questions concerning the FreeBSD mailing lists (and of course answer " +"them!). Although originally intended to reduce bandwidth and avoid the same " +"old questions being asked over and over again, FAQs have become recognized " +"as valuable information resources." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:63 +msgid "" +"This document attempts to represent a community consensus, and as such it " +"can never really be __authoritative__. However, if you find technical " +"errors within this document, or have suggestions about items that should be " +"added, please either submit a PR, or email the {freebsd-doc}. Thanks." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:64 +#, no-wrap +msgid "What is the purpose of the FreeBSD mailing lists?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:67 +msgid "" +"The FreeBSD mailing lists serve as the primary communication channels for " +"the FreeBSD community, covering many different topic areas and communities " +"of interest." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:68 +#, no-wrap +msgid "Who is the audience for the FreeBSD mailing lists?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:73 +msgid "" +"This depends on charter of each individual list. Some lists are more " +"oriented to developers; some are more oriented towards the FreeBSD community " +"as a whole. Please see link:https://lists.FreeBSD.org/[this list] for the " +"current summary." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:75 +msgid "Lists are English language, unless stated otherwise." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:76 +#, no-wrap +msgid "Are the FreeBSD mailing lists open for anyone to participate?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:81 +msgid "" +"Again, this depends on charter of each individual list. Please read the " +"charter of a mailing list before you post to it, and respect it when you " +"post. This will help everyone to have a better experience with the lists." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:83 +msgid "" +"If after reading the above lists, you still do not know which mailing list " +"to post a question to, you will probably want to post to freebsd-questions " +"(but see below, first)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:86 +msgid "" +"Note that you must subscribe to a mailing list before you can post. You can " +"elect to subscribe without receiving messages posted to the mailing list." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:87 +#, no-wrap +msgid "How can I subscribe?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:90 +msgid "" +"You can use link:https://lists.FreeBSD.org/[the Mlmmj web interface] to " +"subscribe to any of the public lists." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:91 +#, no-wrap +msgid "How can I unsubscribe?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:94 +msgid "" +"You can use the same interface as above; or, you can follow the instructions " +"that are at the bottom of every mailing list message that is sent." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:98 +msgid "" +"Please do not send unsubscribe messages directly to the public lists " +"themselves. First, this will not accomplish your goal, and second, it will " +"irritate the existing subscribers, and you will probably get flamed. This " +"is a classical mistake when using mailing lists; please try to avoid it." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:99 +#, no-wrap +msgid "Are archives available?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:103 +msgid "" +"Yes. Threaded archives with all e-mails since 1994 are available " +"link:https://mail-archive.freebsd.org/mail/[here]. You can also access " +"https://lists.freebsd.org/pipermail[mailman archive] and link:https://" +"lists.freebsd.org/archives[mlmmj archive] directly." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:104 +#, no-wrap +msgid "Are mailing lists available in a digest format?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:107 +msgid "Yes. See link:https://lists.FreeBSD.org/[the Mlmmj web interface]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:109 +#, no-wrap +msgid "Mailing List Etiquette" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:113 +msgid "" +"Participation in the mailing lists, like participation in any community, " +"requires a common basis for communication. Please make only appropriate " +"postings, and follow common rules of etiquette." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:114 +#, no-wrap +msgid "What should I do before I post?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:119 +msgid "" +"You have already taken the most important step by reading this document. " +"However, if you are new to FreeBSD, you may first need to familiarize " +"yourself with the software, and all the social history around it, by reading " +"the numerous link:https://www.FreeBSD.org/docs/books/[books and articles] " +"that are available. Items of particular interest include the extref:{faq}" +"[FreeBSD Frequently Asked Questions (FAQ)] document, the extref:{handbook}" +"[FreeBSD Handbook], and the articles extref:{freebsd-questions-article}[How " +"to get best results from the FreeBSD-questions mailing list], extref:" +"{explaining-bsd}[Explaining BSD], and extref:{new-users}[FreeBSD First " +"Steps]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:124 +msgid "" +"It is always considered bad form to ask a question that is already answered " +"in the above documents. This is not because the volunteers who work on this " +"project are particularly mean people, but after a certain number of times " +"answering the same questions over and over again, frustration begins to set " +"in. This is particularly true if there is an existing answer to the " +"question that is already available. Always keep in mind that almost all of " +"the work done on FreeBSD is done by volunteers, and that we are only human." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:125 +#, no-wrap +msgid "What constitutes an inappropriate posting?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:128 +msgid "Postings must be in accordance with the charter of the mailing list." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:129 +msgid "" +"Personal attacks are discouraged. As good net-citizens, we should try to " +"hold ourselves to high standards of behavior." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:130 +msgid "" +"Spam is not allowed, ever. The mailing lists are actively processed to ban " +"offenders to this rule." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:131 +#, no-wrap +msgid "What is considered proper etiquette when posting to the mailing lists?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:134 +msgid "" +"Please wrap lines at 75 characters, since not everyone uses fancy GUI mail " +"reading programs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:135 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:136 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:137 +msgid "" +"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]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:141 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:142 +msgid "" +"Please use a standards-compliant Mail User Agent (MUA). A lot of badly " +"formatted messages come from http://www.lemis.com/grog/email/email.php[bad " +"mailers or badly configured mailers]. The following mailers are known to " +"send out badly formatted messages without you finding out about them:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:144 +msgid "exmh" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:145 +msgid "Microsoft(R) Exchange" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:146 +msgid "Microsoft(R) Outlook(R)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:148 +msgid "" +"Try not to use MIME: a lot of people use mailers which do not get on very " +"well with MIME." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:149 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:150 +msgid "" +"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," +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:154 +#, no-wrap +msgid "% dmesg > /tmp/dmesg.out\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:157 +msgid "This redirects the information to the file [.filename]#/tmp/dmesg.out#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:158 +msgid "" +"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." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:159 +#, no-wrap +msgid "What are the special etiquette consideration when replying to an existing posting on the mailing lists?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:162 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:164 +msgid "" +"This is especially important for postings of the type \"yes, I see this " +"too\", where the initial posting was dozens or hundreds of lines." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:165 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:166 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:167 +msgid "" +"Please do not `top post`. By this, we mean that if you are replying to a " +"message, please put your replies after the text that you copy in your reply." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:169 +msgid "A: Because it reverses the logical flow of conversation." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:170 +msgid "Q: Why is top posting frowned upon?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:172 +msgid "(Thanks to Randy Bush for the joke.)" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:174 +#, no-wrap +msgid "Recurring Topics On The Mailing Lists" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:181 +msgid "" +"Participation in the mailing lists, like participation in any community, " +"requires a common basis for communication. Many of the mailing lists " +"presuppose a knowledge of the Project's history. In particular, there are " +"certain topics that seem to regularly occur to newcomers to the community. " +"It is the responsibility of each poster to ensure that their postings do not " +"fall into one of these categories. By doing so, you will help the mailing " +"lists to stay on-topic, and probably save yourself being flamed in the " +"process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:185 +msgid "" +"The best method to avoid this is to familiarize yourself with the http://" +"docs.FreeBSD.org/mail/[mailing list archives], to help yourself understand " +"the background of what has gone before. In this, the https://" +"www.FreeBSD.org/search/#mailinglists[mailing list search interface] is " +"invaluable. (If that method does not yield useful results, please " +"supplement it with a search with your favorite major search engine)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:188 +msgid "" +"By familiarizing yourself with the archives, not only will you learn what " +"topics have been discussed before, but also how discussion tends to proceed " +"on that list, who the participants are, and who the target audience is. " +"These are always good things to know before you post to any mailing list, " +"not just a FreeBSD mailing list." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:191 +msgid "" +"There is no doubt that the archives are quite extensive, and some questions " +"recur more often than others, sometimes as followups where the subject line " +"no longer accurately reflects the new content. Nevertheless, the burden is " +"on you, the poster, to do your homework to help avoid these recurring topics." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:193 +#, no-wrap +msgid "What Is A \"Bikeshed\"?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:198 +msgid "" +"Literally, a `bikeshed` is a small outdoor shelter into which one may store " +"one's two-wheeled form of transportation. However, in FreeBSD parlance, the " +"term refers to topics that are simple enough that (nearly) anyone can offer " +"an opinion about, and often (nearly) everyone does. The genesis of this term " +"is explained in more detail extref:{faq}[in this document, bikeshed-" +"painting]. You simply must have a working knowledge of this concept before " +"posting to any FreeBSD mailing list." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:200 +msgid "" +"More generally, a bikeshed is a topic that will tend to generate immediate " +"meta-discussions and flames if you have not read up on their history." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:203 +msgid "" +"Please help us to keep the mailing lists as useful for as many people as " +"possible by avoiding bikesheds whenever you can. Thanks." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:205 +#, no-wrap +msgid "Acknowledgments" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:207 +#, no-wrap +msgid "`{grog}`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:209 +msgid "" +"Original author of most of the material on mailing list etiquette, taken " +"from the article on extref:{freebsd-questions-article}[How to get best " +"results from the FreeBSD-questions mailing list]." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:210 +#, no-wrap +msgid "`{linimon}`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/mailing-list-faq/_index.adoc:211 +msgid "Creation of the rough draft of this FAQ." +msgstr "" diff --git a/documentation/content/en/articles/nanobsd/_index.adoc b/documentation/content/en/articles/nanobsd/_index.adoc index 2f6e420b17..a8f3ba03d6 100644 --- a/documentation/content/en/articles/nanobsd/_index.adoc +++ b/documentation/content/en/articles/nanobsd/_index.adoc @@ -108,6 +108,16 @@ Keeping [.filename]#/cfg# mounted at all times is not a good idea, especially if === Building a NanoBSD Image +The source code of FreeBSD is required to build NanoBSD. +To obtain the source code: + +[source,shell] +.... +# git clone https://git.FreeBSD.org/src.git /usr/src +.... + +For more details, follow the steps extref:{handbook}cutting-edge#updating-src-obtaining-src[here]. + A NanoBSD image is built using a simple [.filename]#nanobsd.sh# shell script, which can be found in the [.filename]#/usr/src/tools/tools/nanobsd# directory. This script creates an image, which can be copied on the storage medium using the man:dd[1] utility. @@ -305,6 +315,7 @@ There are a few default pre-defined customization functions ready for use: * `cust_comconsole` - Disables man:getty[8] on the VGA devices (the [.filename]#/dev/ttyv*# device nodes) and enables the use of the COM1 serial port as the system console. * `cust_allow_ssh_root` - Allow `root` to login via man:sshd[8]. * `cust_install_files` - Installs files from the [.filename]#nanobsd/Files# directory, which contains some useful scripts for system administration. +* `cust_pkgng` - Installs packages from the [.filename]#nanobsd/Pkg# directory (needs also pkg-* package to bootstrap). ==== Adding Packages diff --git a/documentation/content/en/articles/nanobsd/_index.po b/documentation/content/en/articles/nanobsd/_index.po new file mode 100644 index 0000000000..700fff2e60 --- /dev/null +++ b/documentation/content/en/articles/nanobsd/_index.po @@ -0,0 +1,1204 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-01-17 20:35-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:1 +#: documentation/content/en/articles/nanobsd/_index.adoc:46 +#, no-wrap +msgid "This document provides information about the NanoBSD tools, which can be used to create FreeBSD system images for embedded applications, suitable for use on a USB key, memory card or other mass storage media." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/nanobsd/_index.adoc:1 +#: documentation/content/en/articles/nanobsd/_index.adoc:11 +#: documentation/content/en/articles/nanobsd/_index.adoc:52 +#, no-wrap +msgid "Introduction to NanoBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:48 +msgid "'''" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:56 +msgid "" +"NanoBSD is a tool developed by {phk} and now maintained by {imp}. It " +"creates a FreeBSD system image for embedded applications, suitable for use " +"on a USB key, memory card or other mass storage media." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:60 +msgid "" +"It can be used to build specialized install images, designed for easy " +"installation and maintenance of systems commonly called \"computer " +"appliances\". Computer appliances have their hardware and software bundled " +"in the product, which means all applications are pre-installed. The " +"appliance is plugged into an existing network and can begin working (almost) " +"immediately." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:62 +msgid "The features of NanoBSD include:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:64 +msgid "" +"Ports and packages work as in FreeBSD - Every single application can be " +"installed and used in a NanoBSD image, the same way as in FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:65 +msgid "" +"No missing functionality - If it is possible to do something with FreeBSD, " +"it is possible to do the same thing with NanoBSD, unless the specific " +"feature or features were explicitly removed from the NanoBSD image when it " +"was created." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:66 +msgid "" +"Everything is read-only at run-time - It is safe to pull the power-plug. " +"There is no necessity to run man:fsck[8] after a non-graceful shutdown of " +"the system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:67 +msgid "" +"Easy to build and customize - Making use of just one shell script and one " +"configuration file it is possible to build reduced and customized images " +"satisfying any arbitrary set of requirements." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/nanobsd/_index.adoc:69 +#, no-wrap +msgid "NanoBSD Howto" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/nanobsd/_index.adoc:72 +#, no-wrap +msgid "The Design of NanoBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:76 +msgid "" +"Once the image is present on the medium, it is possible to boot NanoBSD. " +"The mass storage medium is divided into three parts by default:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:78 +msgid "Two image partitions: `code#1` and `code#2`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:79 +msgid "" +"The configuration file partition, which can be mounted under the [." +"filename]#/cfg# directory at run time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:81 +msgid "These partitions are normally mounted read-only." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:83 +msgid "" +"The [.filename]#/etc# and [.filename]#/var# directories are man:md[4] " +"(malloc) disks." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:86 +msgid "" +"The configuration file partition persists under the [.filename]#/cfg# " +"directory. It contains files for [.filename]#/etc# directory and is briefly " +"mounted read-only right after the system boot, therefore it is required to " +"copy modified files from [.filename]#/etc# back to the [.filename]#/cfg# " +"directory if changes are expected to persist after the system restarts." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/nanobsd/_index.adoc:87 +#, no-wrap +msgid "Making Persistent Changes to [.filename]#/etc/resolv.conf#" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:98 +#, no-wrap +msgid "" +"# vi /etc/resolv.conf\n" +"[...]\n" +"# mount /cfg\n" +"# cp /etc/resolv.conf /cfg\n" +"# umount /cfg\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:105 +msgid "" +"The partition containing [.filename]#/cfg# should be mounted only at boot " +"time and while overriding the configuration files." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:107 +msgid "" +"Keeping [.filename]#/cfg# mounted at all times is not a good idea, " +"especially if the NanoBSD system runs off a mass storage medium that may be " +"adversely affected by a large number of writes to the partition (like when " +"the filesystem syncer flushes data to the system disks)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/nanobsd/_index.adoc:109 +#, no-wrap +msgid "Building a NanoBSD Image" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:113 +msgid "" +"The source code of FreeBSD is required to build NanoBSD. To obtain the " +"source code:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:117 +#, no-wrap +msgid "# git clone https://git.FreeBSD.org/src.git /usr/src\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:120 +msgid "" +"For more details, follow the steps extref:{handbook}cutting-edge#updating-" +"src-obtaining-src[here]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:123 +msgid "" +"A NanoBSD image is built using a simple [.filename]#nanobsd.sh# shell " +"script, which can be found in the [.filename]#/usr/src/tools/tools/nanobsd# " +"directory. This script creates an image, which can be copied on the storage " +"medium using the man:dd[1] utility." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:125 +msgid "The necessary commands to build a NanoBSD image are:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:132 +#, no-wrap +msgid "" +"# cd /usr/src/tools/tools/nanobsd <.>\n" +"# sh nanobsd.sh <.>\n" +"# cd /usr/obj/nanobsd.full <.>\n" +"# dd if=_.disk.full of=/dev/da0 bs=64k <.>\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:135 +msgid "" +"Change the current directory to the base directory of the NanoBSD build " +"script." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:137 +msgid "Start the build process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:139 +msgid "" +"Change the current directory to the place where the built images are located." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:141 +msgid "Install NanoBSD onto the storage medium." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/nanobsd/_index.adoc:142 +#, no-wrap +msgid "Options When Building a NanoBSD Image" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:146 +msgid "" +"When building a NanoBSD image, several build options can be passed to [." +"filename]#nanobsd.sh# on the command line. These options can have a " +"significant impact on the build process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:148 +msgid "Some options are for verbosity purposes:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:150 +msgid "`-h`: prints the help summary page." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:151 +msgid "`-q`: makes output quieter." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:152 +msgid "`-v`: makes output more verbose" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:155 +msgid "" +"Some other options can be used to restrict the building process. Sometimes " +"it is not necessary to rebuild everything from sources, especially if an " +"image has already been built, and only little change is made." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:157 +msgid "`-k`: do not build the kernel" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:158 +msgid "`-w`: do not build world" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:159 +msgid "`-b`: do not build either kernel and world" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:160 +msgid "" +"`-i`: do not build a disk image at all. As a file will not be created, it " +"will not be possible to man:dd[1] it to a storage media." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:161 +msgid "" +"`-f`: do not build a disk image of the first partition (which is useful for " +"upgrade purposes)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:162 +msgid "" +"`-n`: add `-DNO_CLEAN` to `buildworld`, `buildkernel`. Also, all the files " +"that have already been built in a previous run are kept." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:165 +msgid "" +"A configuration file can be used to tweak as many elements as desired. Load " +"it with `-c`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:167 +msgid "The last options are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:169 +msgid "" +"`-K`: do not install a kernel. A disk image without a kernel will not be " +"able to achieve a normal boot sequence." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/nanobsd/_index.adoc:170 +#, no-wrap +msgid "The Complete Image Building Process" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:175 +msgid "" +"The complete image building process is going through a lot of steps. The " +"exact steps taken will depend on the chosen options when starting the " +"script. Assuming the script is run with no particular options, this is what " +"will happen." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:177 +msgid "" +"`run_early_customize`: commands that are defined in a supplied configuration " +"file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:178 +msgid "" +"`clean_build`: Just cleans the build environment by deleting the previously " +"built files." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:179 +msgid "" +"`make_conf_build`: Assemble make.conffrom the `CONF_WORLD` and `CONF_BUILD` " +"variables." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:180 +msgid "`build_world`: Build world." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:181 +msgid "`build_kernel`: Build the kernel files." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:182 +msgid "`clean_world`: Clean the destination directory." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:183 +msgid "" +"`make_conf_install`: Assemble make.conf from the `CONF_WORLD` and " +"`CONF_INSTALL` variables." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:184 +msgid "`install_world`: Install all files built during `buildworld`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:185 +msgid "" +"`install_etc`: Install the necessary files in the [.filename]#/etc# " +"directory, based on the `make distribution` command." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:186 +msgid "" +"`setup_nanobsd_etc`: the first configuration specific to NanoBSD takes place " +"at this stage. The [.filename]#/etc/diskless# is created and the root " +"filesystem is defined as read-only." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:187 +msgid "`install_kernel`: the kernel and modules files are installed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:188 +msgid "" +"`run_customize`: all the customizing routines defined by the user will be " +"called." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:189 +msgid "" +"`setup_nanobsd`: a special configuration directory layout is setup. The [." +"filename]#/usr/local/etc# gets moved to [.filename]#/etc/local# and a " +"symbolic link is created back from [.filename]#/etc/local# to [.filename]#/" +"usr/local/etc#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:190 +msgid "`prune_usr`: the empty directories from [.filename]#/usr# are removed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:191 +msgid "" +"`run_late_customize`: the very last custom scripts can be run at this point." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:192 +msgid "`fixup_before_diskimage`: List all installed files in a metalog" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:193 +msgid "" +"`create_diskimage`: creates the actual disk image, based on the disk " +"geometries provides parameters." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:194 +msgid "`last_orders`: does nothing for now." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/nanobsd/_index.adoc:195 +#, no-wrap +msgid "Customizing a NanoBSD Image" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:199 +msgid "" +"This is probably the most important and most interesting feature of " +"NanoBSD. This is also where you will be spending most of the time when " +"developing with NanoBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:201 +msgid "" +"Invocation of the following command will force the [.filename]#nanobsd.sh# " +"to read its configuration from [.filename]#myconf.nano# located in the " +"current directory:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:205 +#, no-wrap +msgid "# sh nanobsd.sh -c myconf.nano\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:208 +msgid "Customization is done in two ways:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:210 +msgid "Configuration options" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:211 +msgid "Custom functions" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/nanobsd/_index.adoc:212 +#, no-wrap +msgid "Configuration Options" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:217 +msgid "" +"With configuration settings, it is possible to configure options passed to " +"both the `buildworld` and `installworld` stages of the NanoBSD build " +"process, as well as internal options passed to the main build process of " +"NanoBSD. Through these options it is possible to cut the system down, so it " +"will fit on as little as 64MB. You can use the configuration options to " +"trim down FreeBSD even more, until it will consists of just the kernel and " +"two or three files in the userland." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:220 +msgid "" +"The configuration file consists of configuration options, which override the " +"default values. The most important directives are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:222 +msgid "`NANO_NAME` - Name of build (used to construct the workdir names)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:223 +msgid "`NANO_SRC` - Path to the source tree used to build the image." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:224 +msgid "`NANO_KERNEL` - Name of kernel configuration file used to build kernel." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:225 +msgid "`CONF_BUILD` - Options passed to the `buildworld` stage of the build." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:226 +msgid "" +"`CONF_INSTALL` - Options passed to the `installworld` stage of the build." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:227 +msgid "" +"`CONF_WORLD` - Options passed to both the `buildworld` and the " +"`installworld` stage of the build." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:228 +msgid "" +"`FlashDevice` - Defines what type of media to use. Check [." +"filename]#FlashDevice.sub# for more details." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:230 +msgid "" +"There are many more configuration options that could be relevant depending " +"upon the kind of NanoBSD that is desired." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/nanobsd/_index.adoc:231 +#, no-wrap +msgid "General Customization" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:234 +msgid "" +"There are three stages, by design, at which it is possible to make changes " +"that affect the building process, just by setting up a variable in the " +"provided configuration file:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:236 +msgid "`run_early_customize`: before anything else happens." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:237 +msgid "`run_customize`: after all the standard files have been laid out" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:238 +msgid "" +"`run_late_customize`: at the very end of the process, just before the actual " +"NanoBSD image is built." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:240 +msgid "" +"To customize a NanoBSD image, at any of these steps, it is best to add a " +"specific value to one of the corresponding variables." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:243 +msgid "" +"The `NANO_EARLY_CUSTOMIZE` variable is used at the first step of the " +"building process. At this point, there is no example as to what can be done " +"using that variable, but it may change in the future." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:246 +msgid "" +"The `NANO_CUSTOMIZE` variable is used after the kernel, world and etc " +"configuration files have been installed, and the etc files have been setup " +"as to be a NanoBSD installation. So it is the correct step in the building " +"process to tweak configuration options and add packages, like in the " +"cust_nobeastie example." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:250 +msgid "" +"The `NANO_LATE_CUSTOMIZE` variable is used just before the disk image is " +"created, so it is the very last moment to change anything. Remember that " +"the `setup_nanobsd` routine already executed and that the [.filename]#etc#, " +"[.filename]#conf# and [.filename]#cfg# directories and subdirectories are " +"already modified, so it is not time to change them at this point. Rather, " +"it is possible to add or remove specific files." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/nanobsd/_index.adoc:251 +#, no-wrap +msgid "Booting Options" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:255 +msgid "" +"There are also variables that can change the way the NanoBSD image boots. " +"Two options are passed to man:boot0cfg[8] to initialize the boot sector of " +"the disk image:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:257 +msgid "`NANO_BOOT0CFG`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:258 +msgid "`NANO_BOOTLOADER`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:263 +msgid "" +"With `NANO_BOOTLOADER` a bootloader file can be chosen. The most common " +"possible options are between [.filename]#boot0sio# and [.filename]#boot0# " +"depending on whether the appliance has a serial port or not. It is best to " +"avoid supplying a different bootloader, but it is possible. To do so, it is " +"best to have checked the extref:{handbook}boot[FreeBSD Handbook] chapter on " +"the boot process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:270 +msgid "" +"With `NANO_BOOT0CFG`, the booting process can be tweaked, like selecting on " +"which partition the NanoBSD image will actually boot. It is best to check " +"the man:boot0cfg[8] page before changing the default value of this " +"variable. One option that could be interesting to change is the timeout of " +"the booting procedure. To do so, the `NANO_BOOT0CFG` variable can be " +"changed to `\"-o packet -s 1 -m 3 -t 36\"`. That way the booting process " +"would start after approximately 2 seconds; because it is rare that waiting " +"10 seconds before actually booting is desired." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:273 +msgid "" +"Good to know: the `NANO_BOOT2CFG` variable is only used in the " +"`cust_comconsole` routine that can be called at the `NANO_CUSTOMIZE` step if " +"the appliance has a serial port and all console input and output has to take " +"place through it. Be sure to check the relevant parameters of the serial " +"port, as setting a bad parameter value can make it useless." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/nanobsd/_index.adoc:274 +#, no-wrap +msgid "Disk Image Creation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:278 +msgid "" +"In the end of the boot process is the disk image creation. With this step, " +"the NanoBSD script provides a file that can simply be copied onto a disk for " +"the appliance, and that will make it boot and start." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:280 +msgid "" +"There are many variable that need to be set just right for the script to " +"produce a usable disk image." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:282 +msgid "" +"The `NANO_DRIVE` variable must be set to the drive name of the media at " +"runtime. Usually, the default value `ada0`, which represents the first `IDE`/" +"`ATA`/`SATA` device on the appliance is expected to be the correct one, but " +"a different type of storage could also be used - like a USB key, in which " +"case, it would rather be da0." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:283 +msgid "" +"The `NANO_MEDIASIZE` variable must be set to the size (in 512 bytes sectors) " +"of the storage media that will be used. If you set it wrong, it is possible " +"that the NanoBSD image will not boot at all, and a message at boot time will " +"be warning about incorrect disk geometry." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:285 +msgid "" +"The [.filename]#/etc#, [.filename]#/var#, and [.filename]#/tmp# directories " +"are allocated as man:md[4] (malloc) disks at boot time; so their sizes can " +"be tailored to suit the appliance needs. The `NANO_RAM_ETCSIZE` variable " +"sets the size of the [.filename]#/etc#; and the `NANO_RAM_TMPVARSIZE` " +"variable sets the size of both the [.filename]#/var# and [.filename]#/tmp# " +"directory, as [.filename]#/tmp# is symbolically linked to [.filename]#/var/" +"tmp#. By default, both malloc disks sizes are set at 20MB each. They can " +"always be changed, but usually the [.filename]#/etc# does not grow too much " +"in size, so 20MB is a good starting point, whereas the [.filename]#/var# and " +"especially [.filename]#/tmp# can grow much larger if not careful about it. " +"For memory constrained systems, smaller filesystem sizes may be chosen." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:286 +msgid "" +"As NanoBSD is mainly designed to build a system image for an appliance, it " +"is assumed that the storage media used will be relatively small. For that " +"reason, the filesystem that is laid out is configured to have a small block " +"size (4Kb) and a small fragment size (512b). The configuration options of " +"the filesystem can be modified through the `NANO_NEWFS` variable, but the " +"syntax must respect the man:newfs[8] command format. Also, by default, the " +"filesystem has Soft Updates enabled. The extref:{handbook}[FreeBSD Handbook] " +"can be checked about this." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:287 +msgid "" +"The different partition sizes can be set through the use of `NANO_CODESIZE`, " +"`NANO_CONFSIZE`, and `NANO_DATASIZE` as a multiple of 512 bytes sectors. " +"`NANO_CODESIZE` defines the size of the first two image partitions: `code#1` " +"and `code#2`. They have to be big enough to hold all the files that will be " +"produced as a result of the `buildworld` and `buildkernel` processes. " +"`NANO_CONFSIZE` defines the size of the configuration file partition, so it " +"does not need to be very big; but do not make it so small that it will not " +"hold all configuration files. Finally, `NANO_DATASIZE` defines the size of " +"an optional partition, that can be used on the appliance. The last partition " +"can be used, for example, to keep files created on the fly on disk." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/nanobsd/_index.adoc:288 +#, no-wrap +msgid "Custom Functions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:292 +msgid "" +"It is possible to fine-tune NanoBSD using shell functions in the " +"configuration file. The following example illustrates the basic model of " +"custom functions:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:300 +#, no-wrap +msgid "" +"cust_foo () (\n" +"\techo \"bar=baz\" > \\\n" +"\t\t${NANO_WORLDDIR}/etc/foo\n" +")\n" +"customize_cmd cust_foo\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:303 +msgid "" +"A more useful example of a customization function is the following, which " +"changes the default size of the [.filename]#/etc# directory from 5MB to 30MB:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:311 +#, no-wrap +msgid "" +"cust_etc_size () (\n" +"\tcd ${NANO_WORLDDIR}/conf\n" +"\techo 30000 > default/etc/md_size\n" +")\n" +"customize_cmd cust_etc_size\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:314 +msgid "" +"There are a few default pre-defined customization functions ready for use:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:316 +msgid "" +"`cust_comconsole` - Disables man:getty[8] on the VGA devices (the [." +"filename]#/dev/ttyv*# device nodes) and enables the use of the COM1 serial " +"port as the system console." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:317 +msgid "`cust_allow_ssh_root` - Allow `root` to login via man:sshd[8]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:318 +msgid "" +"`cust_install_files` - Installs files from the [.filename]#nanobsd/Files# " +"directory, which contains some useful scripts for system administration." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:319 +msgid "" +"`cust_pkgng` - Installs packages from the [.filename]#nanobsd/Pkg# directory " +"(needs also pkg-* package to bootstrap)." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/nanobsd/_index.adoc:320 +#, no-wrap +msgid "Adding Packages" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:323 +msgid "" +"Packages can be added to a NanoBSD image, to provide specific " +"functionalities on the appliance. To do so, either:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:325 +msgid "Add the `cust_pkgng` to the `NANO_CUSTOMIZE` variable, or" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:326 +msgid "" +"Add a `'customize_cmd cust_pkgng'` command in a customized configuration " +"file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:329 +msgid "" +"Both methods achieve the same result: launching the `cust_pkgng` routine. " +"This routine will go through `NANO_PACKAGE_DIR` directory to find either all " +"packages or just the list of packages in the `NANO_PACKAGE_LIST` variable." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:335 +msgid "" +"It is common, when installing applications through pkg on a standard FreeBSD " +"environment, that the install process puts configuration files, in the [." +"filename]#usr/local/etc# directory, and startup scripts in the [.filename]#/" +"usr/local/etc/rc.d# directory. So, after the required packages have been " +"installed, they need to be configured in order for them to start right out " +"of the box. To do so, the necessary configuration files have to be " +"installed in the correct directories. This can be achieved by writing " +"dedicated routines or the generic `cust_install_files` routine can be used " +"to lay out files properly from the [.filename]#/usr/src/tools/tools/nanobsd/" +"Files# directory. Usually a statement, sometimes multiple statements, in " +"the [.filename]#/etc/rc.conf# also needs to be added for each package." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/nanobsd/_index.adoc:336 +#, no-wrap +msgid "Configuration File Example" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:339 +msgid "" +"A complete example of a configuration file for building a custom NanoBSD " +"image can be:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:346 +#, no-wrap +msgid "" +"NANO_NAME=custom\n" +"NANO_SRC=/usr/src\n" +"NANO_KERNEL=MYKERNEL\n" +"NANO_IMAGES=2\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:352 +#, no-wrap +msgid "" +"CONF_BUILD='\n" +"WITHOUT_KLDLOAD=YES\n" +"WITHOUT_NETGRAPH=YES\n" +"WITHOUT_PAM=YES\n" +"'\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:368 +#, no-wrap +msgid "" +"CONF_INSTALL='\n" +"WITHOUT_ACPI=YES\n" +"WITHOUT_BLUETOOTH=YES\n" +"WITHOUT_FORTRAN=YES\n" +"WITHOUT_HTML=YES\n" +"WITHOUT_LPR=YES\n" +"WITHOUT_MAN=YES\n" +"WITHOUT_SENDMAIL=YES\n" +"WITHOUT_SHAREDOCS=YES\n" +"WITHOUT_EXAMPLES=YES\n" +"WITHOUT_INSTALLLIB=YES\n" +"WITHOUT_CALENDAR=YES\n" +"WITHOUT_MISC=YES\n" +"WITHOUT_SHARE=YES\n" +"'\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:379 +#, no-wrap +msgid "" +"CONF_WORLD='\n" +"WITHOUT_BIND=YES\n" +"WITHOUT_MODULES=YES\n" +"WITHOUT_KERBEROS=YES\n" +"WITHOUT_GAMES=YES\n" +"WITHOUT_RESCUE=YES\n" +"WITHOUT_LOCALES=YES\n" +"WITHOUT_SYSCONS=YES\n" +"WITHOUT_INFO=YES\n" +"'\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:381 +#, no-wrap +msgid "FlashDevice SanDisk 1G\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:386 +#, no-wrap +msgid "" +"cust_nobeastie() (\n" +"\ttouch ${NANO_WORLDDIR}/boot/loader.conf\n" +"\techo \"beastie_disable=\\\"YES\\\"\" >> ${NANO_WORLDDIR}/boot/loader.conf\n" +")\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:391 +#, no-wrap +msgid "" +"customize_cmd cust_comconsole\n" +"customize_cmd cust_install_files\n" +"customize_cmd cust_allow_ssh_root\n" +"customize_cmd cust_nobeastie\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:395 +msgid "" +"All the build and install compilation options can be found in the man:src." +"conf[5] man page, but not all options can or should be used when building a " +"NanoBSD image. The build and install options should be defined according to " +"the needs of the image being built." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:399 +msgid "" +"For example, the ftp client and server might not be needed. Adding " +"`WITHOUT_FTP=TRUE` to a configuration file in the `CONF_BUILD` section will " +"avoid having them built. Also, if the NanoBSD appliance will not be used to " +"build programs then it is possible to add the `WITHOUT_BINUTILS=TRUE` in the " +"`CONF_INSTALL` section; but not in the `CONF_BUILD` section as they will be " +"used to build the NanoBSD image." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:401 +msgid "" +"Not building a particular set of programs - through a compilation option - " +"shortens the overall building time and lowers the required size for the disk " +"image, whereas not installing the same specific set of programs does not " +"lower the overall building time." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/nanobsd/_index.adoc:402 +#, no-wrap +msgid "Updating NanoBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:405 +msgid "The update process of NanoBSD is relatively simple:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:409 +msgid "Build a new NanoBSD image, as usual." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:410 +msgid "" +"Upload the new image into an unused partition of a running NanoBSD appliance." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:412 +msgid "" +"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)." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:413 +msgid "Reboot, and start the system from the newly installed partition." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:414 +msgid "If all goes well, the upgrade is finished." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:415 +msgid "" +"If anything goes wrong, reboot back into the previous partition (which " +"contains the old, working image), to restore system functionality as fast as " +"possible. Fix any problems of the new build, and repeat the process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:418 +msgid "" +"To install new image onto the running NanoBSD system, it is possible to use " +"either the [.filename]#updatep1# or [.filename]#updatep2# script located in " +"the [.filename]#/root# directory, depending from which partition is running " +"the current system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:420 +msgid "" +"According to which services are available on host serving new NanoBSD image " +"and what type of transfer is preferred, it is possible to examine one of " +"these three ways:" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/nanobsd/_index.adoc:421 +#, no-wrap +msgid "Using man:ftp[1]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:424 +msgid "If the transfer speed is in first place, use this example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:429 +#, no-wrap +msgid "" +"# ftp myhost\n" +"get _.disk.image \"| sh updatep1\"\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/nanobsd/_index.adoc:431 +#, no-wrap +msgid "Using man:ssh[1]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:434 +msgid "If a secure transfer is preferred, consider using this example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:438 +#, no-wrap +msgid "# ssh myhost cat _.disk.image.gz | zcat | sh updatep1\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/nanobsd/_index.adoc:440 +#, no-wrap +msgid "Using man:nc[1]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:443 +msgid "" +"Try this example if the remote host is not running neither man:ftpd[8] or " +"man:sshd[8] service:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:447 +msgid "" +"At first, open a TCP listener on host serving the image and make it send the " +"image to client:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:451 +#, no-wrap +msgid "myhost# nc -l 2222 < _.disk.image\n" +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/nanobsd/_index.adoc:456 +msgid "" +"Make sure that the used port is not blocked to receive incoming connections " +"from NanoBSD host by firewall." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/nanobsd/_index.adoc:458 +msgid "" +"Connect to the host serving new image and execute [.filename]#updatep1# " +"script:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/nanobsd/_index.adoc:462 +#, no-wrap +msgid "# nc myhost 2222 | sh updatep1\n" +msgstr "" diff --git a/documentation/content/en/articles/new-users/_index.po b/documentation/content/en/articles/new-users/_index.po new file mode 100644 index 0000000000..38ff671f2c --- /dev/null +++ b/documentation/content/en/articles/new-users/_index.po @@ -0,0 +1,1126 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2022-02-01 09:21-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/new-users/_index.adoc:1 +#, no-wrap +msgid "Introduction for people new to both FreeBSD and UNIX®" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/articles/new-users/_index.adoc:1 +#, no-wrap +msgid "For People New to Both FreeBSD and UNIX®" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/new-users/_index.adoc:11 +#, no-wrap +msgid "For People New to Both FreeBSD and UNIX(R)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:46 +msgid "" +"Congratulations on installing FreeBSD! This introduction is for people new " +"to both FreeBSD _and_ UNIX(R)-so it starts with basics." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:48 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/new-users/_index.adoc:52 +#, no-wrap +msgid "Logging in and Getting Out" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:58 +msgid "" +"Log in (when you see `login:`) as a user you created during installation or " +"as `root`. (Your FreeBSD installation will already have an account for " +"`root`; who can go anywhere and do anything, including deleting essential " +"files, so be careful!) The symbols % and # in the following stand for the " +"prompt (yours may be different), with % indicating an ordinary user and # " +"indicating `root`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:60 +msgid "To log out (and get a new `login:` prompt) type" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:64 +#, no-wrap +msgid "# exit\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:68 +msgid "" +"as often as necessary. Yes, press kbd:[enter] after commands, and remember " +"that UNIX(R) is case-sensitive-``exit``, not `EXIT`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:70 +msgid "To shut down the machine type" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:74 +#, no-wrap +msgid "# /sbin/shutdown -h now\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:77 +msgid "Or to reboot type" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:81 +#, no-wrap +msgid "# /sbin/shutdown -r now\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:84 +msgid "or" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:88 +#, no-wrap +msgid "# /sbin/reboot\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:94 +msgid "" +"You can also reboot with kbd:[Ctrl+Alt+Delete]. Give it a little time to do " +"its work. This is equivalent to `/sbin/reboot` in recent releases of " +"FreeBSD and is much, much better than hitting the reset button. You do not " +"want to have to reinstall this thing, do you?" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/new-users/_index.adoc:96 +#, no-wrap +msgid "Adding a User with Root Privileges" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:99 +msgid "" +"If you did not create any users when you installed the system and are thus " +"logged in as `root`, you should probably create a user now with" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:103 +#, no-wrap +msgid "# adduser\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:109 +msgid "" +"The first time you use `adduser`, it might ask for some defaults to save. " +"You might want to make the default shell man:csh[1] instead of man:sh[1], if " +"it suggests `sh` as the default. Otherwise just press enter to accept each " +"default. These defaults are saved in [.filename]#/etc/adduser.conf#, an " +"editable file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:113 +msgid "" +"Suppose you create a user `jack` with full name _Jack Benimble_. Give " +"`jack` a password if security (even kids around who might pound on the " +"keyboard) is an issue. When it asks you if you want to invite `jack` into " +"other groups, type `wheel`" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:117 +#, no-wrap +msgid "Login group is \"jack\". Invite jack into other groups: wheel\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:121 +msgid "" +"This will make it possible to log in as `jack` and use the man:su[1] command " +"to become `root`. Then you will not get scolded any more for logging in as " +"`root`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:124 +msgid "" +"You can quit `adduser` any time by typing kbd:[Ctrl+C], and at the end you " +"will have a chance to approve your new user or simply type kbd:[n] for no. " +"You might want to create a second new user so that when you edit `jack`'s " +"login files, you will have a hot spare in case something goes wrong." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:127 +msgid "" +"Once you have done this, use `exit` to get back to a login prompt and log in " +"as `jack`. In general, it is a good idea to do as much work as possible as " +"an ordinary user who does not have the power-and risk-of `root`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:130 +msgid "" +"If you already created a user and you want the user to be able to `su` to " +"`root`, you can log in as `root` and edit the file [.filename]#/etc/group#, " +"adding `jack` to the first line (the group `wheel`). But first you need to " +"practice man:vi[1], the text editor-or use the simpler text editor, man:" +"ee[1], installed on recent versions of FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:132 +msgid "To delete a user, use `rmuser`." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/new-users/_index.adoc:134 +#, no-wrap +msgid "Looking Around" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:137 +msgid "" +"Logged in as an ordinary user, look around and try out some commands that " +"will access the sources of help and information within FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:139 +msgid "Here are some commands and what they do:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:140 +#, no-wrap +msgid "`id`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:142 +msgid "Tells you who you are!" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:143 +#, no-wrap +msgid "`pwd`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:145 +msgid "Shows you where you are-the current working directory." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:146 +#, no-wrap +msgid "`ls`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:148 +msgid "Lists the files in the current directory." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:149 +#, no-wrap +msgid "`ls -F`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:151 +msgid "" +"Lists the files in the current directory with a * after executables, a `/` " +"after directories, and an `@` after symbolic links." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:152 +#, no-wrap +msgid "`ls -l`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:154 +msgid "Lists the files in long format-size, date, permissions." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:155 +#, no-wrap +msgid "`ls -a`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:158 +msgid "" +"Lists hidden \"dot\" files with the others. If you are `root`, the \"dot\" " +"files show up without the `-a` switch." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:159 +#, no-wrap +msgid "`cd`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:163 +msgid "" +"Changes directories. `cd ..` backs up one level; note the space after `cd`. " +"`cd /usr/local` goes there. `cd ~` goes to the home directory of the person " +"logged in-e.g., [.filename]#/usr/home/jack#. Try `cd /cdrom`, and then " +"`ls`, to find out if your CDROM is mounted and working." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:164 +#, no-wrap +msgid "`less _filename_`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:168 +msgid "" +"Lets you look at a file (named _filename_) without changing it. Try `less /" +"etc/fstab`. Type `q` to quit." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:169 +#, no-wrap +msgid "`cat _filename_`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:174 +msgid "" +"Displays _filename_ on screen. If it is too long and you can see only the " +"end of it, press kbd:[ScrollLock] and use the kbd:[up-arrow] to move " +"backward; you can use kbd:[ScrollLock] with manual pages too. Press kbd:" +"[ScrollLock] again to quit scrolling. You might want to try `cat` on some " +"of the dot files in your home directory-`cat .cshrc`, `cat .login`, `cat ." +"profile`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:178 +msgid "" +"You will notice aliases in [.filename]#.cshrc# for some of the `ls` commands " +"(they are very convenient). You can create other aliases by editing [." +"filename]#.cshrc#. You can make these aliases available to all users on the " +"system by putting them in the system-wide `csh` configuration file, [." +"filename]#/etc/csh.cshrc#." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/new-users/_index.adoc:180 +#, no-wrap +msgid "Getting Help and Information" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:184 +msgid "" +"Here are some useful sources of help. _Text_ stands for something of your " +"choice that you type in-usually a command or filename." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:185 +#, no-wrap +msgid "`apropos _text_`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:187 +msgid "Everything containing string _text_ in the `whatis database`." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:188 +#, no-wrap +msgid "`man _text_`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:193 +msgid "" +"The manual page for _text_. The major source of documentation for UNIX(R) " +"systems. `man ls` will tell you all the ways to use `ls`. Press kbd:" +"[Enter] to move through text, kbd:[Ctrl+B] to go back a page, kbd:[Ctrl+F] " +"to go forward, kbd:[q] or kbd:[Ctrl+C] to quit." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:194 +#, no-wrap +msgid "`which _text_`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:196 +msgid "Tells you where in the user's path the command _text_ is found." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:197 +#, no-wrap +msgid "`locate _text_`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:199 +msgid "All the paths where the string _text_ is found." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:200 +#, no-wrap +msgid "`whatis _text_`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:203 +msgid "" +"Tells you what the command _text_ does and its manual page. Typing `whatis " +"*` will tell you about all the binaries in the current directory." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:204 +#, no-wrap +msgid "`whereis _text_`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:206 +msgid "Finds the file _text_, giving its full path." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:210 +msgid "" +"You might want to try using `whatis` on some common useful commands like " +"`cat`, `more`, `grep`, `mv`, `find`, `tar`, `chmod`, `chown`, `date`, and " +"`script`. `more` lets you read a page at a time as it does in DOS, e.g., " +"`ls -l | more` or `more _filename_`. The * works as a wildcard-e.g., `ls " +"w*` will show you files beginning with `w`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:214 +msgid "" +"Are some of these not working very well? Both man:locate[1] and man:" +"whatis[1] depend on a database that is rebuilt weekly. If your machine is " +"not going to be left on over the weekend (and running FreeBSD), you might " +"want to run the commands for daily, weekly, and monthly maintenance now and " +"then. Run them as `root` and, for now, give each one time to finish before " +"you start the next one." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:223 +#, no-wrap +msgid "" +"# periodic daily\n" +"output omitted\n" +"# periodic weekly\n" +"output omitted\n" +"# periodic monthly\n" +"output omitted\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:229 +msgid "" +"If you get tired of waiting, press kbd:[Alt+F2] to get another _virtual " +"console_, and log in again. After all, it is a multi-user, multi-tasking " +"system. Nevertheless these commands will probably flash messages on your " +"screen while they are running; you can type `clear` at the prompt to clear " +"the screen. Once they have run, you might want to look at [.filename]#/var/" +"mail/root# and [.filename]#/var/log/messages#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:235 +msgid "" +"Running such commands is part of system administration-and as a single user " +"of a UNIX(R) system, you are your own system administrator. Virtually " +"everything you need to be `root` to do is system administration. Such " +"responsibilities are not covered very well even in those big fat books on " +"UNIX(R), which seem to devote a lot of space to pulling down menus in " +"windows managers. You might want to get one of the two leading books on " +"systems administration, either Evi Nemeth et.al.'s UNIX System " +"Administration Handbook (Prentice-Hall, 1995, ISBN 0-13-15051-7)-the second " +"edition with the red cover; or Æleen Frisch's Essential System " +"Administration (O'Reilly & Associates, 2002, ISBN 0-596-00343-9). I used " +"Nemeth." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/new-users/_index.adoc:237 +#, no-wrap +msgid "Editing Text" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:243 +msgid "" +"To configure your system, you need to edit text files. Most of them will be " +"in the [.filename]#/etc# directory; and you will need to `su` to `root` to " +"be able to change them. You can use the easy `ee`, but in the long run the " +"text editor `vi` is worth learning. There is an excellent tutorial on vi in " +"[.filename]#/usr/src/contrib/nvi/docs/tutorial#, if you have the system " +"sources installed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:247 +msgid "" +"Before you edit a file, you should probably back it up. Suppose you want to " +"edit [.filename]#/etc/rc.conf#. You could just use `cd /etc` to get to the " +"[.filename]#/etc# directory and do:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:251 +#, no-wrap +msgid "# cp rc.conf rc.conf.orig\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:255 +msgid "" +"This would copy [.filename]#rc.conf# to [.filename]#rc.conf.orig#, and you " +"could later copy [.filename]#rc.conf.orig# to [.filename]#rc.conf# to " +"recover the original. But even better would be moving (renaming) and then " +"copying back:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:260 +#, no-wrap +msgid "" +"# mv rc.conf rc.conf.orig\n" +"# cp rc.conf.orig rc.conf\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:265 +msgid "" +"because `mv` preserves the original date and owner of the file. You can now " +"edit [.filename]#rc.conf#. If you want the original back, you would then " +"`mv rc.conf rc.conf.myedit` (assuming you want to preserve your edited " +"version) and then" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:269 +#, no-wrap +msgid "# mv rc.conf.orig rc.conf\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:272 +msgid "to put things back the way they were." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:274 +msgid "To edit a file, type" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:278 +#, no-wrap +msgid "# vi filename\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:283 +msgid "" +"Move through the text with the arrow keys. kbd:[Esc] (the escape key) puts " +"`vi` in command mode. Here are some commands:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:284 +#, no-wrap +msgid "`x`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:286 +msgid "delete letter the cursor is on" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:287 +#, no-wrap +msgid "`dd`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:289 +msgid "delete the entire line (even if it wraps on the screen)" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:290 +#, no-wrap +msgid "`i`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:292 +msgid "insert text at the cursor" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:293 +#, no-wrap +msgid "`a`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:295 +msgid "insert text after the cursor" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:298 +msgid "" +"Once you type `i` or `a`, you can enter text. `Esc` puts you back in " +"command mode where you can type" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:299 +#, no-wrap +msgid "`:w`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:301 +msgid "to write your changes to disk and continue editing" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:302 +#, no-wrap +msgid "`:wq`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:304 +msgid "to write and quit" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:305 +#, no-wrap +msgid "`:q!`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:307 +msgid "to quit without saving changes" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:308 +#, no-wrap +msgid "`/_text_`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:310 +msgid "" +"to move the cursor to _text_; `/` kbd:[Enter] (the enter key) to find the " +"next instance of _text_." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:311 +#, no-wrap +msgid "`G`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:313 +msgid "to go to the end of the file" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:314 +#, no-wrap +msgid "`nG`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:316 +msgid "to go to line _n_ in the file, where _n_ is a number" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:317 +#, no-wrap +msgid "kbd:[Ctrl+L]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:319 +msgid "to redraw the screen" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:320 +#, no-wrap +msgid "kbd:[Ctrl+b] and kbd:[Ctrl+f]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:322 +msgid "go back and forward a screen, as they do with `more` and `view`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:327 +msgid "" +"Practice with `vi` in your home directory by creating a new file with `vi " +"_filename_` and adding and deleting text, saving the file, and calling it up " +"again. `vi` delivers some surprises because it is really quite complex, and " +"sometimes you will inadvertently issue a command that will do something you " +"do not expect. (Some people actually like `vi`-it is more powerful than DOS " +"EDIT-find out about `:r`.) Use kbd:[Esc] one or more times to be sure you " +"are in command mode and proceed from there when it gives you trouble, save " +"often with `:w`, and use `:q!` to get out and start over (from your last `:" +"w`) when you need to." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:331 +msgid "" +"Now you can `cd` to [.filename]#/etc#, `su` to `root`, use `vi` to edit the " +"file [.filename]#/etc/group#, and add a user to `wheel` so the user has root " +"privileges. Just add a comma and the user's login name to the end of the " +"first line in the file, press kbd:[Esc], and use `:wq` to write the file to " +"disk and quit. Instantly effective. (You did not put a space after the " +"comma, did you?)" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/new-users/_index.adoc:333 +#, no-wrap +msgid "Other Useful Commands" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:335 +#, no-wrap +msgid "`df`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:337 +msgid "shows file space and mounted systems." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:338 +#, no-wrap +msgid "`ps aux`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:340 +msgid "shows processes running. `ps ax` is a narrower form." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:341 +#, no-wrap +msgid "`rm _filename_`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:343 +msgid "remove _filename_." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:344 +#, no-wrap +msgid "`rm -R _dir_`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:346 +msgid "removes a directory _dir_ and all subdirectories-careful!" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:347 +#, no-wrap +msgid "`ls -R`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:349 +msgid "" +"lists files in the current directory and all subdirectories; I used a " +"variant, `ls -AFR > where.txt`, to get a list of all the files in [." +"filename]#/# and (separately) [.filename]#/usr# before I found better ways " +"to find files." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:350 +#, no-wrap +msgid "`passwd`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:352 +msgid "to change user's password (or ``root``'s password)" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/new-users/_index.adoc:353 +#, no-wrap +msgid "`man hier`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:355 +msgid "manual page on the UNIX(R) filesystem" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:357 +msgid "" +"Use `find` to locate [.filename]#filename# in [.filename]#/usr# or any of " +"its subdirectories with" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:361 +#, no-wrap +msgid "% find /usr -name \"filename\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:365 +msgid "" +"You can use * as a wildcard in `\"_filename_\"` (which should be in " +"quotes). If you tell `find` to search in [.filename]#/# instead of [." +"filename]#/usr# it will look for the file(s) on all mounted filesystems, " +"including the CDROM and the DOS partition." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:367 +msgid "" +"An excellent book that explains UNIX(R) commands and utilities is Abrahams & " +"Larson, Unix for the Impatient (2nd ed., Addison-Wesley, 1996). There is " +"also a lot of UNIX(R) information on the Internet." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/new-users/_index.adoc:369 +#, no-wrap +msgid "Next Steps" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:376 +msgid "" +"You should now have the tools you need to get around and edit files, so you " +"can get everything up and running. There is a great deal of information in " +"the FreeBSD handbook (which is probably on your hard drive) and link:https://" +"www.FreeBSD.org/[FreeBSD's web site]. A wide variety of packages and ports " +"are on the CDROM as well as the web site. The handbook tells you more about " +"how to use them (get the package if it exists, with `pkg add _packagename_`, " +"where _packagename_ is the filename of the package). The CDROM has lists of " +"the packages and ports with brief descriptions in [.filename]#cdrom/packages/" +"index#, [.filename]#cdrom/packages/index.txt#, and [.filename]#cdrom/ports/" +"index#, with fuller descriptions in [.filename]#/cdrom/ports/\\*/*/pkg/" +"DESCR#, where the *s represent subdirectories of kinds of programs and " +"program names respectively." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:378 +msgid "" +"If you find the handbook too sophisticated (what with `lndir` and all) on " +"installing ports from the CDROM, here is what usually works:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:381 +msgid "" +"Find the port you want, say `kermit`. There will be a directory for it on " +"the CDROM. Copy the subdirectory to [.filename]#/usr/local# (a good place " +"for software you add that should be available to all users) with:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:385 +#, no-wrap +msgid "# cp -R /cdrom/ports/comm/kermit /usr/local\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:388 +msgid "" +"This should result in a [.filename]#/usr/local/kermit# subdirectory that has " +"all the files that the `kermit` subdirectory on the CDROM has." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:393 +msgid "" +"Next, create the directory [.filename]#/usr/ports/distfiles# if it does not " +"already exist using `mkdir`. Now check [.filename]#/cdrom/ports/distfiles# " +"for a file with a name that indicates it is the port you want. Copy that " +"file to [.filename]#/usr/ports/distfiles#; in recent versions you can skip " +"this step, as FreeBSD will do it for you. In the case of `kermit`, there is " +"no distfile." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:396 +msgid "" +"Then `cd` to the subdirectory of [.filename]#/usr/local/kermit# that has the " +"file [.filename]#Makefile#. Type" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:400 +#, no-wrap +msgid "# make all install\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:406 +msgid "" +"During this process the port will FTP to get any compressed files it needs " +"that it did not find on the CDROM or in [.filename]#/usr/ports/distfiles#. " +"If you do not have your network running yet and there was no file for the " +"port in [.filename]#/cdrom/ports/distfiles#, you will have to get the " +"distfile using another machine and copy it to [.filename]#/usr/ports/" +"distfiles#. Read [.filename]#Makefile# (with `cat` or `more` or `view`) to " +"find out where to go (the master distribution site) to get the file and what " +"its name is. (Use binary file transfers!) Then go back to [.filename]#/usr/" +"local/kermit#, find the directory with [.filename]#Makefile#, and type `make " +"all install`." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/new-users/_index.adoc:408 +#, no-wrap +msgid "Your Working Environment" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:413 +msgid "" +"Your shell is the most important part of your working environment. The " +"shell is what interprets the commands you type on the command line, and thus " +"communicates with the rest of the operating system. You can also write " +"shell scripts a series of commands to be run without intervention." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:417 +msgid "" +"Two shells come installed with FreeBSD: `csh` and `sh`. `csh` is good for " +"command-line work, but scripts should be written with `sh` (or `bash`). You " +"can find out what shell you have by typing `echo $SHELL`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:423 +msgid "" +"The `csh` shell is okay, but `tcsh` does everything `csh` does and more. It " +"allows you to recall commands with the arrow keys and edit them. It has tab-" +"key completion of filenames (`csh` uses kbd:[Esc]), and it lets you switch " +"to the directory you were last in with `cd -`. It is also much easier to " +"alter your prompt with `tcsh`. It makes life a lot easier." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/new-users/_index.adoc:425 +msgid "Here are the three steps for installing a new shell:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/new-users/_index.adoc:429 +msgid "" +"Install the shell as a port or a package, just as you would any other port " +"or package." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/new-users/_index.adoc:430 +msgid "" +"Use `chsh` to change your shell to `tcsh` permanently, or type `tcsh` at the " +"prompt to change your shell without logging in again." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/new-users/_index.adoc:438 +msgid "" +"It can be dangerous to change `root`'s shell to something other than `sh` or " +"`csh` on early versions of FreeBSD and many other versions of UNIX(R); you " +"may not have a working shell when the system puts you into single user " +"mode. The solution is to use `su -m` to become `root`, which will give you " +"the `tcsh` as `root`, because the shell is part of the environment. You can " +"make this permanent by adding it to your [.filename]#.tcshrc# as an alias " +"with:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/new-users/_index.adoc:442 +#, no-wrap +msgid "alias su su -m\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/new-users/_index.adoc:449 +msgid "" +"When `tcsh` starts up, it will read the [.filename]#/etc/csh.cshrc# and [." +"filename]#/etc/csh.login# files, as does `csh`. It will also read [." +"filename]#.login# in your home directory and [.filename]#.cshrc# as well, " +"unless you provide a [.filename]#.tcshrc#. This you can do by simply " +"copying [.filename]#.cshrc# to [.filename]#.tcshrc#." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/new-users/_index.adoc:453 +msgid "" +"Now that you have installed `tcsh`, you can adjust your prompt. You can " +"find the details in the manual page for `tcsh`, but here is a line to put in " +"your [.filename]#.tcshrc# that will tell you how many commands you have " +"typed, what time it is, and what directory you are in. It also produces a " +"`>` if you are an ordinary user and a # if you are `root`, but tsch will do " +"that in any case:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/new-users/_index.adoc:455 +msgid "set prompt = \"%h %t %~ %# \"" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/new-users/_index.adoc:460 +msgid "" +"This should go in the same place as the existing set prompt line if there is " +"one, or under \"if($?prompt) then\" if not. Comment out the old line; you " +"can always switch back to it if you prefer it. Do not forget the spaces and " +"quotes. You can get the [.filename]#.tcshrc# reread by typing `source ." +"tcshrc`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/new-users/_index.adoc:464 +msgid "" +"You can get a listing of other environmental variables that have been set by " +"typing `env` at the prompt. The result will show you your default editor, " +"pager, and terminal type, among possibly many others. A useful command if " +"you log in from a remote location and cannot run a program because the " +"terminal is not capable is `setenv TERM vt100`." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/new-users/_index.adoc:466 +#, no-wrap +msgid "Other" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/new-users/_index.adoc:470 +msgid "" +"As `root`, you can unmount the CDROM with `/sbin/umount /cdrom`, take it out " +"of the drive, insert another one, and mount it with `/sbin/mount_cd9660 /dev/" +"cd0a /cdrom` assuming cd0a is the device name for your CDROM drive. The " +"most recent versions of FreeBSD let you mount the CDROM with just `/sbin/" +"mount /cdrom`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/new-users/_index.adoc:476 +msgid "" +"Using the live filesystem-the second of FreeBSD's CDROM disks-is useful if " +"you have got limited space. What is on the live filesystem varies from " +"release to release. You might try playing games from the CDROM. This " +"involves using `lndir`, which gets installed with the X Window System, to " +"tell the program(s) where to find the necessary files, because they are in [." +"filename]#/cdrom# instead of in [.filename]#/usr# and its subdirectories, " +"which is where they are expected to be. Read `man lndir`." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/new-users/_index.adoc:478 +#, no-wrap +msgid "Comments Welcome" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/new-users/_index.adoc:482 +msgid "" +"If you use this guide I would be interested in knowing where it was unclear " +"and what was left out that you think should be included, and if it was " +"helpful. My thanks to Eugene W. Stark, professor of computer science at " +"SUNY-Stony Brook, and John Fieber for helpful comments." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/new-users/_index.adoc:483 +msgid "" +"Annelise Anderson, mailto:andrsn@andrsn.stanford.edu[andrsn@andrsn.stanford." +"edu]" +msgstr "" diff --git a/documentation/content/en/articles/pam/_index.adoc b/documentation/content/en/articles/pam/_index.adoc index 8aa56bb4b2..7f6ffe249b 100644 --- a/documentation/content/en/articles/pam/_index.adoc +++ b/documentation/content/en/articles/pam/_index.adoc @@ -411,16 +411,18 @@ It is essential to understand that PAM's configuration system is centered on cha [[pam-config-breakdown]] === Breakdown of a Configuration Line -As explained in <<pam-config-file>>, each line in [.filename]#/etc/pam.conf# consists of four or more fields: the service name, the facility name, the control flag, the module name, and zero or more module arguments. +As explained in crossref:pam[pam-config-file, PAM Policy Files], each line in [.filename]#/etc/pam.conf# consists of four or more fields: the service name, the facility name, the control flag, the module name, and zero or more module arguments. The service name is generally (though not always) the name of the application the statement applies to. If you are unsure, refer to the individual application's documentation to determine what service name it uses. Note that if you use [.filename]#/etc/pam.d/# instead of [.filename]#/etc/pam.conf#, the service name is specified by the name of the policy file, and omitted from the actual configuration lines, which then start with the facility name. -The facility is one of the four facility keywords described in <<pam-facilities-primitives>>. +The facility is one of the four facility keywords described in +crossref:pam[pam-facilities-primitives, Facilities and Primitives]. -Likewise, the control flag is one of the four keywords described in <<pam-chains-policies>>, describing how to interpret the return code from the module. +Likewise, the control flag is one of the four keywords described in + crossref:pam[pam-chains-policies, Chains and Policies], describing how to interpret the return code from the module. Linux-PAM supports an alternate syntax that lets you specify the action to associate with each possible return code, but this should be avoided as it is non-standard and closely tied in with the way Linux-PAM dispatches service calls (which differs greatly from the way Solaris(TM) and OpenPAM do it.) Unsurprisingly, OpenPAM does not support this syntax. @@ -544,22 +546,6 @@ The man:pam_login_access[8] module provides an implementation of the account man The man:pam_nologin[8] module refuses non-root logins when [.filename]#/var/run/nologin# exists. This file is normally created by man:shutdown[8] when less than five minutes remain until the scheduled shutdown time. -[[pam-modules-opie]] -=== man:pam_opie[8] - -The man:pam_opie[8] module implements the man:opie[4] authentication method. -The man:opie[4] system is a challenge-response mechanism where the response to each challenge is a direct function of the challenge and a passphrase, so the response can be easily computed "just in time" by anyone possessing the passphrase, eliminating the need for password lists. -Moreover, since man:opie[4] never reuses a challenge that has been correctly answered, it is not vulnerable to replay attacks. - -[[pam-modules-opieaccess]] -=== man:pam_opieaccess[8] - -The man:pam_opieaccess[8] module is a companion module to man:pam_opie[8]. -Its purpose is to enforce the restrictions codified in man:opieaccess[5], which regulate the conditions under which a user who would normally authenticate herself using man:opie[4] is allowed to use alternate methods. -This is most often used to prohibit the use of password authentication from untrusted hosts. - -In order to be effective, the man:pam_opieaccess[8] module must be listed as `requisite` immediately after a `sufficient` entry for man:pam_opie[8], and before any other modules, in the `auth` chain. - [[pam-modules-passwdqc]] === man:pam_passwdqc[8] @@ -604,7 +590,7 @@ It is most useful for non-networked services such as man:su[1], where the identi The man:pam_ssh[8] module provides both authentication and session services. The authentication service allows users who have passphrase-protected SSH secret keys in their [.filename]#~/.ssh# directory to authenticate themselves by typing their passphrase. The session service starts man:ssh-agent[1] and preloads it with the keys that were decrypted in the authentication phase. -This feature is particularly useful for local logins, whether in X (using man:xdm[1] or another PAM-aware X login manager) or at the console. +This feature is particularly useful for local logins, whether in X (using man:xdm[8] or another PAM-aware X login manager) or at the console. [[pam-modules-tacplus]] === man:pam_tacplus[8] @@ -638,7 +624,7 @@ The following is a minimal implementation of man:su[1] using PAM. Note that it uses the OpenPAM-specific man:openpam_ttyconv[3] conversation function, which is prototyped in [.filename]#security/openpam.h#. If you wish build this application on a system with a different PAM library, you will have to provide your own conversation function. A robust conversation function is surprisingly difficult to implement; -the one presented in <<pam-sample-conv>> is a good starting point, but should not be used in real-world applications. +the one presented in crossref:pam[pam-sample-conv, Sample PAM Conversation Function] is a good starting point, but should not be used in real-world applications. [.programlisting] .... diff --git a/documentation/content/en/articles/pam/_index.po b/documentation/content/en/articles/pam/_index.po new file mode 100644 index 0000000000..103c16dbe2 --- /dev/null +++ b/documentation/content/en/articles/pam/_index.po @@ -0,0 +1,1722 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-12-29 08:30-0500\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/pam/_index.adoc:1 +#, no-wrap +msgid "A guide to the PAM system and modules under FreeBSD" +msgstr "" + +#. Copyright (c) 2001-2003 Networks Associates Technology, Inc. +#. All rights reserved. +#. This software was developed for the FreeBSD Project by ThinkSec AS and +#. Network Associates Laboratories, the Security Research Division of +#. Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +#. ("CBOSS"), as part of the DARPA CHATS research program. +#. Redistribution and use in source and binary forms, with or without +#. modification, are permitted provided that the following conditions +#. are met: +#. 1. Redistributions of source code must retain the above copyright +#. notice, this list of conditions and the following disclaimer. +#. 2. Redistributions in binary form must reproduce the above copyright +#. notice, this list of conditions and the following disclaimer in the +#. documentation and/or other materials provided with the distribution. +#. 3. The name of the author may not be used to endorse or promote +#. products derived from this software without specific prior written +#. permission. +#. THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +#. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +#. IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +#. ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +#. FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +#. DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +#. OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +#. HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +#. LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +#. OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +#. SUCH DAMAGE. +#. type: Title = +#: documentation/content/en/articles/pam/_index.adoc:1 +#: documentation/content/en/articles/pam/_index.adoc:45 +#, no-wrap +msgid "Pluggable Authentication Modules" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:81 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:83 +msgid "" +"This article describes the underlying principles and mechanisms of the " +"Pluggable Authentication Modules (PAM) library, and explains how to " +"configure PAM, how to integrate PAM into applications, and how to write PAM " +"modules." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:85 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pam/_index.adoc:89 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:92 +msgid "" +"The Pluggable Authentication Modules (PAM) library is a generalized API for " +"authentication-related services which allows a system administrator to add " +"new authentication methods simply by installing new PAM modules, and to " +"modify authentication policies by editing configuration files." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:96 +msgid "" +"PAM was defined and developed in 1995 by Vipin Samar and Charlie Lai of Sun " +"Microsystems, and has not changed much since. In 1997, the Open Group " +"published the X/Open Single Sign-on (XSSO) preliminary specification, which " +"standardized the PAM API and added extensions for single (or rather " +"integrated) sign-on. At the time of this writing, this specification has " +"not yet been adopted as a standard." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:98 +msgid "" +"Although this article focuses primarily on FreeBSD 5.x, which uses OpenPAM, " +"it should be equally applicable to FreeBSD 4.x, which uses Linux-PAM, and " +"other operating systems such as Linux and Solaris(TM)." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pam/_index.adoc:100 +#, no-wrap +msgid "Terms and Conventions" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:103 +#, no-wrap +msgid "Definitions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:110 +msgid "" +"The terminology surrounding PAM is rather confused. Neither Samar and Lai's " +"original paper nor the XSSO specification made any attempt at formally " +"defining terms for the various actors and entities involved in PAM, and the " +"terms that they do use (but do not define) are sometimes misleading and " +"ambiguous. The first attempt at establishing a consistent and unambiguous " +"terminology was a whitepaper written by Andrew G. Morgan (author of Linux-" +"PAM) in 1999. While Morgan's choice of terminology was a huge leap forward, " +"it is in this author's opinion by no means perfect. What follows is an " +"attempt, heavily inspired by Morgan, to define precise and unambiguous terms " +"for all actors and entities involved in PAM." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:111 +#, no-wrap +msgid "account" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:113 +msgid "The set of credentials the applicant is requesting from the arbitrator." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:114 +#, no-wrap +msgid "applicant" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:116 +msgid "The user or entity requesting authentication." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:117 +#, no-wrap +msgid "arbitrator" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:119 +msgid "" +"The user or entity who has the privileges necessary to verify the " +"applicant's credentials and the authority to grant or deny the request." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:120 +#, no-wrap +msgid "chain" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:123 +msgid "" +"A sequence of modules that will be invoked in response to a PAM request. " +"The chain includes information about the order in which to invoke the " +"modules, what arguments to pass to them, and how to interpret the results." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:124 +#, no-wrap +msgid "client" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:126 +msgid "" +"The application responsible for initiating an authentication request on " +"behalf of the applicant and for obtaining the necessary authentication " +"information from him." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:127 +#, no-wrap +msgid "facility" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:129 +msgid "" +"One of the four basic groups of functionality provided by PAM: " +"authentication, account management, session management and authentication " +"token update." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:130 +#, no-wrap +msgid "module" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:132 +msgid "" +"A collection of one or more related functions implementing a particular " +"authentication facility, gathered into a single (normally dynamically " +"loadable) binary file and identified by a single name." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:133 +#, no-wrap +msgid "policy" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:136 +msgid "" +"The complete set of configuration statements describing how to handle PAM " +"requests for a particular service. A policy normally consists of four " +"chains, one for each facility, though some services do not use all four " +"facilities." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:137 +#, no-wrap +msgid "server" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:139 +msgid "" +"The application acting on behalf of the arbitrator to converse with the " +"client, retrieve authentication information, verify the applicant's " +"credentials and grant or deny requests." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:140 +#, no-wrap +msgid "service" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:143 +msgid "" +"A class of servers providing similar or related functionality and requiring " +"similar authentication. PAM policies are defined on a per-service basis, so " +"all servers that claim the same service name will be subject to the same " +"policy." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:144 +#, no-wrap +msgid "session" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:147 +msgid "" +"The context within which service is rendered to the applicant by the " +"server. One of PAM's four facilities, session management, is concerned " +"exclusively with setting up and tearing down this context." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:148 +#, no-wrap +msgid "token" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:150 +msgid "" +"A chunk of information associated with the account, such as a password or " +"passphrase, which the applicant must provide to prove his identity." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:151 +#, no-wrap +msgid "transaction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:153 +msgid "" +"A sequence of requests from the same applicant to the same instance of the " +"same server, beginning with authentication and session set-up and ending " +"with session tear-down." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:155 +#, no-wrap +msgid "Usage Examples" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:158 +msgid "" +"This section aims to illustrate the meanings of some of the terms defined " +"above by way of a handful of simple examples." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/pam/_index.adoc:159 +#, no-wrap +msgid "Client and Server Are One" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:162 +msgid "This simple example shows `alice` man:su[1]'ing to `root`." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:167 +#, no-wrap +msgid "" +"% whoami\n" +"alice\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:170 +#, no-wrap +msgid "" +"% ls -l `which su`\n" +"-r-sr-xr-x 1 root wheel 10744 Dec 6 19:06 /usr/bin/su\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:175 +#, no-wrap +msgid "" +"% su -\n" +"Password: xi3kiune\n" +"# whoami\n" +"root\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:178 +msgid "The applicant is `alice`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:179 +msgid "The account is `root`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:180 +msgid "The man:su[1] process is both client and server." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:181 +msgid "The authentication token is `xi3kiune`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:182 +msgid "The arbitrator is `root`, which is why man:su[1] is setuid `root`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/pam/_index.adoc:183 +#, no-wrap +msgid "Client and Server Are Separate" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:187 +msgid "" +"The example below shows `eve` try to initiate an man:ssh[1] connection to " +"`login.example.com`, ask to log in as `bob`, and succeed. Bob should have " +"chosen a better password!" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:192 +#, no-wrap +msgid "" +"% whoami\n" +"eve\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:200 +#, no-wrap +msgid "" +"% ssh bob@login.example.com\n" +"bob@login.example.com's password:\n" +"% god\n" +"Last login: Thu Oct 11 09:52:57 2001 from 192.168.0.1\n" +"Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994\n" +"\tThe Regents of the University of California. All rights reserved.\n" +"FreeBSD 4.4-STABLE (LOGIN) 4: Tue Nov 27 18:10:34 PST 2001\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:203 +#, no-wrap +msgid "" +"Welcome to FreeBSD!\n" +"%\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:207 +msgid "The applicant is `eve`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:208 +msgid "The client is Eve's man:ssh[1] process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:209 +msgid "The server is the man:sshd[8] process on `login.example.com`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:210 +msgid "The account is `bob`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:211 +msgid "The authentication token is `god`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:212 +msgid "Although this is not shown in this example, the arbitrator is `root`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/pam/_index.adoc:213 +#, no-wrap +msgid "Sample Policy" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:216 +msgid "The following is FreeBSD's default policy for `sshd`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:225 +#, no-wrap +msgid "" +"sshd\tauth\t\trequired\tpam_nologin.so\tno_warn\n" +"sshd\tauth\t\trequired\tpam_unix.so\tno_warn try_first_pass\n" +"sshd\taccount\t\trequired\tpam_login_access.so\n" +"sshd\taccount\t\trequired\tpam_unix.so\n" +"sshd\tsession\t\trequired\tpam_lastlog.so\tno_fail\n" +"sshd\tpassword\trequired\tpam_permit.so\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:228 +msgid "" +"This policy applies to the `sshd` service (which is not necessarily " +"restricted to the man:sshd[8] server.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:229 +msgid "`auth`, `account`, `session` and `password` are facilities." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:230 +msgid "" +"[.filename]#pam_nologin.so#, [.filename]#pam_unix.so#, [." +"filename]#pam_login_access.so#, [.filename]#pam_lastlog.so# and [." +"filename]#pam_permit.so# are modules. It is clear from this example that [." +"filename]#pam_unix.so# provides at least two facilities (authentication and " +"account management.)" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pam/_index.adoc:232 +#, no-wrap +msgid "PAM Essentials" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:235 +#, no-wrap +msgid "Facilities and Primitives" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:238 +msgid "" +"The PAM API offers six different authentication primitives grouped in four " +"facilities, which are described below." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:239 +#, no-wrap +msgid "`auth`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:242 +msgid "" +"_Authentication._ This facility concerns itself with authenticating the " +"applicant and establishing the account credentials. It provides two " +"primitives:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:244 +msgid "" +"man:pam_authenticate[3] authenticates the applicant, usually by requesting " +"an authentication token and comparing it with a value stored in a database " +"or obtained from an authentication server." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:245 +msgid "" +"man:pam_setcred[3] establishes account credentials such as user ID, group " +"membership and resource limits." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:246 +#, no-wrap +msgid "`account`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:249 +msgid "" +"_Account management._ This facility handles non-authentication-related " +"issues of account availability, such as access restrictions based on the " +"time of day or the server's work load. It provides a single primitive:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:251 +msgid "man:pam_acct_mgmt[3] verifies that the requested account is available." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:252 +#, no-wrap +msgid "`session`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:255 +msgid "" +"_Session management._ This facility handles tasks associated with session " +"set-up and tear-down, such as login accounting. It provides two primitives:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:257 +msgid "" +"man:pam_open_session[3] performs tasks associated with session set-up: add " +"an entry in the [.filename]#utmp# and [.filename]#wtmp# databases, start an " +"SSH agent, etc." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:258 +msgid "" +"man:pam_close_session[3] performs tasks associated with session tear-down: " +"add an entry in the [.filename]#utmp# and [.filename]#wtmp# databases, stop " +"the SSH agent, etc." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:259 +#, no-wrap +msgid "`password`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:262 +msgid "" +"_Password management._ This facility is used to change the authentication " +"token associated with an account, either because it has expired or because " +"the user wishes to change it. It provides a single primitive:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:264 +msgid "" +"man:pam_chauthtok[3] changes the authentication token, optionally verifying " +"that it is sufficiently hard to guess, has not been used previously, etc." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:266 +#, no-wrap +msgid "Modules" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:271 +msgid "" +"Modules are a very central concept in PAM; after all, they are the \"M\" in " +"\"PAM\". A PAM module is a self-contained piece of program code that " +"implements the primitives in one or more facilities for one particular " +"mechanism; possible mechanisms for the authentication facility, for " +"instance, include the UNIX(R) password database, NIS, LDAP and Radius." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/pam/_index.adoc:273 +#, no-wrap +msgid "Module Naming" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:278 +msgid "" +"FreeBSD implements each mechanism in a single module, named `pam_mechanism." +"so` (for instance, `pam_unix.so` for the UNIX(R) mechanism.) Other " +"implementations sometimes have separate modules for separate facilities, and " +"include the facility name as well as the mechanism name in the module name. " +"To name one example, Solaris(TM) has a `pam_dial_auth.so.1` module which is " +"commonly used to authenticate dialup users." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/pam/_index.adoc:280 +#, no-wrap +msgid "Module Versioning" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:284 +msgid "" +"FreeBSD's original PAM implementation, based on Linux-PAM, did not use " +"version numbers for PAM modules. This would commonly cause problems with " +"legacy applications, which might be linked against older versions of the " +"system libraries, as there was no way to load a matching version of the " +"required modules." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:287 +msgid "" +"OpenPAM, on the other hand, looks for modules that have the same version " +"number as the PAM library (currently 2), and only falls back to an " +"unversioned module if no versioned module could be loaded. Thus legacy " +"modules can be provided for legacy applications, while allowing new (or " +"newly built) applications to take advantage of the most recent modules." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:289 +msgid "" +"Although Solaris(TM) PAM modules commonly have a version number, they are " +"not truly versioned, because the number is a part of the module name and " +"must be included in the configuration." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:291 +#, no-wrap +msgid "Chains and Policies" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:296 +msgid "" +"When a server initiates a PAM transaction, the PAM library tries to load a " +"policy for the service specified in the man:pam_start[3] call. The policy " +"specifies how authentication requests should be processed, and is defined in " +"a configuration file. This is the other central concept in PAM: the " +"possibility for the admin to tune the system security policy (in the wider " +"sense of the word) simply by editing a text file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:299 +msgid "" +"A policy consists of four chains, one for each of the four PAM facilities. " +"Each chain is a sequence of configuration statements, each specifying a " +"module to invoke, some (optional) parameters to pass to the module, and a " +"control flag that describes how to interpret the return code from the module." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:302 +msgid "" +"Understanding the control flags is essential to understanding PAM " +"configuration files. There are four different control flags:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:303 +#, no-wrap +msgid "`binding`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:306 +msgid "" +"If the module succeeds and no earlier module in the chain has failed, the " +"chain is immediately terminated and the request is granted. If the module " +"fails, the rest of the chain is executed, but the request is ultimately " +"denied." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:308 +msgid "" +"This control flag was introduced by Sun in Solaris(TM) 9 (SunOS(TM) 5.9), " +"and is also supported by OpenPAM." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:308 +#, no-wrap +msgid "`required`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:311 +msgid "" +"If the module succeeds, the rest of the chain is executed, and the request " +"is granted unless some other module fails. If the module fails, the rest of " +"the chain is also executed, but the request is ultimately denied." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:312 +#, no-wrap +msgid "`requisite`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:315 +msgid "" +"If the module succeeds, the rest of the chain is executed, and the request " +"is granted unless some other module fails. If the module fails, the chain " +"is immediately terminated and the request is denied." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:316 +#, no-wrap +msgid "`sufficient`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:319 +msgid "" +"If the module succeeds and no earlier module in the chain has failed, the " +"chain is immediately terminated and the request is granted. If the module " +"fails, the module is ignored and the rest of the chain is executed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:321 +msgid "" +"As the semantics of this flag may be somewhat confusing, especially when it " +"is used for the last module in a chain, it is recommended that the `binding` " +"control flag be used instead if the implementation supports it." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pam/_index.adoc:321 +#, no-wrap +msgid "`optional`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:324 +msgid "" +"The module is executed, but its result is ignored. If all modules in a " +"chain are marked `optional`, all requests will always be granted." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:327 +msgid "" +"When a server invokes one of the six PAM primitives, PAM retrieves the chain " +"for the facility the primitive belongs to, and invokes each of the modules " +"listed in the chain, in the order they are listed, until it reaches the end, " +"or determines that no further processing is necessary (either because a " +"`binding` or `sufficient` module succeeded, or because a `requisite` module " +"failed.) The request is granted if and only if at least one module was " +"invoked, and all non-optional modules succeeded." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:331 +msgid "" +"Note that it is possible, though not very common, to have the same module " +"listed several times in the same chain. For instance, a module that looks " +"up user names and passwords in a directory server could be invoked multiple " +"times with different parameters specifying different directory servers to " +"contact. PAM treat different occurrences of the same module in the same " +"chain as different, unrelated modules." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:333 +#, no-wrap +msgid "Transactions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:337 +msgid "" +"The lifecycle of a typical PAM transaction is described below. Note that if " +"any of these steps fails, the server should report a suitable error message " +"to the client and abort the transaction." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:339 +msgid "" +"If necessary, the server obtains arbitrator credentials through a mechanism " +"independent of PAM-most commonly by virtue of having been started by `root`, " +"or of being setuid `root`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:340 +msgid "" +"The server calls man:pam_start[3] to initialize the PAM library and specify " +"its service name and the target account, and register a suitable " +"conversation function." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:341 +msgid "" +"The server obtains various information relating to the transaction (such as " +"the applicant's user name and the name of the host the client runs on) and " +"submits it to PAM using man:pam_set_item[3]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:342 +msgid "The server calls man:pam_authenticate[3] to authenticate the applicant." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:343 +msgid "" +"The server calls man:pam_acct_mgmt[3] to verify that the requested account " +"is available and valid. If the password is correct but has expired, man:" +"pam_acct_mgmt[3] will return `PAM_NEW_AUTHTOK_REQD` instead of `PAM_SUCCESS`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:344 +msgid "" +"If the previous step returned `PAM_NEW_AUTHTOK_REQD`, the server now calls " +"man:pam_chauthtok[3] to force the client to change the authentication token " +"for the requested account." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:345 +msgid "" +"Now that the applicant has been properly authenticated, the server calls man:" +"pam_setcred[3] to establish the credentials of the requested account. It is " +"able to do this because it acts on behalf of the arbitrator, and holds the " +"arbitrator's credentials." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:346 +msgid "" +"Once the correct credentials have been established, the server calls man:" +"pam_open_session[3] to set up the session." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:347 +msgid "" +"The server now performs whatever service the client requested-for instance, " +"provide the applicant with a shell." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:348 +msgid "" +"Once the server is done serving the client, it calls man:" +"pam_close_session[3] to tear down the session." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:349 +msgid "" +"Finally, the server calls man:pam_end[3] to notify the PAM library that it " +"is done and that it can release whatever resources it has allocated in the " +"course of the transaction." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pam/_index.adoc:351 +#, no-wrap +msgid "PAM Configuration" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:354 +#, no-wrap +msgid "PAM Policy Files" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/pam/_index.adoc:357 +#, no-wrap +msgid "The [.filename]#/etc/pam.conf#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:362 +msgid "" +"The traditional PAM policy file is [.filename]#/etc/pam.conf#. This file " +"contains all the PAM policies for your system. Each line of the file " +"describes one step in a chain, as shown below:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:366 +#, no-wrap +msgid "login auth required pam_nologin.so no_warn\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:370 +msgid "" +"The fields are, in order: service name, facility name, control flag, module " +"name, and module arguments. Any additional fields are interpreted as " +"additional module arguments." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:374 +msgid "" +"A separate chain is constructed for each service / facility pair, so while " +"the order in which lines for the same service and facility appear is " +"significant, the order in which the individual services and facilities are " +"listed is not. The examples in the original PAM paper grouped configuration " +"lines by facility, and the Solaris(TM) stock [.filename]#pam.conf# still " +"does that, but FreeBSD's stock configuration groups configuration lines by " +"service. Either way is fine; either way makes equal sense." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/pam/_index.adoc:376 +#, no-wrap +msgid "The [.filename]#/etc/pam.d#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:381 +msgid "" +"OpenPAM and Linux-PAM support an alternate configuration mechanism, which is " +"the preferred mechanism in FreeBSD. In this scheme, each policy is " +"contained in a separate file bearing the name of the service it applies to. " +"These files are stored in [.filename]#/etc/pam.d/#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:384 +msgid "" +"These per-service policy files have only four fields instead of [." +"filename]#pam.conf#'s five: the service name field is omitted. Thus, " +"instead of the sample [.filename]#pam.conf# line from the previous section, " +"one would have the following line in [.filename]#/etc/pam.d/login#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:388 +#, no-wrap +msgid "auth required pam_nologin.so no_warn\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:392 +msgid "" +"As a consequence of this simplified syntax, it is possible to use the same " +"policy for multiple services by linking each service name to a same policy " +"file. For instance, to use the same policy for the `su` and `sudo` " +"services, one could do as follows:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:397 +#, no-wrap +msgid "" +"# cd /etc/pam.d\n" +"# ln -s su sudo\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:400 +msgid "" +"This works because the service name is determined from the file name rather " +"than specified in the policy file, so the same file can be used for multiple " +"differently-named services." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:402 +msgid "" +"Since each service's policy is stored in a separate file, the [." +"filename]#pam.d# mechanism also makes it very easy to install additional " +"policies for third-party software packages." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/pam/_index.adoc:404 +#, no-wrap +msgid "The Policy Search Order" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:408 +msgid "" +"As we have seen above, PAM policies can be found in a number of places. " +"What happens if policies for the same service exist in multiple places?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:410 +msgid "" +"It is essential to understand that PAM's configuration system is centered on " +"chains." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:412 +#, no-wrap +msgid "Breakdown of a Configuration Line" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:415 +msgid "" +"As explained in crossref:pam[pam-config-file, PAM Policy Files], each line " +"in [.filename]#/etc/pam.conf# consists of four or more fields: the service " +"name, the facility name, the control flag, the module name, and zero or more " +"module arguments." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:418 +msgid "" +"The service name is generally (though not always) the name of the " +"application the statement applies to. If you are unsure, refer to the " +"individual application's documentation to determine what service name it " +"uses." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:420 +msgid "" +"Note that if you use [.filename]#/etc/pam.d/# instead of [.filename]#/etc/" +"pam.conf#, the service name is specified by the name of the policy file, and " +"omitted from the actual configuration lines, which then start with the " +"facility name." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:423 +msgid "" +"The facility is one of the four facility keywords described in crossref:" +"pam[pam-facilities-primitives, Facilities and Primitives]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:428 +#, no-wrap +msgid "" +"Likewise, the control flag is one of the four keywords described in\n" +"\tcrossref:pam[pam-chains-policies, Chains and Policies], describing how to interpret the return code from the module. \n" +"Linux-PAM supports an alternate syntax that lets you specify the action to associate with each possible return code, but this should be avoided as it is non-standard and closely tied in with the way Linux-PAM dispatches service calls (which differs greatly from the way Solaris(TM) and OpenPAM do it.) \n" +"Unsurprisingly, OpenPAM does not support this syntax.\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:430 +#, no-wrap +msgid "Policies" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:433 +msgid "" +"To configure PAM correctly, it is essential to understand how policies are " +"interpreted." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:436 +msgid "" +"When an application calls man:pam_start[3], the PAM library loads the policy " +"for the specified service and constructs four module chains (one for each " +"facility.) If one or more of these chains are empty, the corresponding " +"chains from the policy for the `other` service are substituted." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:440 +msgid "" +"When the application later calls one of the six PAM primitives, the PAM " +"library retrieves the chain for the corresponding facility and calls the " +"appropriate service function in each module listed in the chain, in the " +"order in which they were listed in the configuration. After each call to a " +"service function, the module type and the error code returned by the service " +"function are used to determine what happens next. With a few exceptions, " +"which we discuss below, the following table applies:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/pam/_index.adoc:441 +#, no-wrap +msgid "PAM Chain Execution Summary" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pam/_index.adoc:446 +#, no-wrap +msgid "PAM_SUCCESS" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pam/_index.adoc:447 +#, no-wrap +msgid "PAM_IGNORE" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pam/_index.adoc:449 +#, no-wrap +msgid "other" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pam/_index.adoc:450 +#, no-wrap +msgid "binding" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pam/_index.adoc:451 +#: documentation/content/en/articles/pam/_index.adoc:466 +#, no-wrap +msgid "if (!fail) break;" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pam/_index.adoc:452 +#: documentation/content/en/articles/pam/_index.adoc:456 +#: documentation/content/en/articles/pam/_index.adoc:457 +#: documentation/content/en/articles/pam/_index.adoc:461 +#: documentation/content/en/articles/pam/_index.adoc:462 +#: documentation/content/en/articles/pam/_index.adoc:467 +#: documentation/content/en/articles/pam/_index.adoc:469 +#: documentation/content/en/articles/pam/_index.adoc:471 +#: documentation/content/en/articles/pam/_index.adoc:472 +#: documentation/content/en/articles/pam/_index.adoc:473 +#, no-wrap +msgid "-" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pam/_index.adoc:454 +#: documentation/content/en/articles/pam/_index.adoc:459 +#, no-wrap +msgid "fail = true;" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pam/_index.adoc:455 +#, no-wrap +msgid "required" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pam/_index.adoc:460 +#, no-wrap +msgid "requisite" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pam/_index.adoc:464 +#, no-wrap +msgid "fail = true; break;" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pam/_index.adoc:465 +#, no-wrap +msgid "sufficient" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pam/_index.adoc:470 +#, no-wrap +msgid "optional" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:477 +msgid "" +"If `fail` is true at the end of a chain, or when a \"break\" is reached, the " +"dispatcher returns the error code returned by the first module that failed. " +"Otherwise, it returns `PAM_SUCCESS`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:479 +msgid "" +"The first exception of note is that the error code `PAM_NEW_AUTHTOK_REQD` is " +"treated like a success, except that if no module failed, and at least one " +"module returned `PAM_NEW_AUTHTOK_REQD`, the dispatcher will return " +"`PAM_NEW_AUTHTOK_REQD`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:481 +msgid "" +"The second exception is that man:pam_setcred[3] treats `binding` and " +"`sufficient` modules as if they were `required`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:483 +msgid "" +"The third and final exception is that man:pam_chauthtok[3] runs the entire " +"chain twice (once for preliminary checks and once to actually set the " +"password), and in the preliminary phase it treats `binding` and `sufficient` " +"modules as if they were `required`." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pam/_index.adoc:485 +#, no-wrap +msgid "FreeBSD PAM Modules" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:488 +#, no-wrap +msgid "man:pam_deny[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:492 +msgid "" +"The man:pam_deny[8] module is one of the simplest modules available; it " +"responds to any request with `PAM_AUTH_ERR`. It is useful for quickly " +"disabling a service (add it to the top of every chain), or for terminating " +"chains of `sufficient` modules." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:494 +#, no-wrap +msgid "man:pam_echo[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:498 +msgid "" +"The man:pam_echo[8] module simply passes its arguments to the conversation " +"function as a `PAM_TEXT_INFO` message. It is mostly useful for debugging, " +"but can also serve to display messages such as \"Unauthorized access will be " +"prosecuted\" before starting the authentication procedure." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:500 +#, no-wrap +msgid "man:pam_exec[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:504 +msgid "" +"The man:pam_exec[8] module takes its first argument to be the name of a " +"program to execute, and the remaining arguments are passed to that program " +"as command-line arguments. One possible application is to use it to run a " +"program at login time which mounts the user's home directory." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:506 +#, no-wrap +msgid "man:pam_ftpusers[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:509 +msgid "The man:pam_ftpusers[8] module" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:511 +#, no-wrap +msgid "man:pam_group[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:515 +msgid "" +"The man:pam_group[8] module accepts or rejects applicants on the basis of " +"their membership in a particular file group (normally `wheel` for man:" +"su[1]). It is primarily intended for maintaining the traditional behavior " +"of BSD man:su[1], but has many other uses, such as excluding certain groups " +"of users from a particular service." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:517 +#, no-wrap +msgid "man:pam_guest[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:522 +msgid "" +"The man:pam_guest[8] module allows guest logins using fixed login names. " +"Various requirements can be placed on the password, but the default behavior " +"is to allow any password as long as the login name is that of a guest " +"account. The man:pam_guest[8] module can easily be used to implement " +"anonymous FTP logins." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:524 +#, no-wrap +msgid "man:pam_krb5[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:527 +msgid "The man:pam_krb5[8] module" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:529 +#, no-wrap +msgid "man:pam_ksu[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:532 +msgid "The man:pam_ksu[8] module" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:534 +#, no-wrap +msgid "man:pam_lastlog[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:537 +msgid "The man:pam_lastlog[8] module" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:539 +#, no-wrap +msgid "man:pam_login_access[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:542 +msgid "" +"The man:pam_login_access[8] module provides an implementation of the account " +"management primitive which enforces the login restrictions specified in the " +"man:login.access[5] table." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:544 +#, no-wrap +msgid "man:pam_nologin[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:548 +msgid "" +"The man:pam_nologin[8] module refuses non-root logins when [.filename]#/var/" +"run/nologin# exists. This file is normally created by man:shutdown[8] when " +"less than five minutes remain until the scheduled shutdown time." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:550 +#, no-wrap +msgid "man:pam_passwdqc[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:553 +msgid "The man:pam_passwdqc[8] module" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:555 +#, no-wrap +msgid "man:pam_permit[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:559 +msgid "" +"The man:pam_permit[8] module is one of the simplest modules available; it " +"responds to any request with `PAM_SUCCESS`. It is useful as a placeholder " +"for services where one or more chains would otherwise be empty." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:561 +#, no-wrap +msgid "man:pam_radius[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:564 +msgid "The man:pam_radius[8] module" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:566 +#, no-wrap +msgid "man:pam_rhosts[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:569 +msgid "The man:pam_rhosts[8] module" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:571 +#, no-wrap +msgid "man:pam_rootok[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:575 +msgid "" +"The man:pam_rootok[8] module reports success if and only if the real user id " +"of the process calling it (which is assumed to be run by the applicant) is " +"0. This is useful for non-networked services such as man:su[1] or man:" +"passwd[1], to which the `root` should have automatic access." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:577 +#, no-wrap +msgid "man:pam_securetty[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:580 +msgid "The man:pam_securetty[8] module" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:582 +#, no-wrap +msgid "man:pam_self[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:586 +msgid "" +"The man:pam_self[8] module reports success if and only if the names of the " +"applicant matches that of the target account. It is most useful for non-" +"networked services such as man:su[1], where the identity of the applicant " +"can be easily verified." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:588 +#, no-wrap +msgid "man:pam_ssh[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:594 +msgid "" +"The man:pam_ssh[8] module provides both authentication and session " +"services. The authentication service allows users who have passphrase-" +"protected SSH secret keys in their [.filename]#~/.ssh# directory to " +"authenticate themselves by typing their passphrase. The session service " +"starts man:ssh-agent[1] and preloads it with the keys that were decrypted in " +"the authentication phase. This feature is particularly useful for local " +"logins, whether in X (using man:xdm[8] or another PAM-aware X login manager) " +"or at the console." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:596 +#, no-wrap +msgid "man:pam_tacplus[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:599 +msgid "The man:pam_tacplus[8] module" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:601 +#, no-wrap +msgid "man:pam_unix[8]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:606 +msgid "" +"The man:pam_unix[8] module implements traditional UNIX(R) password " +"authentication, using man:getpwnam[3] to obtain the target account's " +"password and compare it with the one provided by the applicant. It also " +"provides account management services (enforcing account and password " +"expiration times) and password-changing services. This is probably the " +"single most useful module, as the great majority of admins will want to " +"maintain historical behavior for at least some services." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pam/_index.adoc:608 +#, no-wrap +msgid "PAM Application Programming" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:611 +#: documentation/content/en/articles/pam/_index.adoc:616 +msgid "This section has not yet been written." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pam/_index.adoc:613 +#, no-wrap +msgid "PAM Module Programming" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pam/_index.adoc:621 +#, no-wrap +msgid "Sample PAM Application" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:628 +msgid "" +"The following is a minimal implementation of man:su[1] using PAM. Note that " +"it uses the OpenPAM-specific man:openpam_ttyconv[3] conversation function, " +"which is prototyped in [.filename]#security/openpam.h#. If you wish build " +"this application on a system with a different PAM library, you will have to " +"provide your own conversation function. A robust conversation function is " +"surprisingly difficult to implement; the one presented in crossref:pam[pam-" +"sample-conv, Sample PAM Conversation Function] is a good starting point, but " +"should not be used in real-world applications." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:632 +#, no-wrap +msgid "include::{include-path}su.c[]\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pam/_index.adoc:638 +#, no-wrap +msgid "Sample PAM Module" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:642 +msgid "" +"The following is a minimal implementation of man:pam_unix[8], offering only " +"authentication services. It should build and run with most PAM " +"implementations, but takes advantage of OpenPAM extensions if available: " +"note the use of man:pam_get_authtok[3], which enormously simplifies " +"prompting the user for a password." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:646 +#, no-wrap +msgid "include::{include-path}pam_unix.c[]\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pam/_index.adoc:652 +#, no-wrap +msgid "Sample PAM Conversation Function" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:657 +msgid "" +"The conversation function presented below is a greatly simplified version of " +"OpenPAM's man:openpam_ttyconv[3]. It is fully functional, and should give " +"the reader a good idea of how a conversation function should behave, but it " +"is far too simple for real-world use. Even if you are not using OpenPAM, " +"feel free to download the source code and adapt man:openpam_ttyconv[3] to " +"your uses; we believe it to be as robust as a tty-oriented conversation " +"function can reasonably get." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/pam/_index.adoc:661 +#, no-wrap +msgid "include::{include-path}converse.c[]\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pam/_index.adoc:666 +#, no-wrap +msgid "Further Reading" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:668 +#, no-wrap +msgid "Papers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:671 +msgid "" +"Making Login Services Independent of Authentication Technologies Vipin " +"Samar. Charlie Lai. Sun Microsystems." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:673 +msgid "" +"_link:https://pubs.opengroup.org/onlinepubs/8329799/toc.htm[X/Open Single " +"Sign-on Preliminary Specification]_. The Open Group. 1-85912-144-6. June " +"1997." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:675 +msgid "" +"_link:https://mirrors.kernel.org/pub/linux/libs/pam/pre/doc/draft-morgan-" +"pam-07.txt[Pluggable Authentication Modules]_. Andrew G. Morgan. 1999-10-06." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:676 +#, no-wrap +msgid "User Manuals" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:679 +msgid "" +"_link:https://docs.oracle.com/cd/E26505_01/html/E27224/pam-1.html[PAM " +"Administration]_. Sun Microsystems." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pam/_index.adoc:680 +#, no-wrap +msgid "Related Web Pages" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:683 +msgid "" +"_link:https://www.openpam.org/[OpenPAM homepage]_ Dag-Erling Smørgrav. " +"ThinkSec AS." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:685 +msgid "" +"_link:http://www.kernel.org/pub/linux/libs/pam/[Linux-PAM homepage]_ Andrew " +"Morgan." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pam/_index.adoc:686 +msgid "_Solaris PAM homepage_. Sun Microsystems." +msgstr "" diff --git a/documentation/content/en/articles/pgpkeys/_index.adoc b/documentation/content/en/articles/pgpkeys/_index.adoc index 3d651721da..8fd6cd8eff 100644 --- a/documentation/content/en/articles/pgpkeys/_index.adoc +++ b/documentation/content/en/articles/pgpkeys/_index.adoc @@ -63,51 +63,48 @@ shown in the Handbook PGP keys chapter. === {security-officer-name} `<{security-officer-email}>` include::{include-path}security-officer.key[] -=== {secteam-secretary-name} `<{secteam-secretary-email}>` -include::{include-path}secteam-secretary.key[] - === {core-secretary-name} `<{core-secretary-email}>` include::{include-path}core-secretary.key[] === {portmgr-secretary-name} `<{portmgr-secretary-email}>` include::{include-path}portmgr-secretary.key[] -=== `{doceng-secretary-email}` +=== {doceng-secretary-name} `<{doceng-secretary-email}>` include::{include-path}doceng-secretary.key[] [[pgpkeys-core]] == Core Team Members -=== `{bapt}` -include::{include-path}bapt.key[] +=== `{allanjude}` +include::{include-path}allanjude.key[] -=== `{emaste}` -include::{include-path}emaste.key[] +=== `{dch}` +include::{include-path}dch.key[] -=== `{gnn}` -include::{include-path}gnn.key[] +=== `{glebius}` +include::{include-path}glebius.key[] === `{hrs}` include::{include-path}hrs.key[] -=== `{imp}` -include::{include-path}imp.key[] - -=== `{kevans}` -include::{include-path}kevans.key[] +=== `{lwhsu}` +include::{include-path}lwhsu.key[] -=== `{markj}` -include::{include-path}markj.key[] +=== `{mat}` +include::{include-path}mat.key[] -=== `{scottl}` -include::{include-path}scottl.key[] +=== `{olivier}` +include::{include-path}olivier.key[] -=== `{seanc}` -include::{include-path}seanc.key[] +=== `{tcberner}` +include::{include-path}tcberner.key[] [[pgpkeys-developers]] == Developers +=== `{jgh}` +include::{include-path}jgh.key[] + === `{ariff}` include::{include-path}ariff.key[] @@ -117,8 +114,8 @@ include::{include-path}tabthorpe.key[] === `{eadler}` include::{include-path}eadler.key[] -=== `{mahrens}` -include::{include-path}mahrens.key[] +=== `{pauamma}` +include::{include-path}pauamma.key[] === `{shaun}` include::{include-path}shaun.key[] @@ -156,9 +153,6 @@ include::{include-path}syuu.key[] === `{asami}` include::{include-path}asami.key[] -=== `{gavin}` -include::{include-path}gavin.key[] - === `{jsa}` include::{include-path}jsa.key[] @@ -168,9 +162,6 @@ include::{include-path}jadawin.key[] === `{jwb}` include::{include-path}jwb.key[] -=== `{badger}` -include::{include-path}badger.key[] - === `{dbaio}` include::{include-path}dbaio.key[] @@ -192,9 +183,6 @@ include::{include-path}barner.key[] === `{lbartoletti}` include::{include-path}lbartoletti.key[] -=== `{jbeich}` -include::{include-path}jbeich.key[] - === `{art}` include::{include-path}art.key[] @@ -213,20 +201,14 @@ include::{include-path}tcberner.key[] === `{tdb}` include::{include-path}tdb.key[] -=== `{gblach}` -include::{include-path}gblach.key[] - === `{mbr}` include::{include-path}mbr.key[] -=== `{wblock}` -include::{include-path}wblock.key[] - === `{bvs}` include::{include-path}bvs.key[] -=== `{zbb}` -include::{include-path}zbb.key[] +=== `{jbo}` +include::{include-path}jbo.key[] === `{novel}` include::{include-path}novel.key[] @@ -240,15 +222,9 @@ include::{include-path}kbowling.key[] === `{alexbl}` include::{include-path}alexbl.key[] -=== `{sbz}` -include::{include-path}sbz.key[] - === `{ebrandi}` include::{include-path}ebrandi.key[] -=== `{dab}` -include::{include-path}dab.key[] - === `{harti}` include::{include-path}harti.key[] @@ -261,6 +237,9 @@ include::{include-path}makc.key[] === `{jmb}` include::{include-path}jmb.key[] +=== `{dab}` +include::{include-path}dab.key[] + === `{antoine}` include::{include-path}antoine.key[] @@ -273,21 +252,9 @@ include::{include-path}brueffer.key[] === `{markus}` include::{include-path}markus.key[] -=== `{sbruno}` -include::{include-path}sbruno.key[] - === `{br}` include::{include-path}br.key[] -=== `{oleg}` -include::{include-path}oleg.key[] - -=== `{bushman}` -include::{include-path}bushman.key[] - -=== `{adrian}` -include::{include-path}adrian.key[] - === `{jch}` include::{include-path}jch.key[] @@ -300,6 +267,9 @@ include::{include-path}jcamou.key[] === `{acm}` include::{include-path}acm.key[] +=== `{olce}` +include::{include-path}olce.key[] + === `{gahr}` include::{include-path}gahr.key[] @@ -327,9 +297,6 @@ include::{include-path}ache.key[] === `{melifaro}` include::{include-path}melifaro.key[] -=== `{seanc}` -include::{include-path}seanc.key[] - === `{cjh}` include::{include-path}cjh.key[] @@ -345,6 +312,9 @@ include::{include-path}cjc.key[] === `{marcus}` include::{include-path}marcus.key[] +=== `{fuz}` +include::{include-path}fuz.key[] + === `{nik}` include::{include-path}nik.key[] @@ -357,33 +327,27 @@ include::{include-path}lcook.key[] === `{ngie}` include::{include-path}ngie.key[] -=== `{tijl}` -include::{include-path}tijl.key[] - === `{rakuco}` include::{include-path}rakuco.key[] -=== `{dch}` -include::{include-path}dch.key[] - === `{alc}` include::{include-path}alc.key[] === `{olivier}` include::{include-path}olivier.key[] -=== `{jeb}` -include::{include-path}jeb.key[] +=== `{dch}` +include::{include-path}dch.key[] === `{bcran}` include::{include-path}bcran.key[] +=== `{cc}` +include::{include-path}cc.key[] + === `{culot}` include::{include-path}culot.key[] -=== `{aaron}` -include::{include-path}aaron.key[] - === `{alfredo}` include::{include-path}alfredo.key[] @@ -393,15 +357,9 @@ include::{include-path}bapt.key[] === `{ceri}` include::{include-path}ceri.key[] -=== `{brd}` -include::{include-path}brd.key[] - === `{edavis}` include::{include-path}edavis.key[] -=== `{pjd}` -include::{include-path}pjd.key[] - === `{alexey}` include::{include-path}alexey.key[] @@ -414,9 +372,6 @@ include::{include-path}carl.key[] === `{carlavilla}` include::{include-path}carlavilla.key[] -=== `{jmd}` -include::{include-path}jmd.key[] - === `{vd}` include::{include-path}vd.key[] @@ -435,6 +390,9 @@ include::{include-path}bdrewery.key[] === `{gad}` include::{include-path}gad.key[] +=== `{kd}` +include::{include-path}kd.key[] + === `{olivierd}` include::{include-path}olivierd.key[] @@ -444,6 +402,9 @@ include::{include-path}bruno.key[] === `{ale}` include::{include-path}ale.key[] +=== `{jlduran}` +include::{include-path}jlduran.key[] + === `{nemysis}` include::{include-path}nemysis.key[] @@ -453,36 +414,12 @@ include::{include-path}peadar.key[] === `{deischen}` include::{include-path}deischen.key[] -=== `{josef}` -include::{include-path}josef.key[] - === `{diizzy}` include::{include-path}diizzy.key[] -=== `{lme}` -include::{include-path}lme.key[] - === `{ue}` include::{include-path}ue.key[] -=== `{ru}` -include::{include-path}ru.key[] - -=== `{le}` -include::{include-path}le.key[] - -=== `{se}` -include::{include-path}se.key[] - -=== `{kevans}` -include::{include-path}kevans.key[] - -=== `{bf}` -include::{include-path}bf.key[] - -=== `{sef}` -include::{include-path}sef.key[] - === `{madpilot}` include::{include-path}madpilot.key[] @@ -492,9 +429,6 @@ include::{include-path}rafan.key[] === `{kami}` include::{include-path}kami.key[] -=== `{stefanf}` -include::{include-path}stefanf.key[] - === `{farrokhi}` include::{include-path}farrokhi.key[] @@ -510,12 +444,6 @@ include::{include-path}feld.key[] === `{green}` include::{include-path}green.key[] -=== `{lioux}` -include::{include-path}lioux.key[] - -=== `{mdf}` -include::{include-path}mdf.key[] - === `{fanf}` include::{include-path}fanf.key[] @@ -534,24 +462,24 @@ include::{include-path}landonf.key[] === `{billf}` include::{include-path}billf.key[] -=== `{sg}` -include::{include-path}sg.key[] +=== `{grembo}` +include::{include-path}grembo.key[] === `{sgalabov}` include::{include-path}sgalabov.key[] -=== `{ultima}` -include::{include-path}ultima.key[] +=== `{kgalazka}` +include::{include-path}kgalazka.key[] === `{avg}` include::{include-path}avg.key[] +=== `{tiga}` +include::{include-path}tiga.key[] + === `{beat}` include::{include-path}beat.key[] -=== `{danger}` -include::{include-path}danger.key[] - === `{sjg}` include::{include-path}sjg.key[] @@ -573,18 +501,12 @@ include::{include-path}pgollucci.key[] === `{trociny}` include::{include-path}trociny.key[] -=== `{danilo}` -include::{include-path}danilo.key[] - === `{dmgk}` include::{include-path}dmgk.key[] === `{daichi}` include::{include-path}daichi.key[] -=== `{mnag}` -include::{include-path}mnag.key[] - === `{grehan}` include::{include-path}grehan.key[] @@ -594,18 +516,12 @@ include::{include-path}jamie.key[] === `{adridg}` include::{include-path}adridg.key[] -=== `{edwin}` -include::{include-path}edwin.key[] - === `{wg}` include::{include-path}wg.key[] === `{bar}` include::{include-path}bar.key[] -=== `{anish}` -include::{include-path}anish.key[] - === `{jmg}` include::{include-path}jmg.key[] @@ -648,12 +564,6 @@ include::{include-path}mheinen.key[] === `{niels}` include::{include-path}niels.key[] -=== `{jh}` -include::{include-path}jh.key[] - -=== `{jgh}` -include::{include-path}jgh.key[] - === `{ghelmer}` include::{include-path}ghelmer.key[] @@ -684,9 +594,6 @@ include::{include-path}mhorne.key[] === `{bhughes}` include::{include-path}bhughes.key[] -=== `{mich}` -include::{include-path}mich.key[] - === `{sunpoet}` include::{include-path}sunpoet.key[] @@ -702,11 +609,8 @@ include::{include-path}whu.key[] === `{chinsan}` include::{include-path}chinsan.key[] -=== `{shurd}` -include::{include-path}shurd.key[] - -=== `{kibab}` -include::{include-path}kibab.key[] +=== `{zlei}` +include::{include-path}zlei.key[] === `{davide}` include::{include-path}davide.key[] @@ -714,9 +618,6 @@ include::{include-path}davide.key[] === `{jkh}` include::{include-path}jkh.key[] -=== `{sevan}` -include::{include-path}sevan.key[] - === `{versus}` include::{include-path}versus.key[] @@ -741,24 +642,12 @@ include::{include-path}markj.key[] === `{trevor}` include::{include-path}trevor.key[] -=== `{thj}` -include::{include-path}thj.key[] - -=== `{mjoras}` -include::{include-path}mjoras.key[] - === `{erj}` include::{include-path}erj.key[] === `{allanjude}` include::{include-path}allanjude.key[] -=== `{tj}` -include::{include-path}tj.key[] - -=== `{kan}` -include::{include-path}kan.key[] - === `{bjk}` include::{include-path}bjk.key[] @@ -777,15 +666,9 @@ include::{include-path}karels.key[] === `{kato}` include::{include-path}kato.key[] -=== `{joe}` -include::{include-path}joe.key[] - === `{vkashyap}` include::{include-path}vkashyap.key[] -=== `{pkelsey}` -include::{include-path}pkelsey.key[] - === `{pkubaj}` include::{include-path}pkubaj.key[] @@ -810,6 +693,9 @@ include::{include-path}jkim.key[] === `{zack}` include::{include-path}zack.key[] +=== `{akiyano}` +include::{include-path}akiyano.key[] + === `{jceel}` include::{include-path}jceel.key[] @@ -819,15 +705,15 @@ include::{include-path}andreas.key[] === `{kai}` include::{include-path}kai.key[] +=== `{corvink}` +include::{include-path}corvink.key[] + === `{jkois}` include::{include-path}jkois.key[] === `{sergei}` include::{include-path}sergei.key[] -=== `{wulf}` -include::{include-path}wulf.key[] - === `{maxim}` include::{include-path}maxim.key[] @@ -846,30 +732,18 @@ include::{include-path}wkoszek.key[] === `{ak}` include::{include-path}ak.key[] -=== `{skra}` -include::{include-path}skra.key[] - -=== `{skreuzer}` -include::{include-path}skreuzer.key[] - === `{gabor}` include::{include-path}gabor.key[] === `{anchie}` include::{include-path}anchie.key[] -=== `{rik}` -include::{include-path}rik.key[] - === `{rushani}` include::{include-path}rushani.key[] === `{kuriyama}` include::{include-path}kuriyama.key[] -=== `{gleb}` -include::{include-path}gleb.key[] - === `{rene}` include::{include-path}rene.key[] @@ -882,21 +756,12 @@ include::{include-path}clement.key[] === `{mlaier}` include::{include-path}mlaier.key[] -=== `{dvl}` -include::{include-path}dvl.key[] - -=== `{erwin}` -include::{include-path}erwin.key[] - === `{martymac}` include::{include-path}martymac.key[] === `{glarkin}` include::{include-path}glarkin.key[] -=== `{laszlof}` -include::{include-path}laszlof.key[] - === `{dru}` include::{include-path}dru.key[] @@ -942,18 +807,12 @@ include::{include-path}achim.key[] === `{cel}` include::{include-path}cel.key[] -=== `{truckman}` -include::{include-path}truckman.key[] - === `{glewis}` include::{include-path}glewis.key[] === `{vishwin}` include::{include-path}vishwin.key[] -=== `{qingli}` -include::{include-path}qingli.key[] - === `{delphij}` include::{include-path}delphij.key[] @@ -966,18 +825,6 @@ include::{include-path}ijliao.key[] === `{rlibby}` include::{include-path}rlibby.key[] -=== `{lidl}` -include::{include-path}lidl.key[] - -=== `{lifanov}` -include::{include-path}lifanov.key[] - -=== `{lulf}` -include::{include-path}lulf.key[] - -=== `{clive}` -include::{include-path}clive.key[] - === `{pclin}` include::{include-path}pclin.key[] @@ -1005,27 +852,12 @@ include::{include-path}zml.key[] === `{nox}` include::{include-path}nox.key[] -=== `{remko}` -include::{include-path}remko.key[] - === `{avl}` include::{include-path}avl.key[] -=== `{issyl0}` -include::{include-path}issyl0.key[] - === `{scottl}` include::{include-path}scottl.key[] -=== `{jtl}` -include::{include-path}jtl.key[] - -=== `{luporl}` -include::{include-path}luporl.key[] - -=== `{wma}` -include::{include-path}wma.key[] - === `{rmacklem}` include::{include-path}rmacklem.key[] @@ -1044,15 +876,12 @@ include::{include-path}mtm.key[] === `{dwmalone}` include::{include-path}dwmalone.key[] -=== `{amdmi3}` -include::{include-path}amdmi3.key[] +=== `{christos}` +include::{include-path}christos.key[] === `{marino}` include::{include-path}marino.key[] -=== `{kwm}` -include::{include-path}kwm.key[] - === `{emaste}` include::{include-path}emaste.key[] @@ -1068,11 +897,8 @@ include::{include-path}mm.key[] === `{sem}` include::{include-path}sem.key[] -=== `{slm}` -include::{include-path}slm.key[] - -=== `{mckay}` -include::{include-path}mckay.key[] +=== `{rcm}` +include::{include-path}rcm.key[] === `{mckusick}` include::{include-path}mckusick.key[] @@ -1080,12 +906,6 @@ include::{include-path}mckusick.key[] === `{tmclaugh}` include::{include-path}tmclaugh.key[] -=== `{jmcneill}` -include::{include-path}jmcneill.key[] - -=== `{xmj}` -include::{include-path}xmj.key[] - === `{jmelo}` include::{include-path}jmelo.key[] @@ -1122,9 +942,6 @@ include::{include-path}jrm.key[] === `{freqlabs}` include::{include-path}freqlabs.key[] -=== `{mmokhi}` -include::{include-path}mmokhi.key[] - === `{mmoll}` include::{include-path}mmoll.key[] @@ -1149,9 +966,6 @@ include::{include-path}marck.key[] === `{mav}` include::{include-path}mav.key[] -=== `{lippe}` -include::{include-path}lippe.key[] - === `{rich}` include::{include-path}rich.key[] @@ -1161,9 +975,6 @@ include::{include-path}knu.key[] === `{tmm}` include::{include-path}tmm.key[] -=== `{jsm}` -include::{include-path}jsm.key[] - === `{max}` include::{include-path}max.key[] @@ -1173,21 +984,9 @@ include::{include-path}maho.key[] === `{yoichi}` include::{include-path}yoichi.key[] -=== `{trasz}` -include::{include-path}trasz.key[] - -=== `{neel}` -include::{include-path}neel.key[] - -=== `{dbn}` -include::{include-path}dbn.key[] - === `{bland}` include::{include-path}bland.key[] -=== `{joneum}` -include::{include-path}joneum.key[] - === `{gnn}` include::{include-path}gnn.key[] @@ -1212,17 +1011,14 @@ include::{include-path}obrien.key[] === `{olgeni}` include::{include-path}olgeni.key[] -=== `{phil}` -include::{include-path}phil.key[] - === `{philip}` include::{include-path}philip.key[] === `{jpaetzel}` include::{include-path}jpaetzel.key[] -=== `{pgj}` -include::{include-path}pgj.key[] +=== `{zirias}` +include::{include-path}zirias.key[] === `{hiren}` include::{include-path}hiren.key[] @@ -1230,9 +1026,6 @@ include::{include-path}hiren.key[] === `{hmp}` include::{include-path}hmp.key[] -=== `{yuripv}` -include::{include-path}yuripv.key[] - === `{fluffy}` include::{include-path}fluffy.key[] @@ -1254,6 +1047,9 @@ include::{include-path}misha.key[] === `{dumbbell}` include::{include-path}dumbbell.key[] +=== `{rpokala}` +include::{include-path}rpokala.key[] + === `{mp}` include::{include-path}mp.key[] @@ -1266,6 +1062,9 @@ include::{include-path}den.key[] === `{csjp}` include::{include-path}csjp.key[] +=== `{grahamperrin}` +include::{include-path}grahamperrin.key[] + === `{gerald}` include::{include-path}gerald.key[] @@ -1278,18 +1077,15 @@ include::{include-path}jacula.key[] === `{0mp}` include::{include-path}0mp.key[] -=== `{pizzamig}` -include::{include-path}pizzamig.key[] - -=== `{rpokala}` -include::{include-path}rpokala.key[] - === `{jdp}` include::{include-path}jdp.key[] === `{krion}` include::{include-path}krion.key[] +=== `{vladlen}` +include::{include-path}vladlen.key[] + === `{sepotvin}` include::{include-path}sepotvin.key[] @@ -1311,9 +1107,6 @@ include::{include-path}thomas.key[] === `{hq}` include::{include-path}hq.key[] -=== `{dfr}` -include::{include-path}dfr.key[] - === `{bofh}` include::{include-path}bofh.key[] @@ -1335,30 +1128,30 @@ include::{include-path}mr.key[] === `{bcr}` include::{include-path}bcr.key[] -=== `{rezny}` -include::{include-path}rezny.key[] - === `{trhodes}` include::{include-path}trhodes.key[] === `{benno}` include::{include-path}benno.key[] -=== `{arichardson}` -include::{include-path}arichardson.key[] - === `{beech}` include::{include-path}beech.key[] -=== `{matteo}` -include::{include-path}matteo.key[] - === `{roberto}` include::{include-path}roberto.key[] === `{rodrigc}` include::{include-path}rodrigc.key[] +=== `{michaelo}` +include::{include-path}michaelo.key[] + +=== `{igoro}` +include::{include-path}igoro.key[] + +=== `{dtxdf}` +include::{include-path}dtxdf.key[] + === `{ler}` include::{include-path}ler.key[] @@ -1377,9 +1170,6 @@ include::{include-path}rea.key[] === `{ray}` include::{include-path}ray.key[] -=== `{arybchik}` -include::{include-path}arybchik.key[] - === `{niklas}` include::{include-path}niklas.key[] @@ -1392,18 +1182,12 @@ include::{include-path}bsam.key[] === `{marks}` include::{include-path}marks.key[] -=== `{alonso}` -include::{include-path}alonso.key[] - === `{bschmidt}` include::{include-path}bschmidt.key[] === `{wosch}` include::{include-path}wosch.key[] -=== `{ed}` -include::{include-path}ed.key[] - === `{cy}` include::{include-path}cy.key[] @@ -1413,36 +1197,21 @@ include::{include-path}das.key[] === `{scheidell}` include::{include-path}scheidell.key[] -=== `{schweikh}` -include::{include-path}schweikh.key[] - === `{matthew}` include::{include-path}matthew.key[] === `{tmseck}` include::{include-path}tmseck.key[] -=== `{stas}` -include::{include-path}stas.key[] - -=== `{johalun}` -include::{include-path}johalun.key[] - === `{johans}` include::{include-path}johans.key[] -=== `{lev}` -include::{include-path}lev.key[] - === `{bakul}` include::{include-path}bakul.key[] === `{gshapiro}` include::{include-path}gshapiro.key[] -=== `{arun}` -include::{include-path}arun.key[] - === `{wxs}` include::{include-path}wxs.key[] @@ -1455,9 +1224,15 @@ include::{include-path}syrinx.key[] === `{vanilla}` include::{include-path}vanilla.key[] +=== `{ashafer}` +include::{include-path}ashafer.key[] + === `{ashish}` include::{include-path}ashish.key[] +=== `{asiciliano}` +include::{include-path}asiciliano.key[] + === `{chs}` include::{include-path}chs.key[] @@ -1509,18 +1284,12 @@ include::{include-path}nsouch.key[] === `{ssouhlal}` include::{include-path}ssouhlal.key[] -=== `{tsoome}` -include::{include-path}tsoome.key[] - === `{loos}` include::{include-path}loos.key[] === `{brnrd}` include::{include-path}brnrd.key[] -=== `{uqs}` -include::{include-path}uqs.key[] - === `{rink}` include::{include-path}rink.key[] @@ -1536,18 +1305,12 @@ include::{include-path}zi.key[] === `{lstewart}` include::{include-path}lstewart.key[] -=== `{rrs}` -include::{include-path}rrs.key[] - === `{murray}` include::{include-path}murray.key[] === `{vs}` include::{include-path}vs.key[] -=== `{rstone}` -include::{include-path}rstone.key[] - === `{xride}` include::{include-path}xride.key[] @@ -1569,9 +1332,6 @@ include::{include-path}metal.key[] === `{ryusuke}` include::{include-path}ryusuke.key[] -=== `{garys}` -include::{include-path}garys.key[] - === `{nyan}` include::{include-path}nyan.key[] @@ -1590,9 +1350,6 @@ include::{include-path}eduardo.key[] === `{sylvio}` include::{include-path}sylvio.key[] -=== `{dteske}` -include::{include-path}dteske.key[] - === `{itetcu}` include::{include-path}itetcu.key[] @@ -1605,12 +1362,6 @@ include::{include-path}gordon.key[] === `{lth}` include::{include-path}lth.key[] -=== `{jase}` -include::{include-path}jase.key[] - -=== `{lx}` -include::{include-path}lx.key[] - === `{fabient}` include::{include-path}fabient.key[] @@ -1632,18 +1383,15 @@ include::{include-path}ganbold.key[] === `{tuexen}` include::{include-path}tuexen.key[] -=== `{andrew}` -include::{include-path}andrew.key[] - === `{gonzo}` include::{include-path}gonzo.key[] +=== `{uzsolt}` +include::{include-path}uzsolt.key[] + === `{ume}` include::{include-path}ume.key[] -=== `{junovitch}` -include::{include-path}junovitch.key[] - === `{ups}` include::{include-path}ups.key[] @@ -1653,15 +1401,9 @@ include::{include-path}fsu.key[] === `{mikael}` include::{include-path}mikael.key[] -=== `{ivadasz}` -include::{include-path}ivadasz.key[] - === `{manu}` include::{include-path}manu.key[] -=== `{vangyzen}` -include::{include-path}vangyzen.key[] - === `{ram}` include::{include-path}ram.key[] @@ -1680,9 +1422,6 @@ include::{include-path}nivit.key[] === `{ivoras}` include::{include-path}ivoras.key[] -=== `{avos}` -include::{include-path}avos.key[] - === `{stefan}` include::{include-path}stefan.key[] @@ -1701,51 +1440,39 @@ include::{include-path}peter.key[] === `{nwhitehorn}` include::{include-path}nwhitehorn.key[] +=== `{obiwac}` +include::{include-path}obiwac.key[] + === `{miwi}` include::{include-path}miwi.key[] === `{nate}` include::{include-path}nate.key[] -=== `{swills}` -include::{include-path}swills.key[] - === `{twinterg}` include::{include-path}twinterg.key[] === `{def}` include::{include-path}def.key[] -=== `{mw}` -include::{include-path}mw.key[] - === `{wollman}` include::{include-path}wollman.key[] -=== `{woodsb02}` -include::{include-path}woodsb02.key[] - === `{joerg}` include::{include-path}joerg.key[] -=== `{davidxu}` -include::{include-path}davidxu.key[] - === `{ygy}` include::{include-path}ygy.key[] === `{emax}` include::{include-path}emax.key[] -=== `{yongari}` -include::{include-path}yongari.key[] - -=== `{rcyu}` -include::{include-path}rcyu.key[] - === `{oshogbo}` include::{include-path}oshogbo.key[] +=== `{andy}` +include::{include-path}andy.key[] + === `{riggs}` include::{include-path}riggs.key[] @@ -1755,33 +1482,18 @@ include::{include-path}egypcio.key[] === `{bz}` include::{include-path}bz.key[] +=== `{dsl}` +include::{include-path}dsl.key[] + === `{zeising}` include::{include-path}zeising.key[] === `{phantom}` include::{include-path}phantom.key[] -=== `{sephe}` -include::{include-path}sephe.key[] - -=== `{mizhka}` -include::{include-path}mizhka.key[] - -=== `{zont}` -include::{include-path}zont.key[] - === `{tz}` include::{include-path}tz.key[] -=== `{yuri}` -include::{include-path}yuri.key[] - -=== `{slavash}` -include::{include-path}slavash.key[] - -=== `{arrowd}` -include::{include-path}arrowd.key[] - === `{rigoletto}` include::{include-path}rigoletto.key[] @@ -1791,14 +1503,41 @@ include::{include-path}kaktus.key[] === `{samm}` include::{include-path}samm.key[] -[[pgpkeys-other]] -== Other Cluster Account Holders +=== `{arrowd}` +include::{include-path}arrowd.key[] -=== `{arundel}` -include::{include-path}arundel.key[] +=== `{ronald}` +include::{include-path}ronald.key[] -=== `{bhaga}` -include::{include-path}bhaga.key[] +=== `{meta}` +include::{include-path}meta.key[] + +=== `{rnagy}` +include::{include-path}rnagy.key[] + +=== `{vvd}` +include::{include-path}vvd.key[] + +=== `{gbe}` +include::{include-path}gbe.key[] + +=== `{bnovkov}` +include::{include-path}bnovkov.key[] + +=== `{ivy}` +include::{include-path}ivy.key[] + +=== `{khorben}` +include::{include-path}khorben.key[] + +=== `{vexeduxr}` +include::{include-path}vexeduxr.key[] + +=== `{alven}` +include::{include-path}alven.key[] + +[[pgpkeys-other]] +== Other Cluster Account Holders === `{bk}` include::{include-path}bk.key[] @@ -1815,9 +1554,6 @@ include::{include-path}dutchdaemon.key[] === `{keymaster}` include::{include-path}keymaster.key[] -=== `{plosher}` -include::{include-path}plosher.key[] - === `{mwlucas}` include::{include-path}mwlucas.key[] diff --git a/documentation/content/en/articles/pgpkeys/_index.po b/documentation/content/en/articles/pgpkeys/_index.po new file mode 100644 index 0000000000..f961577548 --- /dev/null +++ b/documentation/content/en/articles/pgpkeys/_index.po @@ -0,0 +1,2997 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-08-17 20:54+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/pgpkeys/_index.adoc:1 +#, no-wrap +msgid "List of OpenPGP keys that can be used to verify a signature or send encrypted email to FreeBSD.org officers or developers." +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/pgpkeys/_index.adoc:1 +#: documentation/content/en/articles/pgpkeys/_index.adoc:7 +#, no-wrap +msgid "OpenPGP Keys" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pgpkeys/_index.adoc:45 +msgid "'''" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pgpkeys/_index.adoc:50 +msgid "" +"These OpenPGP keys can be used to verify a signature or send encrypted email " +"to `FreeBSD.org` officers or developers. The complete keyring can be " +"downloaded at link:https://docs.FreeBSD.org/pgpkeys/" +"pgpkeys.txt[pgpkeyring.txt]." +msgstr "" + +# +# +#. Do not edit this file except as instructed by the addkey.sh script. +#. See the README file in /data/pgpkeys for instructions. +#. This article contains all the keys. The officer keys are also +#. shown in the Handbook PGP keys chapter. +#. type: Title == +#: documentation/content/en/articles/pgpkeys/_index.adoc:61 +#, no-wrap +msgid "Officers" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:63 +#, no-wrap +msgid "{security-officer-name} `<{security-officer-email}>`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:66 +#, no-wrap +msgid "{core-secretary-name} `<{core-secretary-email}>`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:69 +#, no-wrap +msgid "{portmgr-secretary-name} `<{portmgr-secretary-email}>`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:72 +#, no-wrap +msgid "{doceng-secretary-name} `<{doceng-secretary-email}>`" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pgpkeys/_index.adoc:76 +#, no-wrap +msgid "Core Team Members" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:78 +#: documentation/content/en/articles/pgpkeys/_index.adoc:645 +#, no-wrap +msgid "`{allanjude}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:81 +#: documentation/content/en/articles/pgpkeys/_index.adoc:339 +#, no-wrap +msgid "`{dch}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:84 +#: documentation/content/en/articles/pgpkeys/_index.adoc:1248 +#, no-wrap +msgid "`{glebius}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:87 +#, no-wrap +msgid "`{hrs}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:90 +#: documentation/content/en/articles/pgpkeys/_index.adoc:597 +#, no-wrap +msgid "`{lwhsu}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:93 +#: documentation/content/en/articles/pgpkeys/_index.adoc:147 +#, no-wrap +msgid "`{mat}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:96 +#: documentation/content/en/articles/pgpkeys/_index.adoc:336 +#, no-wrap +msgid "`{olivier}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:99 +#: documentation/content/en/articles/pgpkeys/_index.adoc:198 +#, no-wrap +msgid "`{tcberner}`" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pgpkeys/_index.adoc:103 +#, no-wrap +msgid "Developers" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:105 +#, no-wrap +msgid "`{jgh}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:108 +#, no-wrap +msgid "`{ariff}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:111 +#, no-wrap +msgid "`{tabthorpe}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:114 +#, no-wrap +msgid "`{eadler}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:117 +#, no-wrap +msgid "`{pauamma}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:120 +#, no-wrap +msgid "`{shaun}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:123 +#, no-wrap +msgid "`{brix}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:126 +#, no-wrap +msgid "`{mandree}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:129 +#, no-wrap +msgid "`{will}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:132 +#, no-wrap +msgid "`{dim}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:135 +#, no-wrap +msgid "`{anholt}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:138 +#, no-wrap +msgid "`{fernape}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:141 +#, no-wrap +msgid "`{mva}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:144 +#, no-wrap +msgid "`{araujo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:150 +#, no-wrap +msgid "`{syuu}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:153 +#, no-wrap +msgid "`{asami}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:156 +#, no-wrap +msgid "`{jsa}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:159 +#, no-wrap +msgid "`{jadawin}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:162 +#, no-wrap +msgid "`{jwb}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:165 +#, no-wrap +msgid "`{dbaio}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:168 +#, no-wrap +msgid "`{timur}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:171 +#, no-wrap +msgid "`{jhb}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:174 +#, no-wrap +msgid "`{gjb}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:177 +#, no-wrap +msgid "`{snb}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:180 +#, no-wrap +msgid "`{barner}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:183 +#, no-wrap +msgid "`{lbartoletti}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:186 +#, no-wrap +msgid "`{art}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:189 +#, no-wrap +msgid "`{tobez}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:192 +#, no-wrap +msgid "`{damien}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:195 +#, no-wrap +msgid "`{bdragon}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:201 +#, no-wrap +msgid "`{tdb}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:204 +#, no-wrap +msgid "`{mbr}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:207 +#, no-wrap +msgid "`{bvs}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:210 +#, no-wrap +msgid "`{jbo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:213 +#, no-wrap +msgid "`{novel}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:216 +#, no-wrap +msgid "`{garga}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:219 +#, no-wrap +msgid "`{kbowling}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:222 +#, no-wrap +msgid "`{alexbl}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:225 +#, no-wrap +msgid "`{ebrandi}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:228 +#, no-wrap +msgid "`{harti}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:231 +#, no-wrap +msgid "`{obraun}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:234 +#, no-wrap +msgid "`{makc}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:237 +#, no-wrap +msgid "`{jmb}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:240 +#, no-wrap +msgid "`{dab}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:243 +#, no-wrap +msgid "`{antoine}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:246 +#, no-wrap +msgid "`{db}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:249 +#, no-wrap +msgid "`{brueffer}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:252 +#, no-wrap +msgid "`{markus}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:255 +#, no-wrap +msgid "`{br}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:258 +#, no-wrap +msgid "`{jch}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:261 +#, no-wrap +msgid "`{jchandra}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:264 +#, no-wrap +msgid "`{jcamou}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:267 +#, no-wrap +msgid "`{acm}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:270 +#, no-wrap +msgid "`{olce}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:273 +#, no-wrap +msgid "`{gahr}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:276 +#, no-wrap +msgid "`{dchagin}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:279 +#, no-wrap +msgid "`{perky}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:282 +#, no-wrap +msgid "`{jon}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:285 +#, no-wrap +msgid "`{jonathan}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:288 +#, no-wrap +msgid "`{loader}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:291 +#, no-wrap +msgid "`{luoqi}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:294 +#, no-wrap +msgid "`{ache}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:297 +#, no-wrap +msgid "`{melifaro}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:300 +#, no-wrap +msgid "`{cjh}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:303 +#, no-wrap +msgid "`{davidch}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:306 +#, no-wrap +msgid "`{milki}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:309 +#, no-wrap +msgid "`{cjc}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:312 +#, no-wrap +msgid "`{marcus}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:315 +#, no-wrap +msgid "`{fuz}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:318 +#, no-wrap +msgid "`{nik}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:321 +#, no-wrap +msgid "`{benjsc}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:324 +#, no-wrap +msgid "`{lcook}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:327 +#, no-wrap +msgid "`{ngie}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:330 +#, no-wrap +msgid "`{rakuco}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:333 +#, no-wrap +msgid "`{alc}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:342 +#, no-wrap +msgid "`{bcran}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:345 +#, no-wrap +msgid "`{cc}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:348 +#, no-wrap +msgid "`{culot}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:351 +#, no-wrap +msgid "`{alfredo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:354 +#, no-wrap +msgid "`{bapt}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:357 +#, no-wrap +msgid "`{ceri}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:360 +#, no-wrap +msgid "`{edavis}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:363 +#, no-wrap +msgid "`{alexey}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:366 +#, no-wrap +msgid "`{bsd}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:369 +#, no-wrap +msgid "`{carl}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:372 +#, no-wrap +msgid "`{carlavilla}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:375 +#, no-wrap +msgid "`{vd}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:378 +#, no-wrap +msgid "`{rdivacky}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:381 +#, no-wrap +msgid "`{danfe}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:384 +#, no-wrap +msgid "`{dd}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:387 +#, no-wrap +msgid "`{bdrewery}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:390 +#, no-wrap +msgid "`{gad}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:393 +#, no-wrap +msgid "`{kd}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:396 +#, no-wrap +msgid "`{olivierd}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:399 +#, no-wrap +msgid "`{bruno}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:402 +#, no-wrap +msgid "`{ale}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:405 +#, no-wrap +msgid "`{jlduran}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:408 +#, no-wrap +msgid "`{nemysis}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:411 +#, no-wrap +msgid "`{peadar}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:414 +#, no-wrap +msgid "`{deischen}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:417 +#, no-wrap +msgid "`{diizzy}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:420 +#, no-wrap +msgid "`{ue}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:423 +#, no-wrap +msgid "`{madpilot}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:426 +#, no-wrap +msgid "`{rafan}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:429 +#, no-wrap +msgid "`{kami}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:432 +#, no-wrap +msgid "`{farrokhi}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:435 +#, no-wrap +msgid "`{jedgar}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:438 +#, no-wrap +msgid "`{mfechner}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:441 +#, no-wrap +msgid "`{feld}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:444 +#, no-wrap +msgid "`{green}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:447 +#, no-wrap +msgid "`{fanf}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:450 +#, no-wrap +msgid "`{blackend}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:453 +#, no-wrap +msgid "`{petef}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:456 +#, no-wrap +msgid "`{decke}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:459 +#, no-wrap +msgid "`{landonf}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:462 +#, no-wrap +msgid "`{billf}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:465 +#, no-wrap +msgid "`{grembo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:468 +#, no-wrap +msgid "`{sgalabov}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:471 +#, no-wrap +msgid "`{kgalazka}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:474 +#, no-wrap +msgid "`{avg}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:477 +#, no-wrap +msgid "`{beat}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:480 +#, no-wrap +msgid "`{sjg}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:483 +#, no-wrap +msgid "`{gibbs}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:486 +#, no-wrap +msgid "`{pfg}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:489 +#, no-wrap +msgid "`{girgen}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:492 +#, no-wrap +msgid "`{eugen}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:495 +#, no-wrap +msgid "`{pgollucci}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:498 +#, no-wrap +msgid "`{trociny}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:501 +#, no-wrap +msgid "`{dmgk}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:504 +#, no-wrap +msgid "`{daichi}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:507 +#, no-wrap +msgid "`{grehan}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:510 +#, no-wrap +msgid "`{jamie}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:513 +#, no-wrap +msgid "`{adridg}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:516 +#, no-wrap +msgid "`{wg}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:519 +#, no-wrap +msgid "`{bar}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:522 +#, no-wrap +msgid "`{jmg}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:525 +#, no-wrap +msgid "`{mjg}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:528 +#, no-wrap +msgid "`{jhale}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:531 +#, no-wrap +msgid "`{jah}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:534 +#, no-wrap +msgid "`{dannyboy}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:537 +#, no-wrap +msgid "`{dhartmei}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:540 +#, no-wrap +msgid "`{ohauer}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:543 +#, no-wrap +msgid "`{ehaupt}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:546 +#, no-wrap +msgid "`{jhay}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:549 +#, no-wrap +msgid "`{bhd}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:552 +#, no-wrap +msgid "`{sheldonh}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:555 +#, no-wrap +msgid "`{mikeh}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:558 +#, no-wrap +msgid "`{mheinen}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:561 +#, no-wrap +msgid "`{niels}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:564 +#, no-wrap +msgid "`{ghelmer}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:567 +#, no-wrap +msgid "`{mux}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:570 +#, no-wrap +msgid "`{wen}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:573 +#, no-wrap +msgid "`{dhn}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:576 +#, no-wrap +msgid "`{jhibbits}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:579 +#, no-wrap +msgid "`{jhixson}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:582 +#, no-wrap +msgid "`{pho}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:585 +#, no-wrap +msgid "`{oh}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:588 +#, no-wrap +msgid "`{mhorne}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:591 +#, no-wrap +msgid "`{bhughes}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:594 +#, no-wrap +msgid "`{sunpoet}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:600 +#, no-wrap +msgid "`{foxfair}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:603 +#, no-wrap +msgid "`{whu}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:606 +#, no-wrap +msgid "`{chinsan}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:609 +#, no-wrap +msgid "`{zlei}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:612 +#, no-wrap +msgid "`{davide}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:615 +#, no-wrap +msgid "`{jkh}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:618 +#, no-wrap +msgid "`{versus}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:621 +#, no-wrap +msgid "`{pi}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:624 +#, no-wrap +msgid "`{weongyo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:627 +#, no-wrap +msgid "`{peterj}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:630 +#, no-wrap +msgid "`{jinmei}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:633 +#, no-wrap +msgid "`{ahze}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:636 +#, no-wrap +msgid "`{markj}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:639 +#, no-wrap +msgid "`{trevor}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:642 +#, no-wrap +msgid "`{erj}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:648 +#, no-wrap +msgid "`{bjk}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:651 +#, no-wrap +msgid "`{phk}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:654 +#, no-wrap +msgid "`{pluknet}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:657 +#, no-wrap +msgid "`{cokane}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:660 +#, no-wrap +msgid "`{karels}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:663 +#, no-wrap +msgid "`{kato}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:666 +#, no-wrap +msgid "`{vkashyap}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:669 +#, no-wrap +msgid "`{pkubaj}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:672 +#, no-wrap +msgid "`{kris}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:675 +#, no-wrap +msgid "`{keramida}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:678 +#, no-wrap +msgid "`{fjoe}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:681 +#, no-wrap +msgid "`{manolis}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:684 +#, no-wrap +msgid "`{stevek}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:687 +#, no-wrap +msgid "`{jkim}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:690 +#, no-wrap +msgid "`{zack}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:693 +#, no-wrap +msgid "`{akiyano}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:696 +#, no-wrap +msgid "`{jceel}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:699 +#, no-wrap +msgid "`{andreas}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:702 +#, no-wrap +msgid "`{kai}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:705 +#, no-wrap +msgid "`{corvink}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:708 +#, no-wrap +msgid "`{jkois}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:711 +#, no-wrap +msgid "`{sergei}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:714 +#, no-wrap +msgid "`{maxim}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:717 +#, no-wrap +msgid "`{taras}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:720 +#, no-wrap +msgid "`{tobik}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:723 +#, no-wrap +msgid "`{jkoshy}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:726 +#, no-wrap +msgid "`{wkoszek}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:729 +#, no-wrap +msgid "`{ak}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:732 +#, no-wrap +msgid "`{gabor}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:735 +#, no-wrap +msgid "`{anchie}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:738 +#, no-wrap +msgid "`{rushani}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:741 +#, no-wrap +msgid "`{kuriyama}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:744 +#, no-wrap +msgid "`{rene}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:747 +#, no-wrap +msgid "`{jlaffaye}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:750 +#, no-wrap +msgid "`{clement}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:753 +#, no-wrap +msgid "`{mlaier}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:756 +#, no-wrap +msgid "`{martymac}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:759 +#, no-wrap +msgid "`{glarkin}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:762 +#, no-wrap +msgid "`{dru}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:765 +#, no-wrap +msgid "`{lawrance}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:768 +#, no-wrap +msgid "`{njl}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:771 +#, no-wrap +msgid "`{jlh}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:774 +#, no-wrap +msgid "`{leeym}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:777 +#, no-wrap +msgid "`{sam}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:780 +#, no-wrap +msgid "`{jylefort}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:783 +#, no-wrap +msgid "`{grog}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:786 +#, no-wrap +msgid "`{oliver}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:789 +#, no-wrap +msgid "`{netchild}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:792 +#, no-wrap +msgid "`{leitao}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:795 +#, no-wrap +msgid "`{ae}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:798 +#, no-wrap +msgid "`{lesi}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:801 +#, no-wrap +msgid "`{achim}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:804 +#, no-wrap +msgid "`{cel}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:807 +#, no-wrap +msgid "`{glewis}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:810 +#, no-wrap +msgid "`{vishwin}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:813 +#, no-wrap +msgid "`{delphij}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:816 +#, no-wrap +msgid "`{avatar}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:819 +#, no-wrap +msgid "`{ijliao}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:822 +#, no-wrap +msgid "`{rlibby}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:825 +#, no-wrap +msgid "`{pclin}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:828 +#, no-wrap +msgid "`{yzlin}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:831 +#, no-wrap +msgid "`{linimon}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:834 +#, no-wrap +msgid "`{arved}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:837 +#, no-wrap +msgid "`{dryice}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:840 +#, no-wrap +msgid "`{nemoliu}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:843 +#, no-wrap +msgid "`{kevlo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:846 +#, no-wrap +msgid "`{zml}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:849 +#, no-wrap +msgid "`{nox}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:852 +#, no-wrap +msgid "`{avl}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:855 +#, no-wrap +msgid "`{scottl}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:858 +#, no-wrap +msgid "`{rmacklem}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:861 +#, no-wrap +msgid "`{vmaffione}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:864 +#, no-wrap +msgid "`{bmah}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:867 +#, no-wrap +msgid "`{rm}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:870 +#, no-wrap +msgid "`{mtm}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:873 +#, no-wrap +msgid "`{dwmalone}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:876 +#, no-wrap +msgid "`{christos}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:879 +#, no-wrap +msgid "`{marino}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:882 +#, no-wrap +msgid "`{cherry}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:885 +#, no-wrap +msgid "`{matusita}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:888 +#, no-wrap +msgid "`{mm}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:891 +#, no-wrap +msgid "`{sem}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:894 +#, no-wrap +msgid "`{rcm}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:897 +#, no-wrap +msgid "`{mckusick}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:900 +#, no-wrap +msgid "`{tmclaugh}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:903 +#, no-wrap +msgid "`{jmelo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:906 +#, no-wrap +msgid "`{mmel}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:909 +#, no-wrap +msgid "`{jmmv}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:912 +#, no-wrap +msgid "`{kadesai}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:915 +#, no-wrap +msgid "`{ken}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:918 +#, no-wrap +msgid "`{markm}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:921 +#, no-wrap +msgid "`{dinoex}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:924 +#, no-wrap +msgid "`{sanpei}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:927 +#, no-wrap +msgid "`{rmh}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:930 +#, no-wrap +msgid "`{driesm}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:933 +#, no-wrap +msgid "`{jrm}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:936 +#, no-wrap +msgid "`{freqlabs}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:939 +#, no-wrap +msgid "`{mmoll}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:942 +#, no-wrap +msgid "`{cmt}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:945 +#, no-wrap +msgid "`{stephen}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:948 +#, no-wrap +msgid "`{marcel}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:951 +#, no-wrap +msgid "`{dougm}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:954 +#, no-wrap +msgid "`{kmoore}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:957 +#, no-wrap +msgid "`{marck}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:960 +#, no-wrap +msgid "`{mav}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:963 +#, no-wrap +msgid "`{rich}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:966 +#, no-wrap +msgid "`{knu}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:969 +#, no-wrap +msgid "`{tmm}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:972 +#, no-wrap +msgid "`{max}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:975 +#, no-wrap +msgid "`{maho}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:978 +#, no-wrap +msgid "`{yoichi}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:981 +#, no-wrap +msgid "`{bland}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:984 +#, no-wrap +msgid "`{gnn}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:987 +#, no-wrap +msgid "`{khng}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:990 +#, no-wrap +msgid "`{simon}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:993 +#, no-wrap +msgid "`{rnoland}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:996 +#, no-wrap +msgid "`{anders}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:999 +#, no-wrap +msgid "`{lofi}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1002 +#, no-wrap +msgid "`{obrien}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1005 +#, no-wrap +msgid "`{olgeni}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1008 +#, no-wrap +msgid "`{philip}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1011 +#, no-wrap +msgid "`{jpaetzel}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1014 +#, no-wrap +msgid "`{zirias}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1017 +#, no-wrap +msgid "`{hiren}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1020 +#, no-wrap +msgid "`{hmp}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1023 +#, no-wrap +msgid "`{fluffy}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1026 +#, no-wrap +msgid "`{sat}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1029 +#, no-wrap +msgid "`{np}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1032 +#, no-wrap +msgid "`{royger}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1035 +#, no-wrap +msgid "`{rpaulo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1038 +#, no-wrap +msgid "`{misha}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1041 +#, no-wrap +msgid "`{dumbbell}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1044 +#, no-wrap +msgid "`{rpokala}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1047 +#, no-wrap +msgid "`{mp}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1050 +#, no-wrap +msgid "`{roam}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1053 +#, no-wrap +msgid "`{den}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1056 +#, no-wrap +msgid "`{csjp}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1059 +#, no-wrap +msgid "`{grahamperrin}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1062 +#, no-wrap +msgid "`{gerald}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1065 +#, no-wrap +msgid "`{scottph}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1068 +#, no-wrap +msgid "`{jacula}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1071 +#, no-wrap +msgid "`{0mp}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1074 +#, no-wrap +msgid "`{jdp}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1077 +#, no-wrap +msgid "`{krion}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1080 +#, no-wrap +msgid "`{sepotvin}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1083 +#, no-wrap +msgid "`{cpm}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1086 +#, no-wrap +msgid "`{markp}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1089 +#, no-wrap +msgid "`{alepulver}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1092 +#, no-wrap +msgid "`{kp}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1095 +#, no-wrap +msgid "`{thomas}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1098 +#, no-wrap +msgid "`{hq}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1101 +#, no-wrap +msgid "`{bofh}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1104 +#, no-wrap +msgid "`{fox}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1107 +#, no-wrap +msgid "`{lbr}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1110 +#, no-wrap +msgid "`{crees}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1113 +#, no-wrap +msgid "`{rees}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1116 +#, no-wrap +msgid "`{mr}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1119 +#, no-wrap +msgid "`{bcr}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1122 +#, no-wrap +msgid "`{trhodes}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1125 +#, no-wrap +msgid "`{benno}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1128 +#, no-wrap +msgid "`{beech}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1131 +#, no-wrap +msgid "`{roberto}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1134 +#, no-wrap +msgid "`{rodrigc}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1137 +#, no-wrap +msgid "`{michaelo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1140 +#, no-wrap +msgid "`{igoro}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1143 +#, no-wrap +msgid "`{dtxdf}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1146 +#, no-wrap +msgid "`{ler}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1149 +#, no-wrap +msgid "`{leres}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1152 +#, no-wrap +msgid "`{robak}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1155 +#, no-wrap +msgid "`{guido}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1158 +#, no-wrap +msgid "`{rea}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1161 +#, no-wrap +msgid "`{ray}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1164 +#, no-wrap +msgid "`{niklas}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1167 +#, no-wrap +msgid "`{salvadore}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1170 +#, no-wrap +msgid "`{bsam}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1173 +#, no-wrap +msgid "`{marks}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1176 +#, no-wrap +msgid "`{bschmidt}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1179 +#, no-wrap +msgid "`{wosch}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1182 +#, no-wrap +msgid "`{cy}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1185 +#, no-wrap +msgid "`{das}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1188 +#, no-wrap +msgid "`{scheidell}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1191 +#, no-wrap +msgid "`{matthew}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1194 +#, no-wrap +msgid "`{tmseck}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1197 +#, no-wrap +msgid "`{johans}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1200 +#, no-wrap +msgid "`{bakul}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1203 +#, no-wrap +msgid "`{gshapiro}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1206 +#, no-wrap +msgid "`{wxs}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1209 +#, no-wrap +msgid "`{nork}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1212 +#, no-wrap +msgid "`{syrinx}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1215 +#, no-wrap +msgid "`{vanilla}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1218 +#, no-wrap +msgid "`{ashafer}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1221 +#, no-wrap +msgid "`{ashish}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1224 +#, no-wrap +msgid "`{asiciliano}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1227 +#, no-wrap +msgid "`{chs}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1230 +#, no-wrap +msgid "`{bms}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1233 +#, no-wrap +msgid "`{demon}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1236 +#, no-wrap +msgid "`{jesper}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1239 +#, no-wrap +msgid "`{scop}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1242 +#, no-wrap +msgid "`{anray}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1245 +#, no-wrap +msgid "`{flo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1251 +#, no-wrap +msgid "`{kensmith}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1254 +#, no-wrap +msgid "`{ben}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1257 +#, no-wrap +msgid "`{des}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1260 +#, no-wrap +msgid "`{sobomax}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1263 +#, no-wrap +msgid "`{asomers}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1266 +#, no-wrap +msgid "`{brian}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1269 +#, no-wrap +msgid "`{sson}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1272 +#, no-wrap +msgid "`{nsouch}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1275 +#, no-wrap +msgid "`{ssouhlal}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1278 +#, no-wrap +msgid "`{loos}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1281 +#, no-wrap +msgid "`{brnrd}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1284 +#, no-wrap +msgid "`{rink}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1287 +#, no-wrap +msgid "`{vsevolod}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1290 +#, no-wrap +msgid "`{pstef}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1293 +#, no-wrap +msgid "`{zi}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1296 +#, no-wrap +msgid "`{lstewart}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1299 +#, no-wrap +msgid "`{murray}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1302 +#, no-wrap +msgid "`{vs}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1305 +#, no-wrap +msgid "`{xride}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1308 +#, no-wrap +msgid "`{marius}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1311 +#, no-wrap +msgid "`{cs}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1314 +#, no-wrap +msgid "`{clsung}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1317 +#, no-wrap +msgid "`{gsutter}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1320 +#, no-wrap +msgid "`{metal}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1323 +#, no-wrap +msgid "`{ryusuke}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1326 +#, no-wrap +msgid "`{nyan}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1329 +#, no-wrap +msgid "`{sahil}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1332 +#, no-wrap +msgid "`{tota}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1335 +#, no-wrap +msgid "`{romain}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1338 +#, no-wrap +msgid "`{eduardo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1341 +#, no-wrap +msgid "`{sylvio}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1344 +#, no-wrap +msgid "`{itetcu}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1347 +#, no-wrap +msgid "`{mi}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1350 +#, no-wrap +msgid "`{gordon}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1353 +#, no-wrap +msgid "`{lth}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1356 +#, no-wrap +msgid "`{fabient}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1359 +#, no-wrap +msgid "`{thierry}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1362 +#, no-wrap +msgid "`{thompsa}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1365 +#, no-wrap +msgid "`{flz}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1368 +#, no-wrap +msgid "`{jilles}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1371 +#, no-wrap +msgid "`{ganbold}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1374 +#, no-wrap +msgid "`{tuexen}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1377 +#, no-wrap +msgid "`{gonzo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1380 +#, no-wrap +msgid "`{uzsolt}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1383 +#, no-wrap +msgid "`{ume}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1386 +#, no-wrap +msgid "`{ups}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1389 +#, no-wrap +msgid "`{fsu}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1392 +#, no-wrap +msgid "`{mikael}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1395 +#, no-wrap +msgid "`{manu}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1398 +#, no-wrap +msgid "`{ram}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1401 +#, no-wrap +msgid "`{bryanv}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1404 +#, no-wrap +msgid "`{nectar}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1407 +#, no-wrap +msgid "`{avilla}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1410 +#, no-wrap +msgid "`{nivit}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1413 +#, no-wrap +msgid "`{ivoras}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1416 +#, no-wrap +msgid "`{stefan}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1419 +#, no-wrap +msgid "`{kaiw}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1422 +#, no-wrap +msgid "`{adamw}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1425 +#, no-wrap +msgid "`{naddy}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1428 +#, no-wrap +msgid "`{peter}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1431 +#, no-wrap +msgid "`{nwhitehorn}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1434 +#, no-wrap +msgid "`{obiwac}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1437 +#, no-wrap +msgid "`{miwi}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1440 +#, no-wrap +msgid "`{nate}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1443 +#, no-wrap +msgid "`{twinterg}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1446 +#, no-wrap +msgid "`{def}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1449 +#, no-wrap +msgid "`{wollman}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1452 +#, no-wrap +msgid "`{joerg}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1455 +#, no-wrap +msgid "`{ygy}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1458 +#, no-wrap +msgid "`{emax}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1461 +#, no-wrap +msgid "`{oshogbo}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1464 +#, no-wrap +msgid "`{riggs}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1467 +#, no-wrap +msgid "`{egypcio}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1470 +#, no-wrap +msgid "`{bz}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1473 +#, no-wrap +msgid "`{dsl}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1476 +#, no-wrap +msgid "`{zeising}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1479 +#, no-wrap +msgid "`{phantom}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1482 +#, no-wrap +msgid "`{tz}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1485 +#, no-wrap +msgid "`{rigoletto}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1488 +#, no-wrap +msgid "`{kaktus}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1491 +#, no-wrap +msgid "`{samm}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1494 +#, no-wrap +msgid "`{arrowd}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1497 +#, no-wrap +msgid "`{ronald}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1500 +#, no-wrap +msgid "`{meta}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1503 +#, no-wrap +msgid "`{rnagy}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1506 +#, no-wrap +msgid "`{vvd}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1509 +#, no-wrap +msgid "`{gbe}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1512 +#, no-wrap +msgid "`{bnovkov}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1515 +#, no-wrap +msgid "`{ivy}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1518 +#, no-wrap +msgid "`{khorben}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1521 +#, no-wrap +msgid "`{vexeduxr}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1524 +#, no-wrap +msgid "`{alven}`" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pgpkeys/_index.adoc:1528 +#, no-wrap +msgid "Other Cluster Account Holders" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1530 +#, no-wrap +msgid "`{bk}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1533 +#, no-wrap +msgid "`{deb}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1536 +#, no-wrap +msgid "`{debdrup}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1539 +#, no-wrap +msgid "`{dutchdaemon}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1542 +#, no-wrap +msgid "`{keymaster}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1545 +#, no-wrap +msgid "`{mwlucas}`" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/pgpkeys/_index.adoc:1548 +#, no-wrap +msgid "`{dhw}`" +msgstr "" diff --git a/documentation/content/en/articles/port-mentor-guidelines/_index.po b/documentation/content/en/articles/port-mentor-guidelines/_index.po new file mode 100644 index 0000000000..8318571d82 --- /dev/null +++ b/documentation/content/en/articles/port-mentor-guidelines/_index.po @@ -0,0 +1,311 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2022-02-01 09:21-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:1 +#, no-wrap +msgid "Port Mentor Guidelines for FreeBSD Mentors" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:1 +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:10 +#, no-wrap +msgid "Port Mentor Guidelines" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:42 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:46 +#, no-wrap +msgid "Guideline for Mentor/Mentee Relationships" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:50 +msgid "" +"This section is intended to help demystify the mentoring process, as well as " +"a way to openly promote a constructive discussion to adapt and grow the " +"guidelines. In our lives we have too many rules; we are not a government " +"organization that inflicts regulation, but rather a collective of like " +"minded individuals working toward a common goal, maintaining the quality " +"assurance of the product we call the Ports Tree." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:52 +#, no-wrap +msgid "Why Mentor?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:55 +msgid "" +"For most of us, we were mentored into the Project, so return the favor by " +"offering to mentor somebody else in." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:56 +msgid "You have an irresistible urge to inflict knowledge on others." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:57 +msgid "" +"The usual punishment applies because you are sick and tired of committing " +"somebody else's good work!" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:59 +#, no-wrap +msgid "Mentor/Co-Mentor" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:62 +msgid "Reasons for a co-mentorship:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:64 +msgid "" +"Significant timezone differential. Accessible, interactive mentor(s) " +"available via IM is extremely helpful!" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:65 +msgid "" +"Potential language barrier. Yes, FreeBSD is very English oriented, as is " +"most software development, however, having a mentor who can speak a native " +"language can be very useful." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:66 +msgid "" +"ENOTIME! Until there is a 30 hour day, and an 8 day week, some of us only " +"have so much time to give. Sharing the load with somebody else will make it " +"easier." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:67 +msgid "" +"A rookie mentor can benefit from the experience of a senior committer/mentor." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:68 +msgid "Two heads are better than one." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:70 +msgid "Reasons for sole mentorship:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:72 +msgid "You do not play nicely with others." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:73 +msgid "You prefer to have a one-on-one relationship." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:74 +msgid "The reasons for co-mentorship do not apply to you." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:76 +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:134 +#, no-wrap +msgid "Expectations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:79 +msgid "" +"We expect mentors to review and test-build all proposed patches, at least " +"for an initial period lasting more than a week or two." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:82 +msgid "" +"We expect that mentors should take responsibility for the actions of their " +"mentee. A mentor should follow up with all commits the mentee makes, both " +"approved and implicit." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:85 +msgid "" +"We expect mentors to make sure their mentees read the extref:{porters-" +"handbook}[Porter's Handbook], the extref:{pr-guidelines}[PR handling guide], " +"and the extref:{committers-guide}[Committer's Guide]. While it is not " +"necessary to memorize all the details, every committer needs to have an " +"overview of these things to be an effective part of the community (and avoid " +"as many rookie mistakes as possible)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:87 +#, no-wrap +msgid "Selecting a Mentee" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:90 +msgid "" +"There is no defined rule for what makes a candidate ready; it can be a " +"combination of number of PRs they have submitted, the number of ports " +"maintained, frequency of ports updates and/or level of participation in a " +"particular area of interest like GNOME, KDE, Gecko or others." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:92 +msgid "" +"A candidate should have almost no timeouts, be responsive to requests, and " +"generally helpful in supporting their ports." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:96 +msgid "" +"There must be a history of commitment, as it is widely understood that " +"training a committer requires time and effort. If somebody has been around " +"longer, and spent the time observing how things are done, there is some " +"anticipation of accumulated knowledge. All too often we have seen a " +"maintainer submit a few PRs, show up in IRC and ask when they will be given " +"a commit bit." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:101 +msgid "" +"Being subscribed to, and following the mailing lists is very beneficial. " +"There is no real expectation that submitting posts on the lists will make " +"somebody a committer, but it demonstrates a commitment. Some mails offer " +"insights into the knowledge of a candidate as well how they interact with " +"others. Similarly participating in IRC can give somebody a higher profile." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:105 +msgid "" +"Ask six different committers how many PRs a maintainer should submit prior " +"to being nominated, and you will get six different answers. Ask those same " +"individuals how long somebody should have been participating, same dilemma. " +"How many ports should they have at a minimum? Now we have a bikeshed! Some " +"things are just hard to quantify, a mentor will just have to use their best " +"judgement, and hope that portmgr agrees." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:107 +#, no-wrap +msgid "Mentorship Duration" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:114 +msgid "" +"As the trust level develops and grows, the mentee may be granted \"implicit" +"\" commit rights. This can include trivial changes to a [." +"filename]#Makefile#, [.filename]#pkg-descr# etc. Similarly, it may include " +"`PORTVERSION` updates that do not include `plist` changes. Other " +"circumstances may be formulated at the discretion of the Mentor. However, " +"during the period of mentorship, a port version bump that affects dependent " +"ports should be checked by a mentor." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:120 +msgid "" +"Just as we are all varied individuals, each mentee has different learning " +"curves, time commitments, and other influencing factors that will contribute " +"to the time required before they can \"fly solo\". Empirically, a mentee " +"should be observed for at least 3 months. 90-100 commits is another target " +"that a mentor could use before releasing a mentee. Other factors to " +"consider prior releasing a mentee are the number of mistakes they may have " +"made, QATs received etc. If they are still making rookie mistakes, they " +"still require mentor guidance." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:122 +#, no-wrap +msgid "Mentor/Co-Mentor Debate" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:126 +msgid "" +"When a request gets to portmgr, it usually reads as, \"I propose 'foo' for a " +"ports commit bit, I will co-mentor with 'bar'\". Proposal received, voted, " +"and carried." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:128 +msgid "" +"The mentor is the primary point of contact or the \"first among equals\", " +"the co-mentor is the backup." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:132 +msgid "" +"Some reprobate, whose name shall be withheld, made the https://lists.freebsd." +"org/pipermail/cvs-ports/2007-September/134614.html[first recorded co-mentor " +"commit]. Similar co-mentor commits have also been spotted in the src tree. " +"Does this make it right? Does this make it wrong? It seems to be part of the " +"evolution of how things are done." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:139 +msgid "" +"We expect mentees to be prepared for constructive criticism from the " +"community. There's still a lot of \"lore\" that is not written down. " +"Responding well to constructive criticism is what we hope we are selecting " +"for by first reviewing their existing contributions on IRC and mailing lists." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/port-mentor-guidelines/_index.adoc:141 +msgid "" +"We warn mentees that some of the criticism they receive may be less " +"\"constructive\" than others, (whether through language communication " +"problems, or excessive nit-picking), and that dealing with this gracefully " +"is just part of being in a large community. In case of specific problems " +"with specific people, or any questions, we hope that they will approach a " +"portmgr member on IRC or by email." +msgstr "" diff --git a/documentation/content/en/articles/pr-guidelines/_index.adoc b/documentation/content/en/articles/pr-guidelines/_index.adoc index 0f5fbab15d..d645d4637b 100644 --- a/documentation/content/en/articles/pr-guidelines/_index.adoc +++ b/documentation/content/en/articles/pr-guidelines/_index.adoc @@ -121,11 +121,11 @@ The "patched" state is directly related to feedback, so you may go directly to " While handling problem reports, either as a developer who has direct access to the Problem Reports database or as a contributor who browses the database and submits followups with patches, comments, suggestions or change requests, you will come across several different types of PRs. -* <<pr-unassigned>> -* <<pr-assigned>> -* <<pr-dups>> -* <<pr-stale>> -* <<pr-misfiled-notpr>> +* crossref:pr-guidelines[pr-unassigned, Unassigned PRs] +* crossref:pr-guidelines[pr-assigned, Assigned PRs] +* crossref:pr-guidelines[pr-dups, Duplicate PRs] +* crossref:pr-guidelines[pr-stale, Stale PRs] +* crossref:pr-guidelines[pr-misfiled-notpr, Non-Bug PRs] The following sections describe what each different type of PRs is used for, when a PR belongs to one of these types, and what treatment each different type receives. @@ -208,7 +208,7 @@ this will avoid duplicate emails sent to the mailing list. [NOTE] ==== -Since the list of individuals who have volunteered to be the default assignee for certain types of PRs changes so often, it is much more suitable for https://wiki.freebsd.org/AssigningPRs[the FreeBSD wiki]. +Since the list of individuals who have volunteered to be the default assignee for certain types of PRs changes so often, it is much more suitable for https://wiki.freebsd.org/AssigningPRs[the FreeBSD wiki]. ==== Here is a sample list of such entities; it is probably not complete. @@ -438,7 +438,7 @@ Here is a sample list of such entities; it is probably not complete. |mailing list |=== -Ports PRs which have a maintainer who is a ports committer may be reassigned by anyone (but note that not every FreeBSD committer is necessarily a ports committer, so you cannot simply go by the email address alone.) +Ports PRs which have a maintainer who is a ports committer may be reassigned by anyone (but note that not every FreeBSD committer is necessarily a ports committer, so you cannot simply go by the email address alone.) For other PRs, please do not reassign them to individuals (other than yourself) unless you are certain that the assignee really wants to track the PR. This will help to avoid the case where no one looks at fixing a particular problem because everyone assumes that the assignee is already working on it. @@ -500,7 +500,7 @@ This means that spammers found them. Whenever you close one of these PRs, please do the following: -* Set the component to `junk` (under `Supporting Services`. +* Set the component to `junk` (under `Supporting Services`). * Set Responsible to `nobody@FreeBSD.org`. * Set State to `Issue Resolved`. diff --git a/documentation/content/en/articles/pr-guidelines/_index.po b/documentation/content/en/articles/pr-guidelines/_index.po new file mode 100644 index 0000000000..fe807d4148 --- /dev/null +++ b/documentation/content/en/articles/pr-guidelines/_index.po @@ -0,0 +1,1439 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-12-29 08:30-0500\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/pr-guidelines/_index.adoc:1 +#, no-wrap +msgid "These guidelines describe recommended handling practices for FreeBSD Problem Reports (PRs)." +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/pr-guidelines/_index.adoc:1 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:11 +#, no-wrap +msgid "Problem Report Handling Guidelines" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:47 +msgid "" +"These guidelines describe recommended handling practices for FreeBSD Problem " +"Reports (PRs). Whilst developed for the FreeBSD PR Database Maintenance " +"Team mailto:freebsd-bugbusters@FreeBSD.org[freebsd-bugbusters@FreeBSD.org], " +"these guidelines should be followed by anyone working with FreeBSD PRs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:49 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pr-guidelines/_index.adoc:53 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:57 +msgid "" +"Bugzilla is an issue management system used by the FreeBSD Project. As " +"accurate tracking of outstanding software defects is important to FreeBSD's " +"quality, the correct use of the software is essential to the forward " +"progress of the Project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:60 +msgid "" +"Access to Bugzilla is available to the entire FreeBSD community. In order " +"to maintain consistency within the database and provide a consistent user " +"experience, guidelines have been established covering common aspects of bug " +"management such as presenting followup, handling close requests, and so " +"forth." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pr-guidelines/_index.adoc:62 +#, no-wrap +msgid "Problem Report Life-cycle" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:65 +msgid "" +"The Reporter submits a bug report on the website. The bug is in the `Needs " +"Triage` state." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:66 +msgid "" +"Jane Random BugBuster confirms that the bug report has sufficient " +"information to be reproducible. If not, she goes back and forth with the " +"reporter to obtain the needed information. At this point the bug is set to " +"the `Open` state." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:67 +msgid "" +"Joe Random Committer takes interest in the PR and assigns it to himself, or " +"Jane Random BugBuster decides that Joe is best suited to handle it and " +"assigns it to him. The bug should be set to the `In Discussion` state." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:68 +msgid "" +"Joe has a brief exchange with the originator (making sure it all goes into " +"the audit trail) and determines the cause of the problem." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:69 +msgid "" +"Joe pulls an all-nighter and whips up a patch that he thinks fixes the " +"problem, and submits it in a follow-up, asking the originator to test it. He " +"then sets the PRs state to `Patch Ready`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:70 +msgid "" +"A couple of iterations later, both Joe and the originator are satisfied with " +"the patch, and Joe commits it to `-CURRENT` (or directly to `-STABLE` if the " +"problem does not exist in `-CURRENT`), making sure to reference the Problem " +"Report in his commit log (and credit the originator if they submitted all or " +"part of the patch) and, if appropriate, start an MFC countdown. The bug is " +"set to the `Needs MFC` state." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:71 +msgid "" +"If the patch does not need MFCing, Joe then closes the PR as `Issue " +"Resolved`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:76 +msgid "" +"Many PRs are submitted with very little information about the problem, and " +"some are either very complex to solve, or just scratch the surface of a " +"larger problem; in these cases, it is very important to obtain all the " +"necessary information needed to solve the problem. If the problem contained " +"within cannot be solved, or has occurred again, it is necessary to re-open " +"the PR." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pr-guidelines/_index.adoc:79 +#, no-wrap +msgid "Problem Report State" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:83 +msgid "" +"It is important to update the state of a PR when certain actions are taken. " +"The state should accurately reflect the current state of work on the PR." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/pr-guidelines/_index.adoc:84 +#, no-wrap +msgid "A small example on when to change PR state" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:89 +msgid "" +"When a PR has been worked on and the developer(s) responsible feel " +"comfortable about the fix, they will submit a followup to the PR and change " +"its state to \"feedback\". At this point, the originator should evaluate " +"the fix in their context and respond indicating whether the defect has " +"indeed been remedied." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:92 +msgid "A Problem Report may be in one of the following states:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pr-guidelines/_index.adoc:93 +#, no-wrap +msgid "open" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:95 +msgid "Initial state; the problem has been pointed out and it needs reviewing." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pr-guidelines/_index.adoc:96 +#, no-wrap +msgid "analyzed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:98 +msgid "The problem has been reviewed and a solution is being sought." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pr-guidelines/_index.adoc:99 +#, no-wrap +msgid "feedback" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:101 +msgid "" +"Further work requires additional information from the originator or the " +"community; possibly information regarding the proposed solution." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pr-guidelines/_index.adoc:102 +#, no-wrap +msgid "patched" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:104 +msgid "" +"A patch has been committed, but something (MFC, or maybe confirmation from " +"originator) is still pending." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pr-guidelines/_index.adoc:105 +#, no-wrap +msgid "suspended" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:110 +msgid "" +"The problem is not being worked on, due to lack of information or " +"resources. This is a prime candidate for somebody who is looking for a " +"project to take on. If the problem cannot be solved at all, it will be " +"closed, rather than suspended. The documentation project uses suspended for " +"wish-list items that entail a significant amount of work which no one " +"currently has time for." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/pr-guidelines/_index.adoc:111 +#, no-wrap +msgid "closed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:113 +msgid "" +"A problem report is closed when any changes have been integrated, " +"documented, and tested, or when fixing the problem is abandoned." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:117 +msgid "" +"The \"patched\" state is directly related to feedback, so you may go " +"directly to \"closed\" state if the originator cannot test the patch, and it " +"works in your own testing." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pr-guidelines/_index.adoc:120 +#, no-wrap +msgid "Types of Problem Reports" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:123 +msgid "" +"While handling problem reports, either as a developer who has direct access " +"to the Problem Reports database or as a contributor who browses the database " +"and submits followups with patches, comments, suggestions or change " +"requests, you will come across several different types of PRs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:125 +msgid "crossref:pr-guidelines[pr-unassigned, Unassigned PRs]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:126 +msgid "crossref:pr-guidelines[pr-assigned, Assigned PRs]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:127 +msgid "crossref:pr-guidelines[pr-dups, Duplicate PRs]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:128 +msgid "crossref:pr-guidelines[pr-stale, Stale PRs]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:129 +msgid "crossref:pr-guidelines[pr-misfiled-notpr, Non-Bug PRs]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:131 +msgid "" +"The following sections describe what each different type of PRs is used for, " +"when a PR belongs to one of these types, and what treatment each different " +"type receives." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pr-guidelines/_index.adoc:133 +#, no-wrap +msgid "Unassigned PRs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:139 +msgid "" +"When PRs arrive, they are initially assigned to a generic (placeholder) " +"assignee. These are always prepended with `freebsd-`. The exact value for " +"this default depends on the category; in most cases, it corresponds to a " +"specific FreeBSD mailing list. Here is the current list, with the most " +"common ones listed first:" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/pr-guidelines/_index.adoc:141 +#, no-wrap +msgid "Default Assignees - most common" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:145 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:174 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:221 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:341 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:451 +#, no-wrap +msgid "Type" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:146 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:175 +#, no-wrap +msgid "Categories" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:148 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:177 +#, no-wrap +msgid "Default Assignee" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:149 +#, no-wrap +msgid "base system" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:150 +#, no-wrap +msgid "bin, conf, gnu, kern, misc" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:152 +#, no-wrap +msgid "freebsd-bugs" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:153 +#, no-wrap +msgid "architecture-specific" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:154 +#, no-wrap +msgid "alpha, amd64, arm, i386, ia64, powerpc, sparc64" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:156 +#, no-wrap +msgid "freebsd-_arch_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:157 +#, no-wrap +msgid "ports collection" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:158 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:347 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:352 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:357 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:362 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:367 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:372 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:377 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:382 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:387 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:392 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:397 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:402 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:407 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:412 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:417 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:422 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:427 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:432 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:437 +#, no-wrap +msgid "ports" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:160 +#, no-wrap +msgid "freebsd-ports-bugs" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:161 +#, no-wrap +msgid "documentation shipped with the system" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:162 +#, no-wrap +msgid "docs" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:164 +#, no-wrap +msgid "freebsd-doc" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:165 +#, no-wrap +msgid "FreeBSD web pages (not including docs)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:166 +#, no-wrap +msgid "Website" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:167 +#, no-wrap +msgid "freebsd-www" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/pr-guidelines/_index.adoc:170 +#, no-wrap +msgid "Default Assignees - other" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:178 +#, no-wrap +msgid "advocacy efforts" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:179 +#, no-wrap +msgid "advocacy" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:181 +#, no-wrap +msgid "freebsd-advocacy" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:182 +#, no-wrap +msgid "Java Virtual Machine(TM) problems" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:183 +#, no-wrap +msgid "java" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:185 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:393 +#, no-wrap +msgid "freebsd-java" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:186 +#, no-wrap +msgid "standards compliance" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:187 +#, no-wrap +msgid "standards" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:189 +#, no-wrap +msgid "freebsd-standards" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:190 +#, no-wrap +msgid "threading libraries" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:191 +#, no-wrap +msgid "threads" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:193 +#, no-wrap +msgid "freebsd-threads" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:194 +#, no-wrap +msgid "man:usb[4] subsystem" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:195 +#, no-wrap +msgid "usb" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:196 +#, no-wrap +msgid "freebsd-usb" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:202 +msgid "" +"Do not be surprised to find that the submitter of the PR has assigned it to " +"the wrong category. If you fix the category, do not forget to fix the " +"assignment as well. (In particular, our submitters seem to have a hard time " +"understanding that just because their problem manifested on an i386 system, " +"that it might be generic to all of FreeBSD, and thus be more appropriate for " +"`kern`. The converse is also true, of course.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:205 +msgid "" +"Certain PRs may be reassigned away from these generic assignees by anyone. " +"There are several types of assignees: specialized mailing lists; mail " +"aliases (used for certain limited-interest items); and individuals." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:208 +msgid "" +"For assignees which are mailing lists, please use the long form when making " +"the assignment (e.g., `freebsd-foo` instead of `foo`); this will avoid " +"duplicate emails sent to the mailing list." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:212 +msgid "" +"Since the list of individuals who have volunteered to be the default " +"assignee for certain types of PRs changes so often, it is much more suitable " +"for https://wiki.freebsd.org/AssigningPRs[the FreeBSD wiki]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:215 +msgid "Here is a sample list of such entities; it is probably not complete." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/pr-guidelines/_index.adoc:217 +#, no-wrap +msgid "Common Assignees - base system" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:222 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:342 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:452 +#, no-wrap +msgid "Suggested Category" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:223 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:343 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:453 +#, no-wrap +msgid "Suggested Assignee" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:225 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:345 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:455 +#, no-wrap +msgid "Assignee Type" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:226 +#, no-wrap +msgid "problem specific to the ARM(R) architecture" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:227 +#, no-wrap +msgid "arm" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:228 +#, no-wrap +msgid "freebsd-arm" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:230 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:235 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:240 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:245 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:250 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:255 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:260 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:265 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:270 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:275 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:280 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:285 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:290 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:295 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:300 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:305 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:310 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:315 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:320 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:325 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:330 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:334 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:355 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:370 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:375 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:380 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:395 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:400 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:405 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:410 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:415 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:420 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:425 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:439 +#, no-wrap +msgid "mailing list" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:231 +#, no-wrap +msgid "problem specific to the MIPS(R) architecture" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:232 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:237 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:242 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:247 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:252 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:257 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:262 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:267 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:272 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:277 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:282 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:287 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:292 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:297 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:302 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:307 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:312 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:322 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:327 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:332 +#, no-wrap +msgid "kern" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:233 +#, no-wrap +msgid "freebsd-mips" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:236 +#, no-wrap +msgid "problem specific to the PowerPC(R) architecture" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:238 +#, no-wrap +msgid "freebsd-ppc" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:241 +#, no-wrap +msgid "problem with Advanced Configuration and Power Management (man:acpi[4])" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:243 +#, no-wrap +msgid "freebsd-acpi" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:246 +#, no-wrap +msgid "problem with Asynchronous Transfer Mode (ATM) drivers" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:248 +#, no-wrap +msgid "freebsd-atm" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:251 +#, no-wrap +msgid "problem with embedded or small-footprint FreeBSD systems (e.g., NanoBSD/PicoBSD/FreeBSD-arm)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:253 +#, no-wrap +msgid "freebsd-embedded" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:256 +#, no-wrap +msgid "problem with FireWire(R) drivers" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:258 +#, no-wrap +msgid "freebsd-firewire" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:261 +#, no-wrap +msgid "problem with the filesystem code" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:263 +#, no-wrap +msgid "freebsd-fs" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:266 +#, no-wrap +msgid "problem with the man:geom[4] subsystem" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:268 +#, no-wrap +msgid "freebsd-geom" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:271 +#, no-wrap +msgid "problem with the man:ipfw[4] subsystem" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:273 +#, no-wrap +msgid "freebsd-ipfw" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:276 +#, no-wrap +msgid "problem with Integrated Services Digital Network (ISDN) drivers" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:278 +#, no-wrap +msgid "freebsd-isdn" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:281 +#, no-wrap +msgid "man:jail[8] subsystem" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:283 +#, no-wrap +msgid "freebsd-jail" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:286 +#, no-wrap +msgid "problem with Linux(R) or SVR4 emulation" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:288 +#, no-wrap +msgid "freebsd-emulation" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:291 +#, no-wrap +msgid "problem with the networking stack" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:293 +#, no-wrap +msgid "freebsd-net" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:296 +#, no-wrap +msgid "problem with the man:pf[4] subsystem" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:298 +#, no-wrap +msgid "freebsd-pf" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:301 +#, no-wrap +msgid "problem with the man:scsi[4] subsystem" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:303 +#, no-wrap +msgid "freebsd-scsi" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:306 +#, no-wrap +msgid "problem with the man:sound[4] subsystem" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:308 +#, no-wrap +msgid "freebsd-multimedia" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:311 +#, no-wrap +msgid "problems with the man:wlan[4] subsystem and wireless drivers" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:313 +#, no-wrap +msgid "freebsd-wireless" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:316 +#, no-wrap +msgid "problem with man:sysinstall[8] or man:bsdinstall[8]" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:317 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:457 +#, no-wrap +msgid "bin" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:318 +#, no-wrap +msgid "freebsd-sysinstall" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:321 +#, no-wrap +msgid "problem with the system startup scripts (man:rc[8])" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:323 +#, no-wrap +msgid "freebsd-rc" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:326 +#, no-wrap +msgid "problem with VIMAGE or VNET functionality and related code" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:328 +#, no-wrap +msgid "freebsd-virtualization" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:331 +#, no-wrap +msgid "problem with Xen emulation" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:333 +#, no-wrap +msgid "freebsd-xen" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/pr-guidelines/_index.adoc:337 +#, no-wrap +msgid "Common Assignees - Ports Collection" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:346 +#, no-wrap +msgid "problem with the ports framework (__not__ with an individual port!)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:348 +#, no-wrap +msgid "portmgr" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:350 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:360 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:365 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:385 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:390 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:430 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:435 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:460 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:464 +#, no-wrap +msgid "alias" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:351 +#, no-wrap +msgid "port which is maintained by apache@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:353 +#, no-wrap +msgid "apache" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:356 +#, no-wrap +msgid "port which is maintained by autotools@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:358 +#, no-wrap +msgid "autotools" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:361 +#, no-wrap +msgid "port which is maintained by doceng@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:363 +#, no-wrap +msgid "doceng" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:366 +#, no-wrap +msgid "port which is maintained by eclipse@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:368 +#, no-wrap +msgid "freebsd-eclipse" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:371 +#, no-wrap +msgid "port which is maintained by gecko@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:373 +#, no-wrap +msgid "gecko" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:376 +#, no-wrap +msgid "port which is maintained by gnome@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:378 +#, no-wrap +msgid "gnome" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:381 +#, no-wrap +msgid "port which is maintained by hamradio@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:383 +#, no-wrap +msgid "hamradio" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:386 +#, no-wrap +msgid "port which is maintained by haskell@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:388 +#, no-wrap +msgid "haskell" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:391 +#, no-wrap +msgid "port which is maintained by java@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:396 +#, no-wrap +msgid "port which is maintained by kde@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:398 +#, no-wrap +msgid "kde" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:401 +#, no-wrap +msgid "port which is maintained by mono@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:403 +#, no-wrap +msgid "mono" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:406 +#, no-wrap +msgid "port which is maintained by office@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:408 +#, no-wrap +msgid "freebsd-office" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:411 +#, no-wrap +msgid "port which is maintained by perl@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:413 +#, no-wrap +msgid "perl" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:416 +#, no-wrap +msgid "port which is maintained by python@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:418 +#, no-wrap +msgid "freebsd-python" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:421 +#, no-wrap +msgid "port which is maintained by ruby@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:423 +#, no-wrap +msgid "freebsd-ruby" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:426 +#, no-wrap +msgid "port which is maintained by secteam@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:428 +#, no-wrap +msgid "secteam" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:431 +#, no-wrap +msgid "port which is maintained by vbox@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:433 +#, no-wrap +msgid "vbox" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:436 +#, no-wrap +msgid "port which is maintained by x11@FreeBSD.org" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:438 +#, no-wrap +msgid "freebsd-x11" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:442 +msgid "" +"Ports PRs which have a maintainer who is a ports committer may be reassigned " +"by anyone (but note that not every FreeBSD committer is necessarily a ports " +"committer, so you cannot simply go by the email address alone.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:445 +msgid "" +"For other PRs, please do not reassign them to individuals (other than " +"yourself) unless you are certain that the assignee really wants to track the " +"PR. This will help to avoid the case where no one looks at fixing a " +"particular problem because everyone assumes that the assignee is already " +"working on it." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/pr-guidelines/_index.adoc:447 +#, no-wrap +msgid "Common Assignees - Other" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:456 +#, no-wrap +msgid "problem with PR database" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:458 +#: documentation/content/en/articles/pr-guidelines/_index.adoc:463 +#, no-wrap +msgid "bugmeister" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:461 +#, no-wrap +msgid "problem with Bugzilla https://bugs.freebsd.org/submit/[web form]." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/pr-guidelines/_index.adoc:462 +#, no-wrap +msgid "doc" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pr-guidelines/_index.adoc:467 +#, no-wrap +msgid "Assigned PRs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:470 +msgid "" +"If a PR has the `responsible` field set to the username of a FreeBSD " +"developer, it means that the PR has been handed over to that particular " +"person for further work." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:475 +msgid "" +"Assigned PRs should not be touched by anyone but the assignee or " +"bugmeister. If you have comments, submit a followup. If for some reason " +"you think the PR should change state or be reassigned, send a message to the " +"assignee. If the assignee does not respond within two weeks, unassign the " +"PR and do as you please." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pr-guidelines/_index.adoc:477 +#, no-wrap +msgid "Duplicate PRs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:481 +msgid "" +"If you find more than one PR that describe the same issue, choose the one " +"that contains the largest amount of useful information and close the others, " +"stating clearly the number of the superseding PR. If several PRs contain " +"non-overlapping useful information, submit all the missing information to " +"one in a followup, including references to the others; then close the other " +"PRs (which are now completely superseded)." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pr-guidelines/_index.adoc:483 +#, no-wrap +msgid "Stale PRs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:486 +msgid "" +"A PR is considered stale if it has not been modified in more than six " +"months. Apply the following procedure to deal with stale PRs:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:488 +msgid "" +"If the PR contains sufficient detail, try to reproduce the problem in `-" +"CURRENT` and `-STABLE`. If you succeed, submit a followup detailing your " +"findings and try to find someone to assign it to. Set the state to " +"\"analyzed\" if appropriate." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:489 +msgid "" +"If the PR describes an issue which you know is the result of a usage error " +"(incorrect configuration or otherwise), submit a followup explaining what " +"the originator did wrong, then close the PR with the reason \"User error\" " +"or \"Configuration error\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:490 +msgid "" +"If the PR describes an error which you know has been corrected in both `-" +"CURRENT` and `-STABLE`, close it with a message stating when it was fixed in " +"each branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:491 +msgid "" +"If the PR describes an error which you know has been corrected in `-" +"CURRENT`, but not in `-STABLE`, try to find out when the person who " +"corrected it is planning to MFC it, or try to find someone else (maybe " +"yourself?) to do it. Set the state to \"patched\" and assign it to whomever " +"will do the MFC." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:492 +msgid "" +"In other cases, ask the originator to confirm if the problem still exists in " +"newer versions. If the originator does not reply within a month, close the " +"PR with the notation \"Feedback timeout\"." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pr-guidelines/_index.adoc:494 +#, no-wrap +msgid "Non-Bug PRs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:497 +msgid "" +"Developers that come across PRs that look like they should have been posted " +"to {freebsd-bugs} or some other list should close the PR, informing the " +"submitter in a comment why this is not really a PR and where the message " +"should be posted." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:500 +msgid "" +"The email addresses that Bugzilla listens to for incoming PRs have been " +"published as part of the FreeBSD documentation, have been announced and " +"listed on the web-site. This means that spammers found them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:502 +msgid "Whenever you close one of these PRs, please do the following:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:504 +msgid "Set the component to `junk` (under `Supporting Services`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:505 +msgid "Set Responsible to `nobody@FreeBSD.org`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:506 +msgid "Set State to `Issue Resolved`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:508 +msgid "" +"Setting the category to `junk` makes it obvious that there is no useful " +"content within the PR, and helps to reduce the clutter within the main " +"categories." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/pr-guidelines/_index.adoc:510 +#, no-wrap +msgid "Further Reading" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:514 +msgid "" +"This is a list of resources relevant to the proper writing and processing of " +"problem reports. It is by no means complete." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/pr-guidelines/_index.adoc:515 +msgid "" +"extref:{problem-reports}[How to Write FreeBSD Problem Reports]-guidelines " +"for PR originators." +msgstr "" diff --git a/documentation/content/en/articles/problem-reports/_index.adoc b/documentation/content/en/articles/problem-reports/_index.adoc index 24b63bb08a..f201711526 100644 --- a/documentation/content/en/articles/problem-reports/_index.adoc +++ b/documentation/content/en/articles/problem-reports/_index.adoc @@ -68,7 +68,7 @@ Read the entire document before submitting a problem report, rather than treatin There are many types of problems, and not all of them should engender a problem report. Of course, nobody is perfect, and there will be times when what seems to be a bug in a program is, in fact, a misunderstanding of the syntax for a command or a typographical error in a configuration file (though that in itself may sometimes be indicative of poor documentation or poor error handling in the application). There are still many cases where submitting a problem report is clearly _not_ the right course of action, and will only serve to frustrate both the submitter and the developers. -Conversely, there are cases where it might be appropriate to submit a problem report about something else than a bug-an enhancement or a new feature, for instance. +Conversely, there are cases where it might be appropriate to submit a problem report about something else than a bug—an enhancement or a new feature, for instance. So how does one determine what is a bug and what is not? As a simple rule of thumb, the problem is _not_ a bug if it can be expressed as a question (usually of the form "How do I do X?" or "Where can I find Y?"). It is not always quite so black and white, but the question rule covers a large majority of cases. @@ -78,12 +78,12 @@ Consider these factors when submitting PRs about ports or other software that is * Please do not submit problem reports that simply state that a newer version of an application is available. Ports maintainers are automatically notified by portscout when a new version of an application becomes available. Actual patches to update a port to the latest version are welcome. * For unmaintained ports (`MAINTAINER` is `ports@FreeBSD.org`), a PR without an included patch is unlikely to get picked up by a committer. To become the maintainer of an unmaintained port, submit a PR with the request (patch preferred but not required). -* In either case, following the process described in extref:{porters-handbook}[Porter's Handbook, port-upgrading] will yield the best results. (You might also wish to read extref:{contributing}[Contributing to the FreeBSD Ports Collection, ports-contributing].) +* In either case, following the process described in extref:{porters-handbook}upgrading/[Porter's Handbook] will yield the best results. (You might also wish to read extref:{contributing}[Contributing to the FreeBSD Ports Collection, ports-contributing].) A bug that cannot be reproduced can rarely be fixed. If the bug only occurred once and you cannot reproduce it, and it does not seem to happen to anybody else, chances are none of the developers will be able to reproduce it or figure out what is wrong. That does not mean it did not happen, but it does mean that the chances of your problem report ever leading to a bug fix are very slim. -To make matters worse, often these kinds of bugs are actually caused by failing hard drives or overheating processors - you should always try to rule out these causes, whenever possible, before submitting a PR. +To make matters worse, often these kinds of bugs are actually caused by failing hard drives or overheating processors—you should always try to rule out these causes, whenever possible, before submitting a PR. Next, to decide to whom you should file your problem report, you need to understand that the software that makes up FreeBSD is composed of several different elements: @@ -94,7 +94,7 @@ Next, to decide to whom you should file your problem report, you need to underst Then, ascertain whether the problem is timely. There are few things that will annoy a developer more than receiving a problem report about a bug she has already fixed. -If the problem is in the base system, first read the FAQ section on extref:{faq}[FreeBSD versions, LATEST-VERSION], if you are not already familiar with the topic. +If the problem is in the base system, first read the FAQ section on extref:{faq}[FreeBSD versions, latest-version], if you are not already familiar with the topic. It is not possible for FreeBSD to fix problems in anything other than certain recent branches of the base system, so filing a bug report about an older version will probably only result in a developer advising you to upgrade to a supported version to see if the problem still recurs. The Security Officer team maintains the link:https://www.FreeBSD.org/security/[list of supported versions]. @@ -110,13 +110,13 @@ You should therefore check all the obvious places before submitting your problem For FreeBSD, this means: * The FreeBSD extref:{faq}[Frequently Asked Questions] (FAQ) list. The FAQ attempts to provide answers for a wide range of questions, such as those concerning extref:{faq}[hardware compatibility, hardware], extref:{faq}[user applications, applications], and extref:{faq}[kernel configuration, kernelconfig]. -* The extref:{handbook}[mailing lists, eresources-mail]-if you are not subscribed, use https://www.FreeBSD.org/search/#mailinglists[the searchable archives] on the FreeBSD web site. If the problem has not been discussed on the lists, you might try posting a message about it and waiting a few days to see if someone can spot something that has been overlooked. +* The extref:{handbook}eresources/[mailing lists, eresources-mail]. If you are not subscribed, use https://www.FreeBSD.org/search/#mailinglists[the searchable archives] on the FreeBSD web site. If the problem has not been discussed on the lists, you might try posting a message about it and waiting a few days to see if someone can spot something that has been overlooked. * 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). +(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. @@ -132,7 +132,9 @@ Before we get into the mechanics of the program used to generate and submit PRs, * _Do not leave the "Summary" line empty._ The PRs go both onto a mailing list that goes all over the world (where the "Summary" is used for the `Subject:` line), but also into a database. Anyone who comes along later and browses the database by synopsis, and finds a PR with a blank subject line, tends just to skip over it. Remember that PRs stay in this database until they are closed by someone; an anonymous one will usually just disappear in the noise. * _Avoid using a weak "Summary" line._ You should not assume that anyone reading your PR has any context for your submission, so the more you provide, the better. For instance, what part of the system does the problem apply to? Do you only see the problem while installing, or while running? To illustrate, instead of `Summary: portupgrade is broken`, see how much more informative this seems: `Summary: port ports-mgmt/portupgrade coredumps on -current`. (In the case of ports, it is especially helpful to have both the category and portname in the "Summary" line.) -* _If you have a patch, say so._ A PR with a patch included is much more likely to be looked at than one without. Please set the `patch` Keyword in Bugzilla. +* _If you have a patch, say so._ +The presence of a patch makes it much easier to progress a report. +** Do not use the `patch` or `patch-ready` keywords – they are deprecated. * _If you are a maintainer, say so._ If you are maintaining a part of the source code (for instance, an existing port), you definitely should set the "Class" of your PR to `maintainer-update`. This way any committer that handles your PR will not have to check. * _Be specific._ The more information you supply about what problem you are having, the better your chance of getting a response. @@ -186,7 +188,7 @@ If you attach a patch inline, instead of as an attachment, note that the most co Do not send patches as attachments using `Content-Transfer-Encoding: quoted-printable`. These will perform character escaping and the entire patch will be useless. -Also note that while including small patches in a PR is generally all right-particularly when they fix the problem described in the PR-large patches and especially new code which may require substantial review before committing should be placed on a web or ftp server, and the URL should be included in the PR instead of the patch. +Also note that while including small patches in a PR is generally all right—particularly when they fix the problem described in the PR-large patches and especially new code which may require substantial review before committing should be placed on a web or ftp server, and the URL should be included in the PR instead of the patch. Patches in email tend to get mangled, and the larger the patch, the harder it will be for interested parties to unmangle it. Also, posting a patch on the web allows you to modify it without having to resubmit the entire patch in a followup to the original PR. Finally, large patches simply increase the size of the database, since closed PRs are not actually deleted but instead kept and simply marked as complete. @@ -250,8 +252,8 @@ You have a common PC-based machine, and think you have encountered a problem spe You are having a problem with an add-in peripheral card on a commonly seen bus, or a problem with a particular type of hard disk drive: in this case, it probably applies to more than one architecture, and `kern` is the right category. ==== ** If you really do not know where the problem lies (or the explanation does not seem to fit into the ones above), use the `misc` category. Before you do so, you may wish to ask for help on the {freebsd-questions} first. You may be advised that one of the existing categories really is a better choice. -* _Environment:_ This should describe, as accurately as possible, the environment in which the problem has been observed. This includes the operating system version, the version of the specific program or file that contains the problem, and any other relevant items such as system configuration, other installed software that influences the problem, etc.-quite simply everything a developer needs to know to reconstruct the environment in which the problem occurs. -* __Description:__A complete and accurate description of the problem you are experiencing. Try to avoid speculating about the causes of the problem unless you are certain that you are on the right track, as it may mislead a developer into making incorrect assumptions about the problem. It should include the actions you need to take to reproduce the problem. If you know any workaround, include it. It not only helps other people with the same problem work around it, but may also help a developer understand the cause for the problem. +* _Environment:_ This should describe, as accurately as possible, the environment in which the problem has been observed. This includes the operating system version, the version of the specific program or file that contains the problem, and any other relevant items such as system configuration, other installed software that influences the problem, etc.—quite simply everything a developer needs to know to reconstruct the environment in which the problem occurs. +* _Description:_ A complete and accurate description of the problem you are experiencing. Try to avoid speculating about the causes of the problem unless you are certain that you are on the right track, as it may mislead a developer into making incorrect assumptions about the problem. It should include the actions you need to take to reproduce the problem. If you know any workaround, include it. It not only helps other people with the same problem work around it, but may also help a developer understand the cause for the problem. [[pr-followup]] == Follow-up @@ -273,7 +275,7 @@ When a problem report has not received attention after several weeks, it is wort There are a few ways to do so, ideally in the following order, with a few days between attempting each communication channel: * Send an e-mail to extref:{handbook}eresources/[the relevant list, eresources-summary] seeking comments on the report. -* Join the relevant IRC channels. A partial listing is here: https://wiki.freebsd.org/IrcChannels[]. Inform the people in that channel about the problem report and ask for assistance. Be patient and stay in the channel after posting, so that the people from different time zones around the world have a chance to catch up. +* Join the relevant IRC channels. A partial listing is here: https://wiki.freebsd.org/IRC/Channels[]. Inform the people in that channel about the problem report and ask for assistance. Be patient and stay in the channel after posting, so that the people from different time zones around the world have a chance to catch up. * Find committers interested in the problem that was reported. If the problem was in a particular tool, binary, port, document, or source file, check the https://cgit.FreeBSD.org[Git Repository]. Locate the last few committers who made substantive changes to the file, and try to reach them via IRC or email. A list of committers and their emails can be found in the extref:{contributors}[Contributors to FreeBSD] article. Remember that these people are volunteers, just like maintainers and users, so they might not be immediately available to assist with the problem report. @@ -292,5 +294,5 @@ If you are unable to do so, contact the bug wranglers at mailto:bugmeister@Free This is a list of resources relevant to the proper writing and processing of problem reports. It is by no means complete. -* https://github.com/smileytechguy/reporting-bugs-effectively/blob/master/ENGLISH.md[How to Report Bugs Effectively]-an excellent essay by Simon G. Tatham on composing useful (non-FreeBSD-specific) problem reports. -* extref:{pr-guidelines}[Problem Report Handling Guidelines]-valuable insight into how problem reports are handled by the FreeBSD developers. +* https://github.com/smileytechguy/reporting-bugs-effectively/blob/master/ENGLISH.md[How to Report Bugs Effectively]: An excellent essay by Simon G. Tatham on composing useful (non-FreeBSD-specific) problem reports. +* extref:{pr-guidelines}[Problem Report Handling Guidelines]: Valuable insight into how problem reports are handled by the FreeBSD developers. diff --git a/documentation/content/en/articles/problem-reports/_index.po b/documentation/content/en/articles/problem-reports/_index.po new file mode 100644 index 0000000000..ccfa3691f2 --- /dev/null +++ b/documentation/content/en/articles/problem-reports/_index.po @@ -0,0 +1,1000 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2023-09-09 18:13-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/problem-reports/_index.adoc:1 +#, no-wrap +msgid "How to best formulate and submit a problem report to the FreeBSD Project" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/problem-reports/_index.adoc:1 +#: documentation/content/en/articles/problem-reports/_index.adoc:11 +#, no-wrap +msgid "Writing FreeBSD Problem Reports" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:46 +msgid "" +"This article describes how to best formulate and submit a problem report to " +"the FreeBSD Project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:48 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/problem-reports/_index.adoc:52 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:56 +msgid "" +"One of the most frustrating experiences one can have as a software user is " +"to submit a problem report only to have it summarily closed with a terse and " +"unhelpful explanation like \"not a bug\" or \"bogus PR\". Similarly, one of " +"the most frustrating experiences as a software developer is to be flooded " +"with problem reports that are not really problem reports but requests for " +"support, or that contain little or no information about what the problem is " +"and how to reproduce it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:59 +msgid "" +"This document attempts to describe how to write good problem reports. What, " +"one asks, is a good problem report? Well, to go straight to the bottom line, " +"a good problem report is one that can be analyzed and dealt with swiftly, to " +"the mutual satisfaction of both user and developer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:61 +msgid "" +"Although the primary focus of this article is on FreeBSD problem reports, " +"most of it should apply quite well to other software projects." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:64 +msgid "" +"Note that this article is organized thematically, not chronologically. Read " +"the entire document before submitting a problem report, rather than treating " +"it as a step-by-step tutorial." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/problem-reports/_index.adoc:66 +#, no-wrap +msgid "When to Submit a Problem Report" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:72 +msgid "" +"There are many types of problems, and not all of them should engender a " +"problem report. Of course, nobody is perfect, and there will be times when " +"what seems to be a bug in a program is, in fact, a misunderstanding of the " +"syntax for a command or a typographical error in a configuration file " +"(though that in itself may sometimes be indicative of poor documentation or " +"poor error handling in the application). There are still many cases where " +"submitting a problem report is clearly _not_ the right course of action, and " +"will only serve to frustrate both the submitter and the developers. " +"Conversely, there are cases where it might be appropriate to submit a " +"problem report about something else than a bug—an enhancement or a new " +"feature, for instance." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:76 +msgid "" +"So how does one determine what is a bug and what is not? As a simple rule of " +"thumb, the problem is _not_ a bug if it can be expressed as a question " +"(usually of the form \"How do I do X?\" or \"Where can I find Y?\"). It is " +"not always quite so black and white, but the question rule covers a large " +"majority of cases. When looking for an answer, consider posing the question " +"to the {freebsd-questions}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:78 +msgid "" +"Consider these factors when submitting PRs about ports or other software " +"that is not part of FreeBSD itself:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:80 +msgid "" +"Please do not submit problem reports that simply state that a newer version " +"of an application is available. Ports maintainers are automatically notified " +"by portscout when a new version of an application becomes available. Actual " +"patches to update a port to the latest version are welcome." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:81 +msgid "" +"For unmaintained ports (`MAINTAINER` is `ports@FreeBSD.org`), a PR without " +"an included patch is unlikely to get picked up by a committer. To become the " +"maintainer of an unmaintained port, submit a PR with the request (patch " +"preferred but not required)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:82 +msgid "" +"In either case, following the process described in extref:{porters-handbook}" +"upgrading/[Porter's Handbook] will yield the best results. (You might also " +"wish to read extref:{contributing}[Contributing to the FreeBSD Ports " +"Collection, ports-contributing].)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:87 +msgid "" +"A bug that cannot be reproduced can rarely be fixed. If the bug only " +"occurred once and you cannot reproduce it, and it does not seem to happen to " +"anybody else, chances are none of the developers will be able to reproduce " +"it or figure out what is wrong. That does not mean it did not happen, but " +"it does mean that the chances of your problem report ever leading to a bug " +"fix are very slim. To make matters worse, often these kinds of bugs are " +"actually caused by failing hard drives or overheating processors—you should " +"always try to rule out these causes, whenever possible, before submitting a " +"PR." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:89 +msgid "" +"Next, to decide to whom you should file your problem report, you need to " +"understand that the software that makes up FreeBSD is composed of several " +"different elements:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:91 +msgid "" +"Code in the base system that is written and maintained by FreeBSD " +"contributors, such as the kernel, the C library, and the device drivers " +"(categorized as `kern`); the binary utilities (`bin`); the manual pages and " +"documentation (`docs`); and the web pages (`www`). All bugs in these areas " +"should be reported to the FreeBSD developers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:92 +msgid "" +"Code in the base system that is written and maintained by others, and " +"imported into FreeBSD and adapted. Examples include man:clang[1], and man:" +"sendmail[8]. Most bugs in these areas should be reported to the FreeBSD " +"developers; but in some cases they may need to be reported to the original " +"authors instead if the problems are not FreeBSD-specific." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:93 +msgid "" +"Individual applications that are not in the base system but are instead part " +"of the FreeBSD Ports Collection (category `ports`). Most of these " +"applications are not written by FreeBSD developers; what FreeBSD provides is " +"merely a framework for installing the application. Therefore, only report a " +"problem to the FreeBSD developers when the problem is believed to be FreeBSD-" +"specific; otherwise, report it to the authors of the software." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:96 +msgid "" +"Then, ascertain whether the problem is timely. There are few things that " +"will annoy a developer more than receiving a problem report about a bug she " +"has already fixed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:100 +msgid "" +"If the problem is in the base system, first read the FAQ section on extref:" +"{faq}[FreeBSD versions, latest-version], if you are not already familiar " +"with the topic. It is not possible for FreeBSD to fix problems in anything " +"other than certain recent branches of the base system, so filing a bug " +"report about an older version will probably only result in a developer " +"advising you to upgrade to a supported version to see if the problem still " +"recurs. The Security Officer team maintains the link:https://www.FreeBSD." +"org/security/[list of supported versions]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:103 +msgid "" +"If the problem is in a port, consider filing a bug with the upstream. The " +"FreeBSD Project can not fix all bugs in all software." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/problem-reports/_index.adoc:105 +#, no-wrap +msgid "Preparations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:111 +msgid "" +"A good rule to follow is to always do a background search before submitting " +"a problem report. Maybe the problem has already been reported; maybe it is " +"being discussed on the mailing lists, or recently was; it may even already " +"be fixed in a newer version than what you are running. You should therefore " +"check all the obvious places before submitting your problem report. For " +"FreeBSD, this means:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:113 +msgid "" +"The FreeBSD extref:{faq}[Frequently Asked Questions] (FAQ) list. The FAQ " +"attempts to provide answers for a wide range of questions, such as those " +"concerning extref:{faq}[hardware compatibility, hardware], extref:{faq}[user " +"applications, applications], and extref:{faq}[kernel configuration, " +"kernelconfig]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:114 +msgid "" +"The extref:{handbook}eresources/[mailing lists, eresources-mail]. If you are " +"not subscribed, use https://www.FreeBSD.org/search/#mailinglists[the " +"searchable archives] on the FreeBSD web site. If the problem has not been " +"discussed on the lists, you might try posting a message about it and waiting " +"a few days to see if someone can spot something that has been overlooked." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:115 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:116 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:117 +msgid "" +"Most importantly, attempt to see if existing documentation in the source " +"base addresses your problem." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:120 +msgid "" +"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)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:123 +msgid "" +"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." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/problem-reports/_index.adoc:125 +#, no-wrap +msgid "Writing the Problem Report" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:129 +msgid "" +"Now that you have decided that your issue merits a problem report, and that " +"it is a FreeBSD problem, it is time to write the actual problem report. " +"Before we get into the mechanics of the program used to generate and submit " +"PRs, here are some tips and tricks to help make sure that your PR will be " +"most effective." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/problem-reports/_index.adoc:131 +#, no-wrap +msgid "Tips and Tricks for Writing a Good Problem Report" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:134 +msgid "" +"_Do not leave the \"Summary\" line empty._ The PRs go both onto a mailing " +"list that goes all over the world (where the \"Summary\" is used for the " +"`Subject:` line), but also into a database. Anyone who comes along later and " +"browses the database by synopsis, and finds a PR with a blank subject line, " +"tends just to skip over it. Remember that PRs stay in this database until " +"they are closed by someone; an anonymous one will usually just disappear in " +"the noise." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:135 +msgid "" +"_Avoid using a weak \"Summary\" line._ You should not assume that anyone " +"reading your PR has any context for your submission, so the more you " +"provide, the better. For instance, what part of the system does the problem " +"apply to? Do you only see the problem while installing, or while running? To " +"illustrate, instead of `Summary: portupgrade is broken`, see how much more " +"informative this seems: `Summary: port ports-mgmt/portupgrade coredumps on -" +"current`. (In the case of ports, it is especially helpful to have both the " +"category and portname in the \"Summary\" line.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:137 +msgid "" +"_If you have a patch, say so._ The presence of a patch makes it much easier " +"to progress a report." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:138 +msgid "Do not use the `patch` or `patch-ready` keywords – they are deprecated." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:139 +msgid "" +"_If you are a maintainer, say so._ If you are maintaining a part of the " +"source code (for instance, an existing port), you definitely should set the " +"\"Class\" of your PR to `maintainer-update`. This way any committer that " +"handles your PR will not have to check." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:140 +msgid "" +"_Be specific._ The more information you supply about what problem you are " +"having, the better your chance of getting a response." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:142 +msgid "" +"Include the version of FreeBSD you are running (there is a place to put " +"that, see below) and on which architecture. You should include whether you " +"are running from a release (e.g., from a CD-ROM or download), or from a " +"system maintained by Git (and, if so, what hash and branch you are at). If " +"you are tracking the FreeBSD-CURRENT branch, that is the very first thing " +"someone will ask, because fixes (especially for high-profile problems) tend " +"to get committed very quickly, and FreeBSD-CURRENT users are expected to " +"keep up." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:143 +msgid "" +"Include which global options you have specified in your [.filename]#make." +"conf#, [.filename]#src.conf#, and [.filename]#src-env.conf#. Given the " +"infinite number of options, not every combination may be fully supported." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:144 +msgid "" +"If the problem can be reproduced easily, include information that will help " +"a developer to reproduce it themselves. If a problem can be demonstrated " +"with specific input then include an example of that input if possible, and " +"include both the actual and the expected output. If this data is large or " +"cannot be made public, then do try to create a minimal file that exhibits " +"the same issue and that can be included within the PR." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:145 +msgid "" +"If this is a kernel problem, then be prepared to supply the following " +"information. (You do not have to include these by default, which only tends " +"to fill up the database, but you should include excerpts that you think " +"might be relevant):" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:147 +msgid "" +"your kernel configuration (including which hardware devices you have " +"installed)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:148 +msgid "" +"whether or not you have debugging options enabled (such as `WITNESS`), and " +"if so, whether the problem persists when you change the sense of that option" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:149 +msgid "" +"the full text of any backtrace, panic or other console output, or entries in " +"[.filename]#/var/log/messages#, if any were generated" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:150 +msgid "" +"the output of `pciconf -l` and relevant parts of your `dmesg` output if your " +"problem relates to a specific piece of hardware" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:151 +msgid "" +"the fact that you have read [.filename]#src/UPDATING# and that your problem " +"is not listed there (someone is guaranteed to ask)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:152 +msgid "" +"whether or not you can run any other kernel as a fallback (this is to rule " +"out hardware-related issues such as failing disks and overheating CPUs, " +"which can masquerade as kernel problems)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:154 +msgid "" +"If this is a ports problem, then be prepared to supply the following " +"information. (You do not have to include these by default, which only tends " +"to fill up the database, but you should include excerpts that you think " +"might be relevant):" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:156 +msgid "which ports you have installed" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:157 +msgid "" +"any environment variables that override the defaults in [.filename]#bsd.port." +"mk#, such as `PORTSDIR`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:158 +msgid "" +"the fact that you have read [.filename]#ports/UPDATING# and that your " +"problem is not listed there (someone is guaranteed to ask)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:160 +msgid "" +"_Avoid vague requests for features._ PRs of the form \"someone should really " +"implement something that does so-and-so\" are less likely to get results " +"than very specific requests. Remember, the source is available to everyone, " +"so if you want a feature, the best way to ensure it being included is to get " +"to work! Also consider the fact that many things like this would make a " +"better topic for discussion on `freebsd-questions` than an entry in the PR " +"database, as discussed above." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:161 +msgid "" +"_Make sure no one else has already submitted a similar PR._ Although this " +"has already been mentioned above, it bears repeating here. It only take a " +"minute or two to use the web-based search engine at https://bugs.freebsd.org/" +"bugzilla/query.cgi[https://bugs.freebsd.org/bugzilla/query.cgi]. (Of course, " +"everyone is guilty of forgetting to do this now and then.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:162 +msgid "" +"_Report only one issue per Problem Report._ Avoid including two or more " +"problems within the same report unless they are related. When submitting " +"patches, avoid adding multiple features or fixing multiple bugs in the same " +"PR unless they are closely related-such PRs often take longer to resolve." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:163 +msgid "" +"_Avoid controversial requests._ If your PR addresses an area that has been " +"controversial in the past, you should probably be prepared to not only offer " +"patches, but also justification for why the patches are \"The Right Thing To " +"Do\". As noted above, a careful search of the mailing lists using the " +"archives at https://www.FreeBSD.org/search/#mailinglists[https://www.FreeBSD." +"org/search/#mailinglists] is always good preparation." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:164 +msgid "" +"_Be polite._ Almost anyone who would potentially work on your PR is a " +"volunteer. No one likes to be told that they have to do something when they " +"are already doing it for some motivation other than monetary gain. This is a " +"good thing to keep in mind at all times on Open Source projects." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/problem-reports/_index.adoc:166 +#, no-wrap +msgid "Before Beginning" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:170 +msgid "" +"Similar considerations apply to use of the https://bugs.freebsd.org/bugzilla/" +"enter_bug.cgi[web-based PR submission form]. Be careful of cut-and-paste " +"operations that might change whitespace or other text formatting." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:172 +msgid "" +"Finally, if the submission is lengthy, prepare the work offline so that " +"nothing will be lost if there is a problem submitting it." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/problem-reports/_index.adoc:174 +#, no-wrap +msgid "Attaching Patches or Files" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:182 +msgid "" +"In general, we recommend using `git format-patch` to generate one or a " +"series of unified diff against the base branch (e.g. `origin/main`). " +"Patches generated this way would include the Git hashes and will include " +"your name and email address, making it easier for committers to apply your " +"patch and properly credit you as the author (using `git am`). For minor " +"changes where you prefer not to use git, please be sure to use man:diff[1] " +"with the `-u` option to create a unified diff, as this would give developers " +"more context and are more readable than other diff formats." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:185 +msgid "" +"For problems with the kernel or the base utilities, a patch against FreeBSD-" +"CURRENT (the main Git branch) is preferred since all new code should be " +"applied and tested there first. After appropriate or substantial testing " +"has been done, the code will be merged/migrated to the FreeBSD-STABLE branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:187 +msgid "" +"If you attach a patch inline, instead of as an attachment, note that the " +"most common problem by far is the tendency of some email programs to render " +"tabs as spaces, which will completely ruin anything intended to be part of a " +"Makefile." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:190 +msgid "" +"Do not send patches as attachments using `Content-Transfer-Encoding: quoted-" +"printable`. These will perform character escaping and the entire patch will " +"be useless." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:195 +msgid "" +"Also note that while including small patches in a PR is generally all right—" +"particularly when they fix the problem described in the PR-large patches and " +"especially new code which may require substantial review before committing " +"should be placed on a web or ftp server, and the URL should be included in " +"the PR instead of the patch. Patches in email tend to get mangled, and the " +"larger the patch, the harder it will be for interested parties to unmangle " +"it. Also, posting a patch on the web allows you to modify it without having " +"to resubmit the entire patch in a followup to the original PR. Finally, " +"large patches simply increase the size of the database, since closed PRs are " +"not actually deleted but instead kept and simply marked as complete." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:197 +msgid "" +"You should also take note that unless you explicitly specify otherwise in " +"your PR or in the patch itself, any patches you submit will be assumed to be " +"licensed under the same terms as the original file you modified." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/problem-reports/_index.adoc:199 +#, no-wrap +msgid "Filling out the Form" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/problem-reports/_index.adoc:206 +msgid "" +"The email address you use will become public information and may become " +"available to spammers. You should either have spam handling procedures in " +"place, or use a temporary email account. However, please note that if you " +"do not use a valid email account at all, we will not be able to ask you " +"questions about your PR." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:209 +msgid "When you file a bug, you will find the following fields:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:211 +msgid "" +"_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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:212 +msgid "" +"_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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:213 +msgid "_Category:_ Choose an appropriate category." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:218 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:220 +msgid "Here is a description of the major categories:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:222 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:223 +msgid "" +"If a problem is with a binary program such as man:sh[1] or man:mount[8], you " +"will first need to determine whether these programs are in the base system " +"or were added via the Ports Collection. If you are unsure, you can do " +"`whereis _programname_`. FreeBSD's convention for the Ports Collection is to " +"install everything underneath [.filename]#/usr/local#, although this can be " +"overridden by a system administrator. For these, you will use the `ports` " +"category (yes, even if the port's category is `www`; see below). If the " +"location is [.filename]#/bin#, [.filename]#/usr/bin#, [.filename]#/sbin#, or " +"[.filename]#/usr/sbin#, it is part of the base system, and you should use " +"the `bin` category. These are all things that are described in section 1 or " +"8 of the manual pages." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:224 +msgid "" +"If you believe that the error is in the startup `(rc)` scripts, or in some " +"kind of other non-executable configuration file, then the right category is " +"`conf` (configuration). These are things that are described in section 5 of " +"the manual pages." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:225 +msgid "" +"If you have found a problem in the documentation set (articles, books, man " +"pages) or website the correct choice is `docs`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/problem-reports/_index.adoc:229 +msgid "" +"if you are having a problem with something from a port named `www/" +"_someportname_`, this nevertheless goes in the `ports` category." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:232 +msgid "There are a few more specialized categories." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:234 +msgid "" +"If the problem would otherwise be filed in `kern` but has to do with the USB " +"subsystem, the correct choice is `usb`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:235 +msgid "" +"If the problem would otherwise be filed in `kern` but has to do with the " +"threading libraries, the correct choice is `threads`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:236 +msgid "" +"If the problem would otherwise be in the base system, but has to do with our " +"adherence to standards such as POSIX(R), the correct choice is `standards`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:237 +msgid "" +"If you are convinced that the problem will only occur under the processor " +"architecture you are using, select one of the architecture-specific " +"categories: commonly `i386` for Intel-compatible machines in 32-bit mode; " +"`amd64` for AMD machines running in 64-bit mode (this also includes Intel-" +"compatible machines running in EMT64 mode); and less commonly `arm` or " +"`powerpc`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/problem-reports/_index.adoc:241 +msgid "" +"These categories are quite often misused for \"I do not know\" problems. " +"Rather than guessing, please just use `misc`." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/problem-reports/_index.adoc:243 +#, no-wrap +msgid "Correct Use of Arch-Specific Category" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/problem-reports/_index.adoc:247 +msgid "" +"You have a common PC-based machine, and think you have encountered a problem " +"specific to a particular chipset or a particular motherboard: `i386` is the " +"right category." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/problem-reports/_index.adoc:249 +#, no-wrap +msgid "Incorrect Use of Arch-Specific Category" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/problem-reports/_index.adoc:253 +msgid "" +"You are having a problem with an add-in peripheral card on a commonly seen " +"bus, or a problem with a particular type of hard disk drive: in this case, " +"it probably applies to more than one architecture, and `kern` is the right " +"category." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:255 +msgid "" +"If you really do not know where the problem lies (or the explanation does " +"not seem to fit into the ones above), use the `misc` category. Before you do " +"so, you may wish to ask for help on the {freebsd-questions} first. You may " +"be advised that one of the existing categories really is a better choice." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:256 +msgid "" +"_Environment:_ This should describe, as accurately as possible, the " +"environment in which the problem has been observed. This includes the " +"operating system version, the version of the specific program or file that " +"contains the problem, and any other relevant items such as system " +"configuration, other installed software that influences the problem, etc.—" +"quite simply everything a developer needs to know to reconstruct the " +"environment in which the problem occurs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:257 +msgid "" +"_Description:_ A complete and accurate description of the problem you are " +"experiencing. Try to avoid speculating about the causes of the problem " +"unless you are certain that you are on the right track, as it may mislead a " +"developer into making incorrect assumptions about the problem. It should " +"include the actions you need to take to reproduce the problem. If you know " +"any workaround, include it. It not only helps other people with the same " +"problem work around it, but may also help a developer understand the cause " +"for the problem." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/problem-reports/_index.adoc:259 +#, no-wrap +msgid "Follow-up" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:264 +msgid "" +"Once the problem report has been filed, you will receive a confirmation by " +"email which will include the tracking number that was assigned to your " +"problem report and a URL you can use to check its status. With a little " +"luck, someone will take an interest in your problem and try to address it, " +"or, as the case may be, explain why it is not a problem. You will be " +"automatically notified of any change of status, and you will receive copies " +"of any comments or patches someone may attach to your problem report's audit " +"trail." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:268 +msgid "" +"If someone requests additional information from you, or you remember or " +"discover something you did not mention in the initial report, please submit " +"a follow up. The number one reason for a bug not getting fixed is lack of " +"communication with the originator. The easiest way is to use the comment " +"option on the individual PR's web page, which you can reach from the https://" +"bugs.freebsd.org/bugzilla/query.cgi[PR search page]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:270 +msgid "" +"If the problem report remains open after the problem has gone away, just add " +"a comment saying that the problem report can be closed, and, if possible, " +"explaining how or when the problem was fixed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:274 +msgid "" +"Sometimes there is a delay of a week or two where the problem report remains " +"untouched, not assigned or commented on by anyone. This can happen when " +"there is an increased problem report backlog or during a holiday season. " +"When a problem report has not received attention after several weeks, it is " +"worth finding a committer particularly interested in working on it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:276 +msgid "" +"There are a few ways to do so, ideally in the following order, with a few " +"days between attempting each communication channel:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:278 +msgid "" +"Send an e-mail to extref:{handbook}eresources/[the relevant list, eresources-" +"summary] seeking comments on the report." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:279 +msgid "" +"Join the relevant IRC channels. A partial listing is here: https://wiki." +"freebsd.org/IRC/Channels[]. Inform the people in that channel about the " +"problem report and ask for assistance. Be patient and stay in the channel " +"after posting, so that the people from different time zones around the world " +"have a chance to catch up." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:280 +msgid "" +"Find committers interested in the problem that was reported. If the problem " +"was in a particular tool, binary, port, document, or source file, check the " +"https://cgit.FreeBSD.org[Git Repository]. Locate the last few committers who " +"made substantive changes to the file, and try to reach them via IRC or " +"email. A list of committers and their emails can be found in the extref:" +"{contributors}[Contributors to FreeBSD] article." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:284 +msgid "" +"Remember that these people are volunteers, just like maintainers and users, " +"so they might not be immediately available to assist with the problem " +"report. Patience and consistency in the follow-ups is highly advised and " +"appreciated. With enough care and effort dedicated to that follow-up " +"process, finding a committer to take care of the problem report is just a " +"matter of time." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/problem-reports/_index.adoc:286 +#, no-wrap +msgid "If There Are Problems" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:290 +msgid "" +"If you found an issue with the bug system, file a bug! There is a category " +"for exactly this purpose. If you are unable to do so, contact the bug " +"wranglers at mailto:bugmeister@FreeBSD.org[bugmeister@FreeBSD.org]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/problem-reports/_index.adoc:292 +#, no-wrap +msgid "Further Reading" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:296 +msgid "" +"This is a list of resources relevant to the proper writing and processing of " +"problem reports. It is by no means complete." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:298 +msgid "" +"https://github.com/smileytechguy/reporting-bugs-effectively/blob/master/" +"ENGLISH.md[How to Report Bugs Effectively]: An excellent essay by Simon G. " +"Tatham on composing useful (non-FreeBSD-specific) problem reports." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/problem-reports/_index.adoc:298 +msgid "" +"extref:{pr-guidelines}[Problem Report Handling Guidelines]: Valuable insight " +"into how problem reports are handled by the FreeBSD developers." +msgstr "" diff --git a/documentation/content/en/articles/rc-scripting/_index.adoc b/documentation/content/en/articles/rc-scripting/_index.adoc index bc939aec04..dbb718ebb9 100644 --- a/documentation/content/en/articles/rc-scripting/_index.adoc +++ b/documentation/content/en/articles/rc-scripting/_index.adoc @@ -62,7 +62,7 @@ With few exceptions, [.filename]#/etc/rc# had to be modified, and true hackers l The real problem with the monolithic approach was that it provided no control over the individual components started from [.filename]#/etc/rc#. For instance, [.filename]#/etc/rc# could not restart a single daemon. The system admin had to find the daemon process by hand, kill it, wait until it actually exited, then browse through [.filename]#/etc/rc# for the flags, and finally type the full command line to start the daemon again. -The task would become even more difficult and prone to errors if the service to restart consisted of more than one daemon or demanded additional actions. +The task would become even more difficult and prone to errors if the service to restart consisted of more than one daemon or demanded additional actions. In a few words, the single script failed to fulfil what scripts are for: to make the system admin's life easier. Later there was an attempt to split out some parts of [.filename]#/etc/rc# for the sake of starting the most important subsystems separately. @@ -84,15 +84,15 @@ The basic ideas behind BSD [.filename]#rc.d# are _fine modularity_ and __code re _Fine modularity_ means that each basic "service" such as a system daemon or primitive startup task gets its own man:sh[1] script able to start the service, stop it, reload it, check its status. A particular action is chosen by the command-line argument to the script. The [.filename]#/etc/rc# script still drives system startup, but now it merely invokes the smaller scripts one by one with the `start` argument. -It is easy to perform shutdown tasks as well by running the same set of scripts with the `stop` argument, which is done by [.filename]#/etc/rc.shutdown#. +It is easy to perform shutdown tasks as well by running the same set of scripts with the `stop` argument, which is done by [.filename]#/etc/rc.shutdown#. Note how closely this follows the Unix way of having a set of small specialized tools, each fulfilling its task as well as possible. _Code reuse_ means that common operations are implemented as man:sh[1] functions and collected in [.filename]#/etc/rc.subr#. Now a typical script can be just a few lines' worth of man:sh[1] code. Finally, an important part of the [.filename]#rc.d# framework is man:rcorder[8], which helps [.filename]#/etc/rc# to run the small scripts orderly with respect to dependencies between them. It can help [.filename]#/etc/rc.shutdown#, too, because the proper order for the shutdown sequence is opposite to that of startup. -The BSD [.filename]#rc.d# design is described in <<lukem, the original article by Luke Mewburn>>, and the [.filename]#rc.d# components are documented in great detail in <<manpages, the respective manual pages>>. -However, it might not appear obvious to an [.filename]#rc.d# newbie how to tie the numerous bits and pieces together in order to create a well-styled script for a particular task. +The BSD [.filename]#rc.d# design is described in crossref:rc-scripting[lukem, the original article by Luke Mewburn], and the [.filename]#rc.d# components are documented in great detail in crossref:rc-scripting[manpages, the respective manual pages]. +However, it might not appear obvious to an [.filename]#rc.d# newbie how to tie the numerous bits and pieces together to create a well-styled script for a particular task. Therefore this article will try a different approach to describe [.filename]#rc.d#. It will show which features should be used in a number of typical cases, and why. Note that this is not a how-to document because our aim is not at giving ready-made recipes, but at showing a few easy entrances into the [.filename]#rc.d# realm. @@ -100,7 +100,7 @@ Neither is this article a replacement for the relevant manual pages. Do not hesitate to refer to them for more formal and complete documentation while reading this article. There are prerequisites to understanding this article. -First of all, you should be familiar with the man:sh[1] scripting language in order to master [.filename]#rc.d#. +First of all, you should be familiar with the man:sh[1] scripting language to master [.filename]#rc.d#. In addition, you should know how the system performs userland startup and shutdown tasks, which is described in man:rc[8]. This article focuses on the FreeBSD branch of [.filename]#rc.d#. @@ -110,7 +110,7 @@ Nevertheless, it may be useful to NetBSD developers, too, because the two branch == Outlining the task A little consideration before starting `$EDITOR` will not hurt. -In order to write a well-tempered [.filename]#rc.d# script for a system service, we should be able to answer the following questions first: +To write a well-tempered [.filename]#rc.d# script for a system service, we should be able to answer the following questions first: * Is the service mandatory or optional? * Will the script serve a single program, e.g., a daemon, or perform more complex actions? @@ -157,7 +157,7 @@ For example, a system admin can run our script manually, from the command line: [NOTE] ==== -In order to be properly managed by the [.filename]#rc.d# framework, its scripts need to be written in the man:sh[1] language. +To be properly managed by the [.filename]#rc.d# framework, its scripts need to be written in the man:sh[1] language. If you have a service or port that uses a binary control utility or a startup routine written in another language, install that element in [.filename]#/usr/sbin# (for the system) or [.filename]#/usr/local/sbin# (for ports) and call it from a man:sh[1] script in the appropriate [.filename]#rc.d# directory. ==== @@ -185,7 +185,9 @@ That is, each [.filename]#rc.d# script _must_ set `name` before it calls man:rc. Now it is the right time to choose a unique name for our script once and for all. We will use it in a number of places while developing the script. -For a start, let us give the same name to the script file, too. +The content of the name variable needs to match the script name, +some parts of FreeBSD (e.g., crossref:rc-scripting[rcng-service-jails, service jails] and the cpuset feature of the rc framework) depend upon this. +As such the filename shall also not contain characters which may be troublesome in scripting (e.g., do not use a hyphen "-" and others). [NOTE] ==== @@ -365,7 +367,8 @@ This is reflected in the list of processes, which can confuse man:rc.subr[8]. You should additionally set `command_interpreter` to let man:rc.subr[8] know the actual name of the process if `$command` is a script. For each [.filename]#rc.d# script, there is an optional man:rc.conf[5] variable that takes precedence over `command`. -Its name is constructed as follows: `${name}_program`, where `name` is the mandatory variable we discussed <<name-var, earlier>>. +Its name is constructed as follows: `${name}_program`, where `name` is the +mandatory variable we discussed crossref:rc-scripting[name-var, earlier]. E.g., in this case it will be `mumbled_program`. It is man:rc.subr[8] that arranges `${name}_program` to override `command`. @@ -448,7 +451,7 @@ Since the final command line is passed to `eval` for its actual execution, input _Never_ include dashed options, like `-X` or `--foo`, in `command_args`. The contents of `command_args` will appear at the end of the final command line, hence they are likely to follow arguments present in `${name}_flags`; but most commands will not recognize dashed options after ordinary arguments. A better way of passing additional options to `$command` is to add them to the beginning of `${name}_flags`. -Another way is to modify `rc_flags` <<rc-flags, as shown later>>. +Another way is to modify `rc_flags` crossref:rc-scripting[rc-flags, as shown later]. ==== ➋ A good-mannered daemon should create a _pidfile_ so that its process can be found more easily and reliably. @@ -504,7 +507,7 @@ The reason is that not all daemons use the same reload mechanism and some have n So we need to ask explicitly that the builtin functionality be provided. We can do so via `extra_commands`. -What do we get from the default method for `reload`? Quite often daemons reload their configuration upon reception of a signal - typically, SIGHUP. +What do we get from the default method for `reload`? Quite often daemons reload their configuration upon reception of a signal - typically, SIGHUP. Therefore man:rc.subr[8] attempts to reload the daemon by sending a signal to it. The signal is preset to SIGHUP but can be customized via `sig_reload` if necessary. ==== @@ -586,8 +589,8 @@ However, man:rc.subr[8] can be instructed from the command line to ignore those After a script has been written, it needs to be integrated into [.filename]#rc.d#. The crucial step is to install the script in [.filename]#/etc/rc.d# (for the base system) or [.filename]#/usr/local/etc/rc.d# (for ports). Both [.filename]#bsd.prog.mk# and [.filename]#bsd.port.mk# provide convenient hooks for that, and usually you do not have to worry about the proper ownership and mode. -System scripts should be installed from [.filename]#src/etc/rc.d# through the [.filename]#Makefile# found there. -Port scripts can be installed using `USE_RC_SUBR` as described extref:{porters-handbook}[in the Porter's Handbook, rc-scripts]. +System scripts should be installed from [.filename]#src/libexec/rc/rc.d# through the [.filename]#Makefile# found there. +Port scripts can be installed using `USE_RC_SUBR` as described extref:{porters-handbook}special[in the Porter's Handbook, rc-scripts]. However, we should consider beforehand the place of our script in the system startup sequence. The service handled by our script is likely to depend on other services. @@ -664,18 +667,18 @@ According to the lines, our script asks man:rcorder[8] to put it after the scrip [NOTE] ==== The `BEFORE:` line should not be abused to work around an incomplete dependency list in the other script. -The appropriate case for using `BEFORE:` is when the other script does not care about ours, but our script can do its task better if run before the other one. +The appropriate case for using `BEFORE:` is when the other script does not care about ours, but our script can do its task better if run before the other one. A typical real-life example is the network interfaces vs. the firewall: While the interfaces do not depend on the firewall in doing their job, the system security will benefit from the firewall being ready before there is any network traffic. Besides conditions corresponding to a single service each, there are meta-conditions and their "placeholder" scripts used to ensure that certain groups of operations are performed before others. These are denoted by [.filename]#UPPERCASE# names. Their list and purposes can be found in man:rc[8]. -Keep in mind that putting a service name in the `REQUIRE:` line does not guarantee that the service will actually be running by the time our script starts. +Keep in mind that putting a service name in the `REQUIRE:` line does not guarantee that the service will actually be running by the time our script starts. The required service may fail to start or just be disabled in man:rc.conf[5]. Obviously, man:rcorder[8] cannot track such details, and man:rc[8] will not do that either. Consequently, the application started by our script should be able to cope with any required services being unavailable. -In certain cases, we can help it as discussed <<forcedep, below>> +In certain cases, we can help it as discussed crossref:rc-scripting[forcedep, below] ==== [[keywords]]➍ As we remember from the above text, man:rcorder[8] keywords can be used to select or leave out some scripts. @@ -831,6 +834,182 @@ That is, arguments with embedded whitespace may not be processed correctly. The bug stems from `$*` misuse. ==== +[[rcng-service-jails]] +== Making a script ready for Service Jails + +Scripts which start a long running service are suitable for service jails, and should come with a suitable service jail configuration. + +Some examples of scripts which are not suitable to run in a service jail: + +* any script which in the start command only changes a runtime setting for programs or the kernel, +* or tries to mount something, +* or finds and deletes files + +Scripts not suitable to run in a service jail need to prevent the use within service jails. + +A script with a long running service which needs to do something listed above before the start or after the stop, can either be split-up into two scripts with dependencies, or use the precommand and postcommand parts of the script to perform this action. + +By default, only the start and stop parts of a script are run within a service jail, the rest is run outside the jail. +As such any setting used in the start/stop parts of the script can not be set from e.g. a precommand. + +To make a script ready for use with extref:{handbook}jails[Service Jails, service-jails], only one more config line needs to be inserted: + +[.programlisting] +.... +#!/bin/sh + +. /etc/rc.subr + +name="dummy" +start_cmd="${name}_start" +stop_cmd=":" + +: ${dummy_svcj_options:=""} <.> + +dummy_start() +{ + echo "Nothing started." +} + +load_rc_config $name +run_rc_command "$1" +.... + +➊ If it makes sense that the script runs in a jail, it must have an overridable service jails configuration. +If it does not need network access or access to any other resource which is restricted in jails, an empty config like displayed is enough. + +Strictly speaking an empty config is not needed, but it explicitly describes that the script is service jails ready, and that it does not need additional jail permissions. +As such it is highly recommended to add such an empty config in such a case. +The most common option to use is "net_basic", which enables the use of the hosts IPv4 and IPv6 addresses. +All possible options are explained in man:rc.conf[5]. + +If a setting for the start/stop depends on variables from the rc-framework (e.g., set inside man:rc.conf[5]), this needs to be handled by ``load_rc_config`` and ``run_rc_command`` instead of inside a precommand. + +If for some reason a script can not be run within a service jail, e.g., because it is not possible to run or it does not make sense to run it in a jail, use the following: + +[.programlisting] +.... +#!/bin/sh + +. /etc/rc.subr + +name="dummy" +start_cmd="${name}_start" +stop_cmd=":" + +dummy_start() +{ + echo "Nothing started." +} + +load_rc_config $name +dummy_svcj="NO" # does not make sense to run in a svcj <.> +run_rc_command "$1" +.... + +➊ The disabling needs to happen after the ``load_rc_config`` call, else a man:rc.conf[5] setting may override it. + +[[rcng-instancing]] +== Advanced rc-scripting: Instancing + +Sometimes it is useful to run several instances of a service. +Typically you want to be able to start/stop such instances independently, +and you want to have a separate config file for each instance. +Each instance should be started at boot, +survive updates, +and benefit from updates. + +Here is an example of a rc script which supports this: + +[.programlisting] +.... +#!/bin/sh + +# +# PROVIDE: dummy +# REQUIRE: NETWORKING SERVERS +# KEYWORD: shutdown +# +# Add these following line to /etc/rc.conf.local or /etc/rc.conf +# to enable this service: +# +# dummy_enable (bool): Set it to YES to enable dummy on startup. +# Default: NO +# dummy_user (string): User account to run with. +# Default: www +# + +. /etc/rc.subr + +case $0 in <.> +/etc/rc*) + # during boot (shutdown) $0 is /etc/rc (/etc/rc.shutdown), + # so get the name of the script from $_file + name=$_file + ;; +*) + name=$0 + ;; +esac + +name=${name##*/} <.> +rcvar="${name}_enable" <.> +desc="Short description of this service" +command="/usr/local/sbin/dummy" + +load_rc_config "$name" + +eval "${rcvar}=\${${rcvar}:-'NO'}" <.> +eval "${name}_svcj_options=\${${name}_svcj_options:-'net_basic'}" <.> +eval "_dummy_user=\${${name}_user:-'www'}" <.> + +_dummy_configname=/usr/local/etc/${name}.cfg <.> +pidfile=/var/run/dummy/${name}.pid +required_files ${_dummy_configname} +command_args="-u ${_dummy_user} -c ${_dummy_configfile} -p ${pidfile}" + +run_rc_command "$1" +.... + +➊ and ➋ make sure to set the name variable to the man:basename[1] of the script name. +If the filename is [.filename]#/usr/local/etc/rc.d/dummy#, +name is set to [.filename]#dummy#. +This way changing the filename of the rc script changes automatically the content of the name variable. + +➌ specifies the variable name which is used in [.filename]#rc.conf# to enable this service based upon the filename of this script. +In this example this resolves to dummy_enable. + +➍ makes sure the default for the _enable variable is NO. + +➎ is an example of having some defaults for service specific framework variables, +in this case the service jails options. + +➏ and ➐ set variables internal to the script (pay attention to the underscore in front of _dummy_user to make it different from dummy_user which can be set in [.filename]#rc.conf#). + +The part in ➎ is for variables which are not used inside the script itself but in the rc framework. +All the variables which are used as parameters somewhere in the script are assigned to a generic variable like in ➐ to make it more easy to reference them (no need to eval them at each place of use). + +This script will now behave differently if the start script has a different name. +This allows to create symlinks to it: + +[source,shell] +.... +# ln -s dummy /usr/local/etc/rc.d/dummy_foo +# sysrc dummy_foo_enable=YES +# service dummy_foo start +.... + +The above creates an instance of the dummy service with the name dummy_foo. +It does not use the config file [.filename]#/usr/local/etc/dummy.cfg# but the config file [.filename]#/usr/local/etc/dummy_foo.cfg# (➐), +and it uses the PID file [.filename]#/var/run/dummy/dummy_foo.pid# instead of [.filename]#/var/run/dummy/dummy.pid#. + +The services dummy and dummy_foo can be managed independently of each other, +while having the start script update itself on package update (due to the symlink). +This does not update the REQUIRE line, +as such there is no easy way of depending on a specific instance. +To depend upon a specific instance in the startup order a copy needs to be made instead of using a symlink. +This prevents the automatic pick-up of changes to the start script when an update is installed. + [[rcng-furthur]] == Further reading diff --git a/documentation/content/en/articles/rc-scripting/_index.po b/documentation/content/en/articles/rc-scripting/_index.po new file mode 100644 index 0000000000..8600e08d60 --- /dev/null +++ b/documentation/content/en/articles/rc-scripting/_index.po @@ -0,0 +1,1957 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-09-14 15:00-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/rc-scripting/_index.adoc:1 +#, no-wrap +msgid "A guide to writing new rc.d scripts and understanding those already written" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/rc-scripting/_index.adoc:1 +#: documentation/content/en/articles/rc-scripting/_index.adoc:12 +#, no-wrap +msgid "Practical rc.d scripting in BSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:45 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:49 +msgid "" +"Beginners may find it difficult to relate the facts from the formal " +"documentation on the BSD [.filename]#rc.d# framework with the practical " +"tasks of [.filename]#rc.d# scripting. In this article, we consider a few " +"typical cases of increasing complexity, show [.filename]#rc.d# features " +"suited for each case, and discuss how they work. Such an examination should " +"provide reference points for further study of the design and efficient " +"application of [.filename]#rc.d#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:51 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/rc-scripting/_index.adoc:55 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:61 +msgid "" +"The historical BSD had a monolithic startup script, [.filename]#/etc/rc#. " +"It was invoked by man:init[8] at system boot time and performed all userland " +"tasks required for multi-user operation: checking and mounting file systems, " +"setting up the network, starting daemons, and so on. The precise list of " +"tasks was not the same in every system; admins needed to customize it. With " +"few exceptions, [.filename]#/etc/rc# had to be modified, and true hackers " +"liked it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:67 +msgid "" +"The real problem with the monolithic approach was that it provided no " +"control over the individual components started from [.filename]#/etc/rc#. " +"For instance, [.filename]#/etc/rc# could not restart a single daemon. The " +"system admin had to find the daemon process by hand, kill it, wait until it " +"actually exited, then browse through [.filename]#/etc/rc# for the flags, and " +"finally type the full command line to start the daemon again. The task " +"would become even more difficult and prone to errors if the service to " +"restart consisted of more than one daemon or demanded additional actions. " +"In a few words, the single script failed to fulfil what scripts are for: to " +"make the system admin's life easier." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:74 +msgid "" +"Later there was an attempt to split out some parts of [.filename]#/etc/rc# " +"for the sake of starting the most important subsystems separately. The " +"notorious example was [.filename]#/etc/netstart# to bring up networking. It " +"did allow for accessing the network from single-user mode, but it did not " +"integrate well into the automatic startup process because parts of its code " +"needed to interleave with actions essentially unrelated to networking. That " +"was why [.filename]#/etc/netstart# mutated into [.filename]#/etc/rc." +"network#. The latter was no longer an ordinary script; it comprised of " +"large, tangled man:sh[1] functions called from [.filename]#/etc/rc# at " +"different stages of system startup. However, as the startup tasks grew " +"diverse and sophisticated, the \"quasi-modular\" approach became even more " +"of a drag than the monolithic [.filename]#/etc/rc# had been." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:82 +msgid "" +"Without a clean and well-designed framework, the startup scripts had to bend " +"over backwards to satisfy the needs of rapidly developing BSD-based " +"operating systems. It became obvious at last that more steps are necessary " +"on the way to a fine-grained and extensible [.filename]#rc# system. Thus " +"BSD [.filename]#rc.d# was born. Its acknowledged fathers were Luke Mewburn " +"and the NetBSD community. Later it was imported into FreeBSD. Its name " +"refers to the location of system scripts for individual services, which is " +"in [.filename]#/etc/rc.d#. Soon we will learn about more components of the " +"[.filename]#rc.d# system and see how the individual scripts are invoked." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:93 +msgid "" +"The basic ideas behind BSD [.filename]#rc.d# are _fine modularity_ and " +"__code reuse__. _Fine modularity_ means that each basic \"service\" such as " +"a system daemon or primitive startup task gets its own man:sh[1] script able " +"to start the service, stop it, reload it, check its status. A particular " +"action is chosen by the command-line argument to the script. The [." +"filename]#/etc/rc# script still drives system startup, but now it merely " +"invokes the smaller scripts one by one with the `start` argument. It is " +"easy to perform shutdown tasks as well by running the same set of scripts " +"with the `stop` argument, which is done by [.filename]#/etc/rc.shutdown#. " +"Note how closely this follows the Unix way of having a set of small " +"specialized tools, each fulfilling its task as well as possible. _Code " +"reuse_ means that common operations are implemented as man:sh[1] functions " +"and collected in [.filename]#/etc/rc.subr#. Now a typical script can be " +"just a few lines' worth of man:sh[1] code. Finally, an important part of " +"the [.filename]#rc.d# framework is man:rcorder[8], which helps [.filename]#/" +"etc/rc# to run the small scripts orderly with respect to dependencies " +"between them. It can help [.filename]#/etc/rc.shutdown#, too, because the " +"proper order for the shutdown sequence is opposite to that of startup." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:101 +msgid "" +"The BSD [.filename]#rc.d# design is described in crossref:rc-" +"scripting[lukem, the original article by Luke Mewburn], and the [." +"filename]#rc.d# components are documented in great detail in crossref:rc-" +"scripting[manpages, the respective manual pages]. However, it might not " +"appear obvious to an [.filename]#rc.d# newbie how to tie the numerous bits " +"and pieces together to create a well-styled script for a particular task. " +"Therefore this article will try a different approach to describe [." +"filename]#rc.d#. It will show which features should be used in a number of " +"typical cases, and why. Note that this is not a how-to document because our " +"aim is not at giving ready-made recipes, but at showing a few easy entrances " +"into the [.filename]#rc.d# realm. Neither is this article a replacement for " +"the relevant manual pages. Do not hesitate to refer to them for more formal " +"and complete documentation while reading this article." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:105 +msgid "" +"There are prerequisites to understanding this article. First of all, you " +"should be familiar with the man:sh[1] scripting language to master [." +"filename]#rc.d#. In addition, you should know how the system performs " +"userland startup and shutdown tasks, which is described in man:rc[8]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:108 +msgid "" +"This article focuses on the FreeBSD branch of [.filename]#rc.d#. " +"Nevertheless, it may be useful to NetBSD developers, too, because the two " +"branches of BSD [.filename]#rc.d# not only share the same design but also " +"stay similar in their aspects visible to script authors." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/rc-scripting/_index.adoc:110 +#, no-wrap +msgid "Outlining the task" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:114 +msgid "" +"A little consideration before starting `$EDITOR` will not hurt. To write a " +"well-tempered [.filename]#rc.d# script for a system service, we should be " +"able to answer the following questions first:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:116 +msgid "Is the service mandatory or optional?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:117 +msgid "" +"Will the script serve a single program, e.g., a daemon, or perform more " +"complex actions?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:118 +msgid "Which other services will our service depend on, and vice versa?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:120 +msgid "" +"From the examples that follow we will see why it is important to know the " +"answers to these questions." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/rc-scripting/_index.adoc:122 +#, no-wrap +msgid "A dummy script" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:125 +msgid "" +"The following script just emits a message each time the system boots up:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:129 +#, no-wrap +msgid "#!/bin/sh <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:131 +#, no-wrap +msgid ". /etc/rc.subr <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:135 +#, no-wrap +msgid "" +"name=\"dummy\" <.>\n" +"start_cmd=\"${name}_start\" <.>\n" +"stop_cmd=\":\" <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:140 +#, no-wrap +msgid "" +"dummy_start() <.>\n" +"{\n" +"\techo \"Nothing started.\"\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:143 +#, no-wrap +msgid "" +"load_rc_config $name <.>\n" +"run_rc_command \"$1\" <.>\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:146 +msgid "Things to note are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:152 +msgid "" +"➊ An interpreted script should begin with the magic \"shebang\" " +"line. That line specifies the interpreter program for the script. Due to " +"the shebang line, the script can be invoked exactly like a binary program " +"provided that it has the execute bit set. (See man:chmod[1].) For example, " +"a system admin can run our script manually, from the command line:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:156 +#, no-wrap +msgid "# /etc/rc.d/dummy start\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:162 +msgid "" +"To be properly managed by the [.filename]#rc.d# framework, its scripts need " +"to be written in the man:sh[1] language. If you have a service or port that " +"uses a binary control utility or a startup routine written in another " +"language, install that element in [.filename]#/usr/sbin# (for the system) or " +"[.filename]#/usr/local/sbin# (for ports) and call it from a man:sh[1] script " +"in the appropriate [.filename]#rc.d# directory." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:167 +msgid "" +"If you would like to learn the details of why [.filename]#rc.d# scripts must " +"be written in the man:sh[1] language, see how [.filename]#/etc/rc# invokes " +"them by means of `run_rc_script`, then study the implementation of " +"`run_rc_script` in [.filename]#/etc/rc.subr#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:173 +msgid "" +"➋ In [.filename]#/etc/rc.subr#, a number of man:sh[1] functions are " +"defined for an [.filename]#rc.d# script to use. The functions are " +"documented in man:rc.subr[8]. While it is theoretically possible to write " +"an [.filename]#rc.d# script without ever using man:rc.subr[8], its functions " +"prove extremely handy and make the job an order of magnitude easier. So it " +"is no surprise that everybody resorts to man:rc.subr[8] in [.filename]#rc.d# " +"scripts. We are not going to be an exception." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:176 +msgid "" +"An [.filename]#rc.d# script must \"source\"[.filename]#/etc/rc.subr# " +"(include it using \"`.`\") _before_ it calls man:rc.subr[8] functions so " +"that man:sh[1] has an opportunity to learn the functions. The preferred " +"style is to source [.filename]#/etc/rc.subr# first of all." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:180 +msgid "" +"Some useful functions related to networking are provided by another include " +"file, [.filename]#/etc/network.subr#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:185 +msgid "" +"➌ [[name-var]]The mandatory variable `name` specifies the name of our " +"script. It is required by man:rc.subr[8]. That is, each [.filename]#rc.d# " +"script _must_ set `name` before it calls man:rc.subr[8] functions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:191 +msgid "" +"Now it is the right time to choose a unique name for our script once and for " +"all. We will use it in a number of places while developing the script. The " +"content of the name variable needs to match the script name, some parts of " +"FreeBSD (e.g., crossref:rc-scripting[rcng-service-jails, service jails] and " +"the cpuset feature of the rc framework) depend upon this. As such the " +"filename shall also not contain characters which may be troublesome in " +"scripting (e.g., do not use a hyphen \"-\" and others)." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:198 +msgid "" +"The current style of [.filename]#rc.d# scripting is to enclose values " +"assigned to variables in double quotes. Keep in mind that it is just a " +"style issue that may not always be applicable. You can safely omit quotes " +"from around simple words without man:sh[1] metacharacters in them, while in " +"certain cases you will need single quotes to prevent any interpretation of " +"the value by man:sh[1]. A programmer should be able to tell the language " +"syntax from style conventions and use both of them wisely." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:204 +msgid "" +"➍ The main idea behind man:rc.subr[8] is that an [.filename]#rc.d# " +"script provides handlers, or methods, for man:rc.subr[8] to invoke. In " +"particular, `start`, `stop`, and other arguments to an [.filename]#rc.d# " +"script are handled this way. A method is a man:sh[1] expression stored in a " +"variable named `argument_cmd`, where _argument_ corresponds to what can be " +"specified on the script's command line. We will see later how man:rc." +"subr[8] provides default methods for the standard arguments." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:209 +msgid "" +"To make the code in [.filename]#rc.d# more uniform, it is common to use " +"`${name}` wherever appropriate. Thus a number of lines can be just copied " +"from one script to another." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:213 +msgid "" +"➎ We should keep in mind that man:rc.subr[8] provides default methods " +"for the standard arguments. Consequently, we must override a standard " +"method with a no-op man:sh[1] expression if we want it to do nothing." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:216 +msgid "" +"➏ The body of a sophisticated method can be implemented as a " +"function. It is a good idea to make the function name meaningful." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:220 +msgid "" +"It is strongly recommended to add the prefix `${name}` to the names of all " +"functions defined in our script so they never clash with the functions from " +"man:rc.subr[8] or another common include file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:224 +msgid "" +"➐ This call to man:rc.subr[8] loads man:rc.conf[5] variables. Our " +"script makes no use of them yet, but it still is recommended to load man:rc." +"conf[5] because there can be man:rc.conf[5] variables controlling man:rc." +"subr[8] itself." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:227 +msgid "" +"➑ Usually this is the last command in an [.filename]#rc.d# script. " +"It invokes the man:rc.subr[8] machinery to perform the requested action " +"using the variables and methods our script has provided." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/rc-scripting/_index.adoc:229 +#, no-wrap +msgid "A configurable dummy script" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:239 +msgid "" +"Now let us add some controls to our dummy script. As you may know, [." +"filename]#rc.d# scripts are controlled with man:rc.conf[5]. Fortunately, " +"man:rc.subr[8] hides all the complications from us. The following script " +"uses man:rc.conf[5] via man:rc.subr[8] to see whether it is enabled in the " +"first place, and to fetch a message to show at boot time. These two tasks " +"in fact are independent. On the one hand, an [.filename]#rc.d# script can " +"just support enabling and disabling its service. On the other hand, a " +"mandatory [.filename]#rc.d# script can have configuration variables. We " +"will do both things in the same script though:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:243 +#: documentation/content/en/articles/rc-scripting/_index.adoc:334 +#: documentation/content/en/articles/rc-scripting/_index.adoc:392 +#: documentation/content/en/articles/rc-scripting/_index.adoc:624 +#: documentation/content/en/articles/rc-scripting/_index.adoc:755 +#: documentation/content/en/articles/rc-scripting/_index.adoc:860 +#: documentation/content/en/articles/rc-scripting/_index.adoc:893 +#: documentation/content/en/articles/rc-scripting/_index.adoc:927 +#, no-wrap +msgid "#!/bin/sh\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:245 +#: documentation/content/en/articles/rc-scripting/_index.adoc:336 +#: documentation/content/en/articles/rc-scripting/_index.adoc:394 +#: documentation/content/en/articles/rc-scripting/_index.adoc:631 +#: documentation/content/en/articles/rc-scripting/_index.adoc:757 +#: documentation/content/en/articles/rc-scripting/_index.adoc:862 +#: documentation/content/en/articles/rc-scripting/_index.adoc:895 +#: documentation/content/en/articles/rc-scripting/_index.adoc:943 +#, no-wrap +msgid ". /etc/rc.subr\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:248 +#, no-wrap +msgid "" +"name=dummy\n" +"rcvar=dummy_enable <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:251 +#, no-wrap +msgid "" +"start_cmd=\"${name}_start\"\n" +"stop_cmd=\":\"\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:255 +#, no-wrap +msgid "" +"load_rc_config $name <.>\n" +": ${dummy_enable:=no} <.>\n" +": ${dummy_msg=\"Nothing started.\"} <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:260 +#, no-wrap +msgid "" +"dummy_start()\n" +"{\n" +"\techo \"$dummy_msg\" <.>\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:262 +#: documentation/content/en/articles/rc-scripting/_index.adoc:972 +#, no-wrap +msgid "run_rc_command \"$1\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:265 +msgid "What changed in this example?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:267 +msgid "" +"➊ The variable `rcvar` specifies the name of the ON/OFF knob variable." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:269 +msgid "" +"➋ Now `load_rc_config` is invoked earlier in the script, before any " +"man:rc.conf[5] variables are accessed." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:275 +msgid "" +"While examining [.filename]#rc.d# scripts, keep in mind that man:sh[1] " +"defers the evaluation of expressions in a function until the latter is " +"called. Therefore it is not an error to invoke `load_rc_config` as late as " +"just before `run_rc_command` and still access man:rc.conf[5] variables from " +"the method functions exported to `run_rc_command`. This is because the " +"method functions are to be called by `run_rc_command`, which is invoked " +"_after_ `load_rc_config`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:281 +msgid "" +"➌ A warning will be emitted by `run_rc_command` if `rcvar` itself is " +"set, but the indicated knob variable is unset. If your [.filename]#rc.d# " +"script is for the base system, you should add a default setting for the knob " +"to [.filename]#/etc/defaults/rc.conf# and document it in man:rc.conf[5]. " +"Otherwise it is your script that should provide a default setting for the " +"knob. The canonical approach to the latter case is shown in the example." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:288 +msgid "" +"You can make man:rc.subr[8] act as though the knob is set to `ON`, " +"irrespective of its current setting, by prefixing the argument to the script " +"with `one` or `force`, as in `onestart` or `forcestop`. Keep in mind though " +"that `force` has other dangerous effects we will touch upon below, while " +"`one` just overrides the ON/OFF knob. E.g., assume that `dummy_enable` is " +"`OFF`. The following command will run the `start` method in spite of the " +"setting:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:292 +#, no-wrap +msgid "# /etc/rc.d/dummy onestart\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:299 +msgid "" +"➍ Now the message to be shown at boot time is no longer hard-coded in " +"the script. It is specified by an man:rc.conf[5] variable named " +"`dummy_msg`. This is a trivial example of how man:rc.conf[5] variables can " +"control an [.filename]#rc.d# script." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:304 +msgid "" +"The names of all man:rc.conf[5] variables used exclusively by our script " +"_must_ have the same prefix: `${name}_`. For example: `dummy_mode`, " +"`dummy_state_file`, and so on." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:309 +msgid "" +"While it is possible to use a shorter name internally, e.g., just `msg`, " +"adding the unique prefix `${name}_` to all global names introduced by our " +"script will save us from possible collisions with the man:rc.subr[8] " +"namespace." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:312 +msgid "" +"As a rule, [.filename]#rc.d# scripts of the base system need not provide " +"defaults for their man:rc.conf[5] variables because the defaults should be " +"set in [.filename]#/etc/defaults/rc.conf# instead. On the other hand, [." +"filename]#rc.d# scripts for ports should provide the defaults as shown in " +"the example." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:316 +msgid "" +"➎ Here we use `dummy_msg` to actually control our script, i.e., to " +"emit a variable message. Use of a shell function is overkill here, since it " +"only runs a single command; an equally valid alternative is:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:320 +#, no-wrap +msgid "start_cmd=\"echo \\\"$dummy_msg\\\"\"\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/rc-scripting/_index.adoc:323 +#, no-wrap +msgid "Startup and shutdown of a simple daemon" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:330 +msgid "" +"We said earlier that man:rc.subr[8] could provide default methods. " +"Obviously, such defaults cannot be too general. They are suited for the " +"common case of starting and shutting down a simple daemon program. Let us " +"assume now that we need to write an [.filename]#rc.d# script for such a " +"daemon called `mumbled`. Here it is:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:339 +#: documentation/content/en/articles/rc-scripting/_index.adoc:397 +#: documentation/content/en/articles/rc-scripting/_index.adoc:634 +#, no-wrap +msgid "" +"name=mumbled\n" +"rcvar=mumbled_enable\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:341 +#, no-wrap +msgid "command=\"/usr/sbin/${name}\" <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:344 +#: documentation/content/en/articles/rc-scripting/_index.adoc:443 +#: documentation/content/en/articles/rc-scripting/_index.adoc:649 +#: documentation/content/en/articles/rc-scripting/_index.adoc:876 +#, no-wrap +msgid "" +"load_rc_config $name\n" +"run_rc_command \"$1\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:348 +msgid "" +"Pleasingly simple, isn't it? Let us examine our little script. The only new " +"thing to note is as follows:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:352 +msgid "" +"➊ The `command` variable is meaningful to man:rc.subr[8]. If it is " +"set, man:rc.subr[8] will act according to the scenario of serving a " +"conventional daemon. In particular, the default methods will be provided " +"for such arguments: `start`, `stop`, `restart`, `poll`, and `status`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:361 +msgid "" +"The daemon will be started by running `$command` with command-line flags " +"specified by `$mumbled_flags`. Thus all the input data for the default " +"`start` method are available in the variables set by our script. Unlike " +"`start`, other methods may require additional information about the process " +"started. For instance, `stop` must know the PID of the process to terminate " +"it. In the present case, man:rc.subr[8] will scan through the list of all " +"processes, looking for a process with its name equal to `procname`. The " +"latter is another variable of meaning to man:rc.subr[8], and its value " +"defaults to that of `command`. In other words, when we set `command`, " +"`procname` is effectively set to the same value. This enables our script to " +"kill the daemon and to check if it is running in the first place." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:368 +msgid "" +"Some programs are in fact executable scripts. The system runs such a script " +"by starting its interpreter and passing the name of the script to it as a " +"command-line argument. This is reflected in the list of processes, which " +"can confuse man:rc.subr[8]. You should additionally set " +"`command_interpreter` to let man:rc.subr[8] know the actual name of the " +"process if `$command` is a script." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:374 +msgid "" +"For each [.filename]#rc.d# script, there is an optional man:rc.conf[5] " +"variable that takes precedence over `command`. Its name is constructed as " +"follows: `${name}_program`, where `name` is the mandatory variable we " +"discussed crossref:rc-scripting[name-var, earlier]. E.g., in this case it " +"will be `mumbled_program`. It is man:rc.subr[8] that arranges `${name}" +"_program` to override `command`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:378 +msgid "" +"Of course, man:sh[1] will permit you to set `${name}_program` from man:rc." +"conf[5] or the script itself even if `command` is unset. In that case, the " +"special properties of `${name}_program` are lost, and it becomes an ordinary " +"variable your script can use for its own purposes. However, the sole use of " +"`${name}_program` is discouraged because using it together with `command` " +"became an idiom of [.filename]#rc.d# scripting." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:381 +msgid "" +"For more detailed information on default methods, refer to man:rc.subr[8]." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/rc-scripting/_index.adoc:383 +#, no-wrap +msgid "Startup and shutdown of an advanced daemon" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:388 +msgid "" +"Let us add some meat onto the bones of the previous script and make it more " +"complex and featureful. The default methods can do a good job for us, but " +"we may need some of their aspects tweaked. Now we will learn how to tune " +"the default methods to our needs." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:400 +#, no-wrap +msgid "" +"command=\"/usr/sbin/${name}\"\n" +"command_args=\"mock arguments > /dev/null 2>&1\" <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:402 +#, no-wrap +msgid "pidfile=\"/var/run/${name}.pid\" <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:404 +#, no-wrap +msgid "required_files=\"/etc/${name}.conf /usr/share/misc/${name}.rules\" <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:406 +#, no-wrap +msgid "sig_reload=\"USR1\" <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:409 +#, no-wrap +msgid "" +"start_precmd=\"${name}_prestart\" <.>\n" +"stop_postcmd=\"echo Bye-bye\" <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:411 +#, no-wrap +msgid "extra_commands=\"reload plugh xyzzy\" <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:414 +#, no-wrap +msgid "" +"plugh_cmd=\"mumbled_plugh\" <.>\n" +"xyzzy_cmd=\"echo 'Nothing happens.'\"\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:435 +#, no-wrap +msgid "" +"mumbled_prestart()\n" +"{\n" +"\tif checkyesno mumbled_smart; then <.>\n" +"\t\trc_flags=\"-o smart ${rc_flags}\" <.>\n" +"\tfi\n" +"\tcase \"$mumbled_mode\" in\n" +"\tfoo)\n" +"\t\trc_flags=\"-frotz ${rc_flags}\"\n" +"\t\t;;\n" +"\tbar)\n" +"\t\trc_flags=\"-baz ${rc_flags}\"\n" +"\t\t;;\n" +"\t*)\n" +"\t\twarn \"Invalid value for mumbled_mode\" <.>\n" +"\t\treturn 1 <.>\n" +"\t\t;;\n" +"\tesac\n" +"\trun_rc_command xyzzy <.>\n" +"\treturn 0\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:440 +#, no-wrap +msgid "" +"mumbled_plugh() <.>\n" +"{\n" +"\techo 'A hollow voice says \"plugh\".'\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:448 +msgid "" +"➊ Additional arguments to `$command` can be passed in " +"`command_args`. They will be added to the command line after " +"`$mumbled_flags`. Since the final command line is passed to `eval` for its " +"actual execution, input and output redirections can be specified in " +"`command_args`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:455 +msgid "" +"_Never_ include dashed options, like `-X` or `--foo`, in `command_args`. " +"The contents of `command_args` will appear at the end of the final command " +"line, hence they are likely to follow arguments present in `${name}_flags`; " +"but most commands will not recognize dashed options after ordinary " +"arguments. A better way of passing additional options to `$command` is to " +"add them to the beginning of `${name}_flags`. Another way is to modify " +"`rc_flags` crossref:rc-scripting[rc-flags, as shown later]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:459 +msgid "" +"➋ A good-mannered daemon should create a _pidfile_ so that its " +"process can be found more easily and reliably. The variable `pidfile`, if " +"set, tells man:rc.subr[8] where it can find the pidfile for its default " +"methods to use." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:464 +msgid "" +"In fact, man:rc.subr[8] will also use the pidfile to see if the daemon is " +"already running before starting it. This check can be skipped by using the " +"`faststart` argument." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:469 +msgid "" +"➌ If the daemon cannot run unless certain files exist, just list them " +"in `required_files`, and man:rc.subr[8] will check that those files do exist " +"before starting the daemon. There also are `required_dirs` and " +"`required_vars` for directories and environment variables, respectively. " +"They all are described in detail in man:rc.subr[8]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:473 +msgid "" +"The default method from man:rc.subr[8] can be forced to skip the " +"prerequisite checks by using `forcestart` as the argument to the script." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:479 +msgid "" +"➍ We can customize signals to send to the daemon in case they differ " +"from the well-known ones. In particular, `sig_reload` specifies the signal " +"that makes the daemon reload its configuration; it is SIGHUP by default. " +"Another signal is sent to stop the daemon process; the default is SIGTERM, " +"but this can be changed by setting `sig_stop` appropriately." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:484 +msgid "" +"The signal names should be specified to man:rc.subr[8] without the `SIG` " +"prefix, as it is shown in the example. The FreeBSD version of man:kill[1] " +"can recognize the `SIG` prefix, but the versions from other OS types may not." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:489 +msgid "" +"➎➏ Performing additional tasks before or after the default " +"methods is easy. For each command-argument supported by our script, we can " +"define `argument_precmd` and `argument_postcmd`. These man:sh[1] commands " +"are invoked before and after the respective method, as it is evident from " +"their names." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:495 +msgid "" +"Overriding a default method with a custom `argument_cmd` still does not " +"prevent us from making use of `argument_precmd` or `argument_postcmd` if we " +"need to. In particular, the former is good for checking custom, " +"sophisticated conditions that should be met before performing the command " +"itself. Using `argument_precmd` along with `argument_cmd` lets us logically " +"separate the checks from the action." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:498 +msgid "" +"Do not forget that you can cram any valid man:sh[1] expressions into the " +"methods, pre-, and post-commands you define. Just invoking a function that " +"makes the real job is a good style in most cases, but never let style limit " +"your understanding of what is going on behind the curtain." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:501 +msgid "" +"➐ If we would like to implement custom arguments, which can also be " +"thought of as _commands_ to our script, we need to list them in " +"`extra_commands` and provide methods to handle them." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:509 +msgid "" +"The `reload` command is special. On the one hand, it has a preset method in " +"man:rc.subr[8]. On the other hand, `reload` is not offered by default. The " +"reason is that not all daemons use the same reload mechanism and some have " +"nothing to reload at all. So we need to ask explicitly that the builtin " +"functionality be provided. We can do so via `extra_commands`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:513 +msgid "" +"What do we get from the default method for `reload`? Quite often daemons " +"reload their configuration upon reception of a signal - typically, SIGHUP. " +"Therefore man:rc.subr[8] attempts to reload the daemon by sending a signal " +"to it. The signal is preset to SIGHUP but can be customized via " +"`sig_reload` if necessary." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:518 +msgid "" +"➑⓮ Our script supports two non-standard commands, `plugh` and " +"`xyzzy`. We saw them listed in `extra_commands`, and now it is time to " +"provide methods for them. The method for `xyzzy` is just inlined while that " +"for `plugh` is implemented as the `mumbled_plugh` function." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:522 +msgid "" +"Non-standard commands are not invoked during startup or shutdown. Usually " +"they are for the system admin's convenience. They can also be used from " +"other subsystems, e.g., man:devd[8] if specified in man:devd.conf[5]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:525 +msgid "" +"The full list of available commands can be found in the usage line printed " +"by man:rc.subr[8] when the script is invoked without arguments. For " +"example, here is the usage line from the script under study:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:530 +#, no-wrap +msgid "" +"# /etc/rc.d/mumbled\n" +"Usage: /etc/rc.d/mumbled [fast|force|one](start|stop|restart|rcvar|reload|plugh|xyzzy|status|poll)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:537 +msgid "" +"⓭ A script can invoke its own standard or non-standard commands if " +"needed. This may look similar to calling functions, but we know that " +"commands and shell functions are not always the same thing. For instance, " +"`xyzzy` is not implemented as a function here. In addition, there can be a " +"pre-command and post-command, which should be invoked orderly. So the " +"proper way for a script to run its own command is by means of man:rc." +"subr[8], as shown in the example." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:543 +msgid "" +"➒ A handy function named `checkyesno` is provided by man:rc.subr[8]. " +"It takes a variable name as its argument and returns a zero exit code if and " +"only if the variable is set to `YES`, or `TRUE`, or `ON`, or `1`, case " +"insensitive; a non-zero exit code is returned otherwise. In the latter " +"case, the function tests the variable for being set to `NO`, `FALSE`, `OFF`, " +"or `0`, case insensitive; it prints a warning message if the variable " +"contains anything else, i.e., junk." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:545 +msgid "" +"Keep in mind that for man:sh[1] a zero exit code means true and a non-zero " +"exit code means false." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:550 +msgid "" +"The `checkyesno` function takes a __variable name__. Do not pass the " +"expanded _value_ of a variable to it; it will not work as expected." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:552 +msgid "The following is the correct usage of `checkyesno`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:558 +#, no-wrap +msgid "" +"if checkyesno mumbled_enable; then\n" +" foo\n" +"fi\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:561 +msgid "" +"On the contrary, calling `checkyesno` as shown below will not work - at " +"least not as expected:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:567 +#, no-wrap +msgid "" +"if checkyesno \"${mumbled_enable}\"; then\n" +" foo\n" +"fi\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:572 +msgid "" +"➓ [[rc-flags]]We can affect the flags to be passed to `$command` by " +"modifying `rc_flags` in `$start_precmd`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:576 +msgid "" +"⓫ In certain cases we may need to emit an important message that " +"should go to `syslog` as well. This can be done easily with the following " +"man:rc.subr[8] functions: `debug`, `info`, `warn`, and `err`. The latter " +"function then exits the script with the code specified." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:580 +msgid "" +"⓬ The exit codes from methods and their pre-commands are not just " +"ignored by default. If `argument_precmd` returns a non-zero exit code, the " +"main method will not be performed. In turn, `argument_postcmd` will not be " +"invoked unless the main method returns a zero exit code." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:584 +msgid "" +"However, man:rc.subr[8] can be instructed from the command line to ignore " +"those exit codes and invoke all commands anyway by prefixing an argument " +"with `force`, as in `forcestart`." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/rc-scripting/_index.adoc:587 +#, no-wrap +msgid "Connecting a script to the rc.d framework" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:594 +msgid "" +"After a script has been written, it needs to be integrated into [." +"filename]#rc.d#. The crucial step is to install the script in [.filename]#/" +"etc/rc.d# (for the base system) or [.filename]#/usr/local/etc/rc.d# (for " +"ports). Both [.filename]#bsd.prog.mk# and [.filename]#bsd.port.mk# provide " +"convenient hooks for that, and usually you do not have to worry about the " +"proper ownership and mode. System scripts should be installed from [." +"filename]#src/libexec/rc/rc.d# through the [.filename]#Makefile# found " +"there. Port scripts can be installed using `USE_RC_SUBR` as described " +"extref:{porters-handbook}[in the Porter's Handbook, rc-scripts]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:599 +msgid "" +"However, we should consider beforehand the place of our script in the system " +"startup sequence. The service handled by our script is likely to depend on " +"other services. For instance, a network daemon cannot function without the " +"network interfaces and routing up and running. Even if a service seems to " +"demand nothing, it can hardly start before the basic filesystems have been " +"checked and mounted." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:605 +msgid "" +"We mentioned man:rcorder[8] already. Now it is time to have a close look at " +"it. In a nutshell, man:rcorder[8] takes a set of files, examines their " +"contents, and prints a dependency-ordered list of files from the set to " +"`stdout`. The point is to keep dependency information _inside_ the files so " +"that each file can speak for itself only. A file can specify the following " +"information:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:607 +msgid "" +"the names of the \"conditions\" (which means services to us) it __provides__;" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:608 +msgid "the names of the \"conditions\" it __requires__;" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:609 +msgid "the names of the \"conditions\" this file should run __before__;" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:610 +msgid "" +"additional _keywords_ that can be used to select a subset from the whole set " +"of files (man:rcorder[8] can be instructed via options to include or omit " +"the files having particular keywords listed.)" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:615 +msgid "" +"It is no surprise that man:rcorder[8] can handle only text files with a " +"syntax close to that of man:sh[1]. That is, special lines understood by man:" +"rcorder[8] look like man:sh[1] comments. The syntax of such special lines " +"is rather rigid to simplify their processing. See man:rcorder[8] for " +"details." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:618 +msgid "" +"Besides using man:rcorder[8] special lines, a script can insist on its " +"dependency upon another service by just starting it forcibly. This can be " +"needed when the other service is optional and will not start by itself " +"because the system admin has disabled it mistakenly in man:rc.conf[5]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:620 +msgid "" +"With this general knowledge in mind, let us consider the simple daemon " +"script enhanced with dependency stuff:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:629 +#, no-wrap +msgid "" +"# PROVIDE: mumbled oldmumble <.>\n" +"# REQUIRE: DAEMON cleanvar frotz <.>\n" +"# BEFORE: LOGIN <.>\n" +"# KEYWORD: nojail shutdown <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:637 +#, no-wrap +msgid "" +"command=\"/usr/sbin/${name}\"\n" +"start_precmd=\"${name}_prestart\"\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:646 +#, no-wrap +msgid "" +"mumbled_prestart()\n" +"{\n" +"\tif ! checkyesno frotz_enable && \\\n" +"\t ! /etc/rc.d/frotz forcestatus 1>/dev/null 2>&1; then\n" +"\t\tforce_depend frotz || return 1 <.>\n" +"\tfi\n" +"\treturn 0\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:652 +msgid "As before, detailed analysis follows:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:655 +msgid "" +"➊ That line declares the names of \"conditions\" our script " +"provides. Now other scripts can record a dependency on our script by those " +"names." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:660 +msgid "" +"Usually a script specifies a single condition provided. However, nothing " +"prevents us from listing several conditions there, e.g., for compatibility " +"reasons." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:662 +msgid "" +"In any case, the name of the main, or the only, `PROVIDE:` condition should " +"be the same as `${name}`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:666 +msgid "" +"➋➌ So our script indicates which \"conditions\" provided by " +"other scripts it depends on. According to the lines, our script asks man:" +"rcorder[8] to put it after the script(s) providing [.filename]#DAEMON# and [." +"filename]#cleanvar#, but before that providing [.filename]#LOGIN#." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:672 +msgid "" +"The `BEFORE:` line should not be abused to work around an incomplete " +"dependency list in the other script. The appropriate case for using `BEFORE:" +"` is when the other script does not care about ours, but our script can do " +"its task better if run before the other one. A typical real-life example is " +"the network interfaces vs. the firewall: While the interfaces do not depend " +"on the firewall in doing their job, the system security will benefit from " +"the firewall being ready before there is any network traffic." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:676 +msgid "" +"Besides conditions corresponding to a single service each, there are meta-" +"conditions and their \"placeholder\" scripts used to ensure that certain " +"groups of operations are performed before others. These are denoted by [." +"filename]#UPPERCASE# names. Their list and purposes can be found in man:" +"rc[8]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:682 +msgid "" +"Keep in mind that putting a service name in the `REQUIRE:` line does not " +"guarantee that the service will actually be running by the time our script " +"starts. The required service may fail to start or just be disabled in man:" +"rc.conf[5]. Obviously, man:rcorder[8] cannot track such details, and man:" +"rc[8] will not do that either. Consequently, the application started by our " +"script should be able to cope with any required services being unavailable. " +"In certain cases, we can help it as discussed crossref:rc-" +"scripting[forcedep, below]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:687 +msgid "" +"[[keywords]]➍ As we remember from the above text, man:rcorder[8] " +"keywords can be used to select or leave out some scripts. Namely any man:" +"rcorder[8] consumer can specify through `-k` and `-s` options which keywords " +"are on the \"keep list\" and \"skip list\", respectively. From all the " +"files to be dependency sorted, man:rcorder[8] will pick only those having a " +"keyword from the keep list (unless empty) and not having a keyword from the " +"skip list." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:690 +msgid "" +"In FreeBSD, man:rcorder[8] is used by [.filename]#/etc/rc# and [.filename]#/" +"etc/rc.shutdown#. These two scripts define the standard list of FreeBSD [." +"filename]#rc.d# keywords and their meanings as follows:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/rc-scripting/_index.adoc:691 +#, no-wrap +msgid "nojail" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:693 +msgid "" +"The service is not for man:jail[8] environment. The automatic startup and " +"shutdown procedures will ignore the script if inside a jail." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/rc-scripting/_index.adoc:694 +#, no-wrap +msgid "nostart" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:697 +msgid "" +"The service is to be started manually or not started at all. The automatic " +"startup procedure will ignore the script. In conjunction with the [." +"filename]#shutdown# keyword, this can be used to write scripts that do " +"something only at system shutdown." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/rc-scripting/_index.adoc:698 +#, no-wrap +msgid "shutdown" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:699 +msgid "" +"This keyword is to be listed __explicitly__ if the service needs to be " +"stopped before system shutdown." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:712 +msgid "" +"When the system is going to shut down, [.filename]#/etc/rc.shutdown# runs. " +"It assumes that most [.filename]#rc.d# scripts have nothing to do at that " +"time. Therefore [.filename]#/etc/rc.shutdown# selectively invokes [." +"filename]#rc.d# scripts with the [.filename]#shutdown# keyword, effectively " +"ignoring the rest of the scripts. For even faster shutdown, [.filename]#/" +"etc/rc.shutdown# passes the [.filename]#faststop# command to the scripts it " +"runs so that they skip preliminary checks, e.g., the pidfile check. As " +"dependent services should be stopped before their prerequisites, [." +"filename]#/etc/rc.shutdown# runs the scripts in reverse dependency order. " +"If writing a real [.filename]#rc.d# script, you should consider whether it " +"is relevant at system shutdown time. E.g., if your script does its work in " +"response to the [.filename]#start# command only, then you need not to " +"include this keyword. However, if your script manages a service, it is " +"probably a good idea to stop it before the system proceeds to the final " +"stage of its shutdown sequence described in man:halt[8]. In particular, a " +"service should be stopped explicitly if it needs considerable time or " +"special actions to shut down cleanly. A typical example of such a service " +"is a database engine." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:716 +msgid "" +"[[forcedep]]➎ To begin with, `force_depend` should be used with much " +"care. It is generally better to revise the hierarchy of configuration " +"variables for your [.filename]#rc.d# scripts if they are interdependent." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:725 +msgid "" +"If you still cannot do without `force_depend`, the example offers an idiom " +"of how to invoke it conditionally. In the example, our `mumbled` daemon " +"requires that another one, `frotz`, be started in advance. However, `frotz` " +"is optional, too; and man:rcorder[8] knows nothing about such details. " +"Fortunately, our script has access to all man:rc.conf[5] variables. If " +"`frotz_enable` is true, we hope for the best and rely on [.filename]#rc.d# " +"to have started `frotz`. Otherwise we forcibly check the status of " +"`frotz`. Finally, we enforce our dependency on `frotz` if it is found to be " +"not running. A warning message will be emitted by `force_depend` because it " +"should be invoked only if a misconfiguration has been detected." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/rc-scripting/_index.adoc:727 +#, no-wrap +msgid "Giving more flexibility to an rc.d script" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:736 +msgid "" +"When invoked during startup or shutdown, an [.filename]#rc.d# script is " +"supposed to act on the entire subsystem it is responsible for. E.g., [." +"filename]#/etc/rc.d/netif# should start or stop all network interfaces " +"described by man:rc.conf[5]. Either task can be uniquely indicated by a " +"single command argument such as `start` or `stop`. Between startup and " +"shutdown, [.filename]#rc.d# scripts help the admin to control the running " +"system, and it is when the need for more flexibility and precision arises. " +"For instance, the admin may want to add the settings of a new network " +"interface to man:rc.conf[5] and then to start it without interfering with " +"the operation of the existing interfaces. Next time the admin may need to " +"shut down a single network interface. In the spirit of the command line, " +"the respective [.filename]#rc.d# script calls for an extra argument, the " +"interface name." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:739 +msgid "" +"Fortunately, man:rc.subr[8] allows for passing any number of arguments to " +"script's methods (within the system limits). Due to that, the changes in " +"the script itself can be minimal." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:744 +msgid "" +"How can man:rc.subr[8] gain access to the extra command-line arguments. " +"Should it just grab them directly? Not by any means. Firstly, an man:sh[1] " +"function has no access to the positional parameters of its caller, but man:" +"rc.subr[8] is just a sack of such functions. Secondly, the good manner of [." +"filename]#rc.d# dictates that it is for the main script to decide which " +"arguments are to be passed to its methods." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:748 +msgid "" +"So the approach adopted by man:rc.subr[8] is as follows: `run_rc_command` " +"passes on all its arguments but the first one to the respective method " +"verbatim. The first, omitted, argument is the name of the method itself: " +"`start`, `stop`, etc. It will be shifted out by `run_rc_command`, so what " +"is `$2` in the original command line will be presented as `$1` to the " +"method, and so on." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:751 +msgid "" +"To illustrate this opportunity, let us modify the primitive dummy script so " +"that its messages depend on the additional arguments supplied. Here we go:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:763 +#, no-wrap +msgid "" +"name=\"dummy\"\n" +"start_cmd=\"${name}_start\"\n" +"stop_cmd=\":\"\n" +"kiss_cmd=\"${name}_kiss\"\n" +"extra_commands=\"kiss\"\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:772 +#, no-wrap +msgid "" +"dummy_start()\n" +"{\n" +" if [ $# -gt 0 ]; then <.>\n" +" echo \"Greeting message: $*\"\n" +" else\n" +" echo \"Nothing started.\"\n" +" fi\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:788 +#, no-wrap +msgid "" +"dummy_kiss()\n" +"{\n" +" echo -n \"A ghost gives you a kiss\"\n" +" if [ $# -gt 0 ]; then <.>\n" +" echo -n \" and whispers: $*\"\n" +" fi\n" +" case \"$*\" in\n" +" *[.!?])\n" +" echo\n" +" ;;\n" +" *)\n" +" echo .\n" +" ;;\n" +" esac\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:791 +#, no-wrap +msgid "" +"load_rc_config $name\n" +"run_rc_command \"$@\" <.>\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:794 +msgid "What essential changes can we notice in the script?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:799 +msgid "" +"➊ All arguments you type after `start` can end up as positional " +"parameters to the respective method. We can use them in any way according " +"to our task, skills, and fancy. In the current example, we just pass all of " +"them to man:echo[1] as one string in the next line - note `$*` within the " +"double quotes. Here is how the script can be invoked now:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:804 +#, no-wrap +msgid "" +"# /etc/rc.d/dummy start\n" +"Nothing started.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:807 +#, no-wrap +msgid "" +"# /etc/rc.d/dummy start Hello world!\n" +"Greeting message: Hello world!\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:811 +msgid "" +"➋ The same applies to any method our script provides, not only to a " +"standard one. We have added a custom method named `kiss`, and it can take " +"advantage of the extra arguments not less than `start` does. E.g.:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:816 +#, no-wrap +msgid "" +"# /etc/rc.d/dummy kiss\n" +"A ghost gives you a kiss.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:819 +#, no-wrap +msgid "" +"# /etc/rc.d/dummy kiss Once I was Etaoin Shrdlu...\n" +"A ghost gives you a kiss and whispers: Once I was Etaoin Shrdlu...\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:822 +msgid "" +"➌ If we want just to pass all extra arguments to any method, we can " +"merely substitute `\"$@\"` for `\"$1\"` in the last line of our script, " +"where we invoke `run_rc_command`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:828 +msgid "" +"An man:sh[1] programmer ought to understand the subtle difference between " +"`$*` and `$@` as the ways to designate all positional parameters. For its " +"in-depth discussion, refer to a good handbook on man:sh[1] scripting. _Do " +"not_ use the expressions until you fully understand them because their " +"misuse will result in buggy and insecure scripts." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:835 +msgid "" +"Currently `run_rc_command` may have a bug that prevents it from keeping the " +"original boundaries between arguments. That is, arguments with embedded " +"whitespace may not be processed correctly. The bug stems from `$*` misuse." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/rc-scripting/_index.adoc:838 +#, no-wrap +msgid "Making a script ready for Service Jails" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:841 +msgid "" +"Scripts which start a long running service are suitable for service jails, " +"and should come with a suitable service jail configuration." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:843 +msgid "" +"Some examples of scripts which are not suitable to run in a service jail:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:845 +msgid "" +"any script which in the start command only changes a runtime setting for " +"programs or the kernel," +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:846 +msgid "or tries to mount something," +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:847 +msgid "or finds and deletes files" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:849 +msgid "" +"Scripts not suitable to run in a service jail need to prevent the use within " +"service jails." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:851 +msgid "" +"A script with a long running service which needs to do something listed " +"above before the start or after the stop, can either be split-up into two " +"scripts with dependencies, or use the precommand and postcommand parts of " +"the script to perform this action." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:854 +msgid "" +"By default, only the start and stop parts of a script are run within a " +"service jail, the rest is run outside the jail. As such any setting used in " +"the start/stop parts of the script can not be set from e.g. a precommand." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:856 +msgid "" +"To make a script ready for use with extref:../../books/handbook/jails/" +"#service-jails[Service Jails], only one more config line needs to be " +"inserted:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:866 +#: documentation/content/en/articles/rc-scripting/_index.adoc:899 +#, no-wrap +msgid "" +"name=\"dummy\"\n" +"start_cmd=\"${name}_start\"\n" +"stop_cmd=\":\"\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:868 +#, no-wrap +msgid ": ${dummy_svcj_options:=\"\"} <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:873 +#: documentation/content/en/articles/rc-scripting/_index.adoc:904 +#, no-wrap +msgid "" +"dummy_start()\n" +"{\n" +" echo \"Nothing started.\"\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:880 +msgid "" +"➊ If it makes sense that the script runs in a jail, it must have an " +"overridable service jails configuration. If it does not need network access " +"or access to any other resource which is restricted in jails, an empty " +"config like displayed is enough." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:885 +msgid "" +"Strictly speaking an empty config is not needed, but it explicitly describes " +"that the script is service jails ready, and that it does not need additional " +"jail permissions. As such it is highly recommended to add such an empty " +"config in such a case. The most common option to use is \"net_basic\", " +"which enables the use of the hosts IPv4 and IPv6 addresses. All possible " +"options are explained in man:rc.conf[5]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:887 +msgid "" +"If a setting for the start/stop depends on variables from the rc-framework " +"(e.g., set inside man:rc.conf[5]), this needs to be handled by " +"``load_rc_config`` and ``run_rc_command`` instead of inside a precommand." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:889 +msgid "" +"If for some reason a script can not be run within a service jail, e.g., " +"because it is not possible to run or it does not make sense to run it in a " +"jail, use the following:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:908 +#, no-wrap +msgid "" +"load_rc_config $name\n" +"dummy_svcj=\"NO\"\t\t# does not make sense to run in a svcj <.>\n" +"run_rc_command \"$1\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:911 +msgid "" +"➊ The disabling needs to happen after the ``load_rc_config`` call, " +"else a man:rc.conf[5] setting may override it." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/rc-scripting/_index.adoc:913 +#, no-wrap +msgid "Advanced rc-scripting: Instancing" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:921 +msgid "" +"Sometimes it is useful to run several instances of a service. Typically you " +"want to be able to start/stop such instances independently, and you want to " +"have a separate config file for each instance. Each instance should be " +"started at boot, survive updates, and benefit from updates." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:923 +msgid "Here is an example of a rc script which supports this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:941 +#, no-wrap +msgid "" +"#\n" +"# PROVIDE: dummy\n" +"# REQUIRE: NETWORKING SERVERS\n" +"# KEYWORD: shutdown\n" +"#\n" +"# Add these following line to /etc/rc.conf.local or /etc/rc.conf\n" +"# to enable this service:\n" +"#\n" +"# dummy_enable (bool):\tSet it to YES to enable dummy on startup.\n" +"#\t\t\tDefault: NO\n" +"# dummy_user (string):\tUser account to run with.\n" +"#\t\t\tDefault: www\n" +"#\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:954 +#, no-wrap +msgid "" +"case $0 in <.>\n" +"/etc/rc*)\n" +"\t# during boot (shutdown) $0 is /etc/rc (/etc/rc.shutdown),\n" +"\t# so get the name of the script from $_file\n" +"\tname=$_file\n" +"\t;;\n" +"*)\n" +"\tname=$0\n" +"\t;;\n" +"esac\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:959 +#, no-wrap +msgid "" +"name=${name##*/} <.>\n" +"rcvar=\"${name}_enable\" <.>\n" +"desc=\"Short description of this service\"\n" +"command=\"/usr/local/sbin/dummy\"\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:961 +#, no-wrap +msgid "load_rc_config \"$name\"\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:965 +#, no-wrap +msgid "" +"eval \"${rcvar}=\\${${rcvar}:-'NO'}\" <.>\n" +"eval \"${name}_svcj_options=\\${${name}_svcj_options:-'net_basic'}\" <.>\n" +"eval \"_dummy_user=\\${${name}_user:-'www'}\" <.>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:970 +#, no-wrap +msgid "" +"_dummy_configname=/usr/local/etc/${name}.cfg <.>\n" +"pidfile=/var/run/dummy/${name}.pid\n" +"required_files ${_dummy_configname}\n" +"command_args=\"-u ${_dummy_user} -c ${_dummy_configfile} -p ${pidfile}\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:978 +msgid "" +"➊ and ➋ make sure to set the name variable to the man:" +"basename[1] of the script name. If the filename is [.filename]#/usr/local/" +"etc/rc.d/dummy#, name is set to [.filename]#dummy#. This way changing the " +"filename of the rc script changes automatically the content of the name " +"variable." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:981 +msgid "" +"➌ specifies the variable name which is used in [.filename]#rc.conf# " +"to enable this service based upon the filename of this script. In this " +"example this resolves to dummy_enable." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:983 +msgid "➍ makes sure the default for the _enable variable is NO." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:986 +msgid "" +"➎ is an example of having some defaults for service specific " +"framework variables, in this case the service jails options." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:988 +msgid "" +"➏ and ➐ set variables internal to the script (pay attention to " +"the underscore in front of _dummy_user to make it different from dummy_user " +"which can be set in [.filename]#rc.conf#)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:991 +msgid "" +"The part in ➎ is for variables which are not used inside the script " +"itself but in the rc framework. All the variables which are used as " +"parameters somewhere in the script are assigned to a generic variable like " +"in ➐ to make it more easy to reference them (no need to eval them at " +"each place of use)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:994 +msgid "" +"This script will now behave differently if the start script has a different " +"name. This allows to create symlinks to it:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/rc-scripting/_index.adoc:1000 +#, no-wrap +msgid "" +"# ln -s dummy /usr/local/etc/rc.d/dummy_foo\n" +"# sysrc dummy_foo_enable=YES\n" +"# service dummy_foo start\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:1005 +msgid "" +"The above creates an instance of the dummy service with the name dummy_foo. " +"It does not use the config file [.filename]#/usr/local/etc/dummy.cfg# but " +"the config file [.filename]#/usr/local/etc/dummy_foo.cfg# (➐), and it " +"uses the PID file [.filename]#/var/run/dummy/dummy_foo.pid# instead of [." +"filename]#/var/run/dummy/dummy.pid#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:1012 +msgid "" +"The services dummy and dummy_foo can be managed independently of each other, " +"while having the start script update itself on package update (due to the " +"symlink). This does not update the REQUIRE line, as such there is no easy " +"way of depending on a specific instance. To depend upon a specific instance " +"in the startup order a copy needs to be made instead of using a symlink. " +"This prevents the automatic pick-up of changes to the start script when an " +"update is installed." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/rc-scripting/_index.adoc:1014 +#, no-wrap +msgid "Further reading" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:1018 +msgid "" +"[[lukem]]http://www.mewburn.net/luke/papers/rc.d.pdf[The original article by " +"Luke Mewburn] offers a general overview of [.filename]#rc.d# and detailed " +"rationale for its design decisions. It provides insight on the whole [." +"filename]#rc.d# framework and its place in a modern BSD operating system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:1021 +msgid "" +"[[manpages]]The manual pages man:rc[8], man:rc.subr[8], and man:rcorder[8] " +"document the [.filename]#rc.d# components in great detail. You cannot fully " +"use the [.filename]#rc.d# power without studying the manual pages and " +"referring to them while writing your own scripts." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/rc-scripting/_index.adoc:1025 +msgid "" +"The major source of working, real-life examples is [.filename]#/etc/rc.d# in " +"a live system. Its contents are easy and pleasant to read because most " +"rough corners are hidden deep in man:rc.subr[8]. Keep in mind though that " +"the [.filename]#/etc/rc.d# scripts were not written by angels, so they might " +"suffer from bugs and suboptimal design decisions. Now you can improve them!" +msgstr "" diff --git a/documentation/content/en/articles/releng/_index.adoc b/documentation/content/en/articles/releng/_index.adoc index aea32e4591..56cacf4f0f 100644 --- a/documentation/content/en/articles/releng/_index.adoc +++ b/documentation/content/en/articles/releng/_index.adoc @@ -4,7 +4,7 @@ authors: - author: Murray Stokely email: murray@FreeBSD.org webpage: https://people.FreeBSD.org/~murray/ -description: This paper describes the approach used by past the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System +description: This paper describes the approach previously used by the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System trademarks: ["freebsd", "intel", "general"] tags: ["Release", "Engineering", "Historical", "FreeBSD"] --- @@ -64,7 +64,7 @@ The development of FreeBSD is a very open process. FreeBSD is comprised of contributions from thousands of people around the world. The FreeBSD Project provides Subversion footnote:[Subversion, http://subversion.apache.org] access to the general public so that others can have access to log messages, diffs (patches) between development branches, and other productivity enhancements that formal source code management provides. This has been a huge help in attracting more talented developers to FreeBSD. -However, I think everyone would agree that chaos would soon manifest if write access to the main repository was opened up to everyone on the Internet. +However, I think everyone would agree that chaos would soon manifest if write access to the main repository was opened up to everyone on the Internet. Therefore only a "select" group of nearly 300 people are given write access to the Subversion repository. These extref:{contributors}[FreeBSD committers, staff-committers]footnote:[extref:{contributors}[FreeBSD committers, staff-committers]] are usually the people who do the bulk of FreeBSD development. An elected link:https://www.FreeBSD.org/administration/#t-core[Core Team]footnote:[link:https://www.FreeBSD.org/administration/#t-core[FreeBSD Core Team]] of developers provide some level of direction over the project. @@ -85,11 +85,11 @@ This means that a user application compiled on an older version of the system fr The ABI stability has improved greatly from the compared to previous releases. In most cases, binaries from the older _STABLE_ systems run unmodified on newer systems, including __HEAD__, assuming that the system management interfaces are not used. -In the interim period between releases, weekly snapshots are built automatically by the FreeBSD Project build machines and made available for download from `ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/`. -The widespread availability of binary release snapshots, and the tendency of our user community to keep up with -STABLE development with Subversion and "`make buildworld`" footnote:[extref:{handbook}[Rebuilding world, makeworld]] helps to keep FreeBSD-STABLE in a very reliable condition even before the quality assurance activities ramp up pending a major release. +In the interim period between releases, weekly snapshots are built automatically by the FreeBSD Project build machines and made available for download from `https:/download.FreeBSD.org/snapshots/`. +The widespread availability of binary release snapshots, and the tendency of our user community to keep up with -STABLE development with Subversion and "`make buildworld`" footnote:[extref:{handbook}cutting-edge[Rebuilding world, makeworld]] helps to keep FreeBSD-STABLE in a very reliable condition even before the quality assurance activities ramp up pending a major release. In addition to installation ISO snapshots, weekly virtual machine images are also provided for use with VirtualBox, qemu, or other popular emulation software. -The virtual machine images can be downloaded from `ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/VM-IMAGES/`. +The virtual machine images can be downloaded from `https://download.FreeBSD.org/snapshots/VM-IMAGES/`. The virtual machine images are approximately 150MB man:xz[1] compressed, and contain a 10GB sparse filesystem when attached to a virtual machine. @@ -105,19 +105,19 @@ In addition to source updates via Subversion, binary patchkits are available to The following sections of this article describe: -<<release-proc>>:: +crossref:releng[release-proc, Release Process]:: The different phases of the release engineering process leading up to the actual system build. -<<release-build>>:: +crossref:releng[release-build, Release Building]:: The actual build process. -<<extensibility>>:: +crossref:releng[extensibility, Extensibility]:: How the base release may be extended by third parties. -<<lessons-learned>>:: +crossref:releng[lessons-learned, Lessons Learned from FreeBSD 4.4]:: Some of the lessons learned through the release of FreeBSD 4.4. -<<future>>:: +crossref:releng[future, Future Directions]:: Future directions of development. [[release-proc]] @@ -235,7 +235,7 @@ The release notes and errata files also need to be adjusted for the new release * [.filename]#src/release/doc/en_US.ISO8859-1/errata/article.xml# Sysinstall should be updated to note the number of available ports and the amount of disk space required for the Ports Collection. -footnote:[FreeBSD Ports Collection https://www.FreeBSD.org/ports] +footnote:[FreeBSD Ports Collection https://ports.FreeBSD.org] This information is currently kept in [.filename]#src/usr.sbin/bsdinstall/dist.c#. After the release has been built, a number of files should be updated to announce the release to the world. @@ -263,7 +263,7 @@ When the final release is ready, the following command will create the `release/ The Documentation and Ports managers are responsible for tagging their respective trees with the `tags/RELEASE_9_2_0` tag. When the Subversion `svn cp` command is used to create a __release tag__, this identifies the source at a specific point in time. -By creating tags, we ensure that future release builders will always be able to use the exact same source we used to create the official FreeBSD Project releases. +By creating tags, we ensure that future release builders will always be able to use the same source we used to create the official FreeBSD Project releases. [[release-build]] == Release Building @@ -317,13 +317,13 @@ For example, it would be unwise to distribute binaries that were built on a syst === Contributed Software ("ports") -The https://www.FreeBSD.org/ports[FreeBSD Ports collection] is a collection of over {numports} third-party software packages available for FreeBSD. +The https://ports.FreeBSD.org[FreeBSD Ports collection] is a collection of over {numports} third-party software packages available for FreeBSD. The `{portmgr}` is responsible for maintaining a consistent ports tree that can be used to create the binary packages that accompany official FreeBSD releases. === Release ISOs Starting with FreeBSD 4.4, the FreeBSD Project decided to release all four ISO images that were previously sold on the _BSDi/Wind River Systems/FreeBSD Mall_ "official" CDROM distributions. -Each of the four discs must contain a [.filename]#README.TXT# file that explains the contents of the disc, a [.filename]#CDROM.INF# file that provides meta-data for the disc so that man:bsdinstall[8] can validate and use the contents, and a [.filename]#filename.txt# file that provides a manifest for the disc. +Each of the four discs must contain a [.filename]#README.TXT# file that explains the contents of the disc, a [.filename]#CDROM.INF# file that provides meta-data for the disc so that man:bsdinstall[8] can validate and use the contents, and a [.filename]#filename.txt# file that provides a manifest for the disc. This _manifest_ can be created with a simple command: [source,shell] @@ -355,7 +355,7 @@ This disc should be bootable and should also contain a compressed copy of the CV Sysinstall supports multiple volume package installations. This requires that each disc have an [.filename]#INDEX# file containing all of the packages on all volumes of a set, along with an extra field that indicates which volume that particular package is on. -Each volume in the set must also have the `CD_VOLUME` variable set in the [.filename]#cdrom.inf# file so that bsdinstall can tell which volume is which. +Each volume in the set must also have the `CD_VOLUME` variable set in the [.filename]#cdrom.inf# file so that bsdinstall can tell which volume is which. When a user attempts to install a package that is not on the current disc, bsdinstall will prompt the user to insert the appropriate one. [[distribution]] @@ -403,7 +403,7 @@ Coming soon: Tips for sending FreeBSD ISOs to a replicator and quality assurance [[extensibility]] == Extensibility -Although FreeBSD forms a complete operating system, there is nothing that forces you to use the system exactly as we have packaged it up for distribution. +Although FreeBSD forms a complete operating system, there is nothing that forces you to use the system exactly as we have packaged it up for distribution. We have tried to design the system to be as extensible as possible so that it can serve as a platform that other commercial products can be built on top of. The only "rule" we have about this is that if you are going to distribute FreeBSD with non-trivial changes, we encourage you to document your enhancements! The FreeBSD community can only help support users of the software we provide. @@ -412,7 +412,7 @@ We certainly encourage innovation in the form of advanced installation and admin === Scripting `bsdinstall` The FreeBSD system installation and configuration tool, man:bsdinstall[8], can be scripted to provide automated installs for large sites. -This functionality can be used in conjunction with Intel(R) PXE footnote:[extref:{handbook}[Diskless Operation with PXE, network-diskless]] to bootstrap systems from the network. +This functionality can be used in conjunction with Intel(R) PXE footnote:[extref:{handbook}advanced-networking[Diskless Operation with PXE, network-diskless]] to bootstrap systems from the network. [[lessons-learned]] == Lessons Learned from FreeBSD 4.4 @@ -424,7 +424,7 @@ The security officer was very involved in the last week of the process as severa A total of over _500_ emails were sent to the `{re}` in little over a month. Our user community has made it very clear that the security and stability of a FreeBSD release should not be sacrificed for any self-imposed deadlines or target release dates. -The FreeBSD Project has grown tremendously over its lifetime and the need for standardized release engineering procedures has never been more apparent. +The FreeBSD Project has grown tremendously over its lifetime and the need for standardized release engineering procedures has never been more apparent. This will become even more important as FreeBSD is ported to new platforms. [[future]] diff --git a/documentation/content/en/articles/releng/_index.po b/documentation/content/en/articles/releng/_index.po new file mode 100644 index 0000000000..ba3b61c37a --- /dev/null +++ b/documentation/content/en/articles/releng/_index.po @@ -0,0 +1,1253 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-12-29 08:30-0500\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/releng/_index.adoc:1 +#, no-wrap +msgid "This paper describes the approach previously used by the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System" +msgstr "" + +#. type: YAML Front Matter: title +#: documentation/content/en/articles/releng/_index.adoc:1 +#, no-wrap +msgid "Legacy FreeBSD Release Engineering" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/releng/_index.adoc:12 +#, no-wrap +msgid "FreeBSD Release Engineering" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:45 +msgid "Abstract" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/releng/_index.adoc:51 +msgid "" +"This document is outdated and does not accurately describe the current " +"release procedures of the FreeBSD Release Engineering team. It is retained " +"for historical purposes. The current procedures used by the FreeBSD Release " +"Engineering team are available in the extref:{freebsd-releng}[FreeBSD " +"Release Engineering] article." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:55 +msgid "" +"This paper describes the approach used by the FreeBSD release engineering " +"team to make production quality releases of the FreeBSD Operating System. " +"It details the methodology used for the official FreeBSD releases and " +"describes the tools available for those interested in producing customized " +"FreeBSD releases for corporate rollouts or commercial productization." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:57 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/releng/_index.adoc:61 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:71 +msgid "" +"The development of FreeBSD is a very open process. FreeBSD is comprised of " +"contributions from thousands of people around the world. The FreeBSD " +"Project provides Subversion footnote:[Subversion, http://subversion.apache." +"org] access to the general public so that others can have access to log " +"messages, diffs (patches) between development branches, and other " +"productivity enhancements that formal source code management provides. This " +"has been a huge help in attracting more talented developers to FreeBSD. " +"However, I think everyone would agree that chaos would soon manifest if " +"write access to the main repository was opened up to everyone on the " +"Internet. Therefore only a \"select\" group of nearly 300 people are given " +"write access to the Subversion repository. These extref:{contributors}" +"[FreeBSD committers, staff-committers]footnote:[extref:{contributors}" +"[FreeBSD committers, staff-committers]] are usually the people who do the " +"bulk of FreeBSD development. An elected link:https://www.FreeBSD.org/" +"administration/#t-core[Core Team]footnote:[link:https://www.FreeBSD.org/" +"administration/#t-core[FreeBSD Core Team]] of developers provide some level " +"of direction over the project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:76 +msgid "" +"The rapid pace of `FreeBSD` development makes the main development branch " +"unsuitable for the everyday use by the general public. In particular, " +"stabilizing efforts are required for polishing the development system into a " +"production quality release. To solve this conflict, development continues " +"on several parallel tracks. The main development branch is the _HEAD_ or " +"_trunk_ of our Subversion tree, known as \"FreeBSD-CURRENT\" or \"-CURRENT\" " +"for short." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:82 +msgid "" +"A set of more stable branches are maintained, known as \"FreeBSD-STABLE\" or " +"\"-STABLE\" for short. All branches live in a master Subversion repository " +"maintained by the FreeBSD Project. FreeBSD-CURRENT is the \"bleeding-edge\" " +"of FreeBSD development where all new changes first enter the system. " +"FreeBSD-STABLE is the development branch from which major releases are " +"made. Changes go into this branch at a different pace, and with the general " +"assumption that they have first gone into FreeBSD-CURRENT and have been " +"thoroughly tested by our user community." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:87 +msgid "" +"The term _stable_ in the name of the branch refers to the presumed " +"Application Binary Interface stability, which is promised by the project. " +"This means that a user application compiled on an older version of the " +"system from the same branch works on a newer system from the same branch. " +"The ABI stability has improved greatly from the compared to previous " +"releases. In most cases, binaries from the older _STABLE_ systems run " +"unmodified on newer systems, including __HEAD__, assuming that the system " +"management interfaces are not used." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:90 +msgid "" +"In the interim period between releases, weekly snapshots are built " +"automatically by the FreeBSD Project build machines and made available for " +"download from `https:/download.FreeBSD.org/snapshots/`. The widespread " +"availability of binary release snapshots, and the tendency of our user " +"community to keep up with -STABLE development with Subversion and \"`make " +"buildworld`\" footnote:[extref:{handbook}[Rebuilding world, makeworld]] " +"helps to keep FreeBSD-STABLE in a very reliable condition even before the " +"quality assurance activities ramp up pending a major release." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:93 +msgid "" +"In addition to installation ISO snapshots, weekly virtual machine images are " +"also provided for use with VirtualBox, qemu, or other popular emulation " +"software. The virtual machine images can be downloaded from `https://" +"download.FreeBSD.org/snapshots/VM-IMAGES/`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:95 +msgid "" +"The virtual machine images are approximately 150MB man:xz[1] compressed, and " +"contain a 10GB sparse filesystem when attached to a virtual machine." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:98 +msgid "" +"Bug reports and feature requests are continuously submitted by users " +"throughout the release cycle. Problems reports are entered into our " +"Bugzilla database through the web interface provided at https://www.freebsd." +"org/support/bugreports/[https://www.freebsd.org/support/bugreports/]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:103 +msgid "" +"To service our most conservative users, individual release branches were " +"introduced with FreeBSD 4.3. These release branches are created shortly " +"before a final release is made. After the release goes out, only the most " +"critical security fixes and additions are merged onto the release branch. " +"In addition to source updates via Subversion, binary patchkits are available " +"to keep systems on the _releng/X.Y_ branches updated." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/releng/_index.adoc:104 +#, no-wrap +msgid "What This Article Describes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:107 +msgid "The following sections of this article describe:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/releng/_index.adoc:108 +#, no-wrap +msgid "crossref:releng[release-proc, Release Process]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:110 +msgid "" +"The different phases of the release engineering process leading up to the " +"actual system build." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/releng/_index.adoc:111 +#, no-wrap +msgid "crossref:releng[release-build, Release Building]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:113 +msgid "The actual build process." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/releng/_index.adoc:114 +#, no-wrap +msgid "crossref:releng[extensibility, Extensibility]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:116 +msgid "How the base release may be extended by third parties." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/releng/_index.adoc:117 +#, no-wrap +msgid "crossref:releng[lessons-learned, Lessons Learned from FreeBSD 4.4]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:119 +msgid "Some of the lessons learned through the release of FreeBSD 4.4." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/releng/_index.adoc:120 +#, no-wrap +msgid "crossref:releng[future, Future Directions]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:122 +msgid "Future directions of development." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/releng/_index.adoc:124 +#, no-wrap +msgid "Release Process" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:129 +msgid "" +"New releases of FreeBSD are released from the -STABLE branch at " +"approximately four month intervals. The FreeBSD release process begins to " +"ramp up 70-80 days before the anticipated release date when the release " +"engineer sends an email to the development mailing lists to remind " +"developers that they only have 15 days to integrate new changes before the " +"code freeze. During this time, many developers perform what have become " +"known as \"MFC sweeps\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:133 +msgid "" +"MFC stands for \"Merge From CURRENT\" and it describes the process of " +"merging a tested change from our -CURRENT development branch to our -STABLE " +"branch. Project policy requires any change to be first applied to trunk, " +"and merged to the -STABLE branches after sufficient external testing was " +"done by -CURRENT users (developers are expected to extensively test the " +"change before committing to -CURRENT, but it is impossible for a person to " +"exercise all usages of the general-purpose operating system). Minimal MFC " +"period is 3 days, which is typically used only for trivial or critical " +"bugfixes." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/releng/_index.adoc:134 +#, no-wrap +msgid "Code Review" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:140 +msgid "" +"Sixty days before the anticipated release, the source repository enters a " +"\"code freeze\". During this time, all commits to the -STABLE branch must " +"be approved by `{re}`. The approval process is technically enforced by a " +"pre-commit hook. The kinds of changes that are allowed during this period " +"include:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:142 +msgid "Bug fixes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:143 +msgid "Documentation updates." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:144 +msgid "Security-related fixes of any kind." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:145 +msgid "Minor changes to device drivers, such as adding new Device IDs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:146 +msgid "Driver updates from the vendors." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:147 +msgid "" +"Any additional change that the release engineering team feels is justified, " +"given the potential risk." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:151 +msgid "" +"Shortly after the code freeze is started, a _BETA1_ image is built and " +"released for widespread testing. During the code freeze, at least one beta " +"image or release candidate is released every two weeks until the final " +"release is ready. During the days preceding the final release, the release " +"engineering team is in constant communication with the security-officer " +"team, the documentation maintainers, and the port maintainers to ensure that " +"all of the different components required for a successful release are " +"available." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:154 +msgid "" +"After the quality of the BETA images is satisfying enough, and no large and " +"potentially risky changes are planned, the release branch is created and " +"_Release Candidate_ (RC) images are built from the release branch, instead " +"of the BETA images from the STABLE branch. Also, the freeze on the STABLE " +"branch is lifted and release branch enters a \"hard code freeze\" where it " +"becomes much harder to justify new changes to the system unless a serious " +"bug-fix or security issue is involved." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/releng/_index.adoc:155 +#, no-wrap +msgid "Final Release Checklist" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:158 +msgid "" +"When several BETA images have been made available for widespread testing and " +"all major issues have been resolved, the final release \"polishing\" can " +"begin." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/releng/_index.adoc:160 +#, no-wrap +msgid "Creating the Release Branch" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/releng/_index.adoc:165 +msgid "" +"In all examples below, `$FSVN` refers to the location of the FreeBSD " +"Subversion repository, `svn+ssh://svn.FreeBSD.org/base/`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:169 +msgid "" +"The layout of FreeBSD branches in Subversion is described in the extref:" +"{committers-guide}[Committer's Guide, subversion-primer-base-layout]. The " +"first step in creating a branch is to identify the revision of the `stable/" +"_X_` sources that you want to branch _from_." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/releng/_index.adoc:173 +#, no-wrap +msgid "# svn log -v $FSVN/stable/9\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:176 +msgid "The next step is to create the _release branch_" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/releng/_index.adoc:180 +#, no-wrap +msgid "# svn cp $FSVN/stable/9@REVISION $FSVN/releng/9.2\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:183 +msgid "This branch can be checked out:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/releng/_index.adoc:187 +#, no-wrap +msgid "# svn co $FSVN/releng/9.2 src\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/releng/_index.adoc:192 +msgid "" +"Creating the `releng` branch and `release` tags is done by the link:https://" +"www.FreeBSD.org/administration/#t-re[Release Engineering Team]." +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/articles/releng/_index.adoc:194 +#, no-wrap +msgid "FreeBSD Development Branch" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/releng/_index.adoc:194 +#, no-wrap +msgid "branches-head.png" +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/articles/releng/_index.adoc:196 +#, no-wrap +msgid "FreeBSD 3.x STABLE Branch" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/releng/_index.adoc:196 +#, no-wrap +msgid "branches-releng3.png" +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/articles/releng/_index.adoc:198 +#, no-wrap +msgid "FreeBSD 4.x STABLE Branch" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/releng/_index.adoc:198 +#, no-wrap +msgid "branches-releng4.png" +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/articles/releng/_index.adoc:200 +#, no-wrap +msgid "FreeBSD 5.x STABLE Branch" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/releng/_index.adoc:200 +#, no-wrap +msgid "branches-releng5.png" +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/articles/releng/_index.adoc:202 +#, no-wrap +msgid "FreeBSD 6.x STABLE Branch" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/releng/_index.adoc:202 +#, no-wrap +msgid "branches-releng6.png" +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/articles/releng/_index.adoc:204 +#, no-wrap +msgid "FreeBSD 7.x STABLE Branch" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/releng/_index.adoc:204 +#, no-wrap +msgid "branches-releng7.png" +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/articles/releng/_index.adoc:206 +#, no-wrap +msgid "FreeBSD 8.x STABLE Branch" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/releng/_index.adoc:206 +#, no-wrap +msgid "branches-releng8.png" +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/articles/releng/_index.adoc:208 +#, no-wrap +msgid "FreeBSD 9.x STABLE Branch" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/releng/_index.adoc:208 +#, no-wrap +msgid "branches-releng9.png" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/releng/_index.adoc:211 +#, no-wrap +msgid "Bumping up the Version Number" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:214 +msgid "" +"Before the final release can be tagged, built, and released, the following " +"files need to be modified to reflect the correct version of FreeBSD:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:216 +msgid "[.filename]#doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:217 +msgid "[.filename]#doc/en_US.ISO8859-1/books/porters-handbook/book.xml#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:218 +msgid "[.filename]#doc/en_US.ISO8859-1/htdocs/cgi/ports.cgi#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:219 +msgid "[.filename]#ports/Tools/scripts/release/config#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:220 +msgid "[.filename]#doc/shared/xml/freebsd.ent#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:221 +msgid "[.filename]#src/Makefile.inc1#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:222 +msgid "[.filename]#src/UPDATING#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:223 +msgid "[.filename]#src/gnu/usr.bin/groff/tmac/mdoc.local#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:224 +msgid "[.filename]#src/release/Makefile#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:225 +msgid "[.filename]#src/release/doc/en_US.ISO8859-1/shared/xml/release.dsl#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:226 +msgid "[.filename]#src/release/doc/shared/examples/Makefile.relnotesng#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:227 +msgid "[.filename]#src/release/doc/shared/xml/release.ent#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:228 +msgid "[.filename]#src/sys/conf/newvers.sh#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:229 +msgid "[.filename]#src/sys/sys/param.h#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:230 +msgid "[.filename]#src/usr.sbin/pkg_install/add/main.c#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:231 +msgid "[.filename]#doc/en_US.ISO8859-1/htdocs/search/opensearch/man.xml#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:233 +msgid "" +"The release notes and errata files also need to be adjusted for the new " +"release (on the release branch) and truncated appropriately (on the stable/" +"current branch):" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:235 +msgid "[.filename]#src/release/doc/en_US.ISO8859-1/relnotes/common/new.xml#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:236 +msgid "[.filename]#src/release/doc/en_US.ISO8859-1/errata/article.xml#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:240 +msgid "" +"Sysinstall should be updated to note the number of available ports and the " +"amount of disk space required for the Ports Collection. footnote:[FreeBSD " +"Ports Collection https://ports.FreeBSD.org] This information is currently " +"kept in [.filename]#src/usr.sbin/bsdinstall/dist.c#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:243 +msgid "" +"After the release has been built, a number of files should be updated to " +"announce the release to the world. These files are relative to `head/` " +"within the `doc/` subversion tree." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:245 +msgid "[.filename]#share/images/articles/releng/branches-relengX.pic#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:246 +msgid "[.filename]#head/shared/xml/release.ent#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:247 +msgid "[.filename]#en_US.ISO8859-1/htdocs/releases/*#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:248 +msgid "[.filename]#en_US.ISO8859-1/htdocs/releng/index.xml#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:249 +msgid "[.filename]#share/xml/news.xml#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:251 +msgid "Additionally, update the \"BSD Family Tree\" file:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:253 +msgid "[.filename]#src/shared/misc/bsd-family-tree#" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/releng/_index.adoc:254 +#, no-wrap +msgid "Creating the Release Tag" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:257 +msgid "" +"When the final release is ready, the following command will create the " +"`release/9.2.0` tag." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/releng/_index.adoc:261 +#, no-wrap +msgid "# svn cp $FSVN/releng/9.2 $FSVN/release/9.2.0\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:264 +msgid "" +"The Documentation and Ports managers are responsible for tagging their " +"respective trees with the `tags/RELEASE_9_2_0` tag." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:267 +msgid "" +"When the Subversion `svn cp` command is used to create a __release tag__, " +"this identifies the source at a specific point in time. By creating tags, " +"we ensure that future release builders will always be able to use the same " +"source we used to create the official FreeBSD Project releases." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/releng/_index.adoc:269 +#, no-wrap +msgid "Release Building" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:280 +msgid "" +"FreeBSD \"releases\" can be built by anyone with a fast machine and access " +"to a source repository. (That should be everyone, since we offer Subversion " +"access! See the extref:{handbook}[Subversion section in the Handbook, svn] " +"for details.) The _only_ special requirement is that the man:md[4] device " +"must be available. If the device is not loaded into your kernel, then the " +"kernel module should be automatically loaded when man:mdconfig[8] is " +"executed during the boot media creation phase. All of the tools necessary " +"to build a release are available from the Subversion repository in [." +"filename]#src/release#. These tools aim to provide a consistent way to " +"build FreeBSD releases. A complete release can actually be built with only " +"a single command, including the creation of ISO images suitable for burning " +"to CDROM or DVD, and an FTP install directory. man:release[7] fully " +"documents the `src/release/generate-release.sh` script which is used to " +"build a release. `generate-release.sh` is a wrapper around the Makefile " +"target: `make release`." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/releng/_index.adoc:281 +#, no-wrap +msgid "Building a Release" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:285 +msgid "" +"man:release[7] documents the exact commands required to build a FreeBSD " +"release. The following sequences of commands can build an 9.2.0 release:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/releng/_index.adoc:290 +#, no-wrap +msgid "" +"# cd /usr/src/release\n" +"# sh generate-release.sh release/9.2.0 /local3/release\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:293 +msgid "" +"After running these commands, all prepared release files are available in [." +"filename]#/local3/release/R# directory." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:295 +msgid "" +"The release [.filename]#Makefile# can be broken down into several distinct " +"steps." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:297 +msgid "" +"Creation of a sanitized system environment in a separate directory hierarchy " +"with \"`make installworld`\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:298 +msgid "" +"Checkout from Subversion of a clean version of the system source, " +"documentation, and ports into the release build hierarchy." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:299 +msgid "" +"Population of [.filename]#/etc# and [.filename]#/dev# in the chrooted " +"environment." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:300 +msgid "" +"chroot into the release build hierarchy, to make it harder for the outside " +"environment to taint this build." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:301 +msgid "`make world` in the chrooted environment." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:302 +msgid "Build of Kerberos-related binaries." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:303 +msgid "Build [.filename]#GENERIC# kernel." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:304 +msgid "" +"Creation of a staging directory tree where the binary distributions will be " +"built and packaged." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:305 +msgid "" +"Build and installation of the documentation toolchain needed to convert the " +"documentation source (SGML) into HTML and text documents that will accompany " +"the release." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:306 +msgid "" +"Build and installation of the actual documentation (user manuals, tutorials, " +"release notes, hardware compatibility lists, and so on.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:307 +msgid "Package up distribution tarballs of the binaries and sources." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:308 +msgid "Create FTP installation hierarchy." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:309 +msgid "_(optionally)_ Create ISO images for CDROM/DVD media." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:311 +msgid "" +"For more information about the release build infrastructure, please see man:" +"release[7]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/releng/_index.adoc:316 +msgid "" +"It is important to remove any site-specific settings from [.filename]#/etc/" +"make.conf#. For example, it would be unwise to distribute binaries that " +"were built on a system with `CPUTYPE` set to a specific processor." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/releng/_index.adoc:318 +#, no-wrap +msgid "Contributed Software (\"ports\")" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:322 +msgid "" +"The https://ports.FreeBSD.org[FreeBSD Ports collection] is a collection of " +"over {numports} third-party software packages available for FreeBSD. The " +"`{portmgr}` is responsible for maintaining a consistent ports tree that can " +"be used to create the binary packages that accompany official FreeBSD " +"releases." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/releng/_index.adoc:323 +#, no-wrap +msgid "Release ISOs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:328 +msgid "" +"Starting with FreeBSD 4.4, the FreeBSD Project decided to release all four " +"ISO images that were previously sold on the _BSDi/Wind River Systems/FreeBSD " +"Mall_ \"official\" CDROM distributions. Each of the four discs must contain " +"a [.filename]#README.TXT# file that explains the contents of the disc, a [." +"filename]#CDROM.INF# file that provides meta-data for the disc so that man:" +"bsdinstall[8] can validate and use the contents, and a [.filename]#filename." +"txt# file that provides a manifest for the disc. This _manifest_ can be " +"created with a simple command:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/releng/_index.adoc:332 +#, no-wrap +msgid "/stage/cdrom# find . -type f | sed -e 's/^\\.\\///' | sort > filename.txt\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:335 +msgid "The specific requirements of each CD are outlined below." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/releng/_index.adoc:336 +#, no-wrap +msgid "Disc 1" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:342 +msgid "" +"The first disc is almost completely created by `make release`. The only " +"changes that should be made to the [.filename]#disc1# directory are the " +"addition of a [.filename]#tools# directory, and as many popular third party " +"software packages as will fit on the disc. The [.filename]#tools# directory " +"contains software that allow users to create installation floppies from " +"other operating systems. This disc should be made bootable so that users of " +"modern PCs do not need to create installation floppy disks." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:347 +msgid "" +"If a custom kernel of FreeBSD is to be included, then man:bsdinstall[8] and " +"man:release[7] must be updated to include installation instructions. The " +"relevant code is contained in [.filename]#src/release# and [.filename]#src/" +"usr.sbin/bsdinstall#. Specifically, the file [.filename]#src/release/" +"Makefile#, and [.filename]#dist.c#, [.filename]#dist.h#, [.filename]#menus." +"c#, [.filename]#install.c#, and [.filename]#Makefile# will need to be " +"updated under [.filename]#src/usr.sbin/bsdinstall#. Optionally, you may " +"choose to update [.filename]#bsdinstall.8#." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/releng/_index.adoc:348 +#, no-wrap +msgid "Disc 2" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:353 +msgid "" +"The second disc is also largely created by `make release`. This disc " +"contains a \"live filesystem\" that can be used from man:bsdinstall[8] to " +"troubleshoot a FreeBSD installation. This disc should be bootable and " +"should also contain a compressed copy of the CVS repository in the [." +"filename]#CVSROOT# directory and commercial software demos in the [." +"filename]#commerce# directory." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/releng/_index.adoc:354 +#, no-wrap +msgid "Multi-volume Support" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:360 +msgid "" +"Sysinstall supports multiple volume package installations. This requires " +"that each disc have an [.filename]#INDEX# file containing all of the " +"packages on all volumes of a set, along with an extra field that indicates " +"which volume that particular package is on. Each volume in the set must " +"also have the `CD_VOLUME` variable set in the [.filename]#cdrom.inf# file so " +"that bsdinstall can tell which volume is which. When a user attempts to " +"install a package that is not on the current disc, bsdinstall will prompt " +"the user to insert the appropriate one." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/releng/_index.adoc:362 +#, no-wrap +msgid "Distribution" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/releng/_index.adoc:365 +#, no-wrap +msgid "FTP Sites" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:371 +msgid "" +"When the release has been thoroughly tested and packaged for distribution, " +"the master FTP site must be updated. The official FreeBSD public FTP sites " +"are all mirrors of a master server that is open only to other FTP sites. " +"This site is known as `ftp-master`. When the release is ready, the " +"following files must be modified on `ftp-master`:" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/releng/_index.adoc:372 +#, no-wrap +msgid "[.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:374 +msgid "The installable FTP directory as output from `make release`." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/releng/_index.adoc:375 +#, no-wrap +msgid "[.filename]#/pub/FreeBSD/ports/arch/packages-X.Y-release/#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:377 +msgid "The complete package build for this release." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/releng/_index.adoc:378 +#, no-wrap +msgid "[.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/tools#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:380 +msgid "A symlink to [.filename]#../../../tools#." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/releng/_index.adoc:381 +#, no-wrap +msgid "[.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/packages#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:383 +msgid "A symlink to [.filename]#../../../ports/arch/packages-X.Y-release#." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/releng/_index.adoc:384 +#, no-wrap +msgid "[.filename]#/pub/FreeBSD/releases/arch/ISO-IMAGES/X.Y/X.Y-RELEASE-arch-*.iso#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:387 +msgid "" +"The ISO images. The \"*\" is [.filename]#disc1#, [.filename]#disc2#, etc. " +"Only if there is a [.filename]#disc1# and there is an alternative first " +"installation CD (for example a stripped-down install with no windowing " +"system) there may be a [.filename]#mini# as well." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:389 +msgid "" +"For more information about the distribution mirror architecture of the " +"FreeBSD FTP sites, please see the extref:{hubs}[Mirroring FreeBSD] article." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:397 +msgid "" +"It may take many hours to two days after updating `ftp-master` before a " +"majority of the Tier-1 FTP sites have the new software depending on whether " +"or not a package set got loaded at the same time. It is imperative that the " +"release engineers coordinate with the {mirror-announce} before announcing " +"the general availability of new software on the FTP sites. Ideally the " +"release package set should be loaded at least four days prior to release " +"day. The release bits should be loaded between 24 and 48 hours before the " +"planned release time with \"other\" file permissions turned off. This will " +"allow the mirror sites to download it but the general public will not be " +"able to download it from the mirror sites. Mail should be sent to {mirror-" +"announce} at the time the release bits get posted saying the release has " +"been staged and giving the time that the mirror sites should begin allowing " +"access. Be sure to include a time zone with the time, for example make it " +"relative to GMT." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/releng/_index.adoc:399 +#, no-wrap +msgid "CD-ROM Replication" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:402 +msgid "" +"Coming soon: Tips for sending FreeBSD ISOs to a replicator and quality " +"assurance measures to be taken." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/releng/_index.adoc:404 +#, no-wrap +msgid "Extensibility" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:411 +msgid "" +"Although FreeBSD forms a complete operating system, there is nothing that " +"forces you to use the system exactly as we have packaged it up for " +"distribution. We have tried to design the system to be as extensible as " +"possible so that it can serve as a platform that other commercial products " +"can be built on top of. The only \"rule\" we have about this is that if you " +"are going to distribute FreeBSD with non-trivial changes, we encourage you " +"to document your enhancements! The FreeBSD community can only help support " +"users of the software we provide. We certainly encourage innovation in the " +"form of advanced installation and administration tools, for example, but we " +"cannot be expected to answer questions about it." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/releng/_index.adoc:412 +#, no-wrap +msgid "Scripting `bsdinstall`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:416 +msgid "" +"The FreeBSD system installation and configuration tool, man:bsdinstall[8], " +"can be scripted to provide automated installs for large sites. This " +"functionality can be used in conjunction with Intel(R) PXE footnote:[extref:" +"{handbook}[Diskless Operation with PXE, network-diskless]] to bootstrap " +"systems from the network." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/releng/_index.adoc:418 +#, no-wrap +msgid "Lessons Learned from FreeBSD 4.4" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:425 +msgid "" +"The release engineering process for 4.4 formally began on August 1st, 2001. " +"After that date all commits to the `RELENG_4` branch of FreeBSD had to be " +"explicitly approved by the `{re}`. The first release candidate for the x86 " +"architecture was released on August 16, followed by 4 more release " +"candidates leading up to the final release on September 18th. The security " +"officer was very involved in the last week of the process as several " +"security issues were found in the earlier release candidates. A total of " +"over _500_ emails were sent to the `{re}` in little over a month." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:429 +msgid "" +"Our user community has made it very clear that the security and stability of " +"a FreeBSD release should not be sacrificed for any self-imposed deadlines or " +"target release dates. The FreeBSD Project has grown tremendously over its " +"lifetime and the need for standardized release engineering procedures has " +"never been more apparent. This will become even more important as FreeBSD " +"is ported to new platforms." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/releng/_index.adoc:431 +#, no-wrap +msgid "Future Directions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:435 +msgid "" +"It is imperative for our release engineering activities to scale with our " +"growing userbase. Along these lines we are working very hard to document " +"the procedures involved in producing FreeBSD releases." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:437 +msgid "" +"_Parallelism_ - Certain portions of the release build are actually " +"\"embarrassingly parallel\". Most of the tasks are very I/O intensive, so " +"having multiple high-speed disk drives is actually more important than using " +"multiple processors in speeding up the `make release` process. If multiple " +"disks are used for different hierarchies in the man:chroot[2] environment, " +"then the CVS checkout of the [.filename]#ports# and [.filename]#doc# trees " +"can be happening simultaneously as the `make world` on another disk. Using a " +"RAID solution (hardware or software) can significantly decrease the overall " +"build time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:438 +msgid "" +"_Cross-building releases_ - Building IA-64 or Alpha release on x86 hardware? " +"`make TARGET=ia64 release`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:439 +msgid "" +"_Regression Testing_ - We need better automated correctness testing for " +"FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:440 +msgid "" +"_Installation Tools_ - Our installation program has long since outlived its " +"intended life span. Several projects are under development to provide a more " +"advanced installation mechanism. The libh project was one such project that " +"aimed to provide an intelligent new package framework and GUI installation " +"program." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/releng/_index.adoc:442 +#, no-wrap +msgid "Acknowledgements" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/releng/_index.adoc:447 +msgid "" +"I would like to thank Jordan Hubbard for giving me the opportunity to take " +"on some of the release engineering responsibilities for FreeBSD 4.4 and also " +"for all of his work throughout the years making FreeBSD what it is today. " +"Of course the release would not have been possible without all of the " +"release-related work done by `{asami}`, `{steve}`, `{bmah}`, `{nik}`, " +"`{obrien}`, `{kris}`, `{jhb}` and the rest of the FreeBSD development " +"community. I would also like to thank `{rgrimes}`, `{phk}`, and others who " +"worked on the release engineering tools in the very early days of FreeBSD. " +"This article was influenced by release engineering documents from the CSRG " +"footnote:[Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic: link:" +"http://docs.FreeBSD.org/44doc/papers/releng.html[The Release Engineering of " +"4.3BSD]] , the NetBSD Project, footnote:[NetBSD Developer Documentation: " +"Release Engineering http://www.NetBSD.org/developers/releng/index.html] , " +"and John Baldwin's proposed release engineering process notes. footnote:" +"[John Baldwin's FreeBSD Release Engineering Proposal https://people.FreeBSD." +"org/~jhb/docs/releng.txt]" +msgstr "" diff --git a/documentation/content/en/articles/remote-install/_index.adoc b/documentation/content/en/articles/remote-install/_index.adoc index f1bd16bb37..2575637b94 100644 --- a/documentation/content/en/articles/remote-install/_index.adoc +++ b/documentation/content/en/articles/remote-install/_index.adoc @@ -70,7 +70,7 @@ The instructions included in this article will benefit those using services prov [.procedure] ==== -. As we have mentioned in the <<background>> section, many of the reputable server hosting companies provide some kind of rescue system, which is booted from their LAN and accessible over SSH. They usually provide this support in order to help their customers fix broken operating systems. As this article will explain, it is possible to install FreeBSD with the help of these rescue systems. +. As we have mentioned in the crossref:remote-install[background, Background] section, many of the reputable server hosting companies provide some kind of rescue system, which is booted from their LAN and accessible over SSH. They usually provide this support to help their customers fix broken operating systems. As this article will explain, it is possible to install FreeBSD with the help of these rescue systems. + . The next section of this article will describe how to configure, and build minimalistic FreeBSD on the local machine. That version will eventually be running on the remote machine from a ramdisk, which will allow us to install a complete FreeBSD operating system from an FTP mirror using the sysinstall utility. . The rest of this article will describe the installation procedure itself, as well as the configuration of the ZFS file system. @@ -233,7 +233,7 @@ Repeat the following command for each hard drive: Next, create slices and label them with your preferred tool. While it is considered easier to use `sysinstall`, a powerful and also probably less buggy method will be to use standard text-based UNIX(R) tools, such as man:fdisk[8] and man:bsdlabel[8], which will also be covered in this section. -The former option is well documented in the extref:{handbook}[Installing FreeBSD, install-steps] chapter of the FreeBSD Handbook. +The former option is well documented in the extref:{handbook}install[Installing FreeBSD, install-steps] chapter of the FreeBSD Handbook. As it was mentioned in the introduction, this article will present how to set up a system with RAID-1 and ZFS capabilities. Our set up will consist of a small man:gmirror[8] mirrored [.filename]#/# (root), [.filename]#/usr# and [.filename]#/var# dataset, and the rest of the disk space will be allocated for a man:zpool[8] mirrored ZFS file system. Please note, that the ZFS file system will be configured after the FreeBSD operating system is successfully installed and booted. @@ -261,7 +261,7 @@ The following example will describe how to create slices and labels, initialize <.> Write a standard label for each disk including the bootstrap code. -<.> Now, manually edit the label of the given disk. Refer to the man:bsdlabel[8] manual page in order to find out how to create partitions. Create partitions `a` for [.filename]#/# (root) file system, `b` for swap, `d` for [.filename]#/var#, `e` for [.filename]#/usr# and finally `f` which will later be used for ZFS. +<.> Now, manually edit the label of the given disk. Refer to the man:bsdlabel[8] manual page to find out how to create partitions. Create partitions `a` for [.filename]#/# (root) file system, `b` for swap, `d` for [.filename]#/var#, `e` for [.filename]#/usr# and finally `f` which will later be used for ZFS. <.> Import the recently created label for the second hard drive, so both hard drives will be labeled in the same way. @@ -297,7 +297,7 @@ Note that this step is very important and if skipped, `sysinstall` will be unabl ==== Go to the [.guimenuitem]#Distributions# menu, move the cursor with the arrow keys to `Minimal`, and check it by pressing kbd:[Space]. -This article uses the Minimal distribution in order to save network traffic, because the system itself will be installed over ftp. +This article uses the Minimal distribution to save network traffic, because the system itself will be installed over ftp. Exit this menu by choosing `Exit`. [NOTE] @@ -315,9 +315,9 @@ Exit `sysinstall` when it finishes the installation. === Post Installation Steps The FreeBSD operating system should be installed now; however, the process is not finished yet. -It is necessary to perform some post installation steps in order to allow FreeBSD to boot in the future and to be able to log in to the system. +It is necessary to perform some post installation steps to allow FreeBSD to boot in the future and to be able to log in to the system. -You must now man:chroot[8] into the freshly installed system in order to finish the installation. +You must now man:chroot[8] into the freshly installed system to finish the installation. Use the following command: [source,shell] diff --git a/documentation/content/en/articles/remote-install/_index.po b/documentation/content/en/articles/remote-install/_index.po new file mode 100644 index 0000000000..76131829e7 --- /dev/null +++ b/documentation/content/en/articles/remote-install/_index.po @@ -0,0 +1,779 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-12-29 08:30-0500\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/remote-install/_index.adoc:1 +#, no-wrap +msgid "Describes the remote installation of the FreeBSD operating system when the console of the remote system is unavailable" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/remote-install/_index.adoc:1 +#: documentation/content/en/articles/remote-install/_index.adoc:12 +#, no-wrap +msgid "Remote Installation of the FreeBSD Operating System Without a Remote Console" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:45 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:48 +msgid "" +"This article documents the remote installation of the FreeBSD operating " +"system when the console of the remote system is unavailable. The main idea " +"behind this article is the result of a collaboration with `{mm}` with " +"valuable input provided by `{pjd}`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:50 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/remote-install/_index.adoc:54 +#, no-wrap +msgid "Background" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:58 +msgid "" +"There are many server hosting providers in the world, but very few of them " +"are officially supporting FreeBSD. They usually provide support for a " +"Linux(R) distribution to be installed on the servers they offer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:62 +msgid "" +"In some cases, these companies will install your preferred Linux(R) " +"distribution if you request it. Using this option, we will attempt to " +"install FreeBSD. In other cases, they may offer a rescue system which would " +"be used in an emergency. It is possible to use this for our purposes as " +"well." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:64 +msgid "" +"This article covers the basic installation and configuration steps required " +"to bootstrap a remote installation of FreeBSD with RAID-1 and ZFS " +"capabilities." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/remote-install/_index.adoc:66 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:70 +msgid "" +"This section will summarize the purpose of this article and better explain " +"what is covered herein. The instructions included in this article will " +"benefit those using services provided by colocation facilities not " +"supporting FreeBSD." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/remote-install/_index.adoc:74 +msgid "" +"As we have mentioned in the crossref:remote-install[background, Background] " +"section, many of the reputable server hosting companies provide some kind of " +"rescue system, which is booted from their LAN and accessible over SSH. They " +"usually provide this support to help their customers fix broken operating " +"systems. As this article will explain, it is possible to install FreeBSD " +"with the help of these rescue systems." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/remote-install/_index.adoc:76 +msgid "" +"The next section of this article will describe how to configure, and build " +"minimalistic FreeBSD on the local machine. That version will eventually be " +"running on the remote machine from a ramdisk, which will allow us to install " +"a complete FreeBSD operating system from an FTP mirror using the sysinstall " +"utility." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/remote-install/_index.adoc:77 +msgid "" +"The rest of this article will describe the installation procedure itself, as " +"well as the configuration of the ZFS file system." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/remote-install/_index.adoc:80 +#, no-wrap +msgid "Requirements" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:83 +msgid "To continue successfully, you must:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:85 +msgid "Have a network accessible operating system with SSH access" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:86 +msgid "Understand the FreeBSD installation process" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:87 +msgid "Be familiar with the man:sysinstall[8] utility" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:88 +msgid "Have the FreeBSD installation SO image or CD handy" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/remote-install/_index.adoc:90 +#, no-wrap +msgid "Preparation - mfsBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:94 +msgid "" +"Before FreeBSD may be installed on the target system, it is necessary to " +"build the minimal FreeBSD operating system image which will boot from the " +"hard drive. This way the new system can be accessed from the network, and " +"the rest of the installation can be done without remote access to the system " +"console." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:99 +msgid "" +"The mfsBSD tool-set can be used to build a tiny FreeBSD image. As the name " +"of mfsBSD suggests (\"mfs\" means \"memory file system\"), the resulting " +"image runs entirely from a ramdisk. Thanks to this feature, the " +"manipulation of hard drives will not be limited, therefore it will be " +"possible to install a complete FreeBSD operating system. The mfsBSD http://" +"mfsbsd.vx.sk/[home page] includes pointers to the latest release of the " +"toolset." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:102 +msgid "" +"Please note that the internals of mfsBSD and how it all fits together is " +"beyond the scope of this article. The interested reader should consult the " +"original documentation of mfsBSD for more details." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:104 +msgid "" +"Download and extract the latest mfsBSD release and change your working " +"directory to the directory where the mfsBSD scripts will reside:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:110 +#, no-wrap +msgid "" +"# fetch http://mfsbsd.vx.sk/release/mfsbsd-2.1.tar.gz\n" +"# tar xvzf mfsbsd-2.1.tar.gz\n" +"# cd mfsbsd-2.1/\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/remote-install/_index.adoc:113 +#, no-wrap +msgid "Configuration of mfsBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:119 +msgid "" +"Before booting mfsBSD, a few important configuration options have to be " +"set. The most important that we have to get right is, naturally, the " +"network setup. The most suitable method to configure networking options " +"depends on whether we know beforehand the type of the network interface we " +"will use, and the network interface driver to be loaded for our hardware. " +"We will see how mfsBSD can be configured in either case." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:123 +msgid "" +"Another important thing to set is the `root` password. This can be done by " +"editing [.filename]#conf/loader.conf#. Please see the included comments." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/remote-install/_index.adoc:124 +#, no-wrap +msgid "The [.filename]#conf/interfaces.conf# method" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:128 +msgid "" +"When the installed network interface card is unknown, it is possible to use " +"the auto-detection features of mfsBSD. The startup scripts of mfsBSD can " +"detect the correct driver to use, based on the MAC address of the interface, " +"if we set the following options in [.filename]#conf/interfaces.conf#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:134 +#, no-wrap +msgid "" +"mac_interfaces=\"ext1\"\n" +"ifconfig_ext1_mac=\"00:00:00:00:00:00\"\n" +"ifconfig_ext1=\"inet 192.168.0.2/24\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:137 +msgid "" +"Do not forget to add the `defaultrouter` information to [.filename]#conf/rc." +"conf#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:141 +#, no-wrap +msgid "defaultrouter=\"192.168.0.1\"\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/remote-install/_index.adoc:143 +#, no-wrap +msgid "The [.filename]#conf/rc.conf# Method" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:147 +msgid "" +"When the network interface driver is known, it is more convenient to use [." +"filename]#conf/rc.conf# for networking options. The syntax of this file is " +"the same as the one used in the standard man:rc.conf[5] file of FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:149 +msgid "" +"For example, if you know that a man:re[4] network interface is going to be " +"available, you can set the following options in [.filename]#conf/rc.conf#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:154 +#, no-wrap +msgid "" +"defaultrouter=\"192.168.0.1\"\n" +"ifconfig_re0=\"inet 192.168.0.2/24\"\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/remote-install/_index.adoc:157 +#, no-wrap +msgid "Building an mfsBSD Image" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:160 +msgid "The process of building an mfsBSD image is pretty straightforward." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:164 +msgid "" +"The first step is to mount the FreeBSD installation CD, or the installation " +"ISO image to [.filename]#/cdrom#. For the sake of example, in this article " +"we will assume that you have downloaded the FreeBSD 10.1-RELEASE ISO. " +"Mounting this ISO image to the [.filename]#/cdrom# directory is easy with " +"the man:mdconfig[8] utility:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:169 +#, no-wrap +msgid "" +"# mdconfig -a -t vnode -u 10 -f FreeBSD-10.1-RELEASE-amd64-disc1.iso\n" +"# mount_cd9660 /dev/md10 /cdrom\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:172 +msgid "" +"Since the recent FreeBSD releases do not contain regular distribution sets, " +"it is required to extract the FreeBSD distribution files from the " +"distribution archives located on the ISO image:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:178 +#, no-wrap +msgid "" +"# mkdir DIST\n" +"# tar -xvf /cdrom/usr/freebsd-dist/base.txz -C DIST\n" +"# tar -xvf /cdrom/usr/freebsd-dist/kernel.txz -C DIST\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:181 +msgid "Next, build the bootable mfsBSD image:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:185 +#, no-wrap +msgid "# make BASE=DIST\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/remote-install/_index.adoc:190 +msgid "" +"The above `make` has to be run from the top level of the mfsBSD directory " +"tree, for example [.filename]#~/mfsbsd-2.1/#." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/remote-install/_index.adoc:192 +#, no-wrap +msgid "Booting mfsBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:196 +msgid "" +"Now that the mfsBSD image is ready, it must be uploaded to the remote system " +"running a live rescue system or pre-installed Linux(R) distribution. The " +"most suitable tool for this task is scp:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:200 +#, no-wrap +msgid "# scp disk.img root@192.168.0.2:.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:204 +msgid "" +"To boot mfsBSD image properly, it must be placed on the first (bootable) " +"device of the given machine. This may be accomplished using this example " +"providing that [.filename]#sda# is the first bootable disk device:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:208 +#, no-wrap +msgid "# dd if=/root/disk.img of=/dev/sda bs=1m\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:213 +msgid "" +"If all went well, the image should now be in the MBR of the first device and " +"the machine can be rebooted. Watch for the machine to boot up properly with " +"the man:ping[8] tool. Once it has came back on-line, it should be possible " +"to access it over man:ssh[1] as user `root` with the configured password." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/remote-install/_index.adoc:215 +#, no-wrap +msgid "Installation of the FreeBSD Operating System" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:219 +msgid "" +"The mfsBSD has been successfully booted and it should be possible to log in " +"through man:ssh[1]. This section will describe how to create and label " +"slices, set up `gmirror` for RAID-1, and how to use `sysinstall` to install " +"a minimal distribution of the FreeBSD operating system." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/remote-install/_index.adoc:220 +#, no-wrap +msgid "Preparation of Hard Drives" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:225 +msgid "" +"The first task is to allocate disk space for FreeBSD, i.e.: to create slices " +"and partitions. Obviously, the currently running system is fully loaded in " +"system memory and therefore there will be no problems with manipulating hard " +"drives. To complete this task, it is possible to use either `sysinstall` or " +"man:fdisk[8] in conjunction to man:bsdlabel[8]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:228 +msgid "" +"At the start, mark all system disks as empty. Repeat the following command " +"for each hard drive:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:232 +#, no-wrap +msgid "# dd if=/dev/zero of=/dev/ad0 count=2\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:240 +msgid "" +"Next, create slices and label them with your preferred tool. While it is " +"considered easier to use `sysinstall`, a powerful and also probably less " +"buggy method will be to use standard text-based UNIX(R) tools, such as man:" +"fdisk[8] and man:bsdlabel[8], which will also be covered in this section. " +"The former option is well documented in the extref:{handbook}[Installing " +"FreeBSD, install-steps] chapter of the FreeBSD Handbook. As it was " +"mentioned in the introduction, this article will present how to set up a " +"system with RAID-1 and ZFS capabilities. Our set up will consist of a small " +"man:gmirror[8] mirrored [.filename]#/# (root), [.filename]#/usr# and [." +"filename]#/var# dataset, and the rest of the disk space will be allocated " +"for a man:zpool[8] mirrored ZFS file system. Please note, that the ZFS file " +"system will be configured after the FreeBSD operating system is successfully " +"installed and booted." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:242 +msgid "" +"The following example will describe how to create slices and labels, " +"initialize man:gmirror[8] on each partition and how to create a UFS2 file " +"system in each mirrored partition:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:258 +#, no-wrap +msgid "" +"# fdisk -BI /dev/ad0 <.>\n" +"# fdisk -BI /dev/ad1\n" +"# bsdlabel -wB /dev/ad0s1 <.>\n" +"# bsdlabel -wB /dev/ad1s1\n" +"# bsdlabel -e /dev/ad0s1 <.>\n" +"# bsdlabel /dev/ad0s1 > /tmp/bsdlabel.txt && bsdlabel -R /dev/ad1s1 /tmp/bsdlabel.txt <.>\n" +"# gmirror label root /dev/ad[01]s1a <.>\n" +"# gmirror label var /dev/ad[01]s1d\n" +"# gmirror label usr /dev/ad[01]s1e\n" +"# gmirror label -F swap /dev/ad[01]s1b <.>\n" +"# newfs /dev/mirror/root <.>\n" +"# newfs /dev/mirror/var\n" +"# newfs /dev/mirror/usr\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:261 +msgid "" +"Create a slice covering the entire disk and initialize the boot code " +"contained in sector 0 of the given disk. Repeat this command for all hard " +"drives in the system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:263 +msgid "Write a standard label for each disk including the bootstrap code." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:265 +msgid "" +"Now, manually edit the label of the given disk. Refer to the man:bsdlabel[8] " +"manual page to find out how to create partitions. Create partitions `a` for " +"[.filename]#/# (root) file system, `b` for swap, `d` for [.filename]#/var#, " +"`e` for [.filename]#/usr# and finally `f` which will later be used for ZFS." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:267 +msgid "" +"Import the recently created label for the second hard drive, so both hard " +"drives will be labeled in the same way." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:269 +msgid "Initialize man:gmirror[8] on each partition." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:271 +msgid "" +"Note that `-F` is used for the swap partition. This instructs man:gmirror[8] " +"to assume that the device is in the consistent state after the power/system " +"failure." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:273 +msgid "Create a UFS2 file system on each mirrored partition." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/remote-install/_index.adoc:274 +#, no-wrap +msgid "System Installation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:279 +msgid "" +"This is the most important part. This section will describe how to actually " +"install the minimal distribution of FreeBSD on the hard drives that we have " +"prepared in the previous section. To accomplish this goal, all file systems " +"need to be mounted so `sysinstall` may write the contents of FreeBSD to the " +"hard drives:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:286 +#, no-wrap +msgid "" +"# mount /dev/mirror/root /mnt\n" +"# mkdir /mnt/var /mnt/usr\n" +"# mount /dev/mirror/var /mnt/var\n" +"# mount /dev/mirror/usr /mnt/usr\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:293 +msgid "" +"When you are done, start man:sysinstall[8]. Select the [." +"guimenuitem]#Custom# installation from the main menu. Select [." +"guimenuitem]#Options# and press kbd:[Enter]. With the help of arrow keys, " +"move the cursor on the `Install Root` item, press kbd:[Space] and change it " +"to [.filename]#/mnt#. Press kbd:[Enter] to submit your changes and exit the " +"[.guimenuitem]#Options# menu by pressing kbd:[q]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/remote-install/_index.adoc:297 +msgid "" +"Note that this step is very important and if skipped, `sysinstall` will be " +"unable to install FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:302 +msgid "" +"Go to the [.guimenuitem]#Distributions# menu, move the cursor with the arrow " +"keys to `Minimal`, and check it by pressing kbd:[Space]. This article uses " +"the Minimal distribution to save network traffic, because the system itself " +"will be installed over ftp. Exit this menu by choosing `Exit`." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/remote-install/_index.adoc:306 +msgid "" +"The [.guimenuitem]#Partition# and [.guimenuitem]#Label# menus will be " +"skipped, as these are useless now." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:311 +msgid "" +"In the [.guimenuitem]#Media# menu, select `FTP`. Select the nearest mirror " +"and let `sysinstall` assume that the network is already configured. You " +"will be returned back to the [.guimenuitem]#Custom# menu." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:314 +msgid "" +"Finally, perform the system installation by selecting the last option, [." +"guimenuitem]#Commit#. Exit `sysinstall` when it finishes the installation." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/remote-install/_index.adoc:315 +#, no-wrap +msgid "Post Installation Steps" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:319 +msgid "" +"The FreeBSD operating system should be installed now; however, the process " +"is not finished yet. It is necessary to perform some post installation " +"steps to allow FreeBSD to boot in the future and to be able to log in to the " +"system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:322 +msgid "" +"You must now man:chroot[8] into the freshly installed system to finish the " +"installation. Use the following command:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:326 +#, no-wrap +msgid "# chroot /mnt\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:329 +msgid "To complete our goal, perform these steps:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:331 +msgid "Copy the `GENERIC` kernel to the [.filename]#/boot/kernel# directory:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:335 +#, no-wrap +msgid "# cp -Rp /boot/GENERIC/* /boot/kernel\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:338 +msgid "" +"Create the [.filename]#/etc/rc.conf#, [.filename]#/etc/resolv.conf# and [." +"filename]#/etc/fstab# files. Do not forget to properly set the network " +"information and to enable sshd in [.filename]#/etc/rc.conf#. The contents of " +"[.filename]#/etc/fstab# will be similar to the following:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:347 +#, no-wrap +msgid "" +"# Device Mountpoint FStype Options Dump Pass#\n" +"/dev/mirror/swap none swap sw 0 0\n" +"/dev/mirror/root / ufs rw 1 1\n" +"/dev/mirror/usr /usr ufs rw 2 2\n" +"/dev/mirror/var /var ufs rw 2 2\n" +"/dev/cd0 /cdrom cd9660 ro,noauto 0 0\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:349 +msgid "Create [.filename]#/boot/loader.conf# with the following contents:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:354 +#, no-wrap +msgid "" +"geom_mirror_load=\"YES\"\n" +"zfs_load=\"YES\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:356 +msgid "" +"Perform the following command, which will make ZFS available on the next " +"boot:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:360 +#, no-wrap +msgid "# sysrc zfs_enable=\"YES\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:363 +msgid "" +"Add additional users to the system using the man:adduser[8] tool. Do not " +"forget to add a user to the `wheel` group so you may obtain root access " +"after the reboot." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:364 +msgid "Double-check all your settings." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:367 +msgid "" +"The system should now be ready for the next boot. Use the man:reboot[8] " +"command to reboot your system." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/remote-install/_index.adoc:369 +#, no-wrap +msgid "ZFS" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:373 +msgid "" +"If your system survived the reboot, it should now be possible to log in. " +"Welcome to the fresh FreeBSD installation, performed remotely without the " +"use of a remote console!" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:376 +msgid "" +"The only remaining step is to configure man:zpool[8] and create some man:" +"zfs[8] file systems. Creating and administering ZFS is very " +"straightforward. First, create a mirrored pool:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:380 +#, no-wrap +msgid "# zpool create tank mirror /dev/ad[01]s1f\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:383 +msgid "Next, create some file systems:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/remote-install/_index.adoc:392 +#, no-wrap +msgid "" +"# zfs create tank/ports\n" +"# zfs create tank/src\n" +"# zfs set compression=gzip tank/ports\n" +"# zfs set compression=on tank/src\n" +"# zfs set mountpoint=/usr/ports tank/ports\n" +"# zfs set mountpoint=/usr/src tank/src\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/remote-install/_index.adoc:395 +msgid "" +"That is all. If you are interested in more details about ZFS on FreeBSD, " +"please refer to the https://wiki.freebsd.org/ZFS[ZFS] section of the FreeBSD " +"Wiki." +msgstr "" diff --git a/documentation/content/en/articles/serial-uart/_index.adoc b/documentation/content/en/articles/serial-uart/_index.adoc index 3852251b85..e953644b93 100644 --- a/documentation/content/en/articles/serial-uart/_index.adoc +++ b/documentation/content/en/articles/serial-uart/_index.adoc @@ -445,7 +445,7 @@ Modems operating at 28,800 and higher speeds have variable Symbol rates, but the === The IBM Personal Computer UART -Starting with the original IBM Personal Computer, IBM selected the National Semiconductor INS8250 UART for use in the IBM PC Parallel/Serial Adapter. +Starting with the original IBM Personal Computer, IBM selected the National Semiconductor INS8250 UART for use in the IBM PC Parallel/Serial Adapter. Subsequent generations of compatible computers from IBM and other vendors continued to use the INS8250 or improved versions of the National Semiconductor UART family. ==== National Semiconductor UART Family Tree @@ -815,7 +815,7 @@ Bit 0 -> Delta Clear To Send (DCTS). Set to "1" if the -CTS line has changed sta === Beyond the 16550A UART -Although National Semiconductor has not offered any components compatible with the 16550 that provide additional features, various other vendors have. +Although National Semiconductor has not offered any components compatible with the 16550 that provide additional features, various other vendors have. Some of these components are described below. It should be understood that to effectively utilize these improvements, drivers may have to be provided by the chip vendor since most of the popular operating systems do not support features beyond those provided by the 16550. @@ -839,7 +839,7 @@ This leaves the designer free to components that may have better performance cha [[sio]] == Configuring the [.filename]#sio# driver -The [.filename]#sio# driver provides support for NS8250-, NS16450-, NS16550 and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. +The [.filename]#sio# driver provides support for NS8250-, NS16450-, NS16550 and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. Several multiport cards are supported as well. See the man:sio[4] manual page for detailed technical documentation. @@ -878,12 +878,12 @@ One important note - the actual UART chips for the Boca 16 are in the connector So if you have it unplugged, probes of those ports will fail. I have never tested booting with the box unplugged and plugging it back in, and I suggest you do not either. -If you do not already have a custom kernel configuration file set up, refer to extref:{handbook}[Kernel Configuration, kernelconfig] chapter of the FreeBSD Handbook for general procedures. +If you do not already have a custom kernel configuration file set up, refer to extref:{handbook}kernelconfig[Kernel Configuration, kernelconfig] chapter of the FreeBSD Handbook for general procedures. The following are the specifics for the Boca 16 board and assume you are using the kernel name MYKERNEL and editing with vi. [.procedure] ==== -. Add the line +. Add the line + [.programlisting] .... @@ -905,7 +905,7 @@ 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, +In this example, + [.programlisting] .... @@ -953,7 +953,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, +If the messages go by too fast to see, + [source,shell] .... @@ -976,7 +976,7 @@ If you do need to create the [.filename]#/dev# entries, run the following as `ro .... + 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) +. 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) + [source,shell] .... diff --git a/documentation/content/en/articles/serial-uart/_index.po b/documentation/content/en/articles/serial-uart/_index.po new file mode 100644 index 0000000000..62713aaccd --- /dev/null +++ b/documentation/content/en/articles/serial-uart/_index.po @@ -0,0 +1,3064 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2022-02-01 10:28-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/serial-uart/_index.adoc:1 +#, no-wrap +msgid "Detailed information about the use of serial ports and UART with FreeBSD" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/serial-uart/_index.adoc:1 +#: documentation/content/en/articles/serial-uart/_index.adoc:11 +#, no-wrap +msgid "Serial and UART Tutorial" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:44 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:46 +msgid "This article talks about using serial hardware with FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:48 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/serial-uart/_index.adoc:52 +#, no-wrap +msgid "The UART: What it is and how it works" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:55 +msgid "_Copyright (R) 1996 `{uhclem}`, All Rights Reserved. 13 January 1996._" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:59 +msgid "" +"The Universal Asynchronous Receiver/Transmitter (UART) controller is the key " +"component of the serial communications subsystem of a computer. The UART " +"takes bytes of data and transmits the individual bits in a sequential " +"fashion. At the destination, a second UART re-assembles the bits into " +"complete bytes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:61 +msgid "" +"Serial transmission is commonly used with modems and for non-networked " +"communication between computers, terminals and other devices." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:65 +msgid "" +"There are two primary forms of serial transmission: Synchronous and " +"Asynchronous. Depending on the modes that are supported by the hardware, " +"the name of the communication sub-system will usually include a `A` if it " +"supports Asynchronous communications, and a `S` if it supports Synchronous " +"communications. Both forms are described below." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:67 +msgid "Some common acronyms are:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:70 +msgid "UART Universal Asynchronous Receiver/Transmitter" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:73 +msgid "USART Universal Synchronous-Asynchronous Receiver/Transmitter" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/serial-uart/_index.adoc:74 +#, no-wrap +msgid "Synchronous Serial Transmission" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:79 +msgid "" +"Synchronous serial transmission requires that the sender and receiver share " +"a clock with one another, or that the sender provide a strobe or other " +"timing signal so that the receiver knows when to \"read\" the next bit of " +"the data. In most forms of serial Synchronous communication, if there is no " +"data available at a given instant to transmit, a fill character must be sent " +"instead so that data is always being transmitted. Synchronous communication " +"is usually more efficient because only data bits are transmitted between " +"sender and receiver, and synchronous communication can be more costly if " +"extra wiring and circuits are required to share a clock signal between the " +"sender and receiver." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:83 +msgid "" +"A form of Synchronous transmission is used with printers and fixed disk " +"devices in that the data is sent on one set of wires while a clock or strobe " +"is sent on a different wire. Printers and fixed disk devices are not " +"normally serial devices because most fixed disk interface standards send an " +"entire word of data for each clock or strobe signal by using a separate wire " +"for each bit of the word. In the PC industry, these are known as Parallel " +"devices." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:86 +msgid "" +"The standard serial communications hardware in the PC does not support " +"Synchronous operations. This mode is described here for comparison purposes " +"only." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/serial-uart/_index.adoc:87 +#, no-wrap +msgid "Asynchronous Serial Transmission" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:91 +msgid "" +"Asynchronous transmission allows data to be transmitted without the sender " +"having to send a clock signal to the receiver. Instead, the sender and " +"receiver must agree on timing parameters in advance and special bits are " +"added to each word which are used to synchronize the sending and receiving " +"units." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:96 +msgid "" +"When a word is given to the UART for Asynchronous transmissions, a bit " +"called the \"Start Bit\" is added to the beginning of each word that is to " +"be transmitted. The Start Bit is used to alert the receiver that a word of " +"data is about to be sent, and to force the clock in the receiver into " +"synchronization with the clock in the transmitter. These two clocks must be " +"accurate enough to not have the frequency drift by more than 10% during the " +"transmission of the remaining bits in the word. (This requirement was set " +"in the days of mechanical teleprinters and is easily met by modern " +"electronic equipment.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:100 +msgid "" +"After the Start Bit, the individual bits of the word of data are sent, with " +"the Least Significant Bit (LSB) being sent first. Each bit in the " +"transmission is transmitted for exactly the same amount of time as all of " +"the other bits, and the receiver \"looks\" at the wire at approximately " +"halfway through the period assigned to each bit to determine if the bit is a " +"`1` or a `0`. For example, if it takes two seconds to send each bit, the " +"receiver will examine the signal to determine if it is a `1` or a `0` after " +"one second has passed, then it will wait two seconds and then examine the " +"value of the next bit, and so on." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:103 +msgid "" +"The sender does not know when the receiver has \"looked\" at the value of " +"the bit. The sender only knows when the clock says to begin transmitting " +"the next bit of the word." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:107 +msgid "" +"When the entire data word has been sent, the transmitter may add a Parity " +"Bit that the transmitter generates. The Parity Bit may be used by the " +"receiver to perform simple error checking. Then at least one Stop Bit is " +"sent by the transmitter." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:111 +msgid "" +"When the receiver has received all of the bits in the data word, it may " +"check for the Parity Bits (both sender and receiver must agree on whether a " +"Parity Bit is to be used), and then the receiver looks for a Stop Bit. If " +"the Stop Bit does not appear when it is supposed to, the UART considers the " +"entire word to be garbled and will report a Framing Error to the host " +"processor when the data word is read. The usual cause of a Framing Error is " +"that the sender and receiver clocks were not running at the same speed, or " +"that the signal was interrupted." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:114 +msgid "" +"Regardless of whether the data was received correctly or not, the UART " +"automatically discards the Start, Parity and Stop bits. If the sender and " +"receiver are configured identically, these bits are not passed to the host." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:116 +msgid "" +"If another word is ready for transmission, the Start Bit for the new word " +"can be sent as soon as the Stop Bit for the previous word has been sent." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:118 +msgid "" +"As asynchronous data is \"self synchronizing\", if there is no data to " +"transmit, the transmission line can be idle." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/serial-uart/_index.adoc:119 +#, no-wrap +msgid "Other UART Functions" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:124 +msgid "" +"In addition to the basic job of converting data from parallel to serial for " +"transmission and from serial to parallel on reception, a UART will usually " +"provide additional circuits for signals that can be used to indicate the " +"state of the transmission media, and to regulate the flow of data in the " +"event that the remote device is not prepared to accept more data. For " +"example, when the device connected to the UART is a modem, the modem may " +"report the presence of a carrier on the phone line while the computer may be " +"able to instruct the modem to reset itself or to not take calls by raising " +"or lowering one more of these extra signals. The function of each of these " +"additional signals is defined in the EIA RS232-C standard." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/serial-uart/_index.adoc:125 +#, no-wrap +msgid "The RS232-C and V.24 Standards" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:129 +msgid "" +"In most computer systems, the UART is connected to circuitry that generates " +"signals that comply with the EIA RS232-C specification. There is also a " +"CCITT standard named V.24 that mirrors the specifications included in RS232-" +"C." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/serial-uart/_index.adoc:130 +#, no-wrap +msgid "RS232-C Bit Assignments (Marks and Spaces)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:134 +msgid "" +"In RS232-C, a value of `1` is called a `Mark` and a value of `0` is called a " +"`Space`. When a communication line is idle, the line is said to be \"Marking" +"\", or transmitting continuous `1` values." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:139 +msgid "" +"The Start bit always has a value of `0` (a Space). The Stop Bit always has " +"a value of `1` (a Mark). This means that there will always be a Mark (1) to " +"Space (0) transition on the line at the start of every word, even when " +"multiple word are transmitted back to back. This guarantees that sender and " +"receiver can resynchronize their clocks regardless of the content of the " +"data bits that are being transmitted." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:141 +msgid "" +"The idle time between Stop and Start bits does not have to be an exact " +"multiple (including zero) of the bit rate of the communication link, but " +"most UARTs are designed this way for simplicity." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:145 +msgid "" +"In RS232-C, the \"Marking\" signal (a `1`) is represented by a voltage " +"between -2 VDC and -12 VDC, and a \"Spacing\" signal (a `0`) is represented " +"by a voltage between 0 and +12 VDC. The transmitter is supposed to send +12 " +"VDC or -12 VDC, and the receiver is supposed to allow for some voltage loss " +"in long cables. Some transmitters in low power devices (like portable " +"computers) sometimes use only +5 VDC and -5 VDC, but these values are still " +"acceptable to a RS232-C receiver, provided that the cable lengths are short." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/serial-uart/_index.adoc:146 +#, no-wrap +msgid "RS232-C Break Signal" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:150 +msgid "" +"RS232-C also specifies a signal called a `Break`, which is caused by sending " +"continuous Spacing values (no Start or Stop bits). When there is no " +"electricity present on the data circuit, the line is considered to be " +"sending `Break`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:153 +msgid "" +"The `Break` signal must be of a duration longer than the time it takes to " +"send a complete byte plus Start, Stop and Parity bits. Most UARTs can " +"distinguish between a Framing Error and a Break, but if the UART cannot do " +"this, the Framing Error detection can be used to identify Breaks." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:156 +msgid "" +"In the days of teleprinters, when numerous printers around the country were " +"wired in series (such as news services), any unit could cause a `Break` by " +"temporarily opening the entire circuit so that no current flowed. This was " +"used to allow a location with urgent news to interrupt some other location " +"that was currently sending information." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:161 +msgid "" +"In modern systems there are two types of Break signals. If the Break is " +"longer than 1.6 seconds, it is considered a \"Modem Break\", and some modems " +"can be programmed to terminate the conversation and go on-hook or enter the " +"modems' command mode when the modem detects this signal. If the Break is " +"smaller than 1.6 seconds, it signifies a Data Break and it is up to the " +"remote computer to respond to this signal. Sometimes this form of Break is " +"used as an Attention or Interrupt signal and sometimes is accepted as a " +"substitute for the ASCII CONTROL-C character." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:163 +msgid "" +"Marks and Spaces are also equivalent to \"Holes\" and \"No Holes\" in paper " +"tape systems." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:168 +msgid "" +"Breaks cannot be generated from paper tape or from any other byte value, " +"since bytes are always sent with Start and Stop bit. The UART is usually " +"capable of generating the continuous Spacing signal in response to a special " +"command from the host processor." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/serial-uart/_index.adoc:170 +#, no-wrap +msgid "RS232-C DTE and DCE Devices" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:176 +msgid "" +"The RS232-C specification defines two types of equipment: the Data Terminal " +"Equipment (DTE) and the Data Carrier Equipment (DCE). Usually, the DTE " +"device is the terminal (or computer), and the DCE is a modem. Across the " +"phone line at the other end of a conversation, the receiving modem is also a " +"DCE device and the computer that is connected to that modem is a DTE " +"device. The DCE device receives signals on the pins that the DTE device " +"transmits on, and vice versa." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:180 +msgid "" +"When two devices that are both DTE or both DCE must be connected together " +"without a modem or a similar media translator between them, a NULL modem " +"must be used. The NULL modem electrically re-arranges the cabling so that " +"the transmitter output is connected to the receiver input on the other " +"device, and vice versa. Similar translations are performed on all of the " +"control signals so that each device will see what it thinks are DCE (or DTE) " +"signals from the other device." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:183 +msgid "" +"The number of signals generated by the DTE and DCE devices are not " +"symmetrical. The DTE device generates fewer signals for the DCE device than " +"the DTE device receives from the DCE." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/serial-uart/_index.adoc:184 +#, no-wrap +msgid "RS232-C Pin Assignments" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:187 +msgid "" +"The EIA RS232-C specification (and the ITU equivalent, V.24) calls for a " +"twenty-five pin connector (usually a DB25) and defines the purpose of most " +"of the pins in that connector." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:190 +msgid "" +"In the IBM Personal Computer and similar systems, a subset of RS232-C " +"signals are provided via nine pin connectors (DB9). The signals that are " +"not included on the PC connector deal mainly with synchronous operation, and " +"this transmission mode is not supported by the UART that IBM selected for " +"use in the IBM PC." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:193 +msgid "" +"Depending on the computer manufacturer, a DB25, a DB9, or both types of " +"connector may be used for RS232-C communications. (The IBM PC also uses a " +"DB25 connector for the parallel printer interface which causes some " +"confusion.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:195 +msgid "" +"Below is a table of the RS232-C signal assignments in the DB25 and DB9 " +"connectors." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:200 +#, no-wrap +msgid "DB25 RS232-C Pin" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:201 +#, no-wrap +msgid "DB9 IBM PC Pin" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:202 +#, no-wrap +msgid "EIA Circuit Symbol" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:203 +#, no-wrap +msgid "CCITT Circuit Symbol" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:204 +#, no-wrap +msgid "Common Name" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:205 +#, no-wrap +msgid "Signal Source" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:207 +#: documentation/content/en/articles/serial-uart/_index.adoc:675 +#, no-wrap +msgid "Description" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:208 +#: documentation/content/en/articles/serial-uart/_index.adoc:265 +#, no-wrap +msgid "1" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:209 +#: documentation/content/en/articles/serial-uart/_index.adoc:213 +#: documentation/content/en/articles/serial-uart/_index.adoc:261 +#: documentation/content/en/articles/serial-uart/_index.adoc:273 +#: documentation/content/en/articles/serial-uart/_index.adoc:274 +#: documentation/content/en/articles/serial-uart/_index.adoc:275 +#: documentation/content/en/articles/serial-uart/_index.adoc:276 +#: documentation/content/en/articles/serial-uart/_index.adoc:277 +#: documentation/content/en/articles/serial-uart/_index.adoc:281 +#: documentation/content/en/articles/serial-uart/_index.adoc:282 +#: documentation/content/en/articles/serial-uart/_index.adoc:283 +#: documentation/content/en/articles/serial-uart/_index.adoc:284 +#: documentation/content/en/articles/serial-uart/_index.adoc:285 +#: documentation/content/en/articles/serial-uart/_index.adoc:289 +#: documentation/content/en/articles/serial-uart/_index.adoc:290 +#: documentation/content/en/articles/serial-uart/_index.adoc:291 +#: documentation/content/en/articles/serial-uart/_index.adoc:292 +#: documentation/content/en/articles/serial-uart/_index.adoc:293 +#: documentation/content/en/articles/serial-uart/_index.adoc:297 +#: documentation/content/en/articles/serial-uart/_index.adoc:305 +#: documentation/content/en/articles/serial-uart/_index.adoc:313 +#: documentation/content/en/articles/serial-uart/_index.adoc:321 +#: documentation/content/en/articles/serial-uart/_index.adoc:329 +#: documentation/content/en/articles/serial-uart/_index.adoc:337 +#: documentation/content/en/articles/serial-uart/_index.adoc:345 +#: documentation/content/en/articles/serial-uart/_index.adoc:346 +#: documentation/content/en/articles/serial-uart/_index.adoc:353 +#: documentation/content/en/articles/serial-uart/_index.adoc:369 +#: documentation/content/en/articles/serial-uart/_index.adoc:370 +#: documentation/content/en/articles/serial-uart/_index.adoc:371 +#: documentation/content/en/articles/serial-uart/_index.adoc:385 +#: documentation/content/en/articles/serial-uart/_index.adoc:393 +#: documentation/content/en/articles/serial-uart/_index.adoc:401 +#: documentation/content/en/articles/serial-uart/_index.adoc:402 +#: documentation/content/en/articles/serial-uart/_index.adoc:404 +#, no-wrap +msgid "-" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:210 +#, no-wrap +msgid "AA" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:211 +#, no-wrap +msgid "101" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:212 +#, no-wrap +msgid "PG/FG" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:215 +#, no-wrap +msgid "Frame/Protective Ground" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:216 +#: documentation/content/en/articles/serial-uart/_index.adoc:225 +#, no-wrap +msgid "2" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:217 +#: documentation/content/en/articles/serial-uart/_index.adoc:224 +#: documentation/content/en/articles/serial-uart/_index.adoc:610 +#, no-wrap +msgid "3" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:218 +#, no-wrap +msgid "BA" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:219 +#, no-wrap +msgid "103" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:220 +#, no-wrap +msgid "TD" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:221 +#: documentation/content/en/articles/serial-uart/_index.adoc:237 +#: documentation/content/en/articles/serial-uart/_index.adoc:317 +#: documentation/content/en/articles/serial-uart/_index.adoc:349 +#: documentation/content/en/articles/serial-uart/_index.adoc:357 +#: documentation/content/en/articles/serial-uart/_index.adoc:365 +#: documentation/content/en/articles/serial-uart/_index.adoc:373 +#: documentation/content/en/articles/serial-uart/_index.adoc:389 +#: documentation/content/en/articles/serial-uart/_index.adoc:397 +#, no-wrap +msgid "DTE" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:223 +#, no-wrap +msgid "Transmit Data" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:226 +#, no-wrap +msgid "BB" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:227 +#, no-wrap +msgid "104" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:228 +#, no-wrap +msgid "RD" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:229 +#: documentation/content/en/articles/serial-uart/_index.adoc:245 +#: documentation/content/en/articles/serial-uart/_index.adoc:253 +#: documentation/content/en/articles/serial-uart/_index.adoc:269 +#: documentation/content/en/articles/serial-uart/_index.adoc:301 +#: documentation/content/en/articles/serial-uart/_index.adoc:309 +#: documentation/content/en/articles/serial-uart/_index.adoc:325 +#: documentation/content/en/articles/serial-uart/_index.adoc:333 +#: documentation/content/en/articles/serial-uart/_index.adoc:341 +#: documentation/content/en/articles/serial-uart/_index.adoc:381 +#: documentation/content/en/articles/serial-uart/_index.adoc:405 +#, no-wrap +msgid "DCE" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:231 +#, no-wrap +msgid "Receive Data" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:232 +#: documentation/content/en/articles/serial-uart/_index.adoc:361 +#, no-wrap +msgid "4" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:233 +#: documentation/content/en/articles/serial-uart/_index.adoc:256 +#, no-wrap +msgid "7" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:234 +#, no-wrap +msgid "CA" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:235 +#, no-wrap +msgid "105" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:236 +#, no-wrap +msgid "RTS" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:239 +#, no-wrap +msgid "Request to Send" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:240 +#: documentation/content/en/articles/serial-uart/_index.adoc:257 +#, no-wrap +msgid "5" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:241 +#: documentation/content/en/articles/serial-uart/_index.adoc:264 +#, no-wrap +msgid "8" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:242 +#, no-wrap +msgid "CB" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:243 +#, no-wrap +msgid "106" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:244 +#, no-wrap +msgid "CTS" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:247 +#, no-wrap +msgid "Clear to Send" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:248 +#: documentation/content/en/articles/serial-uart/_index.adoc:249 +#, no-wrap +msgid "6" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:250 +#, no-wrap +msgid "CC" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:251 +#, no-wrap +msgid "107" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:252 +#, no-wrap +msgid "DSR" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:255 +#, no-wrap +msgid "Data Set Ready" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:258 +#, no-wrap +msgid "AV" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:259 +#, no-wrap +msgid "102" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:260 +#, no-wrap +msgid "SG/GND" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:263 +#, no-wrap +msgid "Signal Ground" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:266 +#, no-wrap +msgid "CF" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:267 +#, no-wrap +msgid "109" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:268 +#, no-wrap +msgid "DCD/CD" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:271 +#, no-wrap +msgid "Data Carrier Detect" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:272 +#: documentation/content/en/articles/serial-uart/_index.adoc:377 +#, no-wrap +msgid "9" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:279 +#: documentation/content/en/articles/serial-uart/_index.adoc:287 +#: documentation/content/en/articles/serial-uart/_index.adoc:295 +#, no-wrap +msgid "Reserved for Test" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:280 +#, no-wrap +msgid "10" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:288 +#, no-wrap +msgid "11" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:296 +#, no-wrap +msgid "12" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:298 +#, no-wrap +msgid "CI" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:299 +#, no-wrap +msgid "122" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:300 +#, no-wrap +msgid "SRLSD" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:303 +#, no-wrap +msgid "Sec. Recv. Line Signal Detector" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:304 +#, no-wrap +msgid "13" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:306 +#, no-wrap +msgid "SCB" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:307 +#, no-wrap +msgid "121" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:308 +#, no-wrap +msgid "SCTS" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:311 +#, no-wrap +msgid "Secondary Clear to Send" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:312 +#, no-wrap +msgid "14" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:314 +#, no-wrap +msgid "SBA" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:315 +#, no-wrap +msgid "118" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:316 +#, no-wrap +msgid "STD" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:319 +#, no-wrap +msgid "Secondary Transmit Data" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:320 +#, no-wrap +msgid "15" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:322 +#, no-wrap +msgid "DB" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:323 +#, no-wrap +msgid "114" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:324 +#: documentation/content/en/articles/serial-uart/_index.adoc:396 +#, no-wrap +msgid "TSET" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:327 +#: documentation/content/en/articles/serial-uart/_index.adoc:399 +#, no-wrap +msgid "Trans. Sig. Element Timing" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:328 +#, no-wrap +msgid "16" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:330 +#, no-wrap +msgid "SBB" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:331 +#, no-wrap +msgid "119" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:332 +#, no-wrap +msgid "SRD" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:335 +#, no-wrap +msgid "Secondary Received Data" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:336 +#, no-wrap +msgid "17" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:338 +#, no-wrap +msgid "DD" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:339 +#, no-wrap +msgid "115" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:340 +#, no-wrap +msgid "RSET" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:343 +#, no-wrap +msgid "Receiver Signal Element Timing" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:344 +#, no-wrap +msgid "18" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:347 +#, no-wrap +msgid "141" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:348 +#, no-wrap +msgid "LOOP" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:351 +#, no-wrap +msgid "Local Loopback" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:352 +#: documentation/content/en/articles/serial-uart/_index.adoc:614 +#, no-wrap +msgid "19" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:354 +#, no-wrap +msgid "SCA" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:355 +#, no-wrap +msgid "120" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:356 +#, no-wrap +msgid "SRS" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:359 +#, no-wrap +msgid "Secondary Request to Send" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:360 +#, no-wrap +msgid "20" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:362 +#, no-wrap +msgid "CD" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:363 +#, no-wrap +msgid "108.2" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:364 +#, no-wrap +msgid "DTR" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:367 +#, no-wrap +msgid "Data Terminal Ready" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:368 +#, no-wrap +msgid "21" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:372 +#, no-wrap +msgid "RDL" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:375 +#, no-wrap +msgid "Remote Digital Loopback" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:376 +#, no-wrap +msgid "22" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:378 +#, no-wrap +msgid "CE" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:379 +#, no-wrap +msgid "125" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:380 +#, no-wrap +msgid "RI" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:383 +#, no-wrap +msgid "Ring Indicator" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:384 +#: documentation/content/en/articles/serial-uart/_index.adoc:618 +#, no-wrap +msgid "23" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:386 +#, no-wrap +msgid "CH" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:387 +#, no-wrap +msgid "111" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:388 +#, no-wrap +msgid "DSRS" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:391 +#, no-wrap +msgid "Data Signal Rate Selector" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:392 +#, no-wrap +msgid "24" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:394 +#, no-wrap +msgid "DA" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:395 +#, no-wrap +msgid "113" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:400 +#, no-wrap +msgid "25" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:403 +#, no-wrap +msgid "142" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:406 +#, no-wrap +msgid "Test Mode" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/serial-uart/_index.adoc:408 +#, no-wrap +msgid "Bits, Baud and Symbols" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:412 +msgid "" +"Baud is a measurement of transmission speed in asynchronous communication. " +"Due to advances in modem communication technology, this term is frequently " +"misused when describing the data rates in newer devices." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:417 +msgid "" +"Traditionally, a Baud Rate represents the number of bits that are actually " +"being sent over the media, not the amount of data that is actually moved " +"from one DTE device to the other. The Baud count includes the overhead bits " +"Start, Stop and Parity that are generated by the sending UART and removed by " +"the receiving UART. This means that seven-bit words of data actually take " +"10 bits to be completely transmitted. Therefore, a modem capable of moving " +"300 bits per second from one place to another can normally only move 30 7-" +"bit words if Parity is used and one Start and Stop bit are present." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:419 +msgid "" +"If 8-bit data words are used and Parity bits are also used, the data rate " +"falls to 27.27 words per second, because it now takes 11 bits to send the " +"eight-bit words, and the modem still only sends 300 bits per second." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:425 +msgid "" +"The formula for converting bytes per second into a baud rate and vice versa " +"was simple until error-correcting modems came along. These modems receive " +"the serial stream of bits from the UART in the host computer (even when " +"internal modems are used the data is still frequently serialized) and " +"converts the bits back into bytes. These bytes are then combined into " +"packets and sent over the phone line using a Synchronous transmission " +"method. This means that the Stop, Start, and Parity bits added by the UART " +"in the DTE (the computer) were removed by the modem before transmission by " +"the sending modem. When these bytes are received by the remote modem, the " +"remote modem adds Start, Stop and Parity bits to the words, converts them to " +"a serial format and then sends them to the receiving UART in the remote " +"computer, who then strips the Start, Stop and Parity bits." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:428 +msgid "" +"The reason all these extra conversions are done is so that the two modems " +"can perform error correction, which means that the receiving modem is able " +"to ask the sending modem to resend a block of data that was not received " +"with the correct checksum. This checking is handled by the modems, and the " +"DTE devices are usually unaware that the process is occurring." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:431 +msgid "" +"By striping the Start, Stop and Parity bits, the additional bits of data " +"that the two modems must share between themselves to perform error-" +"correction are mostly concealed from the effective transmission rate seen by " +"the sending and receiving DTE equipment. For example, if a modem sends ten " +"7-bit words to another modem without including the Start, Stop and Parity " +"bits, the sending modem will be able to add 30 bits of its own information " +"that the receiving modem can use to do error-correction without impacting " +"the transmission speed of the real data." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:435 +msgid "" +"The use of the term Baud is further confused by modems that perform " +"compression. A single 8-bit word passed over the telephone line might " +"represent a dozen words that were transmitted to the sending modem. The " +"receiving modem will expand the data back to its original content and pass " +"that data to the receiving DTE." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:438 +msgid "" +"Modern modems also include buffers that allow the rate that bits move across " +"the phone line (DCE to DCE) to be a different speed than the speed that the " +"bits move between the DTE and DCE on both ends of the conversation. " +"Normally the speed between the DTE and DCE is higher than the DCE to DCE " +"speed because of the use of compression by the modems." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:441 +msgid "" +"As the number of bits needed to describe a byte varied during the trip " +"between the two machines plus the differing bits-per-seconds speeds that are " +"used present on the DTE-DCE and DCE-DCE links, the usage of the term Baud to " +"describe the overall communication speed causes problems and can " +"misrepresent the true transmission speed. So Bits Per Second (bps) is the " +"correct term to use to describe the transmission rate seen at the DCE to DCE " +"interface and Baud or Bits Per Second are acceptable terms to use when a " +"connection is made between two systems with a wired connection, or if a " +"modem is in use that is not performing error-correction or compression." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:445 +msgid "" +"Modern high speed modems (2400, 9600, 14,400, and 19,200bps) in reality " +"still operate at or below 2400 baud, or more accurately, 2400 Symbols per " +"second. High speed modem are able to encode more bits of data into each " +"Symbol using a technique called Constellation Stuffing, which is why the " +"effective bits per second rate of the modem is higher, but the modem " +"continues to operate within the limited audio bandwidth that the telephone " +"system provides. Modems operating at 28,800 and higher speeds have variable " +"Symbol rates, but the technique is the same." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/serial-uart/_index.adoc:446 +#, no-wrap +msgid "The IBM Personal Computer UART" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:450 +msgid "" +"Starting with the original IBM Personal Computer, IBM selected the National " +"Semiconductor INS8250 UART for use in the IBM PC Parallel/Serial Adapter. " +"Subsequent generations of compatible computers from IBM and other vendors " +"continued to use the INS8250 or improved versions of the National " +"Semiconductor UART family." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/serial-uart/_index.adoc:451 +#, no-wrap +msgid "National Semiconductor UART Family Tree" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:454 +msgid "" +"There have been several versions and subsequent generations of the INS8250 " +"UART. Each major version is described below." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:467 +#, no-wrap +msgid "" +"INS8250 -> INS8250B\n" +" \\\n" +" \\\n" +" \\-> INS8250A -> INS82C50A\n" +" \\\n" +" \\\n" +" \\-> NS16450 -> NS16C450\n" +" \\\n" +" \\\n" +" \\-> NS16550 -> NS16550A -> PC16550D\n" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:469 +#, no-wrap +msgid "INS8250" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:472 +msgid "" +"This part was used in the original IBM PC and IBM PC/XT. The original name " +"for this part was the INS8250 ACE (Asynchronous Communications Element) and " +"it is made from NMOS technology." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:476 +msgid "" +"The 8250 uses eight I/O ports and has a one-byte send and a one-byte receive " +"buffer. This original UART has several race conditions and other flaws. " +"The original IBM BIOS includes code to work around these flaws, but this " +"made the BIOS dependent on the flaws being present, so subsequent parts like " +"the 8250A, 16450 or 16550 could not be used in the original IBM PC or IBM PC/" +"XT." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:476 +#, no-wrap +msgid "INS8250-B" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:479 +msgid "" +"This is the slower speed of the INS8250 made from NMOS technology. It " +"contains the same problems as the original INS8250." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:480 +#, no-wrap +msgid "INS8250A" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:484 +msgid "" +"An improved version of the INS8250 using XMOS technology with various " +"functional flaws corrected. The INS8250A was used initially in PC clone " +"computers by vendors who used \"clean\" BIOS designs. Due to the " +"corrections in the chip, this part could not be used with a BIOS compatible " +"with the INS8250 or INS8250B." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:485 +#, no-wrap +msgid "INS82C50A" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:487 +msgid "" +"This is a CMOS version (low power consumption) of the INS8250A and has " +"similar functional characteristics." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:488 +#, no-wrap +msgid "NS16450" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:491 +msgid "" +"Same as NS8250A with improvements so it can be used with faster CPU bus " +"designs. IBM used this part in the IBM AT and updated the IBM BIOS to no " +"longer rely on the bugs in the INS8250." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:492 +#, no-wrap +msgid "NS16C450" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:494 +msgid "This is a CMOS version (low power consumption) of the NS16450." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:495 +#, no-wrap +msgid "NS16550" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:497 +msgid "" +"Same as NS16450 with a 16-byte send and receive buffer but the buffer design " +"was flawed and could not be reliably be used." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:498 +#, no-wrap +msgid "NS16550A" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:501 +msgid "" +"Same as NS16550 with the buffer flaws corrected. The 16550A and its " +"successors have become the most popular UART design in the PC industry, " +"mainly due to its ability to reliably handle higher data rates on operating " +"systems with sluggish interrupt response times." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:502 +#, no-wrap +msgid "NS16C552" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:504 +msgid "" +"This component consists of two NS16C550A CMOS UARTs in a single package." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:505 +#, no-wrap +msgid "PC16550D" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:508 +msgid "" +"Same as NS16550A with subtle flaws corrected. This is revision D of the " +"16550 family and is the latest design available from National Semiconductor." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/serial-uart/_index.adoc:509 +#, no-wrap +msgid "The NS16550AF and the PC16550D are the same thing" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:515 +msgid "" +"National reorganized their part numbering system a few years ago, and the " +"NS16550AFN no longer exists by that name. (If you have a NS16550AFN, look " +"at the date code on the part, which is a four digit number that usually " +"starts with a nine. The first two digits of the number are the year, and " +"the last two digits are the week in that year when the part was packaged. " +"If you have a NS16550AFN, it is probably a few years old.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:518 +msgid "" +"The new numbers are like PC16550DV, with minor differences in the suffix " +"letters depending on the package material and its shape. (A description of " +"the numbering system can be found below.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:520 +msgid "" +"It is important to understand that in some stores, you may pay $15(US) for a " +"NS16550AFN made in 1990 and in the next bin are the new PC16550DN parts with " +"minor fixes that National has made since the AFN part was in production, the " +"PC16550DN was probably made in the past six months and it costs half (as low " +"as $5(US) in volume) as much as the NS16550AFN because they are readily " +"available." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:522 +msgid "" +"As the supply of NS16550AFN chips continues to shrink, the price will " +"probably continue to increase until more people discover and accept that the " +"PC16550DN really has the same function as the old part number." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/serial-uart/_index.adoc:523 +#, no-wrap +msgid "National Semiconductor Part Numbering System" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:526 +msgid "" +"The older NS``__nnnnnrqp__`` part numbers are now of the format " +"PC``__nnnnnrgp__``." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:528 +msgid "" +"The `_r_` is the revision field. The current revision of the 16550 from " +"National Semiconductor is `D`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:530 +msgid "The `_p_` is the package-type field. The types are:" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:536 +#, no-wrap +msgid "\"F\"" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:537 +#, no-wrap +msgid "QFP" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:539 +#, no-wrap +msgid "(quad flat pack) L lead type" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:540 +#, no-wrap +msgid "\"N\"" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:541 +#, no-wrap +msgid "DIP" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:543 +#, no-wrap +msgid "(dual inline package) through hole straight lead type" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:544 +#, no-wrap +msgid "\"V\"" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:545 +#, no-wrap +msgid "LPCC" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:546 +#, no-wrap +msgid "(lead plastic chip carrier) J lead type" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:551 +msgid "" +"The _g_ is the product grade field. If an `I` precedes the package-type " +"letter, it indicates an \"industrial\" grade part, which has higher specs " +"than a standard part but not as high as Military Specification (Milspec) " +"component. This is an optional field." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:553 +msgid "" +"So what we used to call a NS16550AFN (DIP Package) is now called a PC16550DN " +"or PC16550DIN." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/serial-uart/_index.adoc:554 +#, no-wrap +msgid "Other Vendors and Similar UARTs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:559 +msgid "" +"Over the years, the 8250, 8250A, 16450 and 16550 have been licensed or " +"copied by other chip vendors. In the case of the 8250, 8250A and 16450, the " +"exact circuit (the \"megacell\") was licensed to many vendors, including " +"Western Digital and Intel. Other vendors reverse-engineered the part or " +"produced emulations that had similar behavior." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:563 +msgid "" +"In internal modems, the modem designer will frequently emulate the " +"8250A/16450 with the modem microprocessor, and the emulated UART will " +"frequently have a hidden buffer consisting of several hundred bytes. Due to " +"the size of the buffer, these emulations can be as reliable as a 16550A in " +"their ability to handle high speed data. However, most operating systems " +"will still report that the UART is only a 8250A or 16450, and may not make " +"effective use of the extra buffering present in the emulated UART unless " +"special drivers are used." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:565 +msgid "" +"Some modem makers are driven by market forces to abandon a design that has " +"hundreds of bytes of buffer and instead use a 16550A UART so that the " +"product will compare favorably in market comparisons even though the " +"effective performance may be lowered by this action." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:568 +msgid "" +"A common misconception is that all parts with \"16550A\" written on them are " +"identical in performance. There are differences, and in some cases, " +"outright flaws in most of these 16550A clones." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:572 +msgid "" +"When the NS16550 was developed, the National Semiconductor obtained several " +"patents on the design and they also limited licensing, making it harder for " +"other vendors to provide a chip with similar features. As a result of the " +"patents, reverse-engineered designs and emulations had to avoid infringing " +"the claims covered by the patents. Subsequently, these copies almost never " +"perform exactly the same as the NS16550A or PC16550D, which are the parts " +"most computer and modem makers want to buy but are sometimes unwilling to " +"pay the price required to get the genuine part." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:577 +msgid "" +"Some of the differences in the clone 16550A parts are unimportant, while " +"others can prevent the device from being used at all with a given operating " +"system or driver. These differences may show up when using other drivers, " +"or when particular combinations of events occur that were not well tested or " +"considered in the Windows(R) driver. This is because most modem vendors and " +"16550-clone makers use the Microsoft drivers from Windows(R) for Workgroups " +"3.11 and the Microsoft(R) MS-DOS(R) utility as the primary tests for " +"compatibility with the NS16550A. This over-simplistic criteria means that " +"if a different operating system is used, problems could appear due to subtle " +"differences between the clones and genuine components." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:580 +msgid "" +"National Semiconductor has made available a program named COMTEST that " +"performs compatibility tests independent of any OS drivers. It should be " +"remembered that the purpose of this type of program is to demonstrate the " +"flaws in the products of the competition, so the program will report major " +"as well as extremely subtle differences in behavior in the part being tested." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:583 +msgid "" +"In a series of tests performed by the author of this document in 1994, " +"components made by National Semiconductor, TI, StarTech, and CMD as well as " +"megacells and emulations embedded in internal modems were tested with " +"COMTEST. A difference count for some of these components is listed below. " +"Since these tests were performed in 1994, they may not reflect the current " +"performance of the given product from a vendor." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:586 +msgid "" +"It should be noted that COMTEST normally aborts when an excessive number or " +"certain types of problems have been detected. As part of this testing, " +"COMTEST was modified so that it would not abort no matter how many " +"differences were encountered." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:591 +#, no-wrap +msgid "Vendor" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:592 +#, no-wrap +msgid "Part Number" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:594 +#, no-wrap +msgid "Errors (aka \"differences\" reported)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:595 +#: documentation/content/en/articles/serial-uart/_index.adoc:599 +#: documentation/content/en/articles/serial-uart/_index.adoc:603 +#, no-wrap +msgid "National" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:596 +#, no-wrap +msgid "(PC16550DV)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:598 +#: documentation/content/en/articles/serial-uart/_index.adoc:602 +#: documentation/content/en/articles/serial-uart/_index.adoc:606 +#, no-wrap +msgid "0" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:600 +#, no-wrap +msgid "(NS16550AFN)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:604 +#, no-wrap +msgid "(NS16C552V)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:607 +#, no-wrap +msgid "TI" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:608 +#, no-wrap +msgid "(TL16550AFN)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:611 +#, no-wrap +msgid "CMD" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:612 +#, no-wrap +msgid "(16C550PE)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:615 +#, no-wrap +msgid "StarTech" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:616 +#, no-wrap +msgid "(ST16C550J)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:619 +#, no-wrap +msgid "Rockwell" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:620 +#, no-wrap +msgid "Reference modem with internal 16550 or an emulation (RC144DPi/C3000-25)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:622 +#, no-wrap +msgid "117" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:623 +#, no-wrap +msgid "Sierra" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:624 +#, no-wrap +msgid "Modem with an internal 16550 (SC11951/SC11351)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:625 +#, no-wrap +msgid "91" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:632 +msgid "" +"To date, the author of this document has not found any non-National parts " +"that report zero differences using the COMTEST program. It should also be " +"noted that National has had five versions of the 16550 over the years and " +"the newest parts behave a bit differently than the classic NS16550AFN that " +"is considered the benchmark for functionality. COMTEST appears to turn a " +"blind eye to the differences within the National product line and reports no " +"errors on the National parts (except for the original 16550) even when there " +"are official erratas that describe bugs in the A, B and C revisions of the " +"parts, so this bias in COMTEST must be taken into account." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:639 +msgid "" +"It is important to understand that a simple count of differences from " +"COMTEST does not reveal a lot about what differences are important and which " +"are not. For example, about half of the differences reported in the two " +"modems listed above that have internal UARTs were caused by the clone UARTs " +"not supporting five- and six-bit character modes. The real 16550, 16450, " +"and 8250 UARTs all support these modes and COMTEST checks the functionality " +"of these modes so over fifty differences are reported. However, almost no " +"modern modem supports five- or six-bit characters, particularly those with " +"error-correction and compression capabilities. This means that the " +"differences related to five- and six-bit character modes can be discounted." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:643 +msgid "" +"Many of the differences COMTEST reports have to do with timing. In many of " +"the clone designs, when the host reads from one port, the status bits in " +"some other port may not update in the same amount of time (some faster, some " +"slower) as a _real_ NS16550AFN and COMTEST looks for these differences. " +"This means that the number of differences can be misleading in that one " +"device may only have one or two differences but they are extremely serious, " +"and some other device that updates the status registers faster or slower " +"than the reference part (that would probably never affect the operation of a " +"properly written driver) could have dozens of differences reported." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:645 +msgid "" +"COMTEST can be used as a screening tool to alert the administrator to the " +"presence of potentially incompatible components that might cause problems or " +"have to be handled as a special case." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:648 +msgid "" +"If you run COMTEST on a 16550 that is in a modem or a modem is attached to " +"the serial port, you need to first issue a ATE0&W command to the modem so " +"that the modem will not echo any of the test characters. If you forget to " +"do this, COMTEST will report at least this one difference:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:652 +#, no-wrap +msgid "Error (6)...Timeout interrupt failed: IIR = c1 LSR = 61\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/serial-uart/_index.adoc:654 +#, no-wrap +msgid "8250/16450/16550 Registers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:660 +msgid "" +"The 8250/16450/16550 UART occupies eight contiguous I/O port addresses. In " +"the IBM PC, there are two defined locations for these eight ports and they " +"are known collectively as [.filename]#COM1# and [.filename]#COM2#. The " +"makers of PC-clones and add-on cards have created two additional areas known " +"as [.filename]#COM3# and [.filename]#COM4#, but these extra COM ports " +"conflict with other hardware on some systems. The most common conflict is " +"with video adapters that provide IBM 8514 emulation." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:665 +msgid "" +"[.filename]#COM1# is located from 0x3f8 to 0x3ff and normally uses IRQ 4. [." +"filename]#COM2# is located from 0x2f8 to 0x2ff and normally uses IRQ 3. [." +"filename]#COM3# is located from 0x3e8 to 0x3ef and has no standardized IRQ. " +"[.filename]#COM4# is located from 0x2e8 to 0x2ef and has no standardized IRQ." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:667 +msgid "" +"A description of the I/O ports of the 8250/16450/16550 UART is provided " +"below." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:672 +#, no-wrap +msgid "I/O Port" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:673 +#, no-wrap +msgid "Access Allowed" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:676 +#: documentation/content/en/articles/serial-uart/_index.adoc:684 +#: documentation/content/en/articles/serial-uart/_index.adoc:692 +#, no-wrap +msgid "+0x00" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:677 +#, no-wrap +msgid "write (DLAB==0)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:683 +#, no-wrap +msgid "" +"Transmit Holding Register (THR).\n" +"\n" +"Information written to this port are treated as data words and will be transmitted by the UART." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:685 +#, no-wrap +msgid "read (DLAB==0)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:691 +#, no-wrap +msgid "" +"Receive Buffer Register (RBR).\n" +"\n" +"Any data words received by the UART form the serial link are accessed by the host by reading this port." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:693 +#: documentation/content/en/articles/serial-uart/_index.adoc:701 +#, no-wrap +msgid "write/read (DLAB==1)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:699 +#, no-wrap +msgid "" +"Divisor Latch LSB (DLL)\n" +"\n" +"This value will be divided from the master input clock (in the IBM PC, the master clock is 1.8432MHz) and the resulting clock will determine the baud rate of the UART. This register holds bits 0 thru 7 of the divisor." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:700 +#: documentation/content/en/articles/serial-uart/_index.adoc:708 +#, no-wrap +msgid "+0x01" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:707 +#, no-wrap +msgid "" +"Divisor Latch MSB (DLH)\n" +"\n" +"This value will be divided from the master input clock (in the IBM PC, the master clock is 1.8432MHz) and the resulting clock will determine the baud rate of the UART. This register holds bits 8 thru 15 of the divisor." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:709 +#, no-wrap +msgid "write/read (DLAB==0)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:721 +#, no-wrap +msgid "" +"Interrupt Enable Register (IER) +\n" +"\n" +"The 8250/16450/16550 UART classifies events into one of four categories. Each category can be configured to generate an interrupt when any of the events occurs. The 8250/16450/16550 UART generates a single external interrupt signal regardless of how many events in the enabled categories have occurred. It is up to the host processor to respond to the interrupt and then poll the enabled interrupt categories (usually all categories have interrupts enabled) to determine the true cause(s) of the interrupt. +\n" +"Bit 7 -> Reserved, always 0. +\n" +"Bit 6 -> Reserved, always 0. +\n" +"Bit 5 -> Reserved, always 0. +\n" +"Bit 4 -> Reserved, always 0. +\n" +"Bit 3 -> Enable Modem Status Interrupt (EDSSI). Setting this bit to \"1\" allows the UART to generate an interrupt when a change occurs on one or more of the status lines. +\n" +"Bit 2 -> Enable Receiver Line Status Interrupt (ELSI) Setting this bit to \"1\" causes the UART to generate an interrupt when the an error (or a BREAK signal) has been detected in the incoming data. +\n" +"Bit 1 -> Enable Transmitter Holding Register Empty Interrupt (ETBEI) Setting this bit to \"1\" causes the UART to generate an interrupt when the UART has room for one or more additional characters that are to be transmitted. +\n" +"Bit 0 -> Enable Received Data Available Interrupt (ERBFI) Setting this bit to \"1\" causes the UART to generate an interrupt when the UART has received enough characters to exceed the trigger level of the FIFO, or the FIFO timer has expired (stale data), or a single character has been received when the FIFO is disabled." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:722 +#: documentation/content/en/articles/serial-uart/_index.adoc:741 +#, no-wrap +msgid "+0x02" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:723 +#, no-wrap +msgid "write" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:740 +#, no-wrap +msgid "" +"FIFO Control Register (FCR) (This port does not exist on the 8250 and 16450 UART.) +\n" +"Bit 7 -> Receiver Trigger Bit #1 +\n" +"Bit 6 -> Receiver Trigger Bit #0 +\n" +"\n" +"These two bits control at what point the receiver is to generate an interrupt when the FIFO is active. +\n" +"7 6 How many words are received before an interrupt is generated +\n" +"0 0 1 +\n" +"0 1 4 +\n" +"1 0 8 +\n" +"1 1 14 +\n" +"Bit 5 -> Reserved, always 0. +\n" +"Bit 4 -> Reserved, always 0. +\n" +"Bit 3 -> DMA Mode Select. If Bit 0 is set to \"1\" (FIFOs enabled), setting this bit changes the operation of the -RXRDY and -TXRDY signals from Mode 0 to Mode 1. +\n" +"Bit 2 -> Transmit FIFO Reset. When a \"1\" is written to this bit, the contents of the FIFO are discarded. Any word currently being transmitted will be sent intact. This function is useful in aborting transfers. +\n" +"Bit 1 -> Receiver FIFO Reset. When a \"1\" is written to this bit, the contents of the FIFO are discarded. Any word currently being assembled in the shift register will be received intact. +\n" +"Bit 0 -> 16550 FIFO Enable. When set, both the transmit and receive FIFOs are enabled. Any contents in the holding register, shift registers or FIFOs are lost when FIFOs are enabled or disabled. +" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:742 +#, no-wrap +msgid "read" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:758 +#, no-wrap +msgid "" +"Interrupt Identification Register +\n" +"Bit 7 -> FIFOs enabled. On the 8250/16450 UART, this bit is zero. +\n" +"Bit 6 -> FIFOs enabled. On the 8250/16450 UART, this bit is zero. +\n" +"Bit 5 -> Reserved, always 0. +\n" +"Bit 4 -> Reserved, always 0. +\n" +"Bit 3 -> Interrupt ID Bit #2. On the 8250/16450 UART, this bit is zero. +\n" +"Bit 2 -> Interrupt ID Bit #1 +\n" +"Bit 1 -> Interrupt ID Bit #0.These three bits combine to report the category of event that caused the interrupt that is in progress. These categories have priorities, so if multiple categories of events occur at the same time, the UART will report the more important events first and the host must resolve the events in the order they are reported. All events that caused the current interrupt must be resolved before any new interrupts will be generated. (This is a limitation of the PC architecture.) +\n" +"2 1 0 Priority Description +\n" +"0 1 1 First Received Error (OE, PE, BI, or FE) +\n" +"0 1 0 Second Received Data Available +\n" +"1 1 0 Second Trigger level identification (Stale data in receive buffer) +\n" +"0 0 1 Third Transmitter has room for more words (THRE) +\n" +"0 0 0 Fourth Modem Status Change (-CTS, -DSR, -RI, or -DCD) +\n" +"Bit 0 -> Interrupt Pending Bit. If this bit is set to \"0\", then at least one interrupt is pending." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:759 +#, no-wrap +msgid "+0x03" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:760 +#: documentation/content/en/articles/serial-uart/_index.adoc:778 +#: documentation/content/en/articles/serial-uart/_index.adoc:790 +#: documentation/content/en/articles/serial-uart/_index.adoc:802 +#: documentation/content/en/articles/serial-uart/_index.adoc:813 +#, no-wrap +msgid "write/read" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:776 +#, no-wrap +msgid "" +"Line Control Register (LCR) +\n" +"Bit 7 -> Divisor Latch Access Bit (DLAB). When set, access to the data transmit/receive register (THR/RBR) and the Interrupt Enable Register (IER) is disabled. Any access to these ports is now redirected to the Divisor Latch Registers. Setting this bit, loading the Divisor Registers, and clearing DLAB should be done with interrupts disabled. +\n" +"Bit 6 -> Set Break. When set to \"1\", the transmitter begins to transmit continuous Spacing until this bit is set to \"0\". This overrides any bits of characters that are being transmitted. +\n" +"Bit 5 -> Stick Parity. When parity is enabled, setting this bit causes parity to always be \"1\" or \"0\", based on the value of Bit 4.\n" +"Bit 4 -> Even Parity Select (EPS). When parity is enabled and Bit 5 is \"0\", setting this bit causes even parity to be transmitted and expected. Otherwise, odd parity is used. +\n" +"Bit 3 -> Parity Enable (PEN). When set to \"1\", a parity bit is inserted between the last bit of the data and the Stop Bit. The UART will also expect parity to be present in the received data. +\n" +"Bit 2 -> Number of Stop Bits (STB). If set to \"1\" and using 5-bit data words, 1.5 Stop Bits are transmitted and expected in each data word. For 6, 7 and 8-bit data words, 2 Stop Bits are transmitted and expected. When this bit is set to \"0\", one Stop Bit is used on each data word. +\n" +"Bit 1 -> Word Length Select Bit #1 (WLSB1) +\n" +"Bit 0 -> Word Length Select Bit #0 (WLSB0) +\n" +"Together these bits specify the number of bits in each data word. +\n" +"1 0 Word Length +\n" +"0 0 5 Data Bits +\n" +"0 1 6 Data Bits +\n" +"1 0 7 Data Bits +\n" +"1 1 8 Data Bits +" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:777 +#, no-wrap +msgid "+0x04" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:788 +#, no-wrap +msgid "" +"Modem Control Register (MCR) +\n" +"Bit 7 -> Reserved, always 0. +\n" +"Bit 6 -> Reserved, always 0. +\n" +"Bit 5 -> Reserved, always 0. +\n" +"Bit 4 -> Loop-Back Enable. When set to \"1\", the UART transmitter and receiver are internally connected together to allow diagnostic operations. In addition, the UART modem control outputs are connected to the UART modem control inputs. CTS is connected to RTS, DTR is connected to DSR, OUT1 is connected to RI, and OUT 2 is connected to DCD. +\n" +"Bit 3 -> OUT 2. An auxiliary output that the host processor may set high or low. In the IBM PC serial adapter (and most clones), OUT 2 is used to tri-state (disable) the interrupt signal from the 8250/16450/16550 UART. +\n" +"Bit 2 -> OUT 1. An auxiliary output that the host processor may set high or low. This output is not used on the IBM PC serial adapter. +\n" +"Bit 1 -> Request to Send (RTS). When set to \"1\", the output of the UART -RTS line is Low (Active). +\n" +"Bit 0 -> Data Terminal Ready (DTR). When set to \"1\", the output of the UART -DTR line is Low (Active). +" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:789 +#, no-wrap +msgid "+0x05" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:800 +#, no-wrap +msgid "" +"Line Status Register (LSR) +\n" +"Bit 7 -> Error in Receiver FIFO. On the 8250/16450 UART, this bit is zero. This bit is set to \"1\" when any of the bytes in the FIFO have one or more of the following error conditions: PE, FE, or BI. +\n" +"Bit 6 -> Transmitter Empty (TEMT). When set to \"1\", there are no words remaining in the transmit FIFO or the transmit shift register. The transmitter is completely idle. +\n" +"Bit 5 -> Transmitter Holding Register Empty (THRE). When set to \"1\", the FIFO (or holding register) now has room for at least one additional word to transmit. The transmitter may still be transmitting when this bit is set to \"1\". +\n" +"Bit 4 -> Break Interrupt (BI). The receiver has detected a Break signal. +\n" +"Bit 3 -> Framing Error (FE). A Start Bit was detected but the Stop Bit did not appear at the expected time. The received word is probably garbled. +\n" +"Bit 2 -> Parity Error (PE). The parity bit was incorrect for the word received. +\n" +"Bit 1 -> Overrun Error (OE). A new word was received and there was no room in the receive buffer. The newly-arrived word in the shift register is discarded. On 8250/16450 UARTs, the word in the holding register is discarded and the newly- arrived word is put in the holding register. +\n" +"Bit 0 -> Data Ready (DR) One or more words are in the receive FIFO that the host may read. A word must be completely received and moved from the shift register into the FIFO (or holding register for 8250/16450 designs) before this bit is set." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:801 +#, no-wrap +msgid "+0x06" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:811 +#, no-wrap +msgid "" +"Modem Status Register (MSR) +\n" +"Bit 7 -> Data Carrier Detect (DCD). Reflects the state of the DCD line on the UART. +\n" +"Bit 6 -> Ring Indicator (RI). Reflects the state of the RI line on the UART. +\n" +"Bit 5 -> Data Set Ready (DSR). Reflects the state of the DSR line on the UART. +\n" +"Bit 4 -> Clear To Send (CTS). Reflects the state of the CTS line on the UART. +\n" +"Bit 3 -> Delta Data Carrier Detect (DDCD). Set to \"1\" if the -DCD line has changed state one more time since the last time the MSR was read by the host. +\n" +"Bit 2 -> Trailing Edge Ring Indicator (TERI). Set to \"1\" if the -RI line has had a low to high transition since the last time the MSR was read by the host. +\n" +"Bit 1 -> Delta Data Set Ready (DDSR). Set to \"1\" if the -DSR line has changed state one more time since the last time the MSR was read by the host. +\n" +"Bit 0 -> Delta Clear To Send (DCTS). Set to \"1\" if the -CTS line has changed state one more time since the last time the MSR was read by the host. +" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:812 +#, no-wrap +msgid "+0x07" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/serial-uart/_index.adoc:814 +#, no-wrap +msgid "Scratch Register (SCR). This register performs no function in the UART. Any value can be written by the host to this location and read by the host later on." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/serial-uart/_index.adoc:816 +#, no-wrap +msgid "Beyond the 16550A UART" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:821 +msgid "" +"Although National Semiconductor has not offered any components compatible " +"with the 16550 that provide additional features, various other vendors " +"have. Some of these components are described below. It should be " +"understood that to effectively utilize these improvements, drivers may have " +"to be provided by the chip vendor since most of the popular operating " +"systems do not support features beyond those provided by the 16550." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:822 +#, no-wrap +msgid "ST16650" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:825 +msgid "" +"By default this part is similar to the NS16550A, but an extended 32-byte " +"send and receive buffer can be optionally enabled. Made by StarTech." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:826 +#, no-wrap +msgid "TIL16660" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:829 +msgid "" +"By default this part behaves similar to the NS16550A, but an extended 64-" +"byte send and receive buffer can be optionally enabled. Made by Texas " +"Instruments." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/serial-uart/_index.adoc:830 +#, no-wrap +msgid "Hayes ESP" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:833 +msgid "" +"This proprietary plug-in card contains a 2048-byte send and receive buffer, " +"and supports data rates to 230.4Kbit/sec. Made by Hayes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:838 +msgid "" +"In addition to these \"dumb\" UARTs, many vendors produce intelligent serial " +"communication boards. This type of design usually provides a microprocessor " +"that interfaces with several UARTs, processes and buffers the data, and then " +"alerts the main PC processor when necessary. As the UARTs are not directly " +"accessed by the PC processor in this type of communication system, it is not " +"necessary for the vendor to use UARTs that are compatible with the 8250, " +"16450, or the 16550 UART. This leaves the designer free to components that " +"may have better performance characteristics." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/serial-uart/_index.adoc:840 +#, no-wrap +msgid "Configuring the [.filename]#sio# driver" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:845 +msgid "" +"The [.filename]#sio# driver provides support for NS8250-, NS16450-, NS16550 " +"and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. " +"Several multiport cards are supported as well. See the man:sio[4] manual " +"page for detailed technical documentation." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/serial-uart/_index.adoc:846 +#, no-wrap +msgid "Digi International (DigiBoard) PC/8" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:849 +msgid "_Contributed by `{awebster}`. 26 August 1995._" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:853 +msgid "" +"Here is a config snippet from a machine with a Digi International PC/8 with " +"16550. It has 8 modems connected to these 8 lines, and they work just " +"great. Do not forget to add `options COM_MULTIPORT` or it will not work " +"very well!" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:864 +#, no-wrap +msgid "" +"device sio4 at isa? port 0x100 flags 0xb05\n" +"device sio5 at isa? port 0x108 flags 0xb05\n" +"device sio6 at isa? port 0x110 flags 0xb05\n" +"device sio7 at isa? port 0x118 flags 0xb05\n" +"device sio8 at isa? port 0x120 flags 0xb05\n" +"device sio9 at isa? port 0x128 flags 0xb05\n" +"device sio10 at isa? port 0x130 flags 0xb05\n" +"device sio11 at isa? port 0x138 flags 0xb05 irq 9\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:867 +msgid "" +"The trick in setting this up is that the MSB of the flags represent the last " +"SIO port, in this case 11 so flags are 0xb05." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/serial-uart/_index.adoc:868 +#, no-wrap +msgid "Boca 16" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:871 +msgid "_Contributed by `{whiteside}`. 26 August 1995._" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:873 +msgid "" +"The procedures to make a Boca 16 port board with FreeBSD are pretty " +"straightforward, but you will need a couple things to make it work:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:875 +msgid "" +"You either need the kernel sources installed so you can recompile the " +"necessary options or you will need someone else to compile it for you. The " +"2.0.5 default kernel does _not_ come with multiport support enabled and you " +"will need to add a device entry for each port anyways." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:876 +msgid "" +"Two, you will need to know the interrupt and IO setting for your Boca Board " +"so you can set these options properly in the kernel." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:880 +msgid "" +"One important note - the actual UART chips for the Boca 16 are in the " +"connector box, not on the internal board itself. So if you have it " +"unplugged, probes of those ports will fail. I have never tested booting " +"with the box unplugged and plugging it back in, and I suggest you do not " +"either." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:883 +msgid "" +"If you do not already have a custom kernel configuration file set up, refer " +"to extref:{handbook}[Kernel Configuration, kernelconfig] chapter of the " +"FreeBSD Handbook for general procedures. The following are the specifics " +"for the Boca 16 board and assume you are using the kernel name MYKERNEL and " +"editing with vi." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:887 +msgid "Add the line" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:891 +#, no-wrap +msgid "options COM_MULTIPORT\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:893 +msgid "to the config file." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:894 +msgid "" +"Where the current `device sio__n__` lines are, you will need to add 16 more " +"devices. The following example is for a Boca Board with an interrupt of 3, " +"and a base IO address 100h. The IO address for Each port is +8 hexadecimal " +"from the previous port, thus the 100h, 108h, 110h... addresses." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:904 +#, no-wrap +msgid "" +"device sio1 at isa? port 0x100 flags 0x1005\n" +"device sio2 at isa? port 0x108 flags 0x1005\n" +"device sio3 at isa? port 0x110 flags 0x1005\n" +"device sio4 at isa? port 0x118 flags 0x1005\n" +"...\n" +"device sio15 at isa? port 0x170 flags 0x1005\n" +"device sio16 at isa? port 0x178 flags 0x1005 irq 3\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:909 +msgid "" +"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," +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:914 +#, no-wrap +msgid "" +" flags\n" +"\t 0x1005\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:918 +msgid "" +"indicates that the master port is sio16. If I added another board and " +"assigned sio17 through sio28, the flags for all 16 ports on _that_ board " +"would be 0x1C05, where 1C indicates the minor number of the master port. Do " +"not change the 05 setting." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:919 +msgid "" +"Save and complete the kernel configuration, recompile, install and reboot. " +"Presuming you have successfully installed the recompiled kernel and have it " +"set to the correct address and IRQ, your boot message should indicate the " +"successful probe of the Boca ports as follows: (obviously the sio numbers, " +"IO and IRQ could be different)" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:954 +#, no-wrap +msgid "" +"sio1 at 0x100-0x107 flags 0x1005 on isa\n" +"sio1: type 16550A (multiport)\n" +"sio2 at 0x108-0x10f flags 0x1005 on isa\n" +"sio2: type 16550A (multiport)\n" +"sio3 at 0x110-0x117 flags 0x1005 on isa\n" +"sio3: type 16550A (multiport)\n" +"sio4 at 0x118-0x11f flags 0x1005 on isa\n" +"sio4: type 16550A (multiport)\n" +"sio5 at 0x120-0x127 flags 0x1005 on isa\n" +"sio5: type 16550A (multiport)\n" +"sio6 at 0x128-0x12f flags 0x1005 on isa\n" +"sio6: type 16550A (multiport)\n" +"sio7 at 0x130-0x137 flags 0x1005 on isa\n" +"sio7: type 16550A (multiport)\n" +"sio8 at 0x138-0x13f flags 0x1005 on isa\n" +"sio8: type 16550A (multiport)\n" +"sio9 at 0x140-0x147 flags 0x1005 on isa\n" +"sio9: type 16550A (multiport)\n" +"sio10 at 0x148-0x14f flags 0x1005 on isa\n" +"sio10: type 16550A (multiport)\n" +"sio11 at 0x150-0x157 flags 0x1005 on isa\n" +"sio11: type 16550A (multiport)\n" +"sio12 at 0x158-0x15f flags 0x1005 on isa\n" +"sio12: type 16550A (multiport)\n" +"sio13 at 0x160-0x167 flags 0x1005 on isa\n" +"sio13: type 16550A (multiport)\n" +"sio14 at 0x168-0x16f flags 0x1005 on isa\n" +"sio14: type 16550A (multiport)\n" +"sio15 at 0x170-0x177 flags 0x1005 on isa\n" +"sio15: type 16550A (multiport)\n" +"sio16 at 0x178-0x17f irq 3 flags 0x1005 on isa\n" +"sio16: type 16550A (multiport master)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:957 +msgid "If the messages go by too fast to see," +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:961 +#, no-wrap +msgid "# dmesg | more\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:963 +msgid "will show you the boot messages." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:964 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:966 +msgid "" +"If you do need to create the [.filename]#/dev# entries, run the following as " +"`root`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:972 +#, no-wrap +msgid "" +"# cd /dev\n" +"# ./MAKEDEV tty1\n" +"# ./MAKEDEV cua1\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:976 +#, no-wrap +msgid "" +"(everything in between)\n" +"# ./MAKEDEV ttyg\n" +"# ./MAKEDEV cuag\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:979 +msgid "" +"If you do not want or need call-out devices for some reason, you can " +"dispense with making the [.filename]#cua*# devices." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:980 +msgid "" +"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)" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:984 +#, no-wrap +msgid "# echo at > ttyd*\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:986 +msgid "" +"for each device you have made. You _should_ see the RX lights flash for each " +"working port." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/serial-uart/_index.adoc:988 +#, no-wrap +msgid "Support for Cheap Multi-UART Cards" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:991 +msgid "" +"_Contributed by Helge Oldach_ mailto:hmo@sep.hamburg.com[hmo@sep.hamburg." +"com], September 1999" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:993 +msgid "" +"Ever wondered about FreeBSD support for your 20$ multi-I/O card with two (or " +"more) COM ports, sharing IRQs? Here is how:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:997 +msgid "" +"Usually the only option to support these kind of boards is to use a distinct " +"IRQ for each port. For example, if your CPU board has an on-board [." +"filename]#COM1# port (aka [.filename]#sio0#-I/O address 0x3F8 and IRQ 4) and " +"you have an extension board with two UARTs, you will commonly need to " +"configure them as [.filename]#COM2# (aka [.filename]#sio1#-I/O address 0x2F8 " +"and IRQ 3), and the third port (aka [.filename]#sio2#) as I/O 0x3E8 and IRQ " +"5. Obviously this is a waste of IRQ resources, as it should be basically " +"possible to run both extension board ports using a single IRQ with the " +"`COM_MULTIPORT` configuration described in the previous sections." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:999 +msgid "" +"Such cheap I/O boards commonly have a 4 by 3 jumper matrix for the COM " +"ports, similar to the following:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1008 +#, no-wrap +msgid "" +" o o o *\n" +"Port A |\n" +" o * o *\n" +"Port B |\n" +" o * o o\n" +"IRQ 2 3 4 5\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1012 +msgid "" +"Shown here is port A wired for IRQ 5 and port B wired for IRQ 3. The IRQ " +"columns on your specific board may vary-other boards may supply jumpers for " +"IRQs 3, 4, 5, and 7 instead." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1016 +msgid "" +"One could conclude that wiring both ports for IRQ 3 using a handcrafted wire-" +"made jumper covering all three connection points in the IRQ 3 column would " +"solve the issue, but no. You cannot duplicate IRQ 3 because the output " +"drivers of each UART are wired in a \"totem pole\" fashion, so if one of the " +"UARTs drives IRQ 3, the output signal will not be what you would expect. " +"Depending on the implementation of the extension board or your motherboard, " +"the IRQ 3 line will continuously stay up, or always stay low." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1020 +msgid "" +"You need to decouple the IRQ drivers for the two UARTs, so that the IRQ line " +"of the board only goes up if (and only if) one of the UARTs asserts a IRQ, " +"and stays low otherwise. The solution was proposed by Joerg Wunsch mailto:" +"j@ida.interface-business.de[j@ida.interface-business.de]: To solder up a " +"wired-or consisting of two diodes (Germanium or Schottky-types strongly " +"preferred) and a 1 kOhm resistor. Here is the schematic, starting from the " +"4 by 3 jumper field above:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1034 +#, no-wrap +msgid "" +" Diode\n" +" +---------->|-------+\n" +" / |\n" +" o * o o | 1 kOhm\n" +"Port A +----|######|-------+\n" +" o * o o | |\n" +"Port B `-------------------+ ==+==\n" +" o * o o | Ground\n" +" \\ |\n" +" +--------->|-------+\n" +"IRQ 2 3 4 5 Diode\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1038 +msgid "" +"The cathodes of the diodes are connected to a common point, together with a " +"1 kOhm pull-down resistor. It is essential to connect the resistor to " +"ground to avoid floating of the IRQ line on the bus." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1041 +msgid "" +"Now we are ready to configure a kernel. Staying with this example, we would " +"configure:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1050 +#, no-wrap +msgid "" +"# standard on-board COM1 port\n" +"device sio0 at isa? port \"IO_COM1\" flags 0x10\n" +"# patched-up multi-I/O extension board\n" +"options COM_MULTIPORT\n" +"device sio1 at isa? port \"IO_COM2\" flags 0x205\n" +"device sio2 at isa? port \"IO_COM3\" flags 0x205 irq 3\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1055 +msgid "" +"Note that the `flags` setting for [.filename]#sio1# and [.filename]#sio2# is " +"truly essential; refer to man:sio[4] for details. (Generally, the `2` in " +"the \"flags\" attribute refers to [.filename]#sio#`2` which holds the IRQ, " +"and you surely want a `5` low nibble.) With kernel verbose mode turned on " +"this should yield something similar to this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1067 +#, no-wrap +msgid "" +"sio0: irq maps: 0x1 0x11 0x1 0x1\n" +"sio0 at 0x3f8-0x3ff irq 4 flags 0x10 on isa\n" +"sio0: type 16550A\n" +"sio1: irq maps: 0x1 0x9 0x1 0x1\n" +"sio1 at 0x2f8-0x2ff flags 0x205 on isa\n" +"sio1: type 16550A (multiport)\n" +"sio2: irq maps: 0x1 0x9 0x1 0x1\n" +"sio2 at 0x3e8-0x3ef irq 3 flags 0x205 on isa\n" +"sio2: type 16550A (multiport master)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1072 +msgid "" +"Though [.filename]#/sys/i386/isa/sio.c# is somewhat cryptic with its use of " +"the \"irq maps\" array above, the basic idea is that you observe `0x1` in " +"the first, third, and fourth place. This means that the corresponding IRQ " +"was set upon output and cleared after, which is just what we would expect. " +"If your kernel does not display this behavior, most likely there is " +"something wrong with your wiring." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/serial-uart/_index.adoc:1074 +#, no-wrap +msgid "Configuring the [.filename]#cy# driver" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1077 +msgid "_Contributed by Alex Nash. 6 June 1996._" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1080 +msgid "" +"The Cyclades multiport cards are based on the [.filename]#cy# driver instead " +"of the usual [.filename]#sio# driver used by other multiport cards. " +"Configuration is a simple matter of:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1084 +msgid "" +"Add the [.filename]#cy# device to your kernel configuration (note that your " +"irq and iomem settings may differ)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1088 +#, no-wrap +msgid "device cy0 at isa? irq 10 iomem 0xd4000 iosiz 0x2000\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1090 +msgid "Rebuild and install the new kernel." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1091 +msgid "" +"Make the device nodes by typing (the following example assumes an 8-port " +"board):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1096 +#, no-wrap +msgid "" +"# cd /dev\n" +"# for i in 0 1 2 3 4 5 6 7;do ./MAKEDEV cuac$i ttyc$i;done\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1099 +msgid "" +"If appropriate, add dialup entries to [.filename]#/etc/ttys# by duplicating " +"serial device (`ttyd`) entries and using `ttyc` in place of `ttyd`. For " +"example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1107 +#, no-wrap +msgid "" +"ttyc0 \"/usr/libexec/getty std.38400\" unknown on insecure\n" +"ttyc1 \"/usr/libexec/getty std.38400\" unknown on insecure\n" +"ttyc2 \"/usr/libexec/getty std.38400\" unknown on insecure\n" +"...\n" +"ttyc7 \"/usr/libexec/getty std.38400\" unknown on insecure\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1109 +msgid "Reboot with the new kernel." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/serial-uart/_index.adoc:1111 +#, no-wrap +msgid "Configuring the [.filename]#si# driver" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1114 +msgid "_Contributed by `{nsayer}`. 25 March 1998._" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1118 +msgid "" +"The Specialix SI/XIO and SX multiport cards use the [.filename]#si# driver. " +"A single machine can have up to 4 host cards. The following host cards are " +"supported:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1120 +msgid "ISA SI/XIO host card (2 versions)" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1121 +msgid "EISA SI/XIO host card" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1122 +msgid "PCI SI/XIO host card" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1123 +msgid "ISA SX host card" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1124 +msgid "PCI SX host card" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1130 +msgid "" +"Although the SX and SI/XIO host cards look markedly different, their " +"functionality are basically the same. The host cards do not use I/O " +"locations, but instead require a 32K chunk of memory. The factory " +"configuration for ISA cards places this at `0xd0000-0xd7fff`. They also " +"require an IRQ. PCI cards will, of course, auto-configure themselves." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1134 +msgid "" +"You can attach up to 4 external modules to each host card. The external " +"modules contain either 4 or 8 serial ports. They come in the following " +"varieties:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1136 +msgid "SI 4 or 8 port modules. Up to 57600 bps on each port supported." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1137 +msgid "" +"XIO 8 port modules. Up to 115200 bps on each port supported. One type of XIO " +"module has 7 serial and 1 parallel port." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1138 +msgid "" +"SXDC 8 port modules. Up to 921600 bps on each port supported. Like XIO, a " +"module is available with one parallel port as well." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1140 +msgid "" +"To configure an ISA host card, add the following line to your kernel " +"configuration file, changing the numbers as appropriate:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1144 +#, no-wrap +msgid "device si0 at isa? iomem 0xd0000 irq 11\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1147 +msgid "" +"Valid IRQ numbers are 9, 10, 11, 12 and 15 for SX ISA host cards and 11, 12 " +"and 15 for SI/XIO ISA host cards." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1149 +msgid "To configure an EISA or PCI host card, use this line:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1153 +#, no-wrap +msgid "device si0\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1156 +msgid "" +"After adding the configuration entry, rebuild and install your new kernel." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1160 +msgid "" +"The following step, is not necessary if you are using man:devfs[5] in " +"FreeBSD 5._X_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1165 +msgid "" +"After rebooting with the new kernel, you need to make the device nodes in [." +"filename]#/dev#. The [.filename]#MAKEDEV# script will take care of this for " +"you. Count how many total ports you have and type:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1170 +#, no-wrap +msgid "" +"# cd /dev\n" +"# ./MAKEDEV ttyAnn cuaAnn\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1173 +msgid "(where _nn_ is the number of ports)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1175 +msgid "" +"If you want login prompts to appear on these ports, you will need to add " +"lines like this to [.filename]#/etc/ttys#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/serial-uart/_index.adoc:1179 +#, no-wrap +msgid "ttyA01 \"/usr/libexec/getty std.9600\" vt100 on insecure\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/serial-uart/_index.adoc:1182 +msgid "" +"Change the terminal type as appropriate. For modems, `dialup` or `unknown` " +"is fine." +msgstr "" diff --git a/documentation/content/en/articles/solid-state/_index.adoc b/documentation/content/en/articles/solid-state/_index.adoc index 2309a9193b..3ea3224636 100644 --- a/documentation/content/en/articles/solid-state/_index.adoc +++ b/documentation/content/en/articles/solid-state/_index.adoc @@ -88,9 +88,7 @@ You should make sure the following lines exist in your kernel configuration file [.programlisting] .... -options MFS # Memory Filesystem options MD_ROOT # md device usable as a potential root device -pseudo-device md # memory disk .... [[ro-fs]] @@ -110,7 +108,7 @@ varsize=8192 Remember that this value is in sectors by default. The fact that [.filename]#/var# is a read-write filesystem is an important distinction, as the [.filename]#/# partition (and any other partitions you may have on your flash media) should be mounted read-only. -Remember that in <<intro>> we detailed the limitations of flash memory - specifically the limited write capability. +Remember that in crossref:solid-state[intro, Solid State Disk Devices] we detailed the limitations of flash memory - specifically the limited write capability. The importance of not mounting filesystems on flash media read-write, and the importance of not using a swap file, cannot be overstated. A swap file on a busy system can burn through a piece of flash media in less than one year. Heavy logging or temporary file creation and destruction can do the same. @@ -124,7 +122,9 @@ Therefore, in addition to removing the `swap` entry from your [.filename]#/etc/f A few applications in the average system will immediately begin to fail as a result of this change. For instance, cron will not run properly as a result of missing cron tabs in the [.filename]#/var# created by [.filename]#/etc/rc.d/var#, and syslog and dhcp will encounter problems as well as a result of the read-only filesystem and missing items in the [.filename]#/var# that [.filename]#/etc/rc.d/var# has created. -These are only temporary problems though, and are addressed, along with solutions to the execution of other common software packages in <<strategies>>. +These are only temporary problems though, and are addressed, along with +solutions to the execution of other common software packages in +crossref:solid-state[strategies, System Strategies for Small and Read Only Environments]. An important thing to remember is that a filesystem that was mounted read-only with [.filename]#/etc/fstab# can be made read-write at any time by issuing the command: @@ -244,7 +244,7 @@ Assuming that you configured your filesystem correctly when it was built on the [[strategies]] == System Strategies for Small and Read Only Environments -In <<ro-fs>>, it was pointed out that the [.filename]#/var# filesystem constructed by [.filename]#/etc/rc.d/var# and the presence of a read-only root filesystem causes problems with many common software packages used with FreeBSD. +In crossref:solid-state[ro-fs, The `rc` Subsystem and Read-Only Filesystems], it was pointed out that the [.filename]#/var# filesystem constructed by [.filename]#/etc/rc.d/var# and the presence of a read-only root filesystem causes problems with many common software packages used with FreeBSD. In this article, suggestions for successfully running cron, syslog, ports installations, and the Apache web server will be provided. === Cron @@ -271,7 +271,8 @@ Therefore, somewhere in [.filename]#/etc/rc.d/var#, after the section that creat === Ports Installation Before discussing the changes necessary to successfully use the ports tree, a reminder is necessary regarding the read-only nature of your filesystems on the flash media. -Since they are read-only, you will need to temporarily mount them read-write using the mount syntax shown in <<ro-fs>>. +Since they are read-only, you will need to temporarily mount them read-write +using the mount syntax shown in crossref:solid-state[ro-fs, The `rc` Subsystem and Read-Only Filesystems]. You should always remount those filesystems read-only when you are done with any maintenance - unnecessary writes to the flash media could considerably shorten its lifespan. To make it possible to enter a ports directory and successfully run `make install`, we must create a packages directory on a non-memory filesystem that will keep track of our packages across reboots. diff --git a/documentation/content/en/articles/solid-state/_index.po b/documentation/content/en/articles/solid-state/_index.po new file mode 100644 index 0000000000..046d1be91e --- /dev/null +++ b/documentation/content/en/articles/solid-state/_index.po @@ -0,0 +1,655 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-12-29 08:30-0500\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/solid-state/_index.adoc:1 +#, no-wrap +msgid "The use of solid state disk devices in FreeBSD" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/solid-state/_index.adoc:1 +#: documentation/content/en/articles/solid-state/_index.adoc:12 +#, no-wrap +msgid "FreeBSD and Solid State Devices" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:45 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:47 +msgid "" +"This article covers the use of solid state disk devices in FreeBSD to create " +"embedded systems." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:50 +msgid "" +"Embedded systems have the advantage of increased stability due to the lack " +"of integral moving parts (hard drives). Account must be taken, however, for " +"the generally low disk space available in the system and the durability of " +"the storage medium." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:53 +msgid "" +"Specific topics to be covered include the types and attributes of solid " +"state media suitable for disk use in FreeBSD, kernel options that are of " +"interest in such an environment, the [.filename]#rc.initdiskless# mechanisms " +"that automate the initialization of such systems and the need for read-only " +"filesystems, and building filesystems from scratch. The article will " +"conclude with some general strategies for small and read-only FreeBSD " +"environments." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:55 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/solid-state/_index.adoc:59 +#, no-wrap +msgid "Solid State Disk Devices" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:69 +msgid "" +"The scope of this article will be limited to solid state disk devices made " +"from flash memory. Flash memory is a solid state memory (no moving parts) " +"that is non-volatile (the memory maintains data even after all power sources " +"have been disconnected). Flash memory can withstand tremendous physical " +"shock and is reasonably fast (the flash memory solutions covered in this " +"article are slightly slower than a EIDE hard disk for write operations, and " +"much faster for read operations). One very important aspect of flash " +"memory, the ramifications of which will be discussed later in this article, " +"is that each sector has a limited rewrite capacity. You can only write, " +"erase, and write again to a sector of flash memory a certain number of times " +"before the sector becomes permanently unusable. Although many flash memory " +"products automatically map bad blocks, and although some even distribute " +"write operations evenly throughout the unit, the fact remains that there " +"exists a limit to the amount of writing that can be done to the device. " +"Competitive units have between 1,000,000 and 10,000,000 writes per sector in " +"their specification. This figure varies due to the temperature of the " +"environment." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:74 +msgid "" +"Specifically, we will be discussing ATA compatible compact-flash units, " +"which are quite popular as storage media for digital cameras. Of particular " +"interest is the fact that they pin out directly to the IDE bus and are " +"compatible with the ATA command set. Therefore, with a very simple and low-" +"cost adaptor, these devices can be attached directly to an IDE bus in a " +"computer. Once implemented in this manner, operating systems such as " +"FreeBSD see the device as a normal hard disk (albeit small)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:76 +msgid "" +"Other solid state disk solutions do exist, but their expense, obscurity, and " +"relative unease of use places them beyond the scope of this article." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/solid-state/_index.adoc:78 +#, no-wrap +msgid "Kernel Options" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:81 +msgid "" +"A few kernel options are of specific interest to those creating an embedded " +"FreeBSD system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:86 +msgid "" +"All embedded FreeBSD systems that use flash memory as system disk will be " +"interested in memory disks and memory filesystems. As a result of the " +"limited number of writes that can be done to flash memory, the disk and the " +"filesystems on the disk will most likely be mounted read-only. In this " +"environment, filesystems such as [.filename]#/tmp# and [.filename]#/var# are " +"mounted as memory filesystems to allow the system to create logs and update " +"counters and temporary files. Memory filesystems are a critical component " +"to a successful solid state FreeBSD implementation." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:88 +msgid "" +"You should make sure the following lines exist in your kernel configuration " +"file:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:92 +#, no-wrap +msgid "options MD_ROOT # md device usable as a potential root device\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/solid-state/_index.adoc:95 +#, no-wrap +msgid "The `rc` Subsystem and Read-Only Filesystems" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:98 +msgid "" +"The post-boot initialization of an embedded FreeBSD system is controlled by " +"[.filename]#/etc/rc.initdiskless#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:102 +msgid "" +"[.filename]#/etc/rc.d/var# mounts [.filename]#/var# as a memory filesystem, " +"makes a configurable list of directories in [.filename]#/var# with the man:" +"mkdir[1] command, and changes modes on some of those directories. In the " +"execution of [.filename]#/etc/rc.d/var#, one other [.filename]#rc.conf# " +"variable comes into play - `varsize`. A [.filename]#/var# partition is " +"created by [.filename]#/etc/rc.d/var# based on the value of this variable in " +"[.filename]#rc.conf#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:106 +#, no-wrap +msgid "varsize=8192\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:109 +msgid "Remember that this value is in sectors by default." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:116 +msgid "" +"The fact that [.filename]#/var# is a read-write filesystem is an important " +"distinction, as the [.filename]#/# partition (and any other partitions you " +"may have on your flash media) should be mounted read-only. Remember that in " +"crossref:solid-state[intro, Solid State Disk Devices] we detailed the " +"limitations of flash memory - specifically the limited write capability. " +"The importance of not mounting filesystems on flash media read-write, and " +"the importance of not using a swap file, cannot be overstated. A swap file " +"on a busy system can burn through a piece of flash media in less than one " +"year. Heavy logging or temporary file creation and destruction can do the " +"same. Therefore, in addition to removing the `swap` entry from your [." +"filename]#/etc/fstab#, you should also change the Options field for each " +"filesystem to `ro` as follows:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:121 +#, no-wrap +msgid "" +"# Device Mountpoint FStype Options Dump Pass#\n" +"/dev/ad0s1a / ufs ro 1 1\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:128 +msgid "" +"A few applications in the average system will immediately begin to fail as a " +"result of this change. For instance, cron will not run properly as a result " +"of missing cron tabs in the [.filename]#/var# created by [.filename]#/etc/rc." +"d/var#, and syslog and dhcp will encounter problems as well as a result of " +"the read-only filesystem and missing items in the [.filename]#/var# that [." +"filename]#/etc/rc.d/var# has created. These are only temporary problems " +"though, and are addressed, along with solutions to the execution of other " +"common software packages in crossref:solid-state[strategies, System " +"Strategies for Small and Read Only Environments]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:130 +msgid "" +"An important thing to remember is that a filesystem that was mounted read-" +"only with [.filename]#/etc/fstab# can be made read-write at any time by " +"issuing the command:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:134 +#, no-wrap +msgid "# /sbin/mount -uw partition\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:137 +msgid "and can be toggled back to read-only with the command:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:141 +#, no-wrap +msgid "# /sbin/mount -ur partition\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/solid-state/_index.adoc:143 +#, no-wrap +msgid "Building a File System from Scratch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:146 +msgid "" +"Since ATA compatible compact-flash cards are seen by FreeBSD as normal IDE " +"hard drives, you could theoretically install FreeBSD from the network using " +"the kern and mfsroot floppies or from a CD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:149 +msgid "" +"However, even a small installation of FreeBSD using normal installation " +"procedures can produce a system in size of greater than 200 megabytes. Most " +"people will be using smaller flash memory devices (128 megabytes is " +"considered fairly large - 32 or even 16 megabytes is common), so an " +"installation using normal mechanisms is not possible-there is simply not " +"enough disk space for even the smallest of conventional installations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:155 +msgid "" +"The easiest way to overcome this space limitation is to install FreeBSD " +"using conventional means to a normal hard disk. After the installation is " +"complete, pare down the operating system to a size that will fit onto your " +"flash media, then tar the entire filesystem. The following steps will guide " +"you through the process of preparing a piece of flash memory for your tarred " +"filesystem. Remember, because a normal installation is not being performed, " +"operations such as partitioning, labeling, file-system creation, etc. need " +"to be performed by hand. In addition to the kern and mfsroot floppy disks, " +"you will also need to use the fixit floppy." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/solid-state/_index.adoc:159 +msgid "Partitioning Your Flash Media Device" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/solid-state/_index.adoc:169 +msgid "" +"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]. After deleting all existing partitions, create a partition using kbd:" +"[c] and accept the default value for the size of the partition. When asked " +"for the type of the partition, make sure the value is set to `165`. Now " +"write this partition table to the disk by pressing kbd:[w] (this is a hidden " +"option on this screen). If you are using an ATA compatible compact flash " +"card, you should choose the FreeBSD Boot Manager. 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." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/solid-state/_index.adoc:170 +msgid "Creating Filesystems on Your Flash Memory Device" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/solid-state/_index.adoc:173 +msgid "" +"Exit the custom installation menu, and from the main installation menu " +"choose the `fixit` option. After entering the fixit environment, enter the " +"following command:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:177 +#, no-wrap +msgid "# disklabel -e /dev/ad0c\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:181 +msgid "" +"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:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:185 +#, no-wrap +msgid "a: 123456 0 4.2BSD 0 0\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:190 +msgid "" +"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." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:195 +#, no-wrap +msgid "" +"# disklabel -B -r /dev/ad0c\n" +"# newfs /dev/ad0a\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:198 +msgid "Placing Your Filesystem on the Flash Media" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:200 +msgid "Mount the newly prepared flash media:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:204 +#, no-wrap +msgid "# mount /dev/ad0a /flash\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:208 +msgid "" +"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:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:213 +#, no-wrap +msgid "" +"# ifconfig xl0 192.168.0.10 netmask 255.255.255.0\n" +"# route add default 192.168.0.1\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:219 +msgid "" +"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. " +"If you perform your transfer in this manner, you will never have the tar " +"file and the tar contents on your disk at the same time:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:223 +#, no-wrap +msgid "ftp> get tarfile.tar \"| tar xvf -\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:226 +msgid "If your tarfile is gzipped, you can accomplish this as well:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:230 +#, no-wrap +msgid "ftp> get tarfile.tar \"| zcat | tar xvf -\"\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:233 +msgid "" +"After the contents of your tarred filesystem are on your flash memory " +"filesystem, you can unmount the flash memory and reboot:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:239 +#, no-wrap +msgid "" +"# cd /\n" +"# umount /flash\n" +"# exit\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:242 +msgid "" +"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." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/solid-state/_index.adoc:245 +#, no-wrap +msgid "System Strategies for Small and Read Only Environments" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/solid-state/_index.adoc:249 +msgid "" +"In crossref:solid-state[ro-fs, The `rc` Subsystem and Read-Only " +"Filesystems], it was pointed out that the [.filename]#/var# filesystem " +"constructed by [.filename]#/etc/rc.d/var# and the presence of a read-only " +"root filesystem causes problems with many common software packages used with " +"FreeBSD. In this article, suggestions for successfully running cron, " +"syslog, ports installations, and the Apache web server will be provided." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/solid-state/_index.adoc:250 +#, no-wrap +msgid "Cron" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/solid-state/_index.adoc:253 +msgid "" +"Upon boot, [.filename]#/var# gets populated by [.filename]#/etc/rc.d/var# " +"using the list from [.filename]#/etc/mtree/BSD.var.dist#, so the [." +"filename]#cron#, [.filename]#cron/tabs#, [.filename]#at#, and a few other " +"standard directories get created." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/solid-state/_index.adoc:258 +msgid "" +"However, this does not solve the problem of maintaining cron tabs across " +"reboots. When the system reboots, the [.filename]#/var# filesystem that is " +"in memory will disappear and any cron tabs you may have had in it will also " +"disappear. Therefore, one solution would be to create cron tabs for the " +"users that need them, mount your [.filename]#/# filesystem as read-write and " +"copy those cron tabs to somewhere safe, like [.filename]#/etc/tabs#, then " +"add a line to the end of [.filename]#/etc/rc.initdiskless# that copies those " +"crontabs into [.filename]#/var/cron/tabs# after that directory has been " +"created during system initialization. You may also need to add a line that " +"changes modes and permissions on the directories you create and the files " +"you copy with [.filename]#/etc/rc.initdiskless#." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/solid-state/_index.adoc:259 +#, no-wrap +msgid "Syslog" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/solid-state/_index.adoc:264 +msgid "" +"[.filename]#syslog.conf# specifies the locations of certain log files that " +"exist in [.filename]#/var/log#. These files are not created by [.filename]#/" +"etc/rc.d/var# upon system initialization. Therefore, somewhere in [." +"filename]#/etc/rc.d/var#, after the section that creates the directories in " +"[.filename]#/var#, you will need to add something like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:269 +#, no-wrap +msgid "" +"# touch /var/log/security /var/log/maillog /var/log/cron /var/log/messages\n" +"# chmod 0644 /var/log/*\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/solid-state/_index.adoc:271 +#, no-wrap +msgid "Ports Installation" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:277 +msgid "" +"Before discussing the changes necessary to successfully use the ports tree, " +"a reminder is necessary regarding the read-only nature of your filesystems " +"on the flash media. Since they are read-only, you will need to temporarily " +"mount them read-write using the mount syntax shown in crossref:solid-" +"state[ro-fs, The `rc` Subsystem and Read-Only Filesystems]. You should " +"always remount those filesystems read-only when you are done with any " +"maintenance - unnecessary writes to the flash media could considerably " +"shorten its lifespan." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:280 +msgid "" +"To make it possible to enter a ports directory and successfully run `make " +"install`, we must create a packages directory on a non-memory filesystem " +"that will keep track of our packages across reboots. As it is necessary to " +"mount your filesystems as read-write for the installation of a package " +"anyway, it is sensible to assume that an area on the flash media can also be " +"used for package information to be written to." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:283 +msgid "" +"First, create a package database directory. This is normally in [." +"filename]#/var/db/pkg#, but we cannot place it there as it will disappear " +"every time the system is booted." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:287 +#, no-wrap +msgid "# mkdir /etc/pkg\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:290 +msgid "" +"Now, add a line to [.filename]#/etc/rc.d/var# that links the [.filename]#/" +"etc/pkg# directory to [.filename]#/var/db/pkg#. An example:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:294 +#, no-wrap +msgid "# ln -s /etc/pkg /var/db/pkg\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:297 +msgid "" +"Now, any time that you mount your filesystems as read-write and install a " +"package, the `make install` will work, and package information will be " +"written successfully to [.filename]#/etc/pkg# (because the filesystem will, " +"at that time, be mounted read-write) which will always be available to the " +"operating system as [.filename]#/var/db/pkg#." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/solid-state/_index.adoc:298 +#, no-wrap +msgid "Apache Web Server" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/solid-state/_index.adoc:304 +msgid "" +"The steps in this section are only necessary if Apache is set up to write " +"its pid or log information outside of [.filename]#/var#. By default, Apache " +"keeps its pid file in [.filename]#/var/run/httpd.pid# and its log files in [." +"filename]#/var/log#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:310 +msgid "" +"It is now assumed that Apache keeps its log files in a directory [." +"filename]#apache_log_dir# outside of [.filename]#/var#. When this directory " +"lives on a read-only filesystem, Apache will not be able to save any log " +"files, and may have problems working. If so, it is necessary to add a new " +"directory to the list of directories in [.filename]#/etc/rc.d/var# to create " +"in [.filename]#/var#, and to link [.filename]#apache_log_dir# to [." +"filename]#/var/log/apache#. It is also necessary to set permissions and " +"ownership on this new directory." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:312 +msgid "" +"First, add the directory `log/apache` to the list of directories to be " +"created in [.filename]#/etc/rc.d/var#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:314 +msgid "" +"Second, add these commands to [.filename]#/etc/rc.d/var# after the directory " +"creation section:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:319 +#, no-wrap +msgid "" +"# chmod 0774 /var/log/apache\n" +"# chown nobody:nobody /var/log/apache\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/solid-state/_index.adoc:322 +msgid "" +"Finally, remove the existing [.filename]#apache_log_dir# directory, and " +"replace it with a link:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/solid-state/_index.adoc:327 +#, no-wrap +msgid "" +"# rm -rf apache_log_dir\n" +"# ln -s /var/log/apache apache_log_dir\n" +msgstr "" diff --git a/documentation/content/en/articles/vinum/_index.adoc b/documentation/content/en/articles/vinum/_index.adoc index f6b0baea11..6c078fa1c6 100644 --- a/documentation/content/en/articles/vinum/_index.adoc +++ b/documentation/content/en/articles/vinum/_index.adoc @@ -66,9 +66,15 @@ In addition to supporting various cards and controllers for hardware Redundant A This chapter provides an overview of potential problems with traditional disk storage, and an introduction to the [.filename]#vinum# volume manager. +[WARNING] +==== +vinum is deprecated and is not present in FreeBSD 15.0 and later. +Users are advised to migrate to man:gconcat[8], man:gmirror[8], man:gstripe[8], man:graid[8], or man:zfs[8]. +==== + [NOTE] ==== -Starting with FreeBSD 5, [.filename]#vinum# has been rewritten in order to fit into the extref:{handbook}[GEOM architecture, geom], while retaining the original ideas, terminology, and on-disk metadata. +Starting with FreeBSD 5, [.filename]#vinum# has been rewritten to fit into the extref:{handbook}geom[GEOM architecture, geom], while retaining the original ideas, terminology, and on-disk metadata. This rewrite is called _gvinum_ (for _GEOM vinum_). While this chapter uses the term [.filename]#vinum#, any command invocations should be performed with `gvinum`. The name of the kernel module has changed from the original [.filename]#vinum.ko# to [.filename]#geom_vinum.ko#, and all device nodes reside under [.filename]#/dev/gvinum# instead of [.filename]#/dev/vinum#. @@ -106,7 +112,7 @@ The most obvious method is to divide the virtual disk into groups of consecutive This method is called _concatenation_ and has the advantage that the disks are not required to have any specific size relationships. It works well when the access to the virtual disk is spread evenly about its address space. When access is concentrated on a smaller area, the improvement is less marked. -<<vinum-concat, Concatenated Organization>> illustrates the sequence in which storage units are allocated in a concatenated organization. +crossref:vinum[vinum-concat, Concatenated Organization] illustrates the sequence in which storage units are allocated in a concatenated organization. [[vinum-concat]] .Concatenated Organization @@ -119,7 +125,7 @@ This mapping is called _striping_ or RAID-0. `RAID` offers various forms of fault tolerance, though RAID-0 is somewhat misleading as it provides no redundancy. Striping requires somewhat more effort to locate the data, and it can cause additional I/O load where a transfer is spread over multiple disks, but it can also provide a more constant load across the disks. -<<vinum-striped, Striped Organization>> illustrates the sequence in which storage units are allocated in a striped organization. +crossref:vinum[vinum-striped, Striped Organization] illustrates the sequence in which storage units are allocated in a striped organization. [[vinum-striped]] .Striped Organization @@ -158,7 +164,7 @@ If one drive fails, the array can continue to operate in degraded mode where a r [[vinum-objects]] == [.filename]#vinum# Objects -In order to address these problems, [.filename]#vinum# implements a four-level hierarchy of objects: +To address these problems, [.filename]#vinum# implements a four-level hierarchy of objects: * The most visible object is the virtual disk, called a _volume_. Volumes have essentially the same properties as a UNIX(R) disk drive, though there are some minor differences. For one, they have no size limitations. * Volumes are composed of _plexes_, each of which represent the total address space of a volume. This level in the hierarchy provides redundancy. Think of plexes as individual disks in a mirrored array, each containing the same data. @@ -186,9 +192,9 @@ As long as at least one plex can provide the data for the complete address range [.filename]#vinum# implements both concatenation and striping at the plex level: * A _concatenated plex_ uses the address space of each subdisk in turn. Concatenated plexes are the most flexible as they can contain any number of subdisks, and the subdisks may be of different length. The plex may be extended by adding additional subdisks. They require less CPU time than striped plexes, though the difference in CPU overhead is not measurable. On the other hand, they are most susceptible to hot spots, where one disk is very active and others are idle. -* A _striped plex_ stripes the data across each subdisk. The subdisks must all be the same size and there must be at least two subdisks in order to distinguish it from a concatenated plex. The greatest advantage of striped plexes is that they reduce hot spots. By choosing an optimum sized stripe, about 256 kB, the load can be evened out on the component drives. Extending a plex by adding new subdisks is so complicated that [.filename]#vinum# does not implement it. +* A _striped plex_ stripes the data across each subdisk. The subdisks must all be the same size and there must be at least two subdisks to distinguish it from a concatenated plex. The greatest advantage of striped plexes is that they reduce hot spots. By choosing an optimum sized stripe, about 256 kB, the load can be evened out on the component drives. Extending a plex by adding new subdisks is so complicated that [.filename]#vinum# does not implement it. -<<vinum-comparison, [.filename]#vinum# Plex Organizations>> summarizes the advantages and disadvantages of each plex organization. +crossref:vinum[vinum-comparison, [.filename]#vinum# Plex Organizations] summarizes the advantages and disadvantages of each plex organization. [[vinum-comparison]] .[.filename]#vinum# Plex Organizations @@ -263,7 +269,7 @@ Subdisks: 1 (16 configured) .... This output shows the brief listing format of man:gvinum[8]. -It is represented graphically in <<vinum-simple-vol, A Simple [.filename]#vinum# Volume>>. +It is represented graphically in crossref:vinum[vinum-simple-vol, A Simple [.filename]#vinum# Volume]. [[vinum-simple-vol]] .A Simple [.filename]#vinum# Volume @@ -319,7 +325,7 @@ After processing this definition, the configuration looks like: S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB .... -<<vinum-mirrored-vol, A Mirrored [.filename]#vinum# Volume>> shows the structure graphically. +crossref:vinum[vinum-mirrored-vol, A Mirrored [.filename]#vinum# Volume] shows the structure graphically. [[vinum-mirrored-vol]] .A Mirrored [.filename]#vinum# Volume @@ -384,7 +390,7 @@ After processing this definition, the configuration looks like: .A Striped [.filename]#vinum# Volume image::vinum-striped-vol.png[] -This volume is represented in <<vinum-striped-vol, A Striped [.filename]#vinum# Volume>>. +This volume is represented in crossref:vinum[vinum-striped-vol, A Striped [.filename]#vinum# Volume]. The darkness of the stripes indicates the position within the plex address space, where the lightest stripes come first and the darkest last. === Resilience and Performance @@ -412,7 +418,7 @@ A typical configuration file might be: The subdisks of the second plex are offset by two drives from those of the first plex. This helps to ensure that writes do not go to the same subdisks even if a transfer goes over two drives. -<<vinum-raid10-vol, A Mirrored, Striped [.filename]#vinum# Volume>> represents the structure of this volume. +crossref:vinum[vinum-raid10-vol, A Mirrored, Striped [.filename]#vinum# Volume] represents the structure of this volume. [[vinum-raid10-vol]] .A Mirrored, Striped [.filename]#vinum# Volume @@ -484,7 +490,7 @@ For example, a disk drive may have a name like [.filename]#/dev/ad0a# or [.filen These names represent the first partition ([.filename]#a#) on the first (0) IDE disk ([.filename]#ad#) and the eighth partition ([.filename]#h#) on the third (2) SCSI disk ([.filename]#da#) respectively. By contrast, a [.filename]#vinum# volume might be called [.filename]#/dev/gvinum/concat#, which has no relationship with a partition name. -In order to create a file system on this volume, use man:newfs[8]: +To create a file system on this volume, use man:newfs[8]: [source,shell] .... @@ -539,7 +545,7 @@ This enables [.filename]#vinum# to identify drives correctly even if they have b _Gvinum_ always features an automatic startup once the kernel module is loaded, via man:loader.conf[5]. To load the _Gvinum_ module at boot time, add `geom_vinum_load="YES"` to [.filename]#/boot/loader.conf#. -When [.filename]#vinum# is started with `gvinum start`, [.filename]#vinum# reads the configuration database from one of the [.filename]#vinum# drives. +When [.filename]#vinum# is started with `gvinum start`, [.filename]#vinum# reads the configuration database from one of the [.filename]#vinum# drives. Under normal circumstances, each drive contains an identical copy of the configuration database, so it does not matter which drive is read. After a crash, however, [.filename]#vinum# must determine which drive was updated most recently and read the configuration from this drive. It then updates the configuration, if necessary, from progressively older drives. @@ -557,7 +563,7 @@ In the following sections, the term "root volume" is generally used to describe === Starting up [.filename]#vinum# Early Enough for the Root File System -[.filename]#vinum# must be available early in the system boot as man:loader[8] must be able to load the vinum kernel module before starting the kernel. +[.filename]#vinum# must be available early in the system boot as man:loader[8] must be able to load the vinum kernel module before starting the kernel. This can be accomplished by putting this line in [.filename]#/boot/loader.conf#: [.programlisting] @@ -582,7 +588,7 @@ Each single subdisk within these plexes needs its own `a` partition illusion, fo It is not strictly needed that each of these faked `a` partitions is located at the same offset within its device, compared with other devices containing plexes of the root volume. However, it is probably a good idea to create the [.filename]#vinum# volumes that way so the resulting mirrored devices are symmetric, to avoid confusion. -In order to set up these `a` partitions for each device containing part of the root volume, the following is required: +To set up these `a` partitions for each device containing part of the root volume, the following is required: [.procedure] ==== @@ -594,7 +600,7 @@ In order to set up these `a` partitions for each device containing part of the r .... + [.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`. +They must be divided by 512 to obtain the block numbers that are to be used by `bsdlabel`. . Run this command for each device that participates in the root volume: + [source,shell] @@ -672,7 +678,8 @@ The bsdlabel for these devices might look like: .... It can be observed that the `size` parameter for the faked `a` partition matches the value outlined above, while the `offset` parameter is the sum of the offset within the [.filename]#vinum# partition `h`, and the offset of this partition within the device or slice. -This is a typical setup that is necessary to avoid the problem described in <<vinum-root-panic, Nothing Boots, the Bootstrap Panics>>. +This is a typical setup that is necessary to avoid the problem described in +crossref:vinum[vinum-root-panic, Nothing Boots, the Bootstrap Panics]. The entire `a` partition is completely within the `h` partition containing all the [.filename]#vinum# data for this device. In the above example, the entire device is dedicated to [.filename]#vinum# and there is no leftover pre-[.filename]#vinum# root partition. @@ -700,7 +707,7 @@ If this file system is to be mounted read-write later on, it is necessary to rem ==== Only Primary Bootstrap Loads If [.filename]#/boot/loader# fails to load, but the primary bootstrap still loads (visible by a single dash in the left column of the screen right after the boot process starts), an attempt can be made to interrupt the primary bootstrap by pressing kbd:[space]. -This will make the bootstrap stop in extref:{handbook}[stage two, boot-boot1]. +This will make the bootstrap stop in extref:{handbook}boot[stage two, boot-boot1]. An attempt can be made here to boot off an alternate partition, like the partition containing the previous root file system that has been moved away from `a`. [[vinum-root-panic]] @@ -711,6 +718,6 @@ Unfortunately, [.filename]#vinum# accidentally leaves only 4 KB at the beginning However, the stage one and two bootstraps plus the bsdlabel require 8 KB. So if a [.filename]#vinum# partition was started at offset 0 within a slice or disk that was meant to be bootable, the [.filename]#vinum# setup will trash the bootstrap. -Similarly, if the above situation has been recovered, by booting from a "Fixit" media, and the bootstrap has been re-installed using `bsdlabel -B` as described in extref:{handbook}[stage two, boot-boot1], the bootstrap will trash the [.filename]#vinum# header, and [.filename]#vinum# will no longer find its disk(s). +Similarly, if the above situation has been recovered, by booting from a "Fixit" media, and the bootstrap has been re-installed using `bsdlabel -B` as described in extref:{handbook}boot[stage two, boot-boot1], the bootstrap will trash the [.filename]#vinum# header, and [.filename]#vinum# will no longer find its disk(s). Though no actual [.filename]#vinum# configuration data or data in [.filename]#vinum# volumes will be trashed, and it would be possible to recover all the data by entering exactly the same [.filename]#vinum# configuration data again, the situation is hard to fix. -It is necessary to move the entire [.filename]#vinum# partition by at least 4 KB, in order to have the [.filename]#vinum# header and the system bootstrap no longer collide. +It is necessary to move the entire [.filename]#vinum# partition by at least 4 KB, to have the [.filename]#vinum# header and the system bootstrap no longer collide. diff --git a/documentation/content/en/articles/vinum/_index.po b/documentation/content/en/articles/vinum/_index.po new file mode 100644 index 0000000000..fa6bf155d1 --- /dev/null +++ b/documentation/content/en/articles/vinum/_index.po @@ -0,0 +1,1661 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-01-24 10:22-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/vinum/_index.adoc:1 +#, no-wrap +msgid "The vinum Volume Manager in FreeBSD" +msgstr "" + +#. The Vinum Volume Manager +#. By Greg Lehey (grog at lemis dot com) +#. Added to the Handbook by Hiten Pandya <hmp@FreeBSD.org> +#. and Tom Rhodes <trhodes@FreeBSD.org> +#. For the FreeBSD Documentation Project +#. type: Title = +#: documentation/content/en/articles/vinum/_index.adoc:1 +#: documentation/content/en/articles/vinum/_index.adoc:19 +#, no-wrap +msgid "The vinum Volume Manager" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:51 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vinum/_index.adoc:55 +#, no-wrap +msgid "Synopsis" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:62 +msgid "" +"No matter the type of disks, there are always potential problems. The disks " +"can be too small, too slow, or too unreliable to meet the system's " +"requirements. While disks are getting bigger, so are data storage " +"requirements. Often a file system is needed that is bigger than a disk's " +"capacity. Various solutions to these problems have been proposed and " +"implemented." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:66 +msgid "" +"One method is through the use of multiple, and sometimes redundant, disks. " +"In addition to supporting various cards and controllers for hardware " +"Redundant Array of Independent Disks RAID systems, the base FreeBSD system " +"includes the [.filename]#vinum# volume manager, a block device driver that " +"implements virtual disk drives and addresses these three problems. " +"[.filename]#vinum# provides more flexibility, performance, and reliability " +"than traditional disk storage and implements `RAID`-0, `RAID`-1, and " +"`RAID`-5 models, both individually and in combination." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:68 +msgid "" +"This chapter provides an overview of potential problems with traditional " +"disk storage, and an introduction to the [.filename]#vinum# volume manager." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/vinum/_index.adoc:73 +msgid "" +"vinum is deprecated and is not present in FreeBSD 15.0 and later. Users are " +"advised to migrate to man:gconcat[8], man:gmirror[8], man:gstripe[8], " +"man:graid[8], or man:zfs[8]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/vinum/_index.adoc:82 +msgid "" +"Starting with FreeBSD 5, [.filename]#vinum# has been rewritten to fit into " +"the extref:{handbook}[GEOM architecture, geom], while retaining the original " +"ideas, terminology, and on-disk metadata. This rewrite is called _gvinum_ " +"(for _GEOM vinum_). While this chapter uses the term [.filename]#vinum#, " +"any command invocations should be performed with `gvinum`. The name of the " +"kernel module has changed from the original [.filename]#vinum.ko# to " +"[.filename]#geom_vinum.ko#, and all device nodes reside under [.filename]#/" +"dev/gvinum# instead of [.filename]#/dev/vinum#. As of FreeBSD 6, the " +"original [.filename]#vinum# implementation is no longer available in the " +"code base." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vinum/_index.adoc:85 +#, no-wrap +msgid "Access Bottlenecks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:89 +msgid "" +"Modern systems frequently need to access data in a highly concurrent " +"manner. For example, large FTP or HTTP servers can maintain thousands of " +"concurrent sessions and have multiple 100 Mbit/s connections to the outside " +"world, well beyond the sustained transfer rate of most disks." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:93 +msgid "" +"Current disk drives can transfer data sequentially at up to 70 MB/s, but " +"this value is of little importance in an environment where many independent " +"processes access a drive, and where they may achieve only a fraction of " +"these values. In such cases, it is more interesting to view the problem " +"from the viewpoint of the disk subsystem. The important parameter is the " +"load that a transfer places on the subsystem, or the time for which a " +"transfer occupies the drives involved in the transfer." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:96 +msgid "" +"In any disk transfer, the drive must first position the heads, wait for the " +"first sector to pass under the read head, and then perform the transfer. " +"These actions can be considered to be atomic as it does not make any sense " +"to interrupt them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:101 +msgid "" +"[[vinum-latency]] Consider a typical transfer of about 10 kB: the current " +"generation of high-performance disks can position the heads in an average of " +"3.5 ms. The fastest drives spin at 15,000 rpm, so the average rotational " +"latency (half a revolution) is 2 ms. At 70 MB/s, the transfer itself takes " +"about 150 μs, almost nothing compared to the positioning time. In such a " +"case, the effective transfer rate drops to a little over 1 MB/s and is " +"clearly highly dependent on the transfer size." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:104 +msgid "" +"The traditional and obvious solution to this bottleneck is \"more " +"spindles\": rather than using one large disk, use several smaller disks with " +"the same aggregate storage space. Each disk is capable of positioning and " +"transferring independently, so the effective throughput increases by a " +"factor close to the number of disks used." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:108 +msgid "" +"The actual throughput improvement is smaller than the number of disks " +"involved. Although each drive is capable of transferring in parallel, there " +"is no way to ensure that the requests are evenly distributed across the " +"drives. Inevitably the load on one drive will be higher than on another." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:116 +msgid "" +"The evenness of the load on the disks is strongly dependent on the way the " +"data is shared across the drives. In the following discussion, it is " +"convenient to think of the disk storage as a large number of data sectors " +"which are addressable by number, rather like the pages in a book. The most " +"obvious method is to divide the virtual disk into groups of consecutive " +"sectors the size of the individual physical disks and store them in this " +"manner, rather like taking a large book and tearing it into smaller " +"sections. This method is called _concatenation_ and has the advantage that " +"the disks are not required to have any specific size relationships. It " +"works well when the access to the virtual disk is spread evenly about its " +"address space. When access is concentrated on a smaller area, the " +"improvement is less marked. crossref:vinum[vinum-concat, Concatenated " +"Organization] illustrates the sequence in which storage units are allocated " +"in a concatenated organization." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/vinum/_index.adoc:118 +#, no-wrap +msgid "Concatenated Organization" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/vinum/_index.adoc:119 +#, no-wrap +msgid "vinum-concat.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:125 +msgid "" +"An alternative mapping is to divide the address space into smaller, equal-" +"sized components and store them sequentially on different devices. For " +"example, the first 256 sectors may be stored on the first disk, the next 256 " +"sectors on the next disk and so on. After filling the last disk, the " +"process repeats until the disks are full. This mapping is called _striping_ " +"or RAID-0." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:129 +msgid "" +"`RAID` offers various forms of fault tolerance, though RAID-0 is somewhat " +"misleading as it provides no redundancy. Striping requires somewhat more " +"effort to locate the data, and it can cause additional I/O load where a " +"transfer is spread over multiple disks, but it can also provide a more " +"constant load across the disks. crossref:vinum[vinum-striped, Striped " +"Organization] illustrates the sequence in which storage units are allocated " +"in a striped organization." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/vinum/_index.adoc:131 +#, no-wrap +msgid "Striped Organization" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/vinum/_index.adoc:132 +#, no-wrap +msgid "vinum-striped.png" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vinum/_index.adoc:135 +#, no-wrap +msgid "Data Integrity" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:140 +msgid "" +"The final problem with disks is that they are unreliable. Although " +"reliability has increased tremendously over the last few years, disk drives " +"are still the most likely core component of a server to fail. When they do, " +"the results can be catastrophic and replacing a failed disk drive and " +"restoring data can result in server downtime." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:143 +msgid "" +"One approach to this problem is _mirroring_, or `RAID-1`, which keeps two " +"copies of the data on different physical hardware. Any write to the volume " +"writes to both disks; a read can be satisfied from either, so if one drive " +"fails, the data is still available on the other drive." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:145 +msgid "Mirroring has two problems:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:147 +msgid "It requires twice as much disk storage as a non-redundant solution." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:148 +msgid "" +"Writes must be performed to both drives, so they take up twice the bandwidth " +"of a non-mirrored volume. Reads do not suffer from a performance penalty and " +"can even be faster." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:155 +msgid "" +"An alternative solution is _parity_, implemented in `RAID` levels 2, 3, 4 " +"and 5. Of these, `RAID-5` is the most interesting. As implemented in " +"[.filename]#vinum#, it is a variant on a striped organization which " +"dedicates one block of each stripe to parity one of the other blocks. As " +"implemented by [.filename]#vinum#, a `RAID-5` plex is similar to a striped " +"plex, except that it implements `RAID-5` by including a parity block in each " +"stripe. As required by `RAID-5`, the location of this parity block changes " +"from one stripe to the next. The numbers in the data blocks indicate the " +"relative block numbers." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/vinum/_index.adoc:157 +#, no-wrap +msgid "`RAID`-5 Organization" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/vinum/_index.adoc:158 +#, no-wrap +msgid "vinum-raid5-org.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:163 +msgid "" +"Compared to mirroring, `RAID-5` has the advantage of requiring significantly " +"less storage space. Read access is similar to that of striped " +"organizations, but write access is significantly slower, approximately 25% " +"of the read performance. If one drive fails, the array can continue to " +"operate in degraded mode where a read from one of the remaining accessible " +"drives continues normally, but a read from the failed drive is recalculated " +"from the corresponding block from all the remaining drives." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vinum/_index.adoc:165 +#, no-wrap +msgid "[.filename]#vinum# Objects" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:168 +msgid "" +"To address these problems, [.filename]#vinum# implements a four-level " +"hierarchy of objects:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:170 +msgid "" +"The most visible object is the virtual disk, called a _volume_. Volumes have " +"essentially the same properties as a UNIX(R) disk drive, though there are " +"some minor differences. For one, they have no size limitations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:171 +msgid "" +"Volumes are composed of _plexes_, each of which represent the total address " +"space of a volume. This level in the hierarchy provides redundancy. Think of " +"plexes as individual disks in a mirrored array, each containing the same " +"data." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:172 +msgid "" +"Since [.filename]#vinum# exists within the UNIX(R) disk storage framework, " +"it would be possible to use UNIX(R) partitions as the building block for " +"multi-disk plexes. In fact, this turns out to be too inflexible as UNIX(R) " +"disks can have only a limited number of partitions. Instead, " +"[.filename]#vinum# subdivides a single UNIX(R) partition, the _drive_, into " +"contiguous areas called _subdisks_, which are used as building blocks for " +"plexes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:173 +msgid "" +"Subdisks reside on [.filename]#vinum#_drives_, currently UNIX(R) partitions. " +"[.filename]#vinum# drives can contain any number of subdisks. With the " +"exception of a small area at the beginning of the drive, which is used for " +"storing configuration and state information, the entire drive is available " +"for data storage." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:175 +msgid "" +"The following sections describe the way these objects provide the " +"functionality required of [.filename]#vinum#." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:176 +#, no-wrap +msgid "Volume Size Considerations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:180 +msgid "" +"Plexes can include multiple subdisks spread over all drives in the " +"[.filename]#vinum# configuration. As a result, the size of an individual " +"drive does not limit the size of a plex or a volume." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:181 +#, no-wrap +msgid "Redundant Data Storage" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:186 +msgid "" +"[.filename]#vinum# implements mirroring by attaching multiple plexes to a " +"volume. Each plex is a representation of the data in a volume. A volume " +"may contain between one and eight plexes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:189 +msgid "" +"Although a plex represents the complete data of a volume, it is possible for " +"parts of the representation to be physically missing, either by design (by " +"not defining a subdisk for parts of the plex) or by accident (as a result of " +"the failure of a drive). As long as at least one plex can provide the data " +"for the complete address range of the volume, the volume is fully functional." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:190 +#, no-wrap +msgid "Which Plex Organization?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:193 +msgid "" +"[.filename]#vinum# implements both concatenation and striping at the plex " +"level:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:195 +msgid "" +"A _concatenated plex_ uses the address space of each subdisk in turn. " +"Concatenated plexes are the most flexible as they can contain any number of " +"subdisks, and the subdisks may be of different length. The plex may be " +"extended by adding additional subdisks. They require less CPU time than " +"striped plexes, though the difference in CPU overhead is not measurable. On " +"the other hand, they are most susceptible to hot spots, where one disk is " +"very active and others are idle." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:196 +msgid "" +"A _striped plex_ stripes the data across each subdisk. The subdisks must all " +"be the same size and there must be at least two subdisks to distinguish it " +"from a concatenated plex. The greatest advantage of striped plexes is that " +"they reduce hot spots. By choosing an optimum sized stripe, about 256 kB, " +"the load can be evened out on the component drives. Extending a plex by " +"adding new subdisks is so complicated that [.filename]#vinum# does not " +"implement it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:198 +msgid "" +"crossref:vinum[vinum-comparison, [.filename]#vinum# Plex Organizations] " +"summarizes the advantages and disadvantages of each plex organization." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/vinum/_index.adoc:200 +#, no-wrap +msgid "[.filename]#vinum# Plex Organizations" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:204 +#, no-wrap +msgid "Plex type" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:205 +#, no-wrap +msgid "Minimum subdisks" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:206 +#, no-wrap +msgid "Can add subdisks" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:207 +#, no-wrap +msgid "Must be equal size" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:209 +#, no-wrap +msgid "Application" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:210 +#, no-wrap +msgid "concatenated" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:211 +#, no-wrap +msgid "1" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:212 +#: documentation/content/en/articles/vinum/_index.adoc:219 +#, no-wrap +msgid "yes" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:213 +#: documentation/content/en/articles/vinum/_index.adoc:218 +#, no-wrap +msgid "no" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:215 +#, no-wrap +msgid "Large data storage with maximum placement flexibility and moderate performance" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:216 +#, no-wrap +msgid "striped" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:217 +#, no-wrap +msgid "2" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/vinum/_index.adoc:220 +#, no-wrap +msgid "High performance in combination with highly concurrent access" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vinum/_index.adoc:223 +#, no-wrap +msgid "Some Examples" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:229 +msgid "" +"[.filename]#vinum# maintains a _configuration database_ which describes the " +"objects known to an individual system. Initially, the user creates the " +"configuration database from one or more configuration files using " +"man:gvinum[8]. [.filename]#vinum# stores a copy of its configuration " +"database on each disk _device_ under its control. This database is updated " +"on each state change, so that a restart accurately restores the state of " +"each [.filename]#vinum# object." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:230 +#, no-wrap +msgid "The Configuration File" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:234 +msgid "" +"The configuration file describes individual [.filename]#vinum# objects. The " +"definition of a simple volume might be:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:241 +#, no-wrap +msgid "" +" drive a device /dev/da3h\n" +" volume myvol\n" +" plex org concat\n" +" sd length 512m drive a\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:244 +msgid "This file describes four [.filename]#vinum# objects:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:246 +msgid "" +"The _drive_ line describes a disk partition (_drive_) and its location " +"relative to the underlying hardware. It is given the symbolic name _a_. This " +"separation of symbolic names from device names allows disks to be moved from " +"one location to another without confusion." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:247 +msgid "" +"The _volume_ line describes a volume. The only required attribute is the " +"name, in this case _myvol_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:248 +msgid "" +"The _plex_ line defines a plex. The only required parameter is the " +"organization, in this case _concat_. No name is necessary as the system " +"automatically generates a name from the volume name by adding the suffix " +"_.px_, where _x_ is the number of the plex in the volume. Thus this plex " +"will be called _myvol.p0_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:249 +msgid "" +"The _sd_ line describes a subdisk. The minimum specifications are the name " +"of a drive on which to store it, and the length of the subdisk. No name is " +"necessary as the system automatically assigns names derived from the plex " +"name by adding the suffix _.sx_, where _x_ is the number of the subdisk in " +"the plex. Thus [.filename]#vinum# gives this subdisk the name _myvol.p0.s0_." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:251 +msgid "" +"After processing this file, man:gvinum[8] produces the following output:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:261 +#, no-wrap +msgid "" +"# gvinum -> create config1\n" +"Configuration summary\n" +"Drives: 1 (4 configured)\n" +"Volumes: 1 (4 configured)\n" +"Plexes: 1 (8 configured)\n" +"Subdisks: 1 (16 configured)\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:263 +#, no-wrap +msgid " D a State: up Device /dev/da3h Avail: 2061/2573 MB (80%)\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:265 +#, no-wrap +msgid " V myvol State: up Plexes: 1 Size: 512 MB\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:267 +#, no-wrap +msgid " P myvol.p0 C State: up Subdisks: 1 Size: 512 MB\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:269 +#, no-wrap +msgid " S myvol.p0.s0 State: up PO: 0 B Size: 512 MB\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:273 +msgid "" +"This output shows the brief listing format of man:gvinum[8]. It is " +"represented graphically in crossref:vinum[vinum-simple-vol, A Simple " +"[.filename]#vinum# Volume]." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/vinum/_index.adoc:275 +#, no-wrap +msgid "A Simple [.filename]#vinum# Volume" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/vinum/_index.adoc:276 +#, no-wrap +msgid "vinum-simple-vol.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:280 +msgid "" +"This figure, and the ones which follow, represent a volume, which contains " +"the plexes, which in turn contains the subdisks. In this example, the " +"volume contains one plex, and the plex contains one subdisk." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:285 +msgid "" +"This particular volume has no specific advantage over a conventional disk " +"partition. It contains a single plex, so it is not redundant. The plex " +"contains a single subdisk, so there is no difference in storage allocation " +"from a conventional disk partition. The following sections illustrate " +"various more interesting configuration methods." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:286 +#, no-wrap +msgid "Increased Resilience: Mirroring" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:291 +msgid "" +"The resilience of a volume can be increased by mirroring. When laying out a " +"mirrored volume, it is important to ensure that the subdisks of each plex " +"are on different drives, so that a drive failure will not take down both " +"plexes. The following configuration mirrors a volume:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:300 +#, no-wrap +msgid "" +"\tdrive b device /dev/da4h\n" +"\tvolume mirror\n" +" plex org concat\n" +" sd length 512m drive a\n" +"\t plex org concat\n" +"\t sd length 512m drive b\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:304 +msgid "" +"In this example, it was not necessary to specify a definition of drive _a_ " +"again, since [.filename]#vinum# keeps track of all objects in its " +"configuration database. After processing this definition, the configuration " +"looks like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:312 +#, no-wrap +msgid "" +"\tDrives: 2 (4 configured)\n" +"\tVolumes: 2 (4 configured)\n" +"\tPlexes: 3 (8 configured)\n" +"\tSubdisks: 3 (16 configured)\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:315 +#, no-wrap +msgid "" +"\tD a State: up Device /dev/da3h Avail: 1549/2573 MB (60%)\n" +"\tD b State: up Device /dev/da4h Avail: 2061/2573 MB (80%)\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:318 +#, no-wrap +msgid "" +" V myvol State: up Plexes: 1 Size: 512 MB\n" +" V mirror State: up Plexes: 2 Size: 512 MB\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:322 +#, no-wrap +msgid "" +" P myvol.p0 C State: up Subdisks: 1 Size: 512 MB\n" +" P mirror.p0 C State: up Subdisks: 1 Size: 512 MB\n" +" P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:326 +#, no-wrap +msgid "" +" S myvol.p0.s0 State: up PO: 0 B Size: 512 MB\n" +"\tS mirror.p0.s0 State: up PO: 0 B Size: 512 MB\n" +"\tS mirror.p1.s0 State: empty PO: 0 B Size: 512 MB\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:329 +msgid "" +"crossref:vinum[vinum-mirrored-vol, A Mirrored [.filename]#vinum# Volume] " +"shows the structure graphically." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/vinum/_index.adoc:331 +#, no-wrap +msgid "A Mirrored [.filename]#vinum# Volume" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/vinum/_index.adoc:332 +#, no-wrap +msgid "vinum-mirrored-vol.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:336 +msgid "" +"In this example, each plex contains the full 512 MB of address space. As in " +"the previous example, each plex contains only a single subdisk." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:337 +#, no-wrap +msgid "Optimizing Performance" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:342 +msgid "" +"The mirrored volume in the previous example is more resistant to failure " +"than an unmirrored volume, but its performance is less as each write to the " +"volume requires a write to both drives, using up a greater proportion of the " +"total disk bandwidth. Performance considerations demand a different " +"approach: instead of mirroring, the data is striped across as many disk " +"drives as possible. The following configuration shows a volume with a plex " +"striped across four disk drives:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:353 +#, no-wrap +msgid "" +" drive c device /dev/da5h\n" +"\tdrive d device /dev/da6h\n" +"\tvolume stripe\n" +"\tplex org striped 512k\n" +"\t sd length 128m drive a\n" +"\t sd length 128m drive b\n" +"\t sd length 128m drive c\n" +"\t sd length 128m drive d\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:357 +msgid "" +"As before, it is not necessary to define the drives which are already known " +"to [.filename]#vinum#. After processing this definition, the configuration " +"looks like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:365 +#, no-wrap +msgid "" +"\tDrives: 4 (4 configured)\n" +"\tVolumes: 3 (4 configured)\n" +"\tPlexes: 4 (8 configured)\n" +"\tSubdisks: 7 (16 configured)\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:370 +#, no-wrap +msgid "" +" D a State: up Device /dev/da3h Avail: 1421/2573 MB (55%)\n" +" D b State: up Device /dev/da4h Avail: 1933/2573 MB (75%)\n" +" D c State: up Device /dev/da5h Avail: 2445/2573 MB (95%)\n" +" D d State: up Device /dev/da6h Avail: 2445/2573 MB (95%)\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:374 +#, no-wrap +msgid "" +" V myvol State: up Plexes: 1 Size: 512 MB\n" +" V mirror State: up Plexes: 2 Size: 512 MB\n" +" V striped State: up Plexes: 1 Size: 512 MB\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:379 +#, no-wrap +msgid "" +" P myvol.p0 C State: up Subdisks: 1 Size: 512 MB\n" +" P mirror.p0 C State: up Subdisks: 1 Size: 512 MB\n" +" P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB\n" +" P striped.p1 State: up Subdisks: 1 Size: 512 MB\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:387 +#, no-wrap +msgid "" +" S myvol.p0.s0 State: up PO: 0 B Size: 512 MB\n" +" S mirror.p0.s0 State: up PO: 0 B Size: 512 MB\n" +" S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB\n" +" S striped.p0.s0 State: up PO: 0 B Size: 128 MB\n" +" S striped.p0.s1 State: up PO: 512 kB Size: 128 MB\n" +" S striped.p0.s2 State: up PO: 1024 kB Size: 128 MB\n" +" S striped.p0.s3 State: up PO: 1536 kB Size: 128 MB\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/vinum/_index.adoc:390 +#, no-wrap +msgid "A Striped [.filename]#vinum# Volume" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/vinum/_index.adoc:391 +#, no-wrap +msgid "vinum-striped-vol.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:395 +msgid "" +"This volume is represented in crossref:vinum[vinum-striped-vol, A Striped " +"[.filename]#vinum# Volume]. The darkness of the stripes indicates the " +"position within the plex address space, where the lightest stripes come " +"first and the darkest last." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:396 +#, no-wrap +msgid "Resilience and Performance" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:400 +msgid "" +"[[vinum-resilience]]With sufficient hardware, it is possible to build " +"volumes which show both increased resilience and increased performance " +"compared to standard UNIX(R) partitions. A typical configuration file might " +"be:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:416 +#, no-wrap +msgid "" +"\tvolume raid10\n" +" plex org striped 512k\n" +" sd length 102480k drive a\n" +" sd length 102480k drive b\n" +" sd length 102480k drive c\n" +" sd length 102480k drive d\n" +" sd length 102480k drive e\n" +" plex org striped 512k\n" +" sd length 102480k drive c\n" +" sd length 102480k drive d\n" +" sd length 102480k drive e\n" +" sd length 102480k drive a\n" +" sd length 102480k drive b\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:420 +msgid "" +"The subdisks of the second plex are offset by two drives from those of the " +"first plex. This helps to ensure that writes do not go to the same subdisks " +"even if a transfer goes over two drives." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:422 +msgid "" +"crossref:vinum[vinum-raid10-vol, A Mirrored, Striped [.filename]#vinum# " +"Volume] represents the structure of this volume." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/vinum/_index.adoc:424 +#, no-wrap +msgid "A Mirrored, Striped [.filename]#vinum# Volume" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/vinum/_index.adoc:425 +#, no-wrap +msgid "vinum-raid10-vol.png" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vinum/_index.adoc:428 +#, no-wrap +msgid "Object Naming" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:432 +msgid "" +"[.filename]#vinum# assigns default names to plexes and subdisks, although " +"they may be overridden. Overriding the default names is not recommended as " +"it does not bring a significant advantage and it can cause confusion." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:435 +msgid "" +"Names may contain any non-blank character, but it is recommended to restrict " +"them to letters, digits and the underscore characters. The names of " +"volumes, plexes, and subdisks may be up to 64 characters long, and the names " +"of drives may be up to 32 characters long." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:438 +msgid "" +"[.filename]#vinum# objects are assigned device nodes in the hierarchy " +"[.filename]#/dev/gvinum#. The configuration shown above would cause " +"[.filename]#vinum# to create the following device nodes:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:440 +msgid "" +"Device entries for each volume. These are the main devices used by " +"[.filename]#vinum#. The configuration above would include the devices " +"[.filename]#/dev/gvinum/myvol#, [.filename]#/dev/gvinum/mirror#, " +"[.filename]#/dev/gvinum/striped#, [.filename]#/dev/gvinum/raid5# and " +"[.filename]#/dev/gvinum/raid10#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:441 +msgid "All volumes get direct entries under [.filename]#/dev/gvinum/#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:442 +msgid "" +"The directories [.filename]#/dev/gvinum/plex#, and [.filename]#/dev/gvinum/" +"sd#, which contain device nodes for each plex and for each subdisk, " +"respectively." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:444 +msgid "For example, consider the following configuration file:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:457 +#, no-wrap +msgid "" +"\tdrive drive1 device /dev/sd1h\n" +"\tdrive drive2 device /dev/sd2h\n" +"\tdrive drive3 device /dev/sd3h\n" +"\tdrive drive4 device /dev/sd4h\n" +" volume s64 setupstate\n" +" plex org striped 64k\n" +" sd length 100m drive drive1\n" +" sd length 100m drive drive2\n" +" sd length 100m drive drive3\n" +" sd length 100m drive drive4\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:460 +msgid "" +"After processing this file, man:gvinum[8] creates the following structure in " +"[.filename]#/dev/gvinum#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:467 +#, no-wrap +msgid "" +"\tdrwxr-xr-x 2 root wheel 512 Apr 13\n" +"16:46 plex\n" +"\tcrwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64\n" +"\tdrwxr-xr-x 2 root wheel 512 Apr 13 16:46 sd\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:471 +#, no-wrap +msgid "" +" /dev/vinum/plex:\n" +" total 0\n" +" crwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:478 +#, no-wrap +msgid "" +" /dev/vinum/sd:\n" +" total 0\n" +" crwxr-xr-- 1 root wheel 91, 0x20000002 Apr 13 16:46 s64.p0.s0\n" +" crwxr-xr-- 1 root wheel 91, 0x20100002 Apr 13 16:46 s64.p0.s1\n" +" crwxr-xr-- 1 root wheel 91, 0x20200002 Apr 13 16:46 s64.p0.s2\n" +" crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:483 +msgid "" +"Although it is recommended that plexes and subdisks should not be allocated " +"specific names, [.filename]#vinum# drives must be named. This makes it " +"possible to move a drive to a different location and still recognize it " +"automatically. Drive names may be up to 32 characters long." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:484 +#, no-wrap +msgid "Creating File Systems" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:492 +msgid "" +"Volumes appear to the system to be identical to disks, with one exception. " +"Unlike UNIX(R) drives, [.filename]#vinum# does not partition volumes, which " +"thus do not contain a partition table. This has required modification to " +"some disk utilities, notably man:newfs[8], so that it does not try to " +"interpret the last letter of a [.filename]#vinum# volume name as a partition " +"identifier. For example, a disk drive may have a name like [.filename]#/dev/" +"ad0a# or [.filename]#/dev/da2h#. These names represent the first partition " +"([.filename]#a#) on the first (0) IDE disk ([.filename]#ad#) and the eighth " +"partition ([.filename]#h#) on the third (2) SCSI disk ([.filename]#da#) " +"respectively. By contrast, a [.filename]#vinum# volume might be called " +"[.filename]#/dev/gvinum/concat#, which has no relationship with a partition " +"name." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:494 +msgid "To create a file system on this volume, use man:newfs[8]:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:498 +#, no-wrap +msgid "# newfs /dev/gvinum/concat\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vinum/_index.adoc:501 +#, no-wrap +msgid "Configuring [.filename]#vinum#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:507 +msgid "" +"The [.filename]#GENERIC# kernel does not contain [.filename]#vinum#. It is " +"possible to build a custom kernel which includes [.filename]#vinum#, but " +"this is not recommended. The standard way to start [.filename]#vinum# is as " +"a kernel module. man:kldload[8] is not needed because when man:gvinum[8] " +"starts, it checks whether the module has been loaded, and if it is not, it " +"loads it automatically." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:508 +#, no-wrap +msgid "Startup" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:513 +msgid "" +"[.filename]#vinum# stores configuration information on the disk slices in " +"essentially the same form as in the configuration files. When reading from " +"the configuration database, [.filename]#vinum# recognizes a number of " +"keywords which are not allowed in the configuration files. For example, a " +"disk configuration might contain the following text:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:535 +#, no-wrap +msgid "" +"volume myvol state up\n" +"volume bigraid state down\n" +"plex name myvol.p0 state up org concat vol myvol\n" +"plex name myvol.p1 state up org concat vol myvol\n" +"plex name myvol.p2 state init org striped 512b vol myvol\n" +"plex name bigraid.p0 state initializing org raid5 512b vol bigraid\n" +"sd name myvol.p0.s0 drive a plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 0b\n" +"sd name myvol.p0.s1 drive b plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 1048576b\n" +"sd name myvol.p1.s0 drive c plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 0b\n" +"sd name myvol.p1.s1 drive d plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 1048576b\n" +"sd name myvol.p2.s0 drive a plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 0b\n" +"sd name myvol.p2.s1 drive b plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 524288b\n" +"sd name myvol.p2.s2 drive c plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1048576b\n" +"sd name myvol.p2.s3 drive d plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1572864b\n" +"sd name bigraid.p0.s0 drive a plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 0b\n" +"sd name bigraid.p0.s1 drive b plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 4194304b\n" +"sd name bigraid.p0.s2 drive c plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 8388608b\n" +"sd name bigraid.p0.s3 drive d plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 12582912b\n" +"sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 16777216b\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:541 +msgid "" +"The obvious differences here are the presence of explicit location " +"information and naming, both of which are allowed but discouraged, and the " +"information on the states. [.filename]#vinum# does not store information " +"about drives in the configuration information. It finds the drives by " +"scanning the configured disk drives for partitions with a [.filename]#vinum# " +"label. This enables [.filename]#vinum# to identify drives correctly even if " +"they have been assigned different UNIX(R) drive IDs." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/vinum/_index.adoc:543 +#, no-wrap +msgid "Automatic Startup" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:547 +msgid "" +"_Gvinum_ always features an automatic startup once the kernel module is " +"loaded, via man:loader.conf[5]. To load the _Gvinum_ module at boot time, " +"add `geom_vinum_load=\"YES\"` to [.filename]#/boot/loader.conf#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:552 +msgid "" +"When [.filename]#vinum# is started with `gvinum start`, [.filename]#vinum# " +"reads the configuration database from one of the [.filename]#vinum# drives. " +"Under normal circumstances, each drive contains an identical copy of the " +"configuration database, so it does not matter which drive is read. After a " +"crash, however, [.filename]#vinum# must determine which drive was updated " +"most recently and read the configuration from this drive. It then updates " +"the configuration, if necessary, from progressively older drives." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vinum/_index.adoc:554 +#, no-wrap +msgid "Using [.filename]#vinum# for the Root File System" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:558 +msgid "" +"For a machine that has fully-mirrored file systems using [.filename]#vinum#, " +"it is desirable to also mirror the root file system. Setting up such a " +"configuration is less trivial than mirroring an arbitrary file system " +"because:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:560 +msgid "" +"The root file system must be available very early during the boot process, " +"so the [.filename]#vinum# infrastructure must already be available at this " +"time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:561 +msgid "" +"The volume containing the root file system also contains the system " +"bootstrap and the kernel. These must be read using the host system's native " +"utilities, such as the BIOS, which often cannot be taught about the details " +"of [.filename]#vinum#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:563 +msgid "" +"In the following sections, the term \"root volume\" is generally used to " +"describe the [.filename]#vinum# volume that contains the root file system." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:564 +#, no-wrap +msgid "Starting up [.filename]#vinum# Early Enough for the Root File System" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:568 +msgid "" +"[.filename]#vinum# must be available early in the system boot as " +"man:loader[8] must be able to load the vinum kernel module before starting " +"the kernel. This can be accomplished by putting this line in [.filename]#/" +"boot/loader.conf#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:572 +#, no-wrap +msgid "geom_vinum_load=\"YES\"\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:574 +#, no-wrap +msgid "Making a [.filename]#vinum#-based Root Volume Accessible to the Bootstrap" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:579 +msgid "" +"The current FreeBSD bootstrap is only 7.5 KB of code and does not understand " +"the internal [.filename]#vinum# structures. This means that it cannot parse " +"the [.filename]#vinum# configuration data or figure out the elements of a " +"boot volume. Thus, some workarounds are necessary to provide the bootstrap " +"code with the illusion of a standard `a` partition that contains the root " +"file system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:581 +msgid "" +"For this to be possible, the following requirements must be met for the root " +"volume:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:583 +msgid "The root volume must not be a stripe or `RAID`-5." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:584 +msgid "" +"The root volume must not contain more than one concatenated subdisk per plex." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:590 +msgid "" +"Note that it is desirable and possible to use multiple plexes, each " +"containing one replica of the root file system. The bootstrap process will " +"only use one replica for finding the bootstrap and all boot files, until the " +"kernel mounts the root file system. Each single subdisk within these plexes " +"needs its own `a` partition illusion, for the respective device to be " +"bootable. It is not strictly needed that each of these faked `a` partitions " +"is located at the same offset within its device, compared with other devices " +"containing plexes of the root volume. However, it is probably a good idea " +"to create the [.filename]#vinum# volumes that way so the resulting mirrored " +"devices are symmetric, to avoid confusion." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:592 +msgid "" +"To set up these `a` partitions for each device containing part of the root " +"volume, the following is required:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/vinum/_index.adoc:596 +msgid "" +"The location, offset from the beginning of the device, and size of this " +"device's subdisk that is part of the root volume needs to be examined, using " +"the command:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:600 +#, no-wrap +msgid "# gvinum l -rv root\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:604 +msgid "" +"[.filename]#vinum# offsets and sizes are measured in bytes. They must be " +"divided by 512 to obtain the block numbers that are to be used by `bsdlabel`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:605 +msgid "Run this command for each device that participates in the root volume:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:609 +#, no-wrap +msgid "# bsdlabel -e devname\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:612 +msgid "" +"_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#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:615 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:621 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:624 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:625 +msgid "" +"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:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:629 +#, no-wrap +msgid "# fsck -n /dev/devnamea\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/vinum/_index.adoc:634 +msgid "" +"It should be remembered that all files containing control information must " +"be relative to the root file system in the [.filename]#vinum# volume which, " +"when setting up a new [.filename]#vinum# root volume, might not match the " +"root file system that is currently active. So in particular, [.filename]#/" +"etc/fstab# and [.filename]#/boot/loader.conf# need to be taken care of." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/vinum/_index.adoc:637 +msgid "" +"At next reboot, the bootstrap should figure out the appropriate control " +"information from the new [.filename]#vinum#-based root file system, and act " +"accordingly. At the end of the kernel initialization process, after all " +"devices have been announced, the prominent notice that shows the success of " +"this setup is a message like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:641 +#, no-wrap +msgid "Mounting root from ufs:/dev/gvinum/root\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:643 +#, no-wrap +msgid "Example of a [.filename]#vinum#-based Root Setup" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:646 +msgid "" +"After the [.filename]#vinum# root volume has been set up, the output of " +"`gvinum l -rv root` could look like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:655 +#, no-wrap +msgid "" +"...\n" +"Subdisk root.p0.s0:\n" +"\t\tSize: 125829120 bytes (120 MB)\n" +"\t\tState: up\n" +"\t\tPlex root.p0 at offset 0 (0 B)\n" +"\t\tDrive disk0 (/dev/da0h) at offset 135680 (132 kB)\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:661 +#, no-wrap +msgid "" +"Subdisk root.p1.s0:\n" +"\t\tSize: 125829120 bytes (120 MB)\n" +"\t\tState: up\n" +"\t\tPlex root.p1 at offset 0 (0 B)\n" +"\t\tDrive disk1 (/dev/da1h) at offset 135680 (132 kB)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:667 +msgid "" +"The values to note are `135680` for the offset, relative to partition " +"[.filename]#/dev/da0h#. This translates to 265 512-byte disk blocks in " +"`bsdlabel`'s terms. Likewise, the size of this root volume is 245760 512-" +"byte blocks. [.filename]#/dev/da1h#, containing the second replica of this " +"root volume, has a symmetric setup." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:669 +msgid "The bsdlabel for these devices might look like:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vinum/_index.adoc:678 +#, no-wrap +msgid "" +"...\n" +"8 partitions:\n" +"# size offset fstype [fsize bsize bps/cpg]\n" +" a: 245760 281 4.2BSD 2048 16384 0 # (Cyl. 0*- 15*)\n" +" c: 71771688 0 unused 0 0 # (Cyl. 0 - 4467*)\n" +" h: 71771672 16 vinum # (Cyl. 0*- 4467*)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:684 +msgid "" +"It can be observed that the `size` parameter for the faked `a` partition " +"matches the value outlined above, while the `offset` parameter is the sum of " +"the offset within the [.filename]#vinum# partition `h`, and the offset of " +"this partition within the device or slice. This is a typical setup that is " +"necessary to avoid the problem described in crossref:vinum[vinum-root-panic, " +"Nothing Boots, the Bootstrap Panics]. The entire `a` partition is " +"completely within the `h` partition containing all the [.filename]#vinum# " +"data for this device." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:686 +msgid "" +"In the above example, the entire device is dedicated to [.filename]#vinum# " +"and there is no leftover pre-[.filename]#vinum# root partition." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vinum/_index.adoc:687 +#, no-wrap +msgid "Troubleshooting" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:690 +msgid "The following list contains a few known pitfalls and solutions." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/vinum/_index.adoc:691 +#, no-wrap +msgid "System Bootstrap Loads, but System Does Not Boot" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:695 +msgid "" +"If for any reason the system does not continue to boot, the bootstrap can be " +"interrupted by pressing kbd:[space] at the 10-seconds warning. The loader " +"variable `vinum.autostart` can be examined by typing `show` and manipulated " +"using `set` or `unset`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:697 +msgid "" +"If the [.filename]#vinum# kernel module was not yet in the list of modules " +"to load automatically, type `load geom_vinum`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:700 +msgid "" +"When ready, the boot process can be continued by typing `boot -as` which `-" +"as` requests the kernel to ask for the root file system to mount (`-a`) and " +"make the boot process stop in single-user mode (`-s`), where the root file " +"system is mounted read-only. That way, even if only one plex of a multi-" +"plex volume has been mounted, no data inconsistency between plexes is being " +"risked." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:706 +msgid "" +"At the prompt asking for a root file system to mount, any device that " +"contains a valid root file system can be entered. If [.filename]#/etc/" +"fstab# is set up correctly, the default should be something like `ufs:/dev/" +"gvinum/root`. A typical alternate choice would be something like `ufs:da0d` " +"which could be a hypothetical partition containing the pre-" +"[.filename]#vinum# root file system. Care should be taken if one of the " +"alias `a` partitions is entered here, that it actually references the " +"subdisks of the [.filename]#vinum# root device, because in a mirrored setup, " +"this would only mount one piece of a mirrored root device. If this file " +"system is to be mounted read-write later on, it is necessary to remove the " +"other plex(es) of the [.filename]#vinum# root volume since these plexes " +"would otherwise carry inconsistent data." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/vinum/_index.adoc:707 +#, no-wrap +msgid "Only Primary Bootstrap Loads" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:712 +msgid "" +"If [.filename]#/boot/loader# fails to load, but the primary bootstrap still " +"loads (visible by a single dash in the left column of the screen right after " +"the boot process starts), an attempt can be made to interrupt the primary " +"bootstrap by pressing kbd:[space]. This will make the bootstrap stop in " +"extref:{handbook}[stage two, boot-boot1]. An attempt can be made here to " +"boot off an alternate partition, like the partition containing the previous " +"root file system that has been moved away from `a`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/vinum/_index.adoc:714 +#, no-wrap +msgid "Nothing Boots, the Bootstrap Panics" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:720 +msgid "" +"This situation will happen if the bootstrap had been destroyed by the " +"[.filename]#vinum# installation. Unfortunately, [.filename]#vinum# " +"accidentally leaves only 4 KB at the beginning of its partition free before " +"starting to write its [.filename]#vinum# header information. However, the " +"stage one and two bootstraps plus the bsdlabel require 8 KB. So if a " +"[.filename]#vinum# partition was started at offset 0 within a slice or disk " +"that was meant to be bootable, the [.filename]#vinum# setup will trash the " +"bootstrap." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vinum/_index.adoc:723 +msgid "" +"Similarly, if the above situation has been recovered, by booting from a " +"\"Fixit\" media, and the bootstrap has been re-installed using `bsdlabel -B` " +"as described in extref:{handbook}[stage two, boot-boot1], the bootstrap will " +"trash the [.filename]#vinum# header, and [.filename]#vinum# will no longer " +"find its disk(s). Though no actual [.filename]#vinum# configuration data or " +"data in [.filename]#vinum# volumes will be trashed, and it would be possible " +"to recover all the data by entering exactly the same [.filename]#vinum# " +"configuration data again, the situation is hard to fix. It is necessary to " +"move the entire [.filename]#vinum# partition by at least 4 KB, to have the " +"[.filename]#vinum# header and the system bootstrap no longer collide." +msgstr "" diff --git a/documentation/content/en/articles/vm-design/_index.adoc b/documentation/content/en/articles/vm-design/_index.adoc index cac81535c5..81f01d484b 100644 --- a/documentation/content/en/articles/vm-design/_index.adoc +++ b/documentation/content/en/articles/vm-design/_index.adoc @@ -39,9 +39,17 @@ ifndef::env-beastie[] include::../../../../../shared/asciidoctor.adoc[] endif::[] +[NOTE] +==== +This document is outdated and some sections do not accurately describe the current state of the VM system. +It is retained for historical purposes and may be updated over time. +==== + [.abstract-title] Abstract +Matthew Dillon <dillon@apollo.backplane.com> + The title is really just a fancy way of saying that I am going to attempt to describe the whole VM enchilada, hopefully in a way that everyone can follow. For the last year I have concentrated on a number of major kernel subsystems within FreeBSD, with the VM and Swap subsystems being the most interesting and NFS being "a necessary chore". I rewrote only small portions of the code. In the VM arena the only major rewrite I have done is to the swap subsystem. @@ -76,7 +84,7 @@ These issues are not due to bad algorithmic design but instead rise from environ In any direct comparison between platforms, these issues become most apparent when system resources begin to get stressed. As I describe FreeBSD's VM/Swap subsystem the reader should always keep two points in mind: -. The most important aspect of performance design is what is known as "Optimizing the Critical Path". It is often the case that performance optimizations add a little bloat to the code in order to make the critical path perform better. +. The most important aspect of performance design is what is known as "Optimizing the Critical Path". It is often the case that performance optimizations add a little bloat to the code to make the critical path perform better. . A solid, generalized design outperforms a heavily-optimized design over the long run. While a generalized design may end up being slower than an heavily-optimized design when they are first implemented, the generalized design tends to be easier to adapt to changing conditions and the heavily-optimized design winds up having to be thrown away. Any codebase that will survive and be maintainable for years must therefore be designed properly from the beginning even if it costs some performance. @@ -106,7 +114,7 @@ Data may be modified on a page-by-page basis whereas the file mapping encompasse The complexity further increases when a process forks. When a process forks, the result is two processes-each with their own private address spaces, including any modifications made by the original process prior to the call to `fork()`. It would be silly for the VM system to make a complete copy of the data at the time of the `fork()` because it is quite possible that at least one of the two processes will only need to read from that page from then on, allowing the original page to continue to be used. -What was a private page is made copy-on-write again, since each process (parent and child) expects their own personal post-fork modifications to remain private to themselves and not effect the other. +What was a private page is made copy-on-write again, since each process (parent and child) expects their own personal post-fork modifications to remain private to themselves and not affect the other. FreeBSD manages all of this with a layered VM Object model. The original binary program file winds up being the lowest VM Object layer. @@ -185,7 +193,7 @@ FreeBSD allocates the swap management structure for a VM Object only when it is However, the swap management structure has had problems historically: * Under FreeBSD 3.X the swap management structure preallocates an array that encompasses the entire object requiring swap backing store-even if only a few pages of that object are swap-backed. This creates a kernel memory fragmentation problem when large objects are mapped, or processes with large runsizes (RSS) fork. -* Also, in order to keep track of swap space, a "list of holes" is kept in kernel memory, and this tends to get severely fragmented as well. Since the "list of holes" is a linear list, the swap allocation and freeing performance is a non-optimal O(n)-per-page. +* Also, to keep track of swap space, a "list of holes" is kept in kernel memory, and this tends to get severely fragmented as well. Since the "list of holes" is a linear list, the swap allocation and freeing performance is a non-optimal O(n)-per-page. * It requires kernel memory allocations to take place during the swap freeing process, and that creates low memory deadlock problems. * The problem is further exacerbated by holes created due to the interleaving algorithm. * Also, the swap block map can become fragmented fairly easily resulting in non-contiguous allocations. @@ -196,10 +204,10 @@ For FreeBSD 4.X, I completely rewrote the swap subsystem: * Swap management structures are allocated through a hash table rather than a linear array giving them a fixed allocation size and much finer granularity. * Rather then using a linearly linked list to keep track of swap space reservations, it now uses a bitmap of swap blocks arranged in a radix tree structure with free-space hinting in the radix node structures. This effectively makes swap allocation and freeing an O(1) operation. -* The entire radix tree bitmap is also preallocated in order to avoid having to allocate kernel memory during critical low memory swapping operations. After all, the system tends to swap when it is low on memory so we should avoid allocating kernel memory at such times in order to avoid potential deadlocks. +* The entire radix tree bitmap is also preallocated to avoid having to allocate kernel memory during critical low memory swapping operations. After all, the system tends to swap when it is low on memory so we should avoid allocating kernel memory at such times to avoid potential deadlocks. * To reduce fragmentation the radix tree is capable of allocating large contiguous chunks at once, skipping over smaller fragmented chunks. -I did not take the final step of having an "allocating hint pointer" that would trundle through a portion of swap as allocations were made in order to further guarantee contiguous allocations or at least locality of reference, but I ensured that such an addition could be made. +I did not take the final step of having an "allocating hint pointer" that would trundle through a portion of swap as allocations were made to further guarantee contiguous allocations or at least locality of reference, but I ensured that such an addition could be made. [[freeing-pages]] == When to free a page @@ -208,7 +216,7 @@ Since the VM system uses all available memory for disk caching, there are usuall The VM system depends on being able to properly choose pages which are not in use to reuse for new allocations. Selecting the optimal pages to free is possibly the single-most important function any VM system can perform because if it makes a poor selection, the VM system may be forced to unnecessarily retrieve pages from disk, seriously degrading system performance. -How much overhead are we willing to suffer in the critical path to avoid freeing the wrong page? Each wrong choice we make will cost us hundreds of thousands of CPU cycles and a noticeable stall of the affected processes, so we are willing to endure a significant amount of overhead in order to be sure that the right page is chosen. +How much overhead are we willing to suffer in the critical path to avoid freeing the wrong page? Each wrong choice we make will cost us hundreds of thousands of CPU cycles and a noticeable stall of the affected processes, so we are willing to endure a significant amount of overhead to be sure that the right page is chosen. This is why FreeBSD tends to outperform other systems when memory resources become stressed. The free page determination algorithm is built upon a history of the use of memory pages. @@ -240,7 +248,7 @@ This is why you will see some systems with very low cache queue counts and high As the VM system becomes more stressed, it makes a greater effort to maintain the various page queues at the levels determined to be the most effective. An urban myth has circulated for years that Linux did a better job avoiding swapouts than FreeBSD, but this in fact is not true. -What was actually occurring was that FreeBSD was proactively paging out unused pages in order to make room for more disk cache while Linux was keeping unused pages in core and leaving less memory available for cache and process pages. +What was actually occurring was that FreeBSD was proactively paging out unused pages to make room for more disk cache while Linux was keeping unused pages in core and leaving less memory available for cache and process pages. I do not know whether this is still true today. [[prefault-optimizations]] @@ -261,8 +269,8 @@ These occur when a process accesses pages in its BSS area. The BSS area is expected to be initially zero but the VM system does not bother to allocate any memory at all until the process actually accesses it. When a fault occurs the VM system must not only allocate a new page, it must zero it as well. To optimize the zeroing operation the VM system has the ability to pre-zero pages and mark them as such, and to request pre-zeroed pages when zero-fill faults occur. -The pre-zeroing occurs whenever the CPU is idle but the number of pages the system pre-zeros is limited in order to avoid blowing away the memory caches. -This is an excellent example of adding complexity to the VM system in order to optimize the critical path. +The pre-zeroing occurs whenever the CPU is idle but the number of pages the system pre-zeros is limited to avoid blowing away the memory caches. +This is an excellent example of adding complexity to the VM system to optimize the critical path. [[page-table-optimizations]] == Page Table Optimizations @@ -281,25 +289,6 @@ FreeBSD is trying to maximize the advantage of a potentially sparse active-mappi FreeBSD generally has the performance advantage here at the cost of wasting a little extra memory, but FreeBSD breaks down in the case where a large file is massively shared across hundreds of processes. Linux, on the other hand, breaks down in the case where many processes are sparsely-mapping the same shared library and also runs non-optimally when trying to determine whether a page can be reused or not. -[[page-coloring-optimizations]] -== Page Coloring - -We will end with the page coloring optimizations. -Page coloring is a performance optimization designed to ensure that accesses to contiguous pages in virtual memory make the best use of the processor cache. -In ancient times (i.e. 10+ years ago) processor caches tended to map virtual memory rather than physical memory. -This led to a huge number of problems including having to clear the cache on every context switch in some cases, and problems with data aliasing in the cache. -Modern processor caches map physical memory precisely to solve those problems. -This means that two side-by-side pages in a processes address space may not correspond to two side-by-side pages in the cache. -In fact, if you are not careful side-by-side pages in virtual memory could wind up using the same page in the processor cache-leading to cacheable data being thrown away prematurely and reducing CPU performance. -This is true even with multi-way set-associative caches (though the effect is mitigated somewhat). - -FreeBSD's memory allocation code implements page coloring optimizations, which means that the memory allocation code will attempt to locate free pages that are contiguous from the point of view of the cache. -For example, if page 16 of physical memory is assigned to page 0 of a process's virtual memory and the cache can hold 4 pages, the page coloring code will not assign page 20 of physical memory to page 1 of a process's virtual memory. -It would, instead, assign page 21 of physical memory. -The page coloring code attempts to avoid assigning page 20 because this maps over the same cache memory as page 16 and would result in non-optimal caching. -This code adds a significant amount of complexity to the VM memory allocation subsystem as you can well imagine, but the result is well worth the effort. -Page Coloring makes VM memory as deterministic as physical memory in regards to cache performance. - [[conclusion]] == Conclusion @@ -360,16 +349,16 @@ A `vm_page` represents an (object,index#) tuple. A `pv_entry` represents a hardw If you have five processes sharing the same physical page, and three of those processes's page tables actually map the page, that page will be represented by a single `vm_page` structure and three `pv_entry` structures. `pv_entry` structures only represent pages mapped by the MMU (one `pv_entry` represents one pte). -This means that when we need to remove all hardware references to a `vm_page` (in order to reuse the page for something else, page it out, clear it, dirty it, and so forth) we can simply scan the linked list of pv_entry's associated with that vm_page to remove or modify the pte's from their page tables. +This means that when we need to remove all hardware references to a `vm_page` (to reuse the page for something else, page it out, clear it, dirty it, and so forth) we can simply scan the linked list of pv_entry's associated with that vm_page to remove or modify the pte's from their page tables. Under Linux there is no such linked list. -In order to remove all the hardware page table mappings for a `vm_page` linux must index into every VM object that _might_ have mapped the page. +To remove all the hardware page table mappings for a `vm_page` linux must index into every VM object that _might_ have mapped the page. For example, if you have 50 processes all mapping the same shared library and want to get rid of page X in that library, you need to index into the page table for each of those 50 processes even if only 10 of them have actually mapped the page. So Linux is trading off the simplicity of its design against performance. Many VM algorithms which are O(1) or (small N) under FreeBSD wind up being O(N), O(N^2), or worse under Linux. Since the pte's representing a particular page in an object tend to be at the same offset in all the page tables they are mapped in, reducing the number of accesses into the page tables at the same pte offset will often avoid blowing away the L1 cache line for that offset, which can lead to better performance. -FreeBSD has added complexity (the `pv_entry` scheme) in order to increase performance (to limit page table accesses to _only_ those pte's that need to be modified). +FreeBSD has added complexity (the `pv_entry` scheme) to increase performance (to limit page table accesses to _only_ those pte's that need to be modified). But FreeBSD has a scaling problem that Linux does not in that there are a limited number of `pv_entry` structures and this causes problems when you have massive sharing of data. In this case you may run out of `pv_entry` structures even though there is plenty of free memory available. @@ -378,44 +367,3 @@ This can be fixed easily enough by bumping up the number of `pv_entry` structure In regards to the memory overhead of a page table verses the `pv_entry` scheme: Linux uses "permanent" page tables that are not throw away, but does not need a `pv_entry` for each potentially mapped pte. FreeBSD uses "throw away" page tables but adds in a `pv_entry` structure for each actually-mapped pte. I think memory utilization winds up being about the same, giving FreeBSD an algorithmic advantage with its ability to throw away page tables at will with very low overhead. - -=== Finally, in the page coloring section, it might help to have a little more description of what you mean here. I did not quite follow it. - -Do you know how an L1 hardware memory cache works? I will explain: Consider a machine with 16MB of main memory but only 128K of L1 cache. -Generally the way this cache works is that each 128K block of main memory uses the _same_ 128K of cache. -If you access offset 0 in main memory and then offset 128K in main memory you can wind up throwing away the cached data you read from offset 0! - -Now, I am simplifying things greatly. -What I just described is what is called a "direct mapped" hardware memory cache. -Most modern caches are what are called 2-way-set-associative or 4-way-set-associative caches. -The set-associatively allows you to access up to N different memory regions that overlap the same cache memory without destroying the previously cached data. -But only N. - -So if I have a 4-way set associative cache I can access offset 0, offset 128K, 256K and offset 384K and still be able to access offset 0 again and have it come from the L1 cache. -If I then access offset 512K, however, one of the four previously cached data objects will be thrown away by the cache. - -It is extremely important... _extremely_ important for most of a processor's memory accesses to be able to come from the L1 cache, because the L1 cache operates at the processor frequency. -The moment you have an L1 cache miss and have to go to the L2 cache or to main memory, the processor will stall and potentially sit twiddling its fingers for _hundreds_ of instructions worth of time waiting for a read from main memory to complete. -Main memory (the dynamic ram you stuff into a computer) is __slow__, when compared to the speed of a modern processor core. - -Ok, so now onto page coloring: All modern memory caches are what are known as _physical_ caches. -They cache physical memory addresses, not virtual memory addresses. -This allows the cache to be left alone across a process context switch, which is very important. - -But in the UNIX(R) world you are dealing with virtual address spaces, not physical address spaces. -Any program you write will see the virtual address space given to it. -The actual _physical_ pages underlying that virtual address space are not necessarily physically contiguous! -In fact, you might have two pages that are side by side in a processes address space which wind up being at offset 0 and offset 128K in _physical_ memory. - -A program normally assumes that two side-by-side pages will be optimally cached. -That is, that you can access data objects in both pages without having them blow away each other's cache entry. -But this is only true if the physical pages underlying the virtual address space are contiguous (insofar as the cache is concerned). - -This is what Page coloring does. -Instead of assigning _random_ physical pages to virtual addresses, which may result in non-optimal cache performance, Page coloring assigns _reasonably-contiguous_ physical pages to virtual addresses. -Thus programs can be written under the assumption that the characteristics of the underlying hardware cache are the same for their virtual address space as they would be if the program had been run directly in a physical address space. - -Note that I say "reasonably" contiguous rather than simply "contiguous". -From the point of view of a 128K direct mapped cache, the physical address 0 is the same as the physical address 128K. -So two side-by-side pages in your virtual address space may wind up being offset 128K and offset 132K in physical memory, but could also easily be offset 128K and offset 4K in physical memory and still retain the same cache performance characteristics. -So page-coloring does _not_ have to assign truly contiguous pages of physical memory to contiguous pages of virtual memory, it just needs to make sure it assigns contiguous pages from the point of view of cache performance and operation. diff --git a/documentation/content/en/articles/vm-design/_index.po b/documentation/content/en/articles/vm-design/_index.po new file mode 100644 index 0000000000..4c46c07fc1 --- /dev/null +++ b/documentation/content/en/articles/vm-design/_index.po @@ -0,0 +1,875 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2025-06-29 21:20+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: YAML Front Matter: description +#: documentation/content/en/articles/vm-design/_index.adoc:1 +#, no-wrap +msgid "An easy to follow description of the design of the FreeBSD virtual memory system" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/vm-design/_index.adoc:1 +#: documentation/content/en/articles/vm-design/_index.adoc:11 +#, no-wrap +msgid "Design elements of the FreeBSD VM system" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/vm-design/_index.adoc:46 +msgid "" +"This document is outdated and some sections do not accurately describe the " +"current state of the VM system. It is retained for historical purposes and " +"may be updated over time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:50 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:52 +msgid "Matthew Dillon <dillon@apollo.backplane.com>" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:59 +msgid "" +"The title is really just a fancy way of saying that I am going to attempt to " +"describe the whole VM enchilada, hopefully in a way that everyone can " +"follow. For the last year I have concentrated on a number of major kernel " +"subsystems within FreeBSD, with the VM and Swap subsystems being the most " +"interesting and NFS being \"a necessary chore\". I rewrote only small " +"portions of the code. In the VM arena the only major rewrite I have done is " +"to the swap subsystem. Most of my work was cleanup and maintenance, with " +"only moderate code rewriting and no major algorithmic adjustments within the " +"VM subsystem. The bulk of the VM subsystem's theoretical base remains " +"unchanged and a lot of the credit for the modernization effort in the last " +"few years belongs to John Dyson and David Greenman. Not being a historian " +"like Kirk I will not attempt to tag all the various features with peoples " +"names, since I will invariably get it wrong." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:61 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vm-design/_index.adoc:65 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:81 +msgid "" +"Before moving along to the actual design let's spend a little time on the " +"necessity of maintaining and modernizing any long-living codebase. In the " +"programming world, algorithms tend to be more important than code and it is " +"precisely due to BSD's academic roots that a great deal of attention was " +"paid to algorithm design from the beginning. More attention paid to the " +"design generally leads to a clean and flexible codebase that can be fairly " +"easily modified, extended, or replaced over time. While BSD is considered " +"an \"old\" operating system by some people, those of us who work on it tend " +"to view it more as a \"mature\" codebase which has various components " +"modified, extended, or replaced with modern code. It has evolved, and " +"FreeBSD is at the bleeding edge no matter how old some of the code might " +"be. This is an important distinction to make and one that is unfortunately " +"lost to many people. The biggest error a programmer can make is to not " +"learn from history, and this is precisely the error that many other modern " +"operating systems have made. Windows NT(R) is the best example of this, and " +"the consequences have been dire. Linux also makes this mistake to some " +"degree-enough that we BSD folk can make small jokes about it every once in a " +"while, anyway. Linux's problem is simply one of a lack of experience and " +"history to compare ideas against, a problem that is easily and rapidly being " +"addressed by the Linux community in the same way it has been addressed in " +"the BSD community-by continuous code development. The Windows NT(R) folk, " +"on the other hand, repeatedly make the same mistakes solved by UNIX(R) " +"decades ago and then spend years fixing them. Over and over again. They " +"have a severe case of \"not designed here\" and \"we are always right " +"because our marketing department says so\". I have little tolerance for " +"anyone who cannot learn from history." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:86 +msgid "" +"Much of the apparent complexity of the FreeBSD design, especially in the VM/" +"Swap subsystem, is a direct result of having to solve serious performance " +"issues that occur under various conditions. These issues are not due to bad " +"algorithmic design but instead rise from environmental factors. In any " +"direct comparison between platforms, these issues become most apparent when " +"system resources begin to get stressed. As I describe FreeBSD's VM/Swap " +"subsystem the reader should always keep two points in mind:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:88 +msgid "" +"The most important aspect of performance design is what is known as " +"\"Optimizing the Critical Path\". It is often the case that performance " +"optimizations add a little bloat to the code to make the critical path " +"perform better." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:89 +msgid "" +"A solid, generalized design outperforms a heavily-optimized design over the " +"long run. While a generalized design may end up being slower than an heavily-" +"optimized design when they are first implemented, the generalized design " +"tends to be easier to adapt to changing conditions and the heavily-optimized " +"design winds up having to be thrown away." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:93 +msgid "" +"Any codebase that will survive and be maintainable for years must therefore " +"be designed properly from the beginning even if it costs some performance. " +"Twenty years ago people were still arguing that programming in assembly was " +"better than programming in a high-level language because it produced code " +"that was ten times as fast. Today, the fallibility of that argument is " +"obvious - as are the parallels to algorithmic design and code generalization." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vm-design/_index.adoc:95 +#, no-wrap +msgid "VM Objects" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:105 +msgid "" +"The best way to begin describing the FreeBSD VM system is to look at it from " +"the perspective of a user-level process. Each user process sees a single, " +"private, contiguous VM address space containing several types of memory " +"objects. These objects have various characteristics. Program code and " +"program data are effectively a single memory-mapped file (the binary file " +"being run), but program code is read-only while program data is copy-on-" +"write. Program BSS is just memory allocated and filled with zeros on " +"demand, called demand zero page fill. Arbitrary files can be memory-mapped " +"into the address space as well, which is how the shared library mechanism " +"works. Such mappings can require modifications to remain private to the " +"process making them. The fork system call adds an entirely new dimension to " +"the VM management problem on top of the complexity already given." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:111 +msgid "" +"A program binary data page (which is a basic copy-on-write page) illustrates " +"the complexity. A program binary contains a preinitialized data section " +"which is initially mapped directly from the program file. When a program is " +"loaded into a process's VM space, this area is initially memory-mapped and " +"backed by the program binary itself, allowing the VM system to free/reuse " +"the page and later load it back in from the binary. The moment a process " +"modifies this data, however, the VM system must make a private copy of the " +"page for that process. Since the private copy has been modified, the VM " +"system may no longer free it, because there is no longer any way to restore " +"it later on." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:118 +msgid "" +"You will notice immediately that what was originally a simple file mapping " +"has become much more complex. Data may be modified on a page-by-page basis " +"whereas the file mapping encompasses many pages at once. The complexity " +"further increases when a process forks. When a process forks, the result is " +"two processes-each with their own private address spaces, including any " +"modifications made by the original process prior to the call to `fork()`. " +"It would be silly for the VM system to make a complete copy of the data at " +"the time of the `fork()` because it is quite possible that at least one of " +"the two processes will only need to read from that page from then on, " +"allowing the original page to continue to be used. What was a private page " +"is made copy-on-write again, since each process (parent and child) expects " +"their own personal post-fork modifications to remain private to themselves " +"and not affect the other." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:127 +msgid "" +"FreeBSD manages all of this with a layered VM Object model. The original " +"binary program file winds up being the lowest VM Object layer. A copy-on-" +"write layer is pushed on top of that to hold those pages which had to be " +"copied from the original file. If the program modifies a data page " +"belonging to the original file the VM system takes a fault and makes a copy " +"of the page in the higher layer. When a process forks, additional VM Object " +"layers are pushed on. This might make a little more sense with a fairly " +"basic example. A `fork()` is a common operation for any *BSD system, so " +"this example will consider a program that starts up, and forks. When the " +"process starts, the VM system creates an object layer, let's call this A:" +msgstr "" + +#. type: Positional ($1) AttributeList argument for macro 'image' +#: documentation/content/en/articles/vm-design/_index.adoc:128 +#, no-wrap +msgid "A picture" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/vm-design/_index.adoc:128 +#, no-wrap +msgid "fig1.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:133 +msgid "" +"A represents the file-pages may be paged in and out of the file's physical " +"media as necessary. Paging in from the disk is reasonable for a program, " +"but we really do not want to page back out and overwrite the executable. " +"The VM system therefore creates a second layer, B, that will be physically " +"backed by swap space:" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/vm-design/_index.adoc:134 +#, no-wrap +msgid "fig2.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:139 +msgid "" +"On the first write to a page after this, a new page is created in B, and its " +"contents are initialized from A. All pages in B can be paged in or out to a " +"swap device. When the program forks, the VM system creates two new object " +"layers-C1 for the parent, and C2 for the child-that rest on top of B:" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/vm-design/_index.adoc:140 +#, no-wrap +msgid "fig3.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:151 +msgid "" +"In this case, let's say a page in B is modified by the original parent " +"process. The process will take a copy-on-write fault and duplicate the page " +"in C1, leaving the original page in B untouched. Now, let's say the same " +"page in B is modified by the child process. The process will take a copy-on-" +"write fault and duplicate the page in C2. The original page in B is now " +"completely hidden since both C1 and C2 have a copy and B could theoretically " +"be destroyed if it does not represent a \"real\" file; however, this sort of " +"optimization is not trivial to make because it is so fine-grained. FreeBSD " +"does not make this optimization. Now, suppose (as is often the case) that " +"the child process does an `exec()`. Its current address space is usually " +"replaced by a new address space representing a new file. In this case, the " +"C2 layer is destroyed:" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/vm-design/_index.adoc:152 +#, no-wrap +msgid "fig4.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:158 +msgid "" +"In this case, the number of children of B drops to one, and all accesses to " +"B now go through C1. This means that B and C1 can be collapsed together. " +"Any pages in B that also exist in C1 are deleted from B during the " +"collapse. Thus, even though the optimization in the previous step could not " +"be made, we can recover the dead pages when either of the processes exit or " +"`exec()`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:165 +msgid "" +"This model creates a number of potential problems. The first is that you " +"can wind up with a relatively deep stack of layered VM Objects which can " +"cost scanning time and memory when you take a fault. Deep layering can " +"occur when processes fork and then fork again (either parent or child). The " +"second problem is that you can wind up with dead, inaccessible pages deep in " +"the stack of VM Objects. In our last example if both the parent and child " +"processes modify the same page, they both get their own private copies of " +"the page and the original page in B is no longer accessible by anyone. That " +"page in B can be freed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:176 +msgid "" +"FreeBSD solves the deep layering problem with a special optimization called " +"the \"All Shadowed Case\". This case occurs if either C1 or C2 take " +"sufficient COW faults to completely shadow all pages in B. Lets say that C1 " +"achieves this. C1 can now bypass B entirely, so rather then have C1->B->A " +"and C2->B->A we now have C1->A and C2->B->A. But look what also happened-" +"now B has only one reference (C2), so we can collapse B and C2 together. " +"The end result is that B is deleted entirely and we have C1->A and C2->A. " +"It is often the case that B will contain a large number of pages and neither " +"C1 nor C2 will be able to completely overshadow it. If we fork again and " +"create a set of D layers, however, it is much more likely that one of the D " +"layers will eventually be able to completely overshadow the much smaller " +"dataset represented by C1 or C2. The same optimization will work at any " +"point in the graph and the grand result of this is that even on a heavily " +"forked machine VM Object stacks tend to not get much deeper then 4. This is " +"true of both the parent and the children and true whether the parent is " +"doing the forking or whether the children cascade forks." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:180 +msgid "" +"The dead page problem still exists in the case where C1 or C2 do not " +"completely overshadow B. Due to our other optimizations this case does not " +"represent much of a problem and we simply allow the pages to be dead. If " +"the system runs low on memory it will swap them out, eating a little swap, " +"but that is it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:184 +msgid "" +"The advantage to the VM Object model is that `fork()` is extremely fast, " +"since no real data copying need take place. The disadvantage is that you " +"can build a relatively complex VM Object layering that slows page fault " +"handling down a little, and you spend memory managing the VM Object " +"structures. The optimizations FreeBSD makes proves to reduce the problems " +"enough that they can be ignored, leaving no real disadvantage." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vm-design/_index.adoc:186 +#, no-wrap +msgid "SWAP Layers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:194 +msgid "" +"Private data pages are initially either copy-on-write or zero-fill pages. " +"When a change, and therefore a copy, is made, the original backing object " +"(usually a file) can no longer be used to save a copy of the page when the " +"VM system needs to reuse it for other purposes. This is where SWAP comes " +"in. SWAP is allocated to create backing store for memory that does not " +"otherwise have it. FreeBSD allocates the swap management structure for a VM " +"Object only when it is actually needed. However, the swap management " +"structure has had problems historically:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:196 +msgid "" +"Under FreeBSD 3.X the swap management structure preallocates an array that " +"encompasses the entire object requiring swap backing store-even if only a " +"few pages of that object are swap-backed. This creates a kernel memory " +"fragmentation problem when large objects are mapped, or processes with large " +"runsizes (RSS) fork." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:197 +msgid "" +"Also, to keep track of swap space, a \"list of holes\" is kept in kernel " +"memory, and this tends to get severely fragmented as well. Since the \"list " +"of holes\" is a linear list, the swap allocation and freeing performance is " +"a non-optimal O(n)-per-page." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:198 +msgid "" +"It requires kernel memory allocations to take place during the swap freeing " +"process, and that creates low memory deadlock problems." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:199 +msgid "" +"The problem is further exacerbated by holes created due to the interleaving " +"algorithm." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:200 +msgid "" +"Also, the swap block map can become fragmented fairly easily resulting in " +"non-contiguous allocations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:201 +msgid "" +"Kernel memory must also be allocated on the fly for additional swap " +"management structures when a swapout occurs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:204 +msgid "" +"It is evident from that list that there was plenty of room for improvement. " +"For FreeBSD 4.X, I completely rewrote the swap subsystem:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:206 +msgid "" +"Swap management structures are allocated through a hash table rather than a " +"linear array giving them a fixed allocation size and much finer granularity." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:207 +msgid "" +"Rather then using a linearly linked list to keep track of swap space " +"reservations, it now uses a bitmap of swap blocks arranged in a radix tree " +"structure with free-space hinting in the radix node structures. This " +"effectively makes swap allocation and freeing an O(1) operation." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:208 +msgid "" +"The entire radix tree bitmap is also preallocated to avoid having to " +"allocate kernel memory during critical low memory swapping operations. After " +"all, the system tends to swap when it is low on memory so we should avoid " +"allocating kernel memory at such times to avoid potential deadlocks." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:209 +msgid "" +"To reduce fragmentation the radix tree is capable of allocating large " +"contiguous chunks at once, skipping over smaller fragmented chunks." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:211 +msgid "" +"I did not take the final step of having an \"allocating hint pointer\" that " +"would trundle through a portion of swap as allocations were made to further " +"guarantee contiguous allocations or at least locality of reference, but I " +"ensured that such an addition could be made." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vm-design/_index.adoc:213 +#, no-wrap +msgid "When to free a page" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:218 +msgid "" +"Since the VM system uses all available memory for disk caching, there are " +"usually very few truly-free pages. The VM system depends on being able to " +"properly choose pages which are not in use to reuse for new allocations. " +"Selecting the optimal pages to free is possibly the single-most important " +"function any VM system can perform because if it makes a poor selection, the " +"VM system may be forced to unnecessarily retrieve pages from disk, seriously " +"degrading system performance." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:221 +msgid "" +"How much overhead are we willing to suffer in the critical path to avoid " +"freeing the wrong page? Each wrong choice we make will cost us hundreds of " +"thousands of CPU cycles and a noticeable stall of the affected processes, so " +"we are willing to endure a significant amount of overhead to be sure that " +"the right page is chosen. This is why FreeBSD tends to outperform other " +"systems when memory resources become stressed." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:224 +msgid "" +"The free page determination algorithm is built upon a history of the use of " +"memory pages. To acquire this history, the system takes advantage of a page-" +"used bit feature that most hardware page tables have." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:230 +msgid "" +"In any case, the page-used bit is cleared and at some later point the VM " +"system comes across the page again and sees that the page-used bit has been " +"set. This indicates that the page is still being actively used. If the bit " +"is still clear it is an indication that the page is not being actively " +"used. By testing this bit periodically, a use history (in the form of a " +"counter) for the physical page is developed. When the VM system later needs " +"to free up some pages, checking this history becomes the cornerstone of " +"determining the best candidate page to reuse." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:235 +msgid "" +"For those platforms that do not have this feature, the system actually " +"emulates a page-used bit. It unmaps or protects a page, forcing a page " +"fault if the page is accessed again. When the page fault is taken, the " +"system simply marks the page as having been used and unprotects the page so " +"that it may be used. While taking such page faults just to determine if a " +"page is being used appears to be an expensive proposition, it is much less " +"expensive than reusing the page for some other purpose only to find that a " +"process needs it back and then have to go to disk." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:245 +msgid "" +"FreeBSD makes use of several page queues to further refine the selection of " +"pages to reuse as well as to determine when dirty pages must be flushed to " +"their backing store. Since page tables are dynamic entities under FreeBSD, " +"it costs virtually nothing to unmap a page from the address space of any " +"processes using it. When a page candidate has been chosen based on the page-" +"use counter, this is precisely what is done. The system must make a " +"distinction between clean pages which can theoretically be freed up at any " +"time, and dirty pages which must first be written to their backing store " +"before being reusable. When a page candidate has been found it is moved to " +"the inactive queue if it is dirty, or the cache queue if it is clean. A " +"separate algorithm based on the dirty-to-clean page ratio determines when " +"dirty pages in the inactive queue must be flushed to disk. Once this is " +"accomplished, the flushed pages are moved from the inactive queue to the " +"cache queue. At this point, pages in the cache queue can still be " +"reactivated by a VM fault at relatively low cost. However, pages in the " +"cache queue are considered to be \"immediately freeable\" and will be reused " +"in an LRU (least-recently used) fashion when the system needs to allocate " +"new memory." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:249 +msgid "" +"It is important to note that the FreeBSD VM system attempts to separate " +"clean and dirty pages for the express reason of avoiding unnecessary flushes " +"of dirty pages (which eats I/O bandwidth), nor does it move pages between " +"the various page queues gratuitously when the memory subsystem is not being " +"stressed. This is why you will see some systems with very low cache queue " +"counts and high active queue counts when doing a `systat -vm` command. As " +"the VM system becomes more stressed, it makes a greater effort to maintain " +"the various page queues at the levels determined to be the most effective." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:253 +msgid "" +"An urban myth has circulated for years that Linux did a better job avoiding " +"swapouts than FreeBSD, but this in fact is not true. What was actually " +"occurring was that FreeBSD was proactively paging out unused pages to make " +"room for more disk cache while Linux was keeping unused pages in core and " +"leaving less memory available for cache and process pages. I do not know " +"whether this is still true today." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vm-design/_index.adoc:255 +#, no-wrap +msgid "Pre-Faulting and Zeroing Optimizations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:265 +msgid "" +"Taking a VM fault is not expensive if the underlying page is already in core " +"and can simply be mapped into the process, but it can become expensive if " +"you take a whole lot of them on a regular basis. A good example of this is " +"running a program such as man:ls[1] or man:ps[1] over and over again. If " +"the program binary is mapped into memory but not mapped into the page table, " +"then all the pages that will be accessed by the program will have to be " +"faulted in every time the program is run. This is unnecessary when the " +"pages in question are already in the VM Cache, so FreeBSD will attempt to " +"pre-populate a process's page tables with those pages that are already in " +"the VM Cache. One thing that FreeBSD does not yet do is pre-copy-on-write " +"certain pages on exec. For example, if you run the man:ls[1] program while " +"running `vmstat 1` you will notice that it always takes a certain number of " +"page faults, even when you run it over and over again. These are zero-fill " +"faults, not program code faults (which were pre-faulted in already). Pre-" +"copying pages on exec or fork is an area that could use more study." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:274 +msgid "" +"A large percentage of page faults that occur are zero-fill faults. You can " +"usually see this by observing the `vmstat -s` output. These occur when a " +"process accesses pages in its BSS area. The BSS area is expected to be " +"initially zero but the VM system does not bother to allocate any memory at " +"all until the process actually accesses it. When a fault occurs the VM " +"system must not only allocate a new page, it must zero it as well. To " +"optimize the zeroing operation the VM system has the ability to pre-zero " +"pages and mark them as such, and to request pre-zeroed pages when zero-fill " +"faults occur. The pre-zeroing occurs whenever the CPU is idle but the " +"number of pages the system pre-zeros is limited to avoid blowing away the " +"memory caches. This is an excellent example of adding complexity to the VM " +"system to optimize the critical path." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vm-design/_index.adoc:276 +#, no-wrap +msgid "Page Table Optimizations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:286 +msgid "" +"The page table optimizations make up the most contentious part of the " +"FreeBSD VM design and they have shown some strain with the advent of serious " +"use of `mmap()`. I think this is actually a feature of most BSDs though I " +"am not sure when it was first introduced. There are two major " +"optimizations. The first is that hardware page tables do not contain " +"persistent state but instead can be thrown away at any time with only a " +"minor amount of management overhead. The second is that every active page " +"table entry in the system has a governing `pv_entry` structure which is tied " +"into the `vm_page` structure. FreeBSD can simply iterate through those " +"mappings that are known to exist while Linux must check all page tables that " +"_might_ contain a specific mapping to see if it does, which can achieve " +"O(n^2) overhead in certain situations. It is because of this that FreeBSD " +"tends to make better choices on which pages to reuse or swap when memory is " +"stressed, giving it better performance under load. However, FreeBSD " +"requires kernel tuning to accommodate large-shared-address-space situations " +"such as those that can occur in a news system because it may run out of " +"`pv_entry` structures." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:291 +msgid "" +"Both Linux and FreeBSD need work in this area. FreeBSD is trying to " +"maximize the advantage of a potentially sparse active-mapping model (not all " +"processes need to map all pages of a shared library, for example), whereas " +"Linux is trying to simplify its algorithms. FreeBSD generally has the " +"performance advantage here at the cost of wasting a little extra memory, but " +"FreeBSD breaks down in the case where a large file is massively shared " +"across hundreds of processes. Linux, on the other hand, breaks down in the " +"case where many processes are sparsely-mapping the same shared library and " +"also runs non-optimally when trying to determine whether a page can be " +"reused or not." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vm-design/_index.adoc:293 +#, no-wrap +msgid "Conclusion" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:298 +msgid "" +"Virtual memory in modern operating systems must address a number of " +"different issues efficiently and for many different usage patterns. The " +"modular and algorithmic approach that BSD has historically taken allows us " +"to study and understand the current implementation as well as relatively " +"cleanly replace large sections of the code. There have been a number of " +"improvements to the FreeBSD VM system in the last several years, and work is " +"ongoing." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vm-design/_index.adoc:300 +#, no-wrap +msgid "Bonus QA session by Allen Briggs" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vm-design/_index.adoc:302 +#, no-wrap +msgid "What is the interleaving algorithm that you refer to in your listing of the ills of the FreeBSD 3.X swap arrangements?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:308 +msgid "" +"FreeBSD uses a fixed swap interleave which defaults to 4. This means that " +"FreeBSD reserves space for four swap areas even if you only have one, two, " +"or three. Since swap is interleaved the linear address space representing " +"the \"four swap areas\" will be fragmented if you do not actually have four " +"swap areas. For example, if you have two swap areas A and B FreeBSD's " +"address space representation for that swap area will be interleaved in " +"blocks of 16 pages:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vm-design/_index.adoc:311 +#, no-wrap +msgid "A B C D A B C D A B C D A B C D\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:318 +msgid "" +"FreeBSD 3.X uses a \"sequential list of free regions\" approach to " +"accounting for the free swap areas. The idea is that large blocks of free " +"linear space can be represented with a single list node ([.filename]#kern/" +"subr_rlist.c#). But due to the fragmentation the sequential list winds up " +"being insanely fragmented. In the above example, completely unused swap " +"will have A and B shown as \"free\" and C and D shown as \"all allocated\". " +"Each A-B sequence requires a list node to account for because C and D are " +"holes, so the list node cannot be combined with the next A-B sequence." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:320 +msgid "" +"Why do we interleave our swap space instead of just tack swap areas onto the " +"end and do something fancier? It is a whole lot easier to allocate linear " +"swaths of an address space and have the result automatically be interleaved " +"across multiple disks than it is to try to put that sophistication elsewhere." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:325 +msgid "" +"The fragmentation causes other problems. Being a linear list under 3.X, and " +"having such a huge amount of inherent fragmentation, allocating and freeing " +"swap winds up being an O(N) algorithm instead of an O(1) algorithm. " +"Combined with other factors (heavy swapping) and you start getting into " +"O(N^2) and O(N^3) levels of overhead, which is bad. The 3.X system may also " +"need to allocate KVM during a swap operation to create a new list node which " +"can lead to a deadlock if the system is trying to pageout pages in a low-" +"memory situation." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:330 +msgid "" +"Under 4.X we do not use a sequential list. Instead we use a radix tree and " +"bitmaps of swap blocks rather than ranged list nodes. We take the hit of " +"preallocating all the bitmaps required for the entire swap area up front but " +"it winds up wasting less memory due to the use of a bitmap (one bit per " +"block) instead of a linked list of nodes. The use of a radix tree instead " +"of a sequential list gives us nearly O(1) performance no matter how " +"fragmented the tree becomes." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vm-design/_index.adoc:331 +#, no-wrap +msgid "How is the separation of clean and dirty (inactive) pages related to the situation where you see low cache queue counts and high active queue counts in systat -vm? Do the systat stats roll the active and dirty pages together for the active queue count?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:336 +msgid "" +"Yes, that is confusing. The relationship is \"goal\" verses \"reality\". " +"Our goal is to separate the pages but the reality is that if we are not in a " +"memory crunch, we do not really have to." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:338 +msgid "" +"What this means is that FreeBSD will not try very hard to separate out dirty " +"pages (inactive queue) from clean pages (cache queue) when the system is not " +"being stressed, nor will it try to deactivate pages (active queue -> " +"inactive queue) when the system is not being stressed, even if they are not " +"being used." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vm-design/_index.adoc:339 +#, no-wrap +msgid "In man:ls[1] the / vmstat 1 example, would not some of the page faults be data page faults (COW from executable file to private page)? I.e., I would expect the page faults to be some zero-fill and some program data. Or are you implying that FreeBSD does do pre-COW for the program data?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:345 +msgid "" +"A COW fault can be either zero-fill or program-data. The mechanism is the " +"same either way because the backing program-data is almost certainly already " +"in the cache. I am indeed lumping the two together. FreeBSD does not pre-" +"COW program data or zero-fill, but it _does_ pre-map pages that exist in its " +"cache." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/vm-design/_index.adoc:346 +#, no-wrap +msgid "In your section on page table optimizations, can you give a little more detail about pv_entry and vm_page (or should vm_page be vm_pmap-as in 4.4, cf. pp. 180-181 of McKusick, Bostic, Karel, Quarterman)? Specifically, what kind of operation/reaction would require scanning the mappings?" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:350 +msgid "" +"A `vm_page` represents an (object,index#) tuple. A `pv_entry` represents a " +"hardware page table entry (pte). If you have five processes sharing the " +"same physical page, and three of those processes's page tables actually map " +"the page, that page will be represented by a single `vm_page` structure and " +"three `pv_entry` structures." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:353 +msgid "" +"`pv_entry` structures only represent pages mapped by the MMU (one `pv_entry` " +"represents one pte). This means that when we need to remove all hardware " +"references to a `vm_page` (to reuse the page for something else, page it " +"out, clear it, dirty it, and so forth) we can simply scan the linked list of " +"pv_entry's associated with that vm_page to remove or modify the pte's from " +"their page tables." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:360 +msgid "" +"Under Linux there is no such linked list. To remove all the hardware page " +"table mappings for a `vm_page` linux must index into every VM object that " +"_might_ have mapped the page. For example, if you have 50 processes all " +"mapping the same shared library and want to get rid of page X in that " +"library, you need to index into the page table for each of those 50 " +"processes even if only 10 of them have actually mapped the page. So Linux " +"is trading off the simplicity of its design against performance. Many VM " +"algorithms which are O(1) or (small N) under FreeBSD wind up being O(N), " +"O(N^2), or worse under Linux. Since the pte's representing a particular " +"page in an object tend to be at the same offset in all the page tables they " +"are mapped in, reducing the number of accesses into the page tables at the " +"same pte offset will often avoid blowing away the L1 cache line for that " +"offset, which can lead to better performance." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:362 +msgid "" +"FreeBSD has added complexity (the `pv_entry` scheme) to increase performance " +"(to limit page table accesses to _only_ those pte's that need to be " +"modified)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:366 +msgid "" +"But FreeBSD has a scaling problem that Linux does not in that there are a " +"limited number of `pv_entry` structures and this causes problems when you " +"have massive sharing of data. In this case you may run out of `pv_entry` " +"structures even though there is plenty of free memory available. This can " +"be fixed easily enough by bumping up the number of `pv_entry` structures in " +"the kernel config, but we really need to find a better way to do it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vm-design/_index.adoc:369 +msgid "" +"In regards to the memory overhead of a page table verses the `pv_entry` " +"scheme: Linux uses \"permanent\" page tables that are not throw away, but " +"does not need a `pv_entry` for each potentially mapped pte. FreeBSD uses " +"\"throw away\" page tables but adds in a `pv_entry` structure for each " +"actually-mapped pte. I think memory utilization winds up being about the " +"same, giving FreeBSD an algorithmic advantage with its ability to throw away " +"page tables at will with very low overhead." +msgstr "" diff --git a/documentation/content/en/articles/vpn-ipsec/_index.adoc b/documentation/content/en/articles/vpn-ipsec/_index.adoc new file mode 100644 index 0000000000..882a4c0f34 --- /dev/null +++ b/documentation/content/en/articles/vpn-ipsec/_index.adoc @@ -0,0 +1,326 @@ +--- +title: VPN over IPsec +authors: + - author: The FreeBSD Documentation Project +copyright: 2023 The FreeBSD Documentation Project +description: VPN over IPsec +trademarks: ["freebsd", "general"] +--- + += VPN over IPsec +:doctype: article +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:source-highlighter: rouge +:experimental: + +''' + +toc::[] + +Internet Protocol Security (IPsec) is a set of protocols which sit on top of the Internet Protocol (IP) layer. +It allows two or more hosts to communicate in a secure manner by authenticating and encrypting each IP packet of a communication session. +The FreeBSD IPsec network stack is based on the http://www.kame.net/[http://www.kame.net/] implementation and supports both IPv4 and IPv6 sessions. + +IPsec is comprised of the following sub-protocols: + +* _Encapsulated Security Payload (ESP)_: this protocol protects the IP packet data from third party interference by encrypting the contents using symmetric cryptography algorithms such as Blowfish and 3DES. +* _Authentication Header (AH)_: this protocol protects the IP packet header from third party interference and spoofing by computing a cryptographic checksum and hashing the IP packet header fields with a secure hashing function. This is then followed by an additional header that contains the hash, to allow the information in the packet to be authenticated. +* _IP Payload Compression Protocol (IPComp_): this protocol tries to increase communication performance by compressing the IP payload in order to reduce the amount of data sent. + +These protocols can either be used together or separately, depending on the environment. + +IPsec supports two modes of operation. +The first mode, _Transport Mode_, protects communications between two hosts. +The second mode, _Tunnel Mode_, is used to build virtual tunnels, commonly known as Virtual Private Networks (VPNs). +Consult man:ipsec[4] for detailed information on the IPsec subsystem in FreeBSD. + +The article demonstrates the process of setting up an IPsecVPN between a home network and a corporate network. + +In the example scenario: + +* Both sites are connected to the Internet through a gateway that is running FreeBSD. +* The gateway on each network has at least one external IP address. In this example, the corporate LAN's external IP address is `172.16.5.4` and the home LAN's external IP address is `192.168.1.12`. +* The internal addresses of the two networks can be either public or private IP addresses. However, the address space must not overlap. In this example, the corporate LAN's internal IP address is `10.246.38.1` and the home LAN's internal IP address is `10.0.0.5`. + +[.programlisting] +.... + corporate home +10.246.38.1/24 -- 172.16.5.4 <--> 192.168.1.12 -- 10.0.0.5/24 +.... + +== Configuring a VPN on FreeBSD + +To begin, package:security/ipsec-tools[] must be installed from the Ports Collection. +This software provides a number of applications which support the configuration. + +The next requirement is to create two man:gif[4] pseudo-devices which will be used to tunnel packets and allow both networks to communicate properly. +As `root`, run the following command on each gateway: + +[source,shell] +.... +corp-gw# ifconfig gif0 create +corp-gw# ifconfig gif0 10.246.38.1 10.0.0.5 +corp-gw# ifconfig gif0 tunnel 172.16.5.4 192.168.1.12 +.... + +[source,shell] +.... +home-gw# ifconfig gif0 create +home-gw# ifconfig gif0 10.0.0.5 10.246.38.1 +home-gw# ifconfig gif0 tunnel 192.168.1.12 172.16.5.4 +.... + +Verify the setup on each gateway, using `ifconfig gif0`. +Here is the output from the home gateway: + +[.programlisting] +.... +gif0: flags=8051 mtu 1280 +tunnel inet 172.16.5.4 --> 192.168.1.12 +inet6 fe80::2e0:81ff:fe02:5881%gif0 prefixlen 64 scopeid 0x6 +inet 10.246.38.1 --> 10.0.0.5 netmask 0xffffff00 +.... + +Here is the output from the corporate gateway: + +[.programlisting] +.... +gif0: flags=8051 mtu 1280 +tunnel inet 192.168.1.12 --> 172.16.5.4 +inet 10.0.0.5 --> 10.246.38.1 netmask 0xffffff00 +inet6 fe80::250:bfff:fe3a:c1f%gif0 prefixlen 64 scopeid 0x4 +.... + +Once complete, both internal IP addresses should be reachable using man:ping[8]: + +[source,shell] +.... +home-gw# ping 10.0.0.5 +PING 10.0.0.5 (10.0.0.5): 56 data bytes +64 bytes from 10.0.0.5: icmp_seq=0 ttl=64 time=42.786 ms +64 bytes from 10.0.0.5: icmp_seq=1 ttl=64 time=19.255 ms +64 bytes from 10.0.0.5: icmp_seq=2 ttl=64 time=20.440 ms +64 bytes from 10.0.0.5: icmp_seq=3 ttl=64 time=21.036 ms +--- 10.0.0.5 ping statistics --- +4 packets transmitted, 4 packets received, 0% packet loss +round-trip min/avg/max/stddev = 19.255/25.879/42.786/9.782 ms + +corp-gw# ping 10.246.38.1 +PING 10.246.38.1 (10.246.38.1): 56 data bytes +64 bytes from 10.246.38.1: icmp_seq=0 ttl=64 time=28.106 ms +64 bytes from 10.246.38.1: icmp_seq=1 ttl=64 time=42.917 ms +64 bytes from 10.246.38.1: icmp_seq=2 ttl=64 time=127.525 ms +64 bytes from 10.246.38.1: icmp_seq=3 ttl=64 time=119.896 ms +64 bytes from 10.246.38.1: icmp_seq=4 ttl=64 time=154.524 ms +--- 10.246.38.1 ping statistics --- +5 packets transmitted, 5 packets received, 0% packet loss +round-trip min/avg/max/stddev = 28.106/94.594/154.524/49.814 ms +.... + +As expected, both sides have the ability to send and receive ICMP packets from the privately configured addresses. +Next, both gateways must be told how to route packets in order to correctly send traffic from the networks behind each gateway. +The following commands will achieve this goal: + +[source,shell] +.... +corp-gw# route add 10.0.0.0 10.0.0.5 255.255.255.0 +corp-gw# route add net 10.0.0.0: gateway 10.0.0.5 +home-gw# route add 10.246.38.0 10.246.38.1 255.255.255.0 +home-gw# route add host 10.246.38.0: gateway 10.246.38.1 +.... + +Internal machines should be reachable from each gateway as well as from machines behind the gateways. +Again, use man:ping[8] to confirm: + +[source,shell] +.... +corp-gw# ping -c 3 10.0.0.8 +PING 10.0.0.8 (10.0.0.8): 56 data bytes +64 bytes from 10.0.0.8: icmp_seq=0 ttl=63 time=92.391 ms +64 bytes from 10.0.0.8: icmp_seq=1 ttl=63 time=21.870 ms +64 bytes from 10.0.0.8: icmp_seq=2 ttl=63 time=198.022 ms +--- 10.0.0.8 ping statistics --- +3 packets transmitted, 3 packets received, 0% packet loss +round-trip min/avg/max/stddev = 21.870/101.846/198.022/74.001 ms + +home-gw# ping -c 3 10.246.38.107 +PING 10.246.38.1 (10.246.38.107): 56 data bytes +64 bytes from 10.246.38.107: icmp_seq=0 ttl=64 time=53.491 ms +64 bytes from 10.246.38.107: icmp_seq=1 ttl=64 time=23.395 ms +64 bytes from 10.246.38.107: icmp_seq=2 ttl=64 time=23.865 ms +--- 10.246.38.107 ping statistics --- +3 packets transmitted, 3 packets received, 0% packet loss +round-trip min/avg/max/stddev = 21.145/31.721/53.491/12.179 ms +.... + +At this point, traffic is flowing between the networks encapsulated in a gif tunnel but without any encryption. +Next, use IPSec to encrypt traffic using pre-shared keys (PSK). +Other than the IP addresses, [.filename]#/usr/local/etc/racoon/racoon.conf# on both gateways will be identical and look similar to: + +[.programlisting] +.... +path pre_shared_key "/usr/local/etc/racoon/psk.txt"; #location of pre-shared key file +log debug; #log verbosity setting: set to 'notify' when testing and debugging is complete + +padding # options are not to be changed +{ + maximum_length 20; + randomize off; + strict_check off; + exclusive_tail off; +} + +timer # timing options. change as needed +{ + counter 5; + interval 20 sec; + persend 1; +# natt_keepalive 15 sec; + phase1 30 sec; + phase2 15 sec; +} + +listen # address [port] that racoon will listen on +{ + isakmp 172.16.5.4 [500]; + isakmp_natt 172.16.5.4 [4500]; +} + +remote 192.168.1.12 [500] +{ + exchange_mode main,aggressive; + doi ipsec_doi; + situation identity_only; + my_identifier address 172.16.5.4; + peers_identifier address 192.168.1.12; + lifetime time 8 hour; + passive off; + proposal_check obey; +# nat_traversal off; + generate_policy off; + + proposal { + encryption_algorithm blowfish; + hash_algorithm md5; + authentication_method pre_shared_key; + lifetime time 30 sec; + dh_group 1; + } +} + +sainfo (address 10.246.38.0/24 any address 10.0.0.0/24 any) # address $network/$netmask $type address $network/$netmask $type ( $type being any or esp) +{ # $network must be the two internal networks you are joining. + pfs_group 1; + lifetime time 36000 sec; + encryption_algorithm blowfish,3des; + authentication_algorithm hmac_md5,hmac_sha1; + compression_algorithm deflate; +} +.... + +For descriptions of each available option, refer to the manual page for [.filename]#racoon.conf#. + +The Security Policy Database (SPD) needs to be configured so that FreeBSD and racoon are able to encrypt and decrypt network traffic between the hosts. + +This can be achieved with a shell script, similar to the following, on the corporate gateway. +This file will be used during system initialization and should be saved as [.filename]#/usr/local/etc/racoon/setkey.conf#. + +[.programlisting] +.... +flush; +spdflush; +# To the home network +spdadd 10.246.38.0/24 10.0.0.0/24 any -P out ipsec esp/tunnel/172.16.5.4-192.168.1.12/use; +spdadd 10.0.0.0/24 10.246.38.0/24 any -P in ipsec esp/tunnel/192.168.1.12-172.16.5.4/use; +.... + +Once in place, racoon may be started on both gateways using the following command: + +[source,shell] +.... +# /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf -l /var/log/racoon.log +.... + +The output should be similar to the following: + +[source,shell] +.... +corp-gw# /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf +Foreground mode. +2006-01-30 01:35:47: INFO: begin Identity Protection mode. +2006-01-30 01:35:48: INFO: received Vendor ID: KAME/racoon +2006-01-30 01:35:55: INFO: received Vendor ID: KAME/racoon +2006-01-30 01:36:04: INFO: ISAKMP-SA established 172.16.5.4[500]-192.168.1.12[500] spi:623b9b3bd2492452:7deab82d54ff704a +2006-01-30 01:36:05: INFO: initiate new phase 2 negotiation: 172.16.5.4[0]192.168.1.12[0] +2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]->172.16.5.4[0] spi=28496098(0x1b2d0e2) +2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]->192.168.1.12[0] spi=47784998(0x2d92426) +2006-01-30 01:36:13: INFO: respond new phase 2 negotiation: 172.16.5.4[0]192.168.1.12[0] +2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]->172.16.5.4[0] spi=124397467(0x76a279b) +2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]->192.168.1.12[0] spi=175852902(0xa7b4d66) +.... + +To ensure the tunnel is working properly, switch to another console and use man:tcpdump[1] to view network traffic using the following command. +Replace `em0` with the network interface card as required: + +[source,shell] +.... +corp-gw# tcpdump -i em0 host 172.16.5.4 and dst 192.168.1.12 +.... + +Data similar to the following should appear on the console. +If not, there is an issue and debugging the returned data will be required. + +[.programlisting] +.... +01:47:32.021683 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xa) +01:47:33.022442 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xb) +01:47:34.024218 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xc) +.... + +At this point, both networks should be available and seem to be part of the same network. +Most likely both networks are protected by a firewall. +To allow traffic to flow between them, rules need to be added to pass packets. +For the man:ipfw[8] firewall, add the following lines to the firewall configuration file: + +[.programlisting] +.... +ipfw add 00201 allow log esp from any to any +ipfw add 00202 allow log ah from any to any +ipfw add 00203 allow log ipencap from any to any +ipfw add 00204 allow log udp from any 500 to any +.... + +[NOTE] +==== +The rule numbers may need to be altered depending on the current host configuration. +==== + +For users of man:pf[4] or man:ipf[8], the following rules should do the trick: + +[.programlisting] +.... +pass in quick proto esp from any to any +pass in quick proto ah from any to any +pass in quick proto ipencap from any to any +pass in quick proto udp from any port = 500 to any port = 500 +pass in quick on gif0 from any to any +pass out quick proto esp from any to any +pass out quick proto ah from any to any +pass out quick proto ipencap from any to any +pass out quick proto udp from any port = 500 to any port = 500 +pass out quick on gif0 from any to any +.... + +Finally, to allow the machine to start support for the VPN during system initialization, add the following lines to [.filename]#/etc/rc.conf#: + +[.programlisting] +.... +ipsec_enable="YES" +ipsec_program="/usr/local/sbin/setkey" +ipsec_file="/usr/local/etc/racoon/setkey.conf" # allows setting up spd policies on boot +racoon_enable="yes" +.... diff --git a/documentation/content/en/articles/vpn-ipsec/_index.po b/documentation/content/en/articles/vpn-ipsec/_index.po new file mode 100644 index 0000000000..906793f27a --- /dev/null +++ b/documentation/content/en/articles/vpn-ipsec/_index.po @@ -0,0 +1,586 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR The FreeBSD Project +# This file is distributed under the same license as the FreeBSD Documentation package. +# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: FreeBSD Documentation VERSION\n" +"POT-Creation-Date: 2024-01-17 20:35-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: Title = +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:1 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:10 +#, no-wrap +msgid "VPN over IPsec" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:21 +msgid "'''" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:27 +msgid "" +"Internet Protocol Security (IPsec) is a set of protocols which sit on top of " +"the Internet Protocol (IP) layer. It allows two or more hosts to " +"communicate in a secure manner by authenticating and encrypting each IP " +"packet of a communication session. The FreeBSD IPsec network stack is based " +"on the http://www.kame.net/[http://www.kame.net/] implementation and " +"supports both IPv4 and IPv6 sessions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:29 +msgid "IPsec is comprised of the following sub-protocols:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:31 +msgid "" +"_Encapsulated Security Payload (ESP)_: this protocol protects the IP packet " +"data from third party interference by encrypting the contents using " +"symmetric cryptography algorithms such as Blowfish and 3DES." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:32 +msgid "" +"_Authentication Header (AH)_: this protocol protects the IP packet header " +"from third party interference and spoofing by computing a cryptographic " +"checksum and hashing the IP packet header fields with a secure hashing " +"function. This is then followed by an additional header that contains the " +"hash, to allow the information in the packet to be authenticated." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:33 +msgid "" +"_IP Payload Compression Protocol (IPComp_): this protocol tries to increase " +"communication performance by compressing the IP payload in order to reduce " +"the amount of data sent." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:35 +msgid "" +"These protocols can either be used together or separately, depending on the " +"environment." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:40 +msgid "" +"IPsec supports two modes of operation. The first mode, _Transport Mode_, " +"protects communications between two hosts. The second mode, _Tunnel Mode_, " +"is used to build virtual tunnels, commonly known as Virtual Private Networks " +"(VPNs). Consult man:ipsec[4] for detailed information on the IPsec " +"subsystem in FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:42 +msgid "" +"The article demonstrates the process of setting up an IPsecVPN between a " +"home network and a corporate network." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:44 +msgid "In the example scenario:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:46 +msgid "" +"Both sites are connected to the Internet through a gateway that is running " +"FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:47 +msgid "" +"The gateway on each network has at least one external IP address. In this " +"example, the corporate LAN's external IP address is `172.16.5.4` and the " +"home LAN's external IP address is `192.168.1.12`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:48 +msgid "" +"The internal addresses of the two networks can be either public or private " +"IP addresses. However, the address space must not overlap. In this example, " +"the corporate LAN's internal IP address is `10.246.38.1` and the home LAN's " +"internal IP address is `10.0.0.5`." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:53 +#, no-wrap +msgid "" +" corporate home\n" +"10.246.38.1/24 -- 172.16.5.4 <--> 192.168.1.12 -- 10.0.0.5/24\n" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:55 +#, no-wrap +msgid "Configuring a VPN on FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:59 +msgid "" +"To begin, package:security/ipsec-tools[] must be installed from the Ports " +"Collection. This software provides a number of applications which support " +"the configuration." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:62 +msgid "" +"The next requirement is to create two man:gif[4] pseudo-devices which will " +"be used to tunnel packets and allow both networks to communicate properly. " +"As `root`, run the following command on each gateway:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:68 +#, no-wrap +msgid "" +"corp-gw# ifconfig gif0 create\n" +"corp-gw# ifconfig gif0 10.246.38.1 10.0.0.5\n" +"corp-gw# ifconfig gif0 tunnel 172.16.5.4 192.168.1.12\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:75 +#, no-wrap +msgid "" +"home-gw# ifconfig gif0 create\n" +"home-gw# ifconfig gif0 10.0.0.5 10.246.38.1\n" +"home-gw# ifconfig gif0 tunnel 192.168.1.12 172.16.5.4\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:79 +msgid "" +"Verify the setup on each gateway, using `ifconfig gif0`. Here is the output " +"from the home gateway:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:86 +#, no-wrap +msgid "" +"gif0: flags=8051 mtu 1280\n" +"tunnel inet 172.16.5.4 --> 192.168.1.12\n" +"inet6 fe80::2e0:81ff:fe02:5881%gif0 prefixlen 64 scopeid 0x6\n" +"inet 10.246.38.1 --> 10.0.0.5 netmask 0xffffff00\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:89 +msgid "Here is the output from the corporate gateway:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:96 +#, no-wrap +msgid "" +"gif0: flags=8051 mtu 1280\n" +"tunnel inet 192.168.1.12 --> 172.16.5.4\n" +"inet 10.0.0.5 --> 10.246.38.1 netmask 0xffffff00\n" +"inet6 fe80::250:bfff:fe3a:c1f%gif0 prefixlen 64 scopeid 0x4\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:99 +msgid "" +"Once complete, both internal IP addresses should be reachable using " +"man:ping[8]:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:111 +#, no-wrap +msgid "" +"home-gw# ping 10.0.0.5\n" +"PING 10.0.0.5 (10.0.0.5): 56 data bytes\n" +"64 bytes from 10.0.0.5: icmp_seq=0 ttl=64 time=42.786 ms\n" +"64 bytes from 10.0.0.5: icmp_seq=1 ttl=64 time=19.255 ms\n" +"64 bytes from 10.0.0.5: icmp_seq=2 ttl=64 time=20.440 ms\n" +"64 bytes from 10.0.0.5: icmp_seq=3 ttl=64 time=21.036 ms\n" +"--- 10.0.0.5 ping statistics ---\n" +"4 packets transmitted, 4 packets received, 0% packet loss\n" +"round-trip min/avg/max/stddev = 19.255/25.879/42.786/9.782 ms\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:122 +#, no-wrap +msgid "" +"corp-gw# ping 10.246.38.1\n" +"PING 10.246.38.1 (10.246.38.1): 56 data bytes\n" +"64 bytes from 10.246.38.1: icmp_seq=0 ttl=64 time=28.106 ms\n" +"64 bytes from 10.246.38.1: icmp_seq=1 ttl=64 time=42.917 ms\n" +"64 bytes from 10.246.38.1: icmp_seq=2 ttl=64 time=127.525 ms\n" +"64 bytes from 10.246.38.1: icmp_seq=3 ttl=64 time=119.896 ms\n" +"64 bytes from 10.246.38.1: icmp_seq=4 ttl=64 time=154.524 ms\n" +"--- 10.246.38.1 ping statistics ---\n" +"5 packets transmitted, 5 packets received, 0% packet loss\n" +"round-trip min/avg/max/stddev = 28.106/94.594/154.524/49.814 ms\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:127 +msgid "" +"As expected, both sides have the ability to send and receive ICMP packets " +"from the privately configured addresses. Next, both gateways must be told " +"how to route packets in order to correctly send traffic from the networks " +"behind each gateway. The following commands will achieve this goal:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:134 +#, no-wrap +msgid "" +"corp-gw# route add 10.0.0.0 10.0.0.5 255.255.255.0\n" +"corp-gw# route add net 10.0.0.0: gateway 10.0.0.5\n" +"home-gw# route add 10.246.38.0 10.246.38.1 255.255.255.0\n" +"home-gw# route add host 10.246.38.0: gateway 10.246.38.1\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:138 +msgid "" +"Internal machines should be reachable from each gateway as well as from " +"machines behind the gateways. Again, use man:ping[8] to confirm:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:149 +#, no-wrap +msgid "" +"corp-gw# ping -c 3 10.0.0.8\n" +"PING 10.0.0.8 (10.0.0.8): 56 data bytes\n" +"64 bytes from 10.0.0.8: icmp_seq=0 ttl=63 time=92.391 ms\n" +"64 bytes from 10.0.0.8: icmp_seq=1 ttl=63 time=21.870 ms\n" +"64 bytes from 10.0.0.8: icmp_seq=2 ttl=63 time=198.022 ms\n" +"--- 10.0.0.8 ping statistics ---\n" +"3 packets transmitted, 3 packets received, 0% packet loss\n" +"round-trip min/avg/max/stddev = 21.870/101.846/198.022/74.001 ms\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:158 +#, no-wrap +msgid "" +"home-gw# ping -c 3 10.246.38.107\n" +"PING 10.246.38.1 (10.246.38.107): 56 data bytes\n" +"64 bytes from 10.246.38.107: icmp_seq=0 ttl=64 time=53.491 ms\n" +"64 bytes from 10.246.38.107: icmp_seq=1 ttl=64 time=23.395 ms\n" +"64 bytes from 10.246.38.107: icmp_seq=2 ttl=64 time=23.865 ms\n" +"--- 10.246.38.107 ping statistics ---\n" +"3 packets transmitted, 3 packets received, 0% packet loss\n" +"round-trip min/avg/max/stddev = 21.145/31.721/53.491/12.179 ms\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:163 +msgid "" +"At this point, traffic is flowing between the networks encapsulated in a gif " +"tunnel but without any encryption. Next, use IPSec to encrypt traffic using " +"pre-shared keys (PSK). Other than the IP addresses, " +"[.filename]#/usr/local/etc/racoon/racoon.conf# on both gateways will be " +"identical and look similar to:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:168 +#, no-wrap +msgid "" +"path pre_shared_key \"/usr/local/etc/racoon/psk.txt\"; #location of " +"pre-shared key file\n" +"log debug;\t#log verbosity setting: set to 'notify' when testing and " +"debugging is complete\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:176 +#, no-wrap +msgid "" +"padding\t# options are not to be changed\n" +"{\n" +" maximum_length 20;\n" +" randomize off;\n" +" strict_check off;\n" +" exclusive_tail off;\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:186 +#, no-wrap +msgid "" +"timer\t# timing options. change as needed\n" +"{\n" +" counter 5;\n" +" interval 20 sec;\n" +" persend 1;\n" +"# natt_keepalive 15 sec;\n" +" phase1 30 sec;\n" +" phase2 15 sec;\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:192 +#, no-wrap +msgid "" +"listen\t# address [port] that racoon will listen on\n" +"{\n" +" isakmp 172.16.5.4 [500];\n" +" isakmp_natt 172.16.5.4 [4500];\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:205 +#, no-wrap +msgid "" +"remote 192.168.1.12 [500]\n" +"{\n" +" exchange_mode main,aggressive;\n" +" doi ipsec_doi;\n" +" situation identity_only;\n" +" my_identifier address 172.16.5.4;\n" +" peers_identifier address 192.168.1.12;\n" +" lifetime time 8 hour;\n" +" passive off;\n" +" proposal_check obey;\n" +"# nat_traversal off;\n" +" generate_policy off;\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:214 +#, no-wrap +msgid "" +" proposal {\n" +" encryption_algorithm blowfish;\n" +" hash_algorithm md5;\n" +" authentication_method pre_shared_key;\n" +" lifetime time 30 sec;\n" +" dh_group 1;\n" +" }\n" +"}\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:223 +#, no-wrap +msgid "" +"sainfo (address 10.246.38.0/24 any address 10.0.0.0/24 any)\t# address " +"$network/$netmask $type address $network/$netmask $type ( $type being any or " +"esp)\n" +"{\t\t\t\t\t\t\t\t# $network must be the two internal networks you are " +"joining.\n" +" pfs_group 1;\n" +" lifetime time 36000 sec;\n" +" encryption_algorithm blowfish,3des;\n" +" authentication_algorithm hmac_md5,hmac_sha1;\n" +" compression_algorithm deflate;\n" +"}\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:226 +msgid "" +"For descriptions of each available option, refer to the manual page for " +"[.filename]#racoon.conf#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:228 +msgid "" +"The Security Policy Database (SPD) needs to be configured so that FreeBSD " +"and racoon are able to encrypt and decrypt network traffic between the " +"hosts." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:231 +msgid "" +"This can be achieved with a shell script, similar to the following, on the " +"corporate gateway. This file will be used during system initialization and " +"should be saved as [.filename]#/usr/local/etc/racoon/setkey.conf#." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:239 +#, no-wrap +msgid "" +"flush;\n" +"spdflush;\n" +"# To the home network\n" +"spdadd 10.246.38.0/24 10.0.0.0/24 any -P out ipsec " +"esp/tunnel/172.16.5.4-192.168.1.12/use;\n" +"spdadd 10.0.0.0/24 10.246.38.0/24 any -P in ipsec " +"esp/tunnel/192.168.1.12-172.16.5.4/use;\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:242 +msgid "" +"Once in place, racoon may be started on both gateways using the following " +"command:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:246 +#, no-wrap +msgid "" +"# /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf -l " +"/var/log/racoon.log\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:249 +msgid "The output should be similar to the following:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:264 +#, no-wrap +msgid "" +"corp-gw# /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf\n" +"Foreground mode.\n" +"2006-01-30 01:35:47: INFO: begin Identity Protection mode.\n" +"2006-01-30 01:35:48: INFO: received Vendor ID: KAME/racoon\n" +"2006-01-30 01:35:55: INFO: received Vendor ID: KAME/racoon\n" +"2006-01-30 01:36:04: INFO: ISAKMP-SA established " +"172.16.5.4[500]-192.168.1.12[500] spi:623b9b3bd2492452:7deab82d54ff704a\n" +"2006-01-30 01:36:05: INFO: initiate new phase 2 negotiation: " +"172.16.5.4[0]192.168.1.12[0]\n" +"2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel " +"192.168.1.12[0]->172.16.5.4[0] spi=28496098(0x1b2d0e2)\n" +"2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel " +"172.16.5.4[0]->192.168.1.12[0] spi=47784998(0x2d92426)\n" +"2006-01-30 01:36:13: INFO: respond new phase 2 negotiation: " +"172.16.5.4[0]192.168.1.12[0]\n" +"2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel " +"192.168.1.12[0]->172.16.5.4[0] spi=124397467(0x76a279b)\n" +"2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel " +"172.16.5.4[0]->192.168.1.12[0] spi=175852902(0xa7b4d66)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:268 +msgid "" +"To ensure the tunnel is working properly, switch to another console and use " +"man:tcpdump[1] to view network traffic using the following command. Replace " +"`em0` with the network interface card as required:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:272 +#, no-wrap +msgid "corp-gw# tcpdump -i em0 host 172.16.5.4 and dst 192.168.1.12\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:276 +msgid "" +"Data similar to the following should appear on the console. If not, there " +"is an issue and debugging the returned data will be required." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:282 +#, no-wrap +msgid "" +"01:47:32.021683 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: " +"ESP(spi=0x02acbf9f,seq=0xa)\n" +"01:47:33.022442 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: " +"ESP(spi=0x02acbf9f,seq=0xb)\n" +"01:47:34.024218 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: " +"ESP(spi=0x02acbf9f,seq=0xc)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:288 +msgid "" +"At this point, both networks should be available and seem to be part of the " +"same network. Most likely both networks are protected by a firewall. To " +"allow traffic to flow between them, rules need to be added to pass packets. " +"For the man:ipfw[8] firewall, add the following lines to the firewall " +"configuration file:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:295 +#, no-wrap +msgid "" +"ipfw add 00201 allow log esp from any to any\n" +"ipfw add 00202 allow log ah from any to any\n" +"ipfw add 00203 allow log ipencap from any to any\n" +"ipfw add 00204 allow log udp from any 500 to any\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:300 +msgid "" +"The rule numbers may need to be altered depending on the current host " +"configuration." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:303 +msgid "" +"For users of man:pf[4] or man:ipf[8], the following rules should do the " +"trick:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:316 +#, no-wrap +msgid "" +"pass in quick proto esp from any to any\n" +"pass in quick proto ah from any to any\n" +"pass in quick proto ipencap from any to any\n" +"pass in quick proto udp from any port = 500 to any port = 500\n" +"pass in quick on gif0 from any to any\n" +"pass out quick proto esp from any to any\n" +"pass out quick proto ah from any to any\n" +"pass out quick proto ipencap from any to any\n" +"pass out quick proto udp from any port = 500 to any port = 500\n" +"pass out quick on gif0 from any to any\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:319 +msgid "" +"Finally, to allow the machine to start support for the VPN during system " +"initialization, add the following lines to [.filename]#/etc/rc.conf#:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/vpn-ipsec/_index.adoc:326 +#, no-wrap +msgid "" +"ipsec_enable=\"YES\"\n" +"ipsec_program=\"/usr/local/sbin/setkey\"\n" +"ipsec_file=\"/usr/local/etc/racoon/setkey.conf\" # allows setting up spd " +"policies on boot\n" +"racoon_enable=\"yes\"\n" +msgstr "" |